mcp-builder

# MCP Builder > Principles for building MCP servers. --- ## 1. MCP Overview ### What is MCP? Model Context Protocol - standard for connecting AI systems with external tools and data sources. ### Core Concepts | Concept | Purpose | |---------|---------| | **Tools** | Functions AI can call | | **Resources** | Data AI can read | | **Prompts** | Pre-defined prompt templates | --- ## 2. Server Architecture ### Project Structure ``` my-mcp-server/ ├── src/ │ └── index.ts # Main entry ├── package.json └── tsconfig.json ``` ### Transport Types | Type | Use | |------|-----| | **Stdio** | Local, CLI-based | | **SSE** | Web-based, streaming | | **WebSocket** | Real-time, bidirectional | --- ## 3. Tool Design Principles ### Good Tool Design | Principle | Description | |-----------|-------------| | Clear name | Action-oriented (get_weather, create_user) | | Single purpose | One thing well | | Validated input | Schema with types and descriptions | | Structured output | Predictable response format | ### Input Schema Design | Field | Required? | |-------|-----------| | Type | Yes - object | | Properties | Define each param | | Required | List mandatory params | | Description | Human-readable | --- ## 4. Resource Patterns ### Resource Types | Type | Use | |------|-----| | Static | Fixed data (config, docs) | | Dynamic | Generated on request | | Template | URI with parameters | ### URI Patterns | Pattern | Example | |---------|---------| | Fixed | `docs://readme` | | Parameterized | `users://{userId}` | | Collection | `files://project/*` | --- ## 5. Error Handling ### Error Types | Situation | Response | |-----------|----------| | Invalid params | Validation error message | | Not found | Clear "not found" | | Server error | Generic error, log details | ### Best Practices - Return structured errors - Don't expose internal details - Log for debugging - Provide actionable messages --- ## 6. Multimodal Handling ### Supported Types | Type | Encoding | |------|----------| | Text | Plain text | | Images | Base64 + MIME type | | Files | Base64 + MIME type | --- ## 7. Security Principles ### Input Validation - Validate all tool inputs - Sanitize user-provided data - Limit resource access ### API Keys - Use environment variables - Don't log secrets - Validate permissions --- ## 8. Configuration ### Claude Desktop Config | Field | Purpose | |-------|---------| | command | Executable to run | | args | Command arguments | | env | Environment variables | --- ## 9. Testing ### Test Categories | Type | Focus | |------|-------| | Unit | Tool logic | | Integration | Full server | | Contract | Schema validation | --- ## 10. Best Practices Checklist - [ ] Clear, action-oriented tool names - [ ] Complete input schemas with descriptions - [ ] Structured JSON output - [ ] Error handling for all cases - [ ] Input validation - [ ] Environment-based configuration - [ ] Logging for debugging --- > **Remember:** MCP tools should be simple, focused, and well-documented. The AI relies on descriptions to use them correctly.