MCP Server Template

# MCP Server Template A production-ready template for building Model Context Protocol (MCP) servers with TypeScript. ## Features - **MCP SDK 1.24.3** - Latest SDK with 2025-11-25 spec support - **Dual Transport** - Stdio (Claude Desktop) and HTTP (cloud deployment) - **OAuth 2.1 Foundations** - Protected resource metadata, bearer token structure - **SQLite Caching** - TTL-based caching with sql.js (WebAssembly) - **Observability** - Sentry error tracking + OpenTelemetry tracing - **Security** - PII sanitization, rate limiting, DNS rebinding protection - **Type Safety** - Strict TypeScript with Zod validation ## Quick Start ```bash # Clone and install git clone <this-repo> my-mcp-server cd my-mcp-server npm install # Development mode (hot reload) npm run dev # Build and run npm run build npm start # Test with MCP Inspector npm run inspector ``` ## Project Structure ``` src/ ├── index.ts # CLI entry point ├── server.ts # MCP server implementation ├── instrumentation.ts # Sentry + OpenTelemetry setup ├── config/ │ └── index.ts # Environment configuration ├── db/ │ ├── database.ts # SQLite connection (sql.js) │ └── cache.ts # TTL-based caching ├── tools/ │ ├── registry.ts # Tool registration pattern │ └── examples.ts # Example tool implementations ├── transport/ │ └── http-transport.ts # HTTP with OAuth foundations ├── shared/ │ ├── logger.ts # Structured logging │ ├── errors.ts # Custom error classes │ ├── rate-limiter.ts # Per-source rate limiting │ ├── pii-sanitizer.ts # PII detection/removal │ └── tracing.ts # OpenTelemetry utilities └── types/ └── index.ts # TypeScript type definitions ``` ## Configuration Environment variables (prefix with `MCP_SERVER_`): | Variable | Default | Description | |----------|---------|-------------| | `MCP_SERVER_NAME` | `mcp-server-template` | Server name | | `MCP_SERVER_VERSION` | `0.1.0` | Server version | | `MCP_SERVER_LOG_LEVEL` | `info` | Log level: debug, info, warning, error | | `MCP_SERVER_DB_PATH` | `.data/cache.db` | SQLite database path | | `MCP_SERVER_CACHE_ENABLED` | `true` | Enable/disable caching | | `MCP_SERVER_CACHE_TTL` | `3600` | Default cache TTL (seconds) | | `MCP_SERVER_TIMEOUT` | `30000` | Request timeout (ms) | | `MCP_SERVER_TRANSPORT` | `stdio` | Transport: `stdio` or `http` | | `MCP_SERVER_PORT` | `3000` | HTTP port (when transport=http) | | `MCP_SERVER_HOST` | `127.0.0.1` | HTTP host (when transport=http) | | `MCP_SERVER_SENTRY_DSN` | - | Sentry DSN for error tracking | | `OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing | | `OTEL_EXPORTER_OTLP_ENDPOINT` | - | OTLP collector endpoint | | `MCP_SERVER_DEBUG` | `false` | Debug mode (skips auth) | ## Creating Tools Tools are registered with the ToolRegistry using Zod schemas: ```typescript import { z } from 'zod'; import { getToolRegistry } from './tools/registry.js'; // Define input schema const MyToolInputSchema = z.object({ query: z.string().min(1).describe('Search query'), limit: z.number().positive().optional().default(10), }); type MyToolInput = z.infer<typeof MyToolInputSchema>; // Implement handler async function myToolHandler(input: MyToolInput) { // Your implementation here return { success: true, data: { results: [] }, }; } // Register tool const registry = getToolRegistry(); registry.register( 'my_tool', 'Description of what this tool does', MyToolInputSchema, myToolHandler ); ``` ## Transport Modes ### Stdio (Default) For Claude Desktop and local integrations: ```bash npm start ``` Add to Claude Desktop config: ```json { "mcpServers": { "my-server": { "command": "node", "args": ["/path/to/dist/index.js"] } } } ``` ### HTTP For cloud deployment: ```bash MCP_SERVER_TRANSPORT=http npm start ``` Endpoints: - `GET /health` - Health check - `GET /.well-known/mcp` - MCP server metadata - `GET /.well-known/oauth-protected-resource` - OAuth metadata (RFC 9728) - `GET /mcp` - SSE stream for server events - `POST /mcp` - JSON-RPC requests - `DELETE /mcp` - Close session ## Security Features ### PII Sanitization Automatically detects and masks sensitive data: ```typescript import { sanitizePii } from './shared/pii-sanitizer.js'; const safe = sanitizePii('Contact: user@example.com'); // Output: "Contact: [EMAIL]" ``` ### Rate Limiting Per-source rate limiting with exponential backoff: ```typescript import { getRateLimiter } from './shared/rate-limiter.js'; const limiter = getRateLimiter(); limiter.configure('external-api', { requestsPerWindow: 100, windowMs: 60000, }); await limiter.waitForSlot('external-api'); // Make request... ``` ### DNS Rebinding Protection HTTP transport validates Host headers against allowlist. ## Observability ### Sentry Error tracking with PII filtering: ```bash MCP_SERVER_SENTRY_DSN=https://xxx@sentry.io/xxx npm start ``` ### OpenTelemetry Distributed tracing: ```bash OTEL_ENABLED=true \ OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \ npm start ``` Use tracing utilities: ```typescript import { withSpan, createApiSpan } from './shared/tracing.js'; const result = await withSpan('my-operation', async (span) => { span.setAttribute('custom.attr', 'value'); return doWork(); }); ``` ## Development ```bash # Type check npm run check # Lint npm run lint npm run lint:fix # Format npm run format # Test npm test npm run test:coverage # Validate (all checks) npm run validate ``` ## MCP 2025-11-25 Spec Compliance | Feature | Status | |---------|--------| | Tools | ✅ Implemented | | Resources | 📝 Scaffolded | | Prompts | 📝 Scaffolded | | Streamable HTTP | ✅ Implemented | | .well-known/mcp | ✅ Implemented | | OAuth 2.1 Foundations | ✅ Scaffolded | | Tasks | ❌ Not yet | | Elicitation | ❌ Not yet | ## OAuth 2.1 Implementation The template includes foundations for OAuth 2.1 per the MCP spec: 1. **Protected Resource Metadata** (RFC 9728) at `/.well-known/oauth-protected-resource` 2. **Bearer token middleware** structure (implement JWT validation) 3. **WWW-Authenticate** headers with resource_metadata reference 4. **Scope checking** structure for tool authorization To complete OAuth integration: 1. Choose an authorization server (Auth0, Logto, etc.) 2. Implement JWT validation in `bearerAuthMiddleware` 3. Add JWKS fetching and caching 4. Configure scopes per tool See [MCP Authorization Spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) for details. ## License MIT ## References - [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25) - [MCP SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)