139 lines
5.6 KiB
Markdown
139 lines
5.6 KiB
Markdown
---
|
|
name: Building MCP
|
|
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 Guide
|
|
|
|
Create high-quality MCP servers that enable LLMs to effectively interact with external services. Quality is measured by how well LLMs accomplish real-world tasks using the provided tools.
|
|
|
|
---
|
|
|
|
# Process
|
|
|
|
## Phase 1: Research and Planning
|
|
|
|
### 1.1 Agent-Centric Design Principles
|
|
|
|
**Build for Workflows:** Create high-impact workflow tools, not API wrappers. Consolidate operations (e.g., `schedule_event` checks availability AND creates event).
|
|
|
|
**Optimize for Context:** Return high-signal info, not dumps. Offer "concise"/"detailed" options. Use human-readable IDs.
|
|
|
|
**Actionable Errors:** Guide agents to correct usage: "Try filter='active_only'". Make errors educational.
|
|
|
|
**Natural Subdivisions:** Tool names reflect human thinking. Group with consistent prefixes. Design around workflows.
|
|
|
|
**Evaluation-Driven:** Create realistic scenarios early. Iterate based on agent performance.
|
|
|
|
### 1.2 Study Documentation
|
|
|
|
**Load these in order:**
|
|
1. MCP Protocol: `https://modelcontextprotocol.io/llms-full.txt`
|
|
2. [📋 MCP Best Practices](./reference/mcp_best_practices.md)
|
|
3. **For Python:** `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` + [🐍 Python Guide](./reference/python_mcp_server.md)
|
|
4. **For Node/TypeScript:** `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` + [⚡ TypeScript Guide](./reference/node_mcp_server.md)
|
|
|
|
### 1.3 Study API Documentation
|
|
|
|
Read ALL: API reference, auth, rate limits, pagination, errors, endpoints, parameters, data models. Use web search and WebFetch.
|
|
|
|
### 1.4 Create Implementation Plan
|
|
|
|
**Tool Selection:** List valuable endpoints. Prioritize common use cases. Consider tool combinations.
|
|
|
|
**Shared Utilities:** API request patterns, pagination/filtering/formatting helpers, error handling.
|
|
|
|
**Input/Output:** Validation (Pydantic/Zod), consistent formats (JSON/Markdown), detail levels (Detailed/Concise), scale planning, character limits (25k tokens).
|
|
|
|
**Error Handling:** Graceful failures, actionable LLM-friendly messages, rate limits, timeouts, auth errors.
|
|
|
|
---
|
|
|
|
## Phase 2: Implementation
|
|
|
|
### 2.1 Set Up Project
|
|
|
|
**Python:** Single `.py` or modules. MCP SDK. Pydantic validation.
|
|
|
|
**Node/TypeScript:** Project structure (`package.json`, `tsconfig.json`). MCP SDK. Zod validation.
|
|
|
|
### 2.2 Core Infrastructure First
|
|
|
|
Create shared utilities: API helpers, error handling, response formatting (JSON/Markdown), pagination, auth/tokens.
|
|
|
|
### 2.3 Implement Tools
|
|
|
|
**Input Schema:** Pydantic/Zod with constraints (min/max, regex, ranges). Clear descriptions with examples.
|
|
|
|
**Descriptions:** Summary, purpose, parameter types with examples, return schema, usage examples, error handling with next steps.
|
|
|
|
**Logic:** Use shared utilities (DRY). Async/await for I/O. Error handling. Multiple formats (JSON/Markdown). Respect pagination. Check limits, truncate.
|
|
|
|
**Annotations:** `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`.
|
|
|
|
### 2.4 Language-Specific Best Practices
|
|
|
|
**Python ([🐍 Guide](./reference/python_mcp_server.md)):** MCP SDK, Pydantic v2 with `model_config`, type hints, async/await, organized imports, constants.
|
|
|
|
**Node/TypeScript ([⚡ Guide](./reference/node_mcp_server.md)):** `server.registerTool`, Zod `.strict()`, strict mode, no `any`, explicit `Promise<T>`, build config.
|
|
|
|
---
|
|
|
|
## Phase 3: Review and Refine
|
|
|
|
### 3.1 Code Quality
|
|
|
|
Check: DRY (no duplication), composability (shared logic), consistency (similar formats), error handling (all calls), type safety (full coverage), documentation (comprehensive).
|
|
|
|
### 3.2 Test and Build
|
|
|
|
**Important:** MCP servers are long-running (stdio/http). Direct runs hang indefinitely.
|
|
|
|
**Safe testing:** Evaluation harness (recommended), tmux, or timeout (`timeout 5s python server.py`).
|
|
|
|
**Python:** `python -m py_compile your_server.py`. Test in tmux or via harness.
|
|
|
|
**Node/TypeScript:** `npm run build`. Verify `dist/index.js`. Test in tmux or via harness.
|
|
|
|
### 3.3 Quality Checklist
|
|
|
|
See [🐍 Python Guide](./reference/python_mcp_server.md) or [⚡ TypeScript Guide](./reference/node_mcp_server.md).
|
|
|
|
---
|
|
|
|
## Phase 4: Create Evaluations
|
|
|
|
**Load [✅ Evaluation Guide](./reference/evaluation.md) for complete guidelines.**
|
|
|
|
### 4.1 Create 10 Questions
|
|
|
|
Process: Tool inspection → content exploration (READ-ONLY) → question generation → answer verification.
|
|
|
|
### 4.2 Requirements
|
|
|
|
Each question: Independent, read-only, complex (multiple tool calls), realistic, verifiable (single answer), stable.
|
|
|
|
### 4.3 Format
|
|
|
|
```xml
|
|
<evaluation>
|
|
<qa_pair>
|
|
<question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
|
|
<answer>3</answer>
|
|
</qa_pair>
|
|
</evaluation>
|
|
```
|
|
|
|
---
|
|
|
|
# Reference Files
|
|
|
|
**Core:** MCP Protocol (`https://modelcontextprotocol.io/llms-full.txt`), [📋 Best Practices](./reference/mcp_best_practices.md)
|
|
|
|
**SDK:** Python (`https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`), TypeScript (`https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`)
|
|
|
|
**Implementation:** [🐍 Python](./reference/python_mcp_server.md), [⚡ TypeScript](./reference/node_mcp_server.md)
|
|
|
|
**Evaluation:** [✅ Guide](./reference/evaluation.md)
|