@magneticwatermelon/mcp-toolkit

Automatically generates boilerplate MCP server code with sensible defaults, eliminating manual protocol setup and configuration. The toolkit infers server structure from TypeScript type definitions and decorators, reducing the typical 50+ lines of MCP initialization code to a single function call. Handles transport layer setup (stdio, SSE, WebSocket) without requiring developers to understand the underlying Model Context Protocol specification.

Provides TypeScript decorators (@Tool, @Resource, @Handler) that declaratively map class methods to MCP protocol endpoints without manual JSON-RPC routing. The toolkit introspects decorated methods at runtime, extracts parameter schemas from TypeScript types, and auto-generates OpenAPI-compatible tool definitions that MCP clients can discover and invoke. Supports async handlers, error propagation, and type validation out of the box.

Abstracts MCP transport layer (stdio, SSE, WebSocket) behind a unified server interface, allowing the same tool definitions to be deployed across multiple transport mechanisms without code changes. The toolkit handles transport-specific concerns (connection lifecycle, message framing, error recovery) and exposes a single server.listen() API that auto-detects the appropriate transport based on environment or explicit configuration.

Validates incoming MCP requests against generated schemas and automatically handles errors with protocol-compliant error responses. The toolkit intercepts requests before they reach tool handlers, validates parameters against TypeScript-derived schemas, and catches exceptions to return properly formatted MCP error objects with stack traces (in development) and user-friendly messages (in production). Supports custom error handlers and validation middleware.

Implements MCP resource and prompt endpoints that allow clients to discover available tools, resources, and prompts through the protocol. The toolkit auto-generates discovery metadata from decorated classes and methods, exposing it via MCP's list_resources, read_resource, and list_prompts endpoints. Clients can query available capabilities without invoking them, enabling dynamic UI generation and capability negotiation.

Enforces end-to-end type safety from tool definition through request handling to response serialization using TypeScript's type system. The toolkit generates type definitions for MCP request/response objects, validates that handlers return compatible types, and catches type mismatches at compile time rather than runtime. Supports strict mode checking and provides IDE autocomplete for all MCP protocol operations.

Provides hooks (beforeRequest, afterResponse, onError) that allow developers to inject custom logic into the request/response pipeline without modifying tool implementations. Middleware runs in sequence, can modify requests/responses, and has access to context (tool name, parameters, execution time). Supports async middleware and error propagation through the chain.

Provides a command-line interface for running MCP servers locally, testing tool invocations, and debugging protocol interactions. The CLI includes a REPL for interactive tool testing, request/response inspection, and protocol validation. Supports hot-reload for rapid iteration and can simulate different transport modes (stdio, WebSocket) without changing server code.

Includes utilities to package MCP servers as npm modules with proper exports, type definitions, and CLI entry points. The toolkit generates package.json configuration, TypeScript type stubs, and bin scripts automatically, reducing the friction of publishing reusable MCP servers to npm. Supports both library (importable) and CLI (executable) distribution modes.