tomevault-io 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
zodfor 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.logfor 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
runorexecutemethod. 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.