Initial commit

skills/building-mcp/SKILL.md

@@ -0,0 +1,138 @@
+---
+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)