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 and LLMs integration guide.
• 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 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.