🇺🇸English

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.

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
• MCP Boilerplate
• Raindrop.io API
• MCP Inspector Tool

Weekly Installs

1

Repository

adeze/raindrop-mcp

GitHub Stars

130

First Seen

Today

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

amp1

cline1

opencode1

cursor1

kimi-cli1

kiro-cli1