JoelBonito/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.