How miyamo2/qilin works
Project type and purpose
• Qilin is a Go-based framework (library) for building Model Context Protocol (MCP) servers that communicate over STDIN/STDOUT.
• It provides a zero-config “server” that lets you register “tools” and “resources” with handlers, bind JSON payloads, and emit JSON responses.
File structure
Top-level files and directories:
• core sources: qilin.go, context.go, errors.go, types.go
• transport layer: transport/transport.go, transport/stdio.go
• examples: full sample app under examples/weather/... showing domain, repository, handler, infrastructure/API, main.go
• tests, helpers, configs, module files
README for additional insights
• Provides the high-level API: qilin.New(), Tool(), Start()
• Highlights supported “transports” (only STDIO) and features (Tool, Resource)
• Demonstrates typical handler signature and JSON binding
Main components
A. Qilin Core Framework
• Package entrypoint: qilin.New() → Starter
• Handler registration (Tool(), Resource())
• Dispatcher / router that maps incoming JSON requests to the correct handler
B. Transport Layer
• STDIO transport implementation (transport/stdio.go)
• Reads raw bytes from STDIN → parses into request objects
• Serializes responses into raw bytes → writes to STDOUT
C. Handler Context
• ToolContext abstraction: Bind, JSON, error handling
• Middleware pipeline support
D. User Application (Examples)
• Domain models and repos (examples/weather/domain/...)
• Business logic in handler functions (examples/weather/handler/handler.go)
• Infrastructure adapters/API clients (examples/weather/infrastructure/api/...)
• main.go wiring it all together
E. External Client
• Any process or client that writes JSON MCP messages to STDIN and reads JSON from STDOUT
Relationships & Data Flow
1. External Client → STDIN
2. STDIO Transport reads bytes → unmarshals into a Qilin Request
3. Core Dispatcher identifies the matching Handler
4. HandlerContext.Bind() parses params → Business Logic (domain + infra)
5. HandlerContext.JSON() serializes response → Core
6. STDIO Transport writes JSON bytes → STDOUT → External Client
Architectural patterns & design principles
• Inversion of Control: user registers handlers; Qilin calls them
• Layered architecture: Transport → Core → Handler → Domain → Infrastructure
• Zero-config convention over configuration
Technologies & frameworks
• Go modules, standard library JSON, interfaces for Transport & Context
• Example shows domain-driven structure (model/repository)
• Tests under *_test.go demonstrating usage