mcp-server-template

Standard template for building HTTP-based MCP (Model Context Protocol) servers.

• Express + StreamableHTTPServerTransport — HTTP-based MCP transport with session management
• OAuth provider — File-backed PKCE OAuth with pre-shared token support
• API client base class — Extensible HTTP client with error handling
• Input validation helpers — Type-safe argument validation for all tools
• `createTool()` factory — Declarative tool definitions mapping HTTP verbs to MCP tools
• Docker + Cloudflare tunnel — Production deployment with multi-stage build
• Test harness — Local/remote integration testing with Node built-in test runner

1. Click "Use this template" on GitHub
2. Replace {{SERVICE_NAME}}, {{SERVICE_DISPLAY_NAME}}, {{SERVICE_UPPER}} placeholders
3. npm install
4. Implement your tools in src/index.ts → buildToolConfigs()
5. npm run build && npm start

See docs/SETUP-GUIDE.md for detailed instructions.

• Setup Guide — Step-by-step new server setup
• Analysis — Audit of all existing servers and consistency findings

Client → HTTP POST /mcp → Bearer Auth → StreamableHTTPServerTransport → MCP Server
                                                                           ↓
                                                                    Tool Handler
                                                                           ↓
                                                                    ApiClient → External API

npm run build          # Compile TypeScript
npm run build:check    # Type check only (no emit)
npm test               # Build + run tests
npm run test:watch     # Watch mode

npm run docker:build   # Full build with tests + Docker image
npm run docker:build:fast  # Skip tests
docker compos