- name
- mcp-builder
- description
- Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
- license
- Complete terms in LICENSE.txt
MCP Server Development
Build MCP servers that enable LLMs to accomplish real-world tasks through well-designed tools.
4-Phase Process
Research → Implement → Review → Evaluate
Load resources on-demand (progressive disclosure):
- Protocol:
https://modelcontextprotocol.io/llms-full.txt - Python SDK:
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - TypeScript SDK:
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
Core Design Principles
Workflows over endpoints: Consolidate operations (e.g., schedule_event checks availability + creates) Optimize context: Return high-signal info, provide concise/detailed formats, use readable IDs Actionable errors: Guide to correct usage ("Try filter='active_only'"), suggest next steps Natural task flow: Name tools how humans think, group with consistent prefixes
Phase 1: Research & Planning
1.1 Core Docs
- Load protocol:
https://modelcontextprotocol.io/llms-full.txt - Read Best Practices
1.2 Framework (choose one)
- Python: Fetch SDK + read Python Guide
- TypeScript: Fetch SDK + read TypeScript Guide
1.3 API Research Study exhaustively: auth, rate limits, pagination, endpoints, errors, schemas
1.4 Plan
- Tool selection (most valuable endpoints)
- Shared utilities (requests, pagination, formatting, errors)
- I/O design (validation schemas, response formats, 25k char limits)
- Error strategy (graceful failures, actionable messages)
Phase 2: Implementation
2.1 Structure Python: single .py or modules | TypeScript: package.json + tsconfig.json
2.2 Infrastructure First Build shared utilities: API helpers, error handling, formatting, pagination, auth See: examples/basic-server.py or .ts
2.3 Tools (for each):
- Schema: Pydantic/Zod with constraints, clear descriptions
- Docs: Summary, purpose, params+examples, returns, usage, errors
- Code: Use utilities, async/await, multiple formats, respect limits
- Annotations:
readOnlyHint,destructiveHint,idempotentHint,openWorldHint
See: examples/tool-with-context.py, error-handling.py
2.4 Best Practices Python: @mcp.tool(), Pydantic v2, type hints, async/await, constants TypeScript: registerTool(), Zod .strict(), strict mode, no any, Promise<T>
Phase 3: Review & Refine
3.1 Quality: Check DRY, composability, consistency, error handling, types, docs
3.2 Test: MCP servers are long-running. See testing.md Quick check: python -m py_compile server.py or npm run build
3.3 Checklist: Load from Python or TypeScript guide
Phase 4: Evaluations
Test LLM effectiveness with your server.
Process: Inspect tools → Explore data → Generate 10 questions → Verify answers
Requirements: Independent, read-only, complex, realistic, verifiable, stable
Format:
<evaluation>
<qa_pair>
<question>Complex question...</question>
<answer>Verifiable answer</answer>
</qa_pair>
</evaluation>Complete guide: evaluation.md
Reference Library
| Resource | Load | Purpose |
|---|---|---|
| Best Practices | Phase 1 | Universal guidelines |
| Python Guide | Phase 1/2 | Python patterns |
| TypeScript Guide | Phase 1/2 | TypeScript patterns |
| Testing | Phase 3 | Safe testing |
| Evaluation | Phase 4 | Creating evals |
Examples
| File | Purpose |
|---|---|
| basic-server.py | Python structure |
| basic-server.ts | TypeScript structure |
| tool-with-context.py | Workflows |
| error-handling.py | Errors |
Success Criteria
- Clear tool boundaries (single purpose)
- Efficient context (concise defaults)
- Educational errors (guide usage)
- Workflow optimization (consolidate steps)
- Production ready (errors, rate limits, logging)
- Agent effective (90%+ eval success)