MCP Server 开发指南
概述
创建 MCP（Model Context Protocol）服务器，使 LLM 能够通过设计良好的工具与外部服务交互。MCP 服务器的质量以它帮助 LLM 完成真实世界任务的程度来衡量。
流程
🚀 高层工作流
创建高质量 MCP 服务器包含四个主要阶段：
阶段 1：深度研究与规划
1.1 理解现代 MCP 设计
API 覆盖与工作流工具： 在全面的 API 端点覆盖与专用工作流工具之间取得平衡。工作流工具对特定任务可能更方便，而全面覆盖则让智能体能够灵活组合操作。不同客户端表现不同——有些客户端受益于组合基础工具的代码执行，另一些则更适合高层工作流。不确定时，优先考虑全面的 API 覆盖。
工具命名与可发现性： 清晰、描述性的工具名称能帮助智能体快速找到正确的工具。使用一致的前缀（例如 github_create_issue、github_list_repos）和面向动作的命名。
上下文管理： 智能体受益于简洁的工具描述以及过滤/分页结果的能力。设计返回聚焦、相关数据的工具。部分客户端支持代码执行，可帮助智能体高效地过滤和处理数据。
可操作的错误消息： 错误消息应通过具体建议和下一步操作引导智能体找到解决方案。
1.2 研读 MCP 协议文档
浏览 MCP 规范：
从 sitemap 开始寻找相关页面：https://modelcontextprotocol.io/sitemap.xml
然后获取带 .md 后缀的特定页面以获取 markdown 格式（例如 https://modelcontextprotocol.io/specification/draft.md）。
需要重点查看的页面：
规范概述与架构
传输机制（streamable HTTP、stdio）
工具、资源与提示定义
1.3 研读框架文档
推荐技术栈：
语言：TypeScript（高质量 SDK 支持，在许多执行环境如 MCPB 中兼容性好。此外 AI 模型擅长生成 TypeScript 代码，得益于其广泛使用、静态类型和良好的 lint 工具）
传输：远程服务器使用 Streamable HTTP，采用无状态 JSON（相比有状态会话和流式响应，更易于扩展和维护）。本地服务器使用 stdio。
加载框架文档：
MCP 最佳实践：📋 查看最佳实践 - 核心指南
TypeScript（推荐）：
TypeScript SDK：使用 WebFetch 加载 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
⚡ TypeScript 指南 - TypeScript 模式与示例
Python：
Python SDK：使用 WebFetch 加载 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
🐍 Python 指南 - Python 模式与示例
1.4 规划你的实现
理解 API： 查看服务的 API 文档，识别关键端点、认证要求和数据模型。按需使用网络搜索和 WebFetch。
工具选择： 优先考虑全面的 API 覆盖。列出要实现的端点，从最常见的操作开始。
阶段 2：实现
2.1 搭建项目结构
参见各语言专用指南进行项目搭建：
⚡ TypeScript 指南 - 项目结构、package.json、tsconfig.json
🐍 Python 指南 - 模块组织、依赖
2.2 实现核心基础设施
创建共享工具：
带认证的 API 客户端
错误处理辅助函数
响应格式化（JSON/Markdown）
分页支持
2.3 实现工具
对于每个工具：
输入 Schema：
使用 Zod（TypeScript）或 Pydantic（Python）
包含约束和清晰描述
在字段描述中添加示例
输出 Schema：
尽可能定义 outputSchema 以处理结构化数据
在工具响应中使用 structuredContent（TypeScript SDK 特性）
帮助客户端理解和处理工具输出
工具描述：
功能的简洁摘要
参数描述
返回类型 schema
实现：
I/O 操作用 async/await
恰当的错误处理并提供可操作的消息
适用时支持分页
使用现代 SDK 时同时返回文本内容和结构化数据
注解：
readOnlyHint: true/false
destructiveHint: true/false
idempotentHint: true/false
openWorldHint: true/false
阶段 3：评审与测试
3.1 代码质量
检查以下方面：
无重复代码（DRY 原则）
一致的错误处理
完整的类型覆盖
清晰的工具描述
3.2 构建与测试
TypeScript：
运行 npm run build 验证编译
使用 MCP Inspector 测试：npx @modelcontextprotocol/inspector
Python：
验证语法：python -m py_compile your_server.py
使用 MCP Inspector 测试
参见各语言专用指南了解详细测试方法和质量检查清单。
阶段 4：创建评测
实现 MCP 服务器后，创建全面的评测来测试其有效性。
加载 ✅ 评测指南以获取完整的评测指引。
4.1 理解评测目的
使用评测来测试 LLM 能否有效使用你的 MCP 服务器回答真实、复杂的问题。
4.2 创建 10 道评测题
要创建有效的评测，请遵循评测指南中概述的流程：
工具检查：列出可用工具并理解其能力
内容探索：使用只读操作探索可用数据
问题生成：创建 10 道复杂、真实的问题
答案验证：自己解答每道题以验证答案
4.3 评测要求
确保每道题：
独立：不依赖其他问题
只读：只需非破坏性操作
复杂：需要多次工具调用和深入探索
真实：基于人们真正关心的真实用例
可验证：有单一、明确的答案，可通过字符串比对验证
稳定：答案不会随时间变化
4.4 输出格式
创建一个具有以下结构的 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> <!-- More qa_pairs... --> </evaluation>
参考文件
📚 文档库
在开发过程中按需加载以下资源：
核心 MCP 文档（优先加载）
MCP 协议：从 https://modelcontextprotocol.io/sitemap.xml 的 sitemap 开始，然后获取带 .md 后缀的特定页面
📋 MCP 最佳实践 - 通用 MCP 指南，包括：
服务器与工具命名约定
响应格式指南（JSON 与 Markdown）
分页最佳实践
传输选择（streamable HTTP 与 stdio）
安全与错误处理标准
SDK 文档（在阶段 1/2 加载）
Python SDK：从 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md 获取
TypeScript SDK：从 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md 获取
语言专用实现指南（在阶段 2 加载）
🐍 Python 实现指南 - 完整的 Python/FastMCP 指南，包括：
服务器初始化模式
Pydantic 模型示例
使用 @mcp.tool 注册工具
完整可运行示例
质量检查清单
⚡ TypeScript 实现指南 - 完整的 TypeScript 指南，包括：
项目结构
Zod schema 模式
使用 server.registerTool 注册工具
完整可运行示例
质量检查清单
评测指南（在阶段 4 加载）
✅ 评测指南 - 完整的评测创建指南，包括：
问题创建准则
答案验证策略
XML 格式规范
示例问题与答案
使用提供的脚本运行评测