mcp-development

# MCP Server Development Skill Guidelines for designing and implementing MCP servers with TypeScript, focusing on protocol compliance, service architecture, and extensibility. ## MCP Server Design Patterns - **Protocol Compliance**: All server logic must strictly follow the Model Context Protocol (MCP) specification. Reference [MCP docs](https://modelcontextprotocol.io/) and [LLMs integration guide](https://modelcontextprotocol.io/llms-full.txt). - **Transport Abstraction**: Implement transport-agnostic logic. Use interfaces and dependency injection for HTTP, STDIO, or custom transports. - **Service Layer**: Encapsulate business logic in service classes. Each service should be stateless, testable, and expose clear async methods for protocol operations. - **Schema Validation**: Use `zod` for all input/output validation. Define schemas for requests, responses, and errors. Validate at the transport boundary. - **Error Handling**: Centralize error handling. Return MCP-compliant error objects with descriptive messages and codes. - **Manifest & Tooling**: Expose a manifest endpoint/tool for host integration. Manifest must declare all supported operations, schemas, and metadata. - **Extensibility**: Design for easy addition of new tools/operations. Use a registry or factory pattern for tool handlers. - **Testing**: Use [Vitest](https://vitest.dev/) for all tests. Place tests in `tests/` and cover protocol, service, and transport logic. - **Logging**: Use a configurable logger. Avoid `console.log` for STDIO servers; use structured logging and log levels. - **Async/Await**: All operations must be async. - **Type Safety**: Use TypeScript interfaces and types for all protocol objects. - **Configuration**: Use environment variables and config files for secrets, endpoints, and options. - **Documentation**: Document all public classes, methods, and schemas. ## Tool Implementation Patterns - **Tool Registration**: Register each tool in a central registry or manifest. Use a factory or mapping to resolve tool handlers by name. - **Tool Handler Structure**: Implement each tool as a class or function with a clear async `run` or `execute` method. Accept validated input, return structured output. - **Schema-Driven**: Define input/output schemas with `zod`. Validate all tool calls at runtime. - **Error Propagation**: Catch errors in tool handlers and return MCP-compliant error objects. - **Resource Access**: For resource tools (e.g., collections, bookmarks), encapsulate resource logic in dedicated service classes. Use dependency injection for external APIs. - **Declarative Manifest**: Ensure all tools and resources are declared in the manifest with their schemas, descriptions, and metadata. - **Isolation**: Tools should be stateless and not share mutable state. Use context objects for per-request data. - **Extensibility**: New tools/resources should be easy to add by implementing a handler and updating the manifest/registry. ## References - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [MCP Boilerplate](https://github.com/cyanheads/mcp-ts-template) - [Raindrop.io API](https://developer.raindrop.io) - [MCP Inspector Tool](https://github.com/modelcontextprotocol/inspector)