MCP Boilerplate

# MCP Boilerplate Research Documentation This directory contains comprehensive research documentation for building a minimal MCP (Model Context Protocol) boilerplate template. The research covers all necessary components for creating a simple, production-ready MCP server with a single addition tool. ## 📁 Directory Structure ``` docs/research/ ├── README.md # This overview document ├── mcp/ # MCP technology research │ ├── fastmcp/ # FastMCP framework documentation │ ├── mcp-sdk/ # Official MCP SDK documentation │ ├── zod-validation/ # Zod validation patterns │ └── error-handling/ # McpError handling patterns └── examples/ # GitHub repository analysis ├── INDEX.md # Repository navigation ├── ANALYSIS_SUMMARY.md # Comprehensive analysis └── [repo-folders]/ # Individual repository docs ``` ## 🔍 Research Summary ### Core Technologies Researched #### 1. **FastMCP Framework** (`docs/research/mcp/fastmcp/`) - **Version**: 2.0.1 (latest) - **Language**: Python (primary), TypeScript (community) - **Key Features**: Decorator-based API, high-level abstractions, built-in validation - **Transport**: STDIO (default), HTTP, SSE support - **Integration**: Full MCP SDK compatibility #### 2. **MCP SDK** (`docs/research/mcp/mcp-sdk/`) - **Version**: @modelcontextprotocol/sdk v1.17.0 (5 days old) - **Protocol**: 2025-06-18 specification - **Key Features**: OAuth 2.0, Elicitation support, Structured tool output - **Architecture**: JSON-RPC 2.0, Tools/Resources/Prompts primitives - **Type Support**: Full TypeScript with Zod integration #### 3. **Zod Validation** (`docs/research/mcp/zod-validation/`) - **Integration**: Seamless with MCP TypeScript SDK - **Features**: Type inference, runtime validation, security patterns - **Security**: XSS/SQL injection prevention, path traversal protection - **Patterns**: Composable schemas, environment-aware validation #### 4. **Error Handling** (`docs/research/mcp/error-handling/`) - **McpError Class**: Standard error structure with codes and context - **Error Codes**: JSON-RPC standards + MCP extensions - **Best Practices**: Protocol vs. tool errors, retry patterns - **FastMCP Integration**: Built-in error types, middleware support ### GitHub Repository Analysis (`docs/research/examples/`) Analyzed **9 MCP repositories** with different approaches: **Tech Stack Distribution**: - **TypeScript**: 56% (5 repos) - Type safety focus - **Python**: 44% (4 repos) - FastMCP emphasis **Repository Categories**: - **Learning-Focused**: 33% - Educational examples - **Production-Ready**: 44% - Enterprise patterns - **Template/Boilerplate**: 22% - Ready-to-use starters ## 🎯 Key Insights for Boilerplate Design ### 1. **Minimal Stack Decision** Based on research, the optimal minimal stack is: - **Language**: TypeScript (better type safety, wider adoption) - **Framework**: MCP SDK v1.17.0 (official, stable, feature-complete) - **Validation**: Zod schemas (type inference, security) - **Transport**: STDIO (simplest for local development) - **Error Handling**: McpError with structured responses ### 2. **Architecture Pattern** Most successful boilerplates follow this pattern: ```typescript src/ ├── index.ts # Server entry point ├── tools/ # Tool definitions │ └── calculator.ts # Addition tool ├── schemas/ # Zod validation schemas └── types/ # TypeScript type definitions ``` ### 3. **Essential Features** Minimum viable features identified: - Single addition tool (proof of concept) - Zod parameter validation - Proper error handling with McpError - TypeScript type safety - STDIO transport - Development tooling (build, lint, test) ### 4. **Best Practices Integration** Key patterns from analysis: - **Security-first validation** with Zod refinements - **Modular tool registration** for extensibility - **Comprehensive error handling** at all layers - **Type inference** to eliminate duplication - **Environment configuration** for dev/prod ## 📋 Implementation Checklist Based on research findings, the boilerplate should include: ### Core Implementation - [ ] TypeScript project setup with proper tsconfig - [ ] MCP SDK v1.17.0 integration - [ ] STDIO transport configuration - [ ] Single addition tool with Zod validation - [ ] McpError handling patterns - [ ] Type definitions and inference ### Development Experience - [ ] Build scripts (TypeScript compilation) - [ ] Linting (ESLint) and formatting (Prettier) - [ ] Testing framework integration - [ ] Development server with hot reload - [ ] Documentation with usage examples ### Production Readiness - [ ] Error handling and logging - [ ] Input validation and security - [ ] Environment configuration - [ ] Deployment instructions - [ ] Claude Desktop integration guide ## 🚀 Next Steps With this comprehensive research foundation, we can now: 1. **Design the minimal boilerplate structure** 2. **Implement the addition tool with best practices** 3. **Set up development and build tooling** 4. **Create comprehensive documentation** 5. **Test integration with Claude Desktop** ## 📚 Further Reading Each research directory contains detailed documentation with: - Implementation examples - Best practices - Security considerations - Performance optimization - Production deployment patterns --- *Research completed: July 30, 2025* *Technologies: FastMCP 2.0.1, MCP SDK v1.17.0, Zod validation, TypeScript* *Repositories analyzed: 9 GitHub boilerplates*