sasanniroo MCP 服务器开发指南
概览
当你要创建高质量的 MCP 服务器，使 LLM 能够高效地与外部服务交互时，请使用本技能。MCP 服务器通过提供工具，让 LLM 可以访问外部服务或 API。衡量 MCP 服务器质量的标准，是它让 LLM 借助这些工具完成真实世界任务的能力。
开发流程
🚀 总体工作流
打造高质量 MCP 服务器通常分为四个阶段：
第一阶段：深入调研与规划
1.1 理解以智能体为中心的设计原则
在开始实现之前，先了解如何为 AI 智能体设计工具，熟悉以下原则：
围绕工作流设计，而非简单包裹 API 端点：
- 不要仅仅把现有 API 端点原样暴露——应打造高价值的工作流工具
- 将相关操作整合（例如
schedule_event同时检查空闲并创建事件） - 专注于能够完成完整任务的工具，而非单一 API 调用
- 思考智能体在真实场景中需要完成哪些工作流
优化有限的上下文窗口：
- 智能体的上下文窗口有限——让每个 token 都物尽其用
- 返回信息聚焦高价值信号，而非大段冗余数据
- 提供“精简模式”与“详细模式”等可选响应格式
- 默认为人类可读的标识，而非技术代码（优先使用名称而非 ID）
- 将智能体的上下文预算视为稀缺资源
设计可行动的错误信息：
- 错误信息应引导智能体朝正确的用法前进
- 给出明确的下一步建议：“可尝试使用 filter='active_only' 来减少结果”
- 让错误提示具有教学意义，而不仅仅是诊断
- 帮助智能体通过清晰的反馈学习正确的工具用法
遵循自然的任务拆分：
- 工具命名应贴近人们的任务思维
- 使用一致的前缀把相关工具归类，方便发现与记忆
- 围绕自然工作流设计工具，而不是照搬 API 结构
坚持基于评估驱动的开发：
- 早期就创建真实评估场景
- 让智能体的反馈驱动工具改进
- 快速原型，基于智能体表现迭代
1.3 学习 MCP 协议文档
获取最新 MCP 协议文档：
使用 WebFetch 访问：https://modelcontextprotocol.io/llms-full.txt
该文档包含完整的 MCP 规范与指南，务必通读。
1.4 熟悉框架文档
加载并阅读以下参考资料：
- MCP 最佳实践：📋 查看最佳实践 —— 所有 MCP 服务器的核心准则
若使用 Python 实现，还需阅读：
- Python SDK 文档：使用 WebFetch 加载
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - 🐍 Python 实现指南 —— Python 专用最佳实践与示例
若使用 Node/TypeScript 实现，还需阅读：
- TypeScript SDK 文档：使用 WebFetch 加载
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md - ⚡ TypeScript 实现指南 —— Node/TypeScript 最佳实践与示例
1.5 彻底研读目标 API 文档
要整合某个服务，需全面阅读所有可用 API 资料：
- 官方 API 参考文档
- 认证与授权要求
- 速率限制与分页策略
- 错误响应与状态码
- 可用端点及其参数
- 数据模型与架构
必要时可使用网页搜索与 WebFetch 工具，获取完整信息。
1.6 制定详尽的实现方案
基于调研结果，编写包含以下内容的详细计划：
工具选择：
- 列出最具价值的端点 / 操作
- 优先实现覆盖常见且重要用例的工具
- 考虑工具之间如何协同完成复杂工作流
通用工具与辅助函数：
- 识别常见 API 请求模式
- 规划分页辅助函数
- 设计过滤与格式化工具
- 制定错误处理策略
输入 / 输出设计：
- 定义输入校验模型（Python 用 Pydantic，TypeScript 用 Zod）
- 设计统一的响应格式（例如 JSON 或 Markdown），并支持可配置的详情级别（如 Detailed/Concise）
- 规划大规模使用场景（成千上万用户 / 资源）
- 实施字符限制与截断策略（如 25,000 tokens）
错误处理策略：
- 考虑优雅的失败模式
- 设计清晰、可操作、适合 LLM 理解的自然语言错误信息，提示后续行动
- 处理速率限制与超时场景
- 覆盖认证与授权错误
第二阶段：实现
在完成全面规划后，按照语言特定的最佳实践开始实现。
2.1 搭建项目结构
Python：
- 可将代码放在单个
.py文件，或按复杂度拆分模块（见 🐍 Python 指南） - 使用 MCP Python SDK 注册工具
- 使用 Pydantic 模型进行输入校验
Node/TypeScript：
- 建立规范的项目结构（见 ⚡ TypeScript 指南）
- 设置
package.json与tsconfig.json - 使用 MCP TypeScript SDK
- 使用 Zod 定义严格的输入校验
2.2 先实现核心基础设施
开始编码前，先编写共享工具：
- API 请求辅助函数
- 错误处理工具
- 响应格式化函数（JSON 与 Markdown）
- 分页辅助工具
- 认证 / Token 管理逻辑
2.3 系统性实现工具
针对计划中的每个工具：
定义输入模式：
- 使用 Pydantic（Python）或 Zod（TypeScript）进行验证
- 添加必要的约束（最小/最大长度、正则、数值范围等）
- 提供清晰、具体的字段说明
- 在字段描述中加入多样化示例
撰写完整的文档注释 / 描述：
- 一句话概述工具功能
- 详述用途与行为
- 明确各参数类型并附示例
- 描述完整的返回结构
- 提供使用示例（何时使用、何时不适用）
- 记录错误处理方式以及如何继续操作
实现工具逻辑：
- 复用共享工具，避免重复代码
- 所有 I/O 操作遵循 async/await 模式
- 实现完善的错误处理
- 支持多种响应格式（JSON 与 Markdown）
- 遵循分页参数
- 检查字符限制并在必要时截断
添加工具注解：
readOnlyHint: true（读操作）destructiveHint: false（非破坏性操作）idempotentHint: true（重复调用结果一致）openWorldHint: true（与外部系统交互时）
2.4 遵循语言特定的最佳实践
此时，加载相应的语言指南：
Python：阅读 🐍 Python 实现指南，确保以下要点：
- 正确使用 MCP Python SDK 注册工具
- 使用带
model_config的 Pydantic v2 模型 - 全面使用类型注解
- 所有 I/O 采用 async/await
- 合理组织导入
- 在模块层定义常量（如 CHARACTER_LIMIT、API_BASE_URL）
Node/TypeScript：阅读 ⚡ TypeScript 实现指南，确保以下要点：
- 正确调用
server.registerTool - Zod 模式使用
.strict() - 启用 TypeScript 严格模式
- 禁用
any，使用精确类型 - 返回值显式声明
Promise<T> - 配置构建流程（如
npm run build）
第三阶段：审查与完善
完成初始实现后：
3.1 代码质量检查
逐项自检以确保质量：
- DRY 原则：避免工具之间的重复代码
- 可组合性：抽取共享逻辑作为函数
- 一致性：类似操作返回一致格式
- 错误处理：所有外部调用都有异常处理
- 类型安全：完善的类型覆盖（Python 类型注解、TypeScript 类型）
- 文档完整：每个工具具备完整注释 / 描述
3.2 测试与构建
重要提示： MCP 服务器是长驻进程，通过 stdio/stdin 或 SSE/HTTP 等方式等待请求。若直接在主进程运行（如 python server.py 或 node dist/index.js），进程会一直阻塞。
安全的测试方式：
- 使用评估脚手架（见第四阶段）——推荐方案
- 在 tmux 中后台运行服务器，避免占用主进程
- 测试时使用超时命令：
timeout 5s python server.py
Python：
- 检查语法：
python -m py_compile your_server.py - 确认导入配置无误
- 若需手动测试：在 tmux 中运行服务器，再在主进程中运行评估脚手架
- 或直接使用评估脚手架（可自行管理 stdio 传输的服务器）
Node/TypeScript：
- 执行
npm run build，确保无报错 - 确认生成
dist/index.js - 手动测试时，在 tmux 中运行服务器，再在主进程执行评估脚手架
- 或直接使用评估脚手架（自动管理 stdio 传输）
3.3 使用质量检查清单
为确保实现质量，请加载语言特定指南中的质量清单：
- Python：参阅 🐍 Python 指南 中的 “Quality Checklist”
- Node/TypeScript：参阅 ⚡ TypeScript 指南 中的 “Quality Checklist”
第四阶段：创建评估
在完成 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>
<!-- 继续添加 qa_pair ... -->
</evaluation>
参考资源
📚 文档库
根据需要加载以下资源：
核心 MCP 文档（优先阅读）
- MCP 协议：通过
https://modelcontextprotocol.io/llms-full.txt获取 —— 完整规格说明 - 📋 MCP 最佳实践 —— 包含：
- 服务器与工具命名规范
- 响应格式指南（JSON vs Markdown）
- 分页最佳实践
- 字符限制与截断策略
- 工具开发指南
- 安全与错误处理标准
SDK 文档（第一/二阶段加载）
- Python SDK：
https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md - TypeScript SDK：
https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
语言特定实现指南（第二阶段参考）
🐍 Python 实现指南，包含：
- 服务器初始化模式
- Pydantic 模型示例
- 使用
@mcp.tool注册工具 - 完整示例代码
- 质量检查清单
-
- 项目结构建议
- Zod 模式示例
- 使用
server.registerTool注册工具 - 完整示例代码
- 质量检查清单
评估指南（第四阶段参考）
- ✅ 评估指南，涵盖：
- 评估问题设计原则
- 答案验证策略
- XML 输出规范
- 示例问答
- 使用脚本运行评估的方法