mcp-builder

MCP 服务开发指南

概述

使用此技能可创建高质量的 MCP（Model Context Protocol）服务，使大模型能够有效地与外部服务交互。MCP 服务提供工具，让大模型能够访问外部服务和 API。MCP 服务的质量取决于它能否借助所提供的工具，帮助大模型完成现实世界中的任务。

---

流程

🚀 高层工作流

创建高质量的 MCP 服务包含四个主要阶段：

阶段 1：深入研究与规划

1.1 理解以 Agent 为中心的设计原则

开始实现之前，先通过了解以下原则，掌握如何为 AI Agent 设计工具：

围绕工作流构建，而不仅仅是 API 端点：

• 不要只是封装现有的 API 端点，而要构建经过深思熟虑、影响重大的工作流工具
• 整合相关操作（例如，schedule_event 同时检查可用性并创建事件）
• 重点关注能够完成完整任务的工具，而不是单独的 API 调用
• 考虑 Agent 实际需要完成哪些工作流

针对有限的上下文进行优化：

• Agent 的上下文窗口有限，因此每个 token 都至关重要
• 返回高信号信息，而不是详尽的数据转储
• 提供“简洁”和“详细”两种响应格式选项
• 默认使用易于人类理解的标识符，而不是技术代码（名称优于 ID）
• 将 Agent 的上下文预算视为稀缺资源

设计可执行的错误消息：

• 错误消息应引导 Agent 正确使用工具
• 给出具体的后续建议：“尝试使用 filter='active_only' 来减少结果”
• 让错误消息具有指导作用，而不仅仅用于诊断
• 通过清晰的反馈，帮助 Agent 学会正确使用工具

遵循自然的任务划分方式：

• 工具名称应符合人们对任务的思考方式
• 使用一致的前缀对相关工具进行分组，便于发现
• 围绕自然工作流设计工具，而不仅仅是照搬 API 结构

采用评估驱动的开发方式：

• 尽早创建真实的评估场景
• 根据 Agent 的反馈改进工具
• 快速制作原型，并根据 Agent 的实际表现进行迭代

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），以及可配置的详细程度（例如详细或简洁）
• 规划大规模使用场景（数千名用户/资源）
• 实现字符限制和截断策略（例如 25,000 个 token）

错误处理策略：

• 规划优雅的失败模式
• 设计清晰、可操作、便于大模型理解的自然语言错误消息，引导其采取后续操作
• 考虑速率限制和超时情况
• 处理身份验证和授权错误

---

阶段 2：实施

现在你已经制定了全面的计划，请遵循特定语言的最佳实践开始实施。

2.1 设置项目结构

对于 Python：

• 创建单个 .py 文件；如果项目较复杂，则按模块组织（参见 🐍 Python 指南）
• 使用 MCP Python SDK 注册工具
• 定义用于输入验证的 Pydantic 模型

对于 Node/TypeScript：

• 创建恰当的项目结构（参见 ⚡ TypeScript 指南）
• 设置 package.json 和 tsconfig.json
• 使用 MCP TypeScript SDK
• 定义用于输入验证的 Zod schema

2.2 优先实现核心基础设施

开始实施时，请先创建共享实用工具，再实现工具：

• API 请求辅助函数
• 错误处理实用工具
• 响应格式化函数（JSON 和 Markdown）
• 分页辅助函数
• 身份验证/令牌管理

2.3 系统地实现工具

对于计划中的每个工具：

定义输入 schema：

• 使用 Pydantic（Python）或 Zod（TypeScript）进行验证
• 添加适当的约束（最小/最大长度、正则表达式模式、最小/最大值、范围）
• 提供清晰、描述性强的字段说明
• 在字段说明中加入多样化的示例

编写全面的文档字符串/说明：

• 用一句话概述工具的功能
• 详细说明工具的用途和功能
• 明确参数类型并提供示例
• 提供完整的返回类型 schema
• 提供使用示例（何时使用、何时不使用）
• 编写错误处理文档，说明遇到特定错误时应如何继续

实现工具逻辑：

• 使用共享实用工具避免代码重复
• 所有 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
• 使用带 .strict() 的 Zod schema
• 启用 TypeScript 严格模式
• 不使用 any 类型，改用适当的类型
• 显式声明 Promise 返回类型
• 配置构建流程（npm run build）

---

阶段 3：审查与优化

初步实现完成后：

3.1 代码质量审查

为确保质量，请检查代码是否符合以下要求：

• DRY 原则：工具之间没有重复代码
• 可组合性：将共享逻辑提取为函数
• 一致性：相似操作返回相似格式
• 错误处理：所有外部调用都有错误处理
• 类型安全：完整的类型覆盖（Python 类型提示、TypeScript 类型）
• 文档：每个工具都有全面的文档字符串/描述

3.2 测试与构建

重要提示： MCP 服务是长期运行的进程，会通过 stdio/stdin 或 sse/http 等待请求。直接在主进程中运行它们（例如，python server.py 或 node dist/index.js）会导致进程无限期挂起。

安全的服务测试方式：

• 使用评估工具（参见阶段 4），这是推荐方式
• 在 tmux 中运行服务，使其独立于主进程
• 测试时使用超时：timeout 5s python server.py

对于 Python：

• 验证 Python 语法：python -m py_compile your_server.py
• 通过检查文件，确认导入正常
• 手动测试：在 tmux 中运行服务，然后在主进程中使用评估工具进行测试
• 或直接使用评估工具（它会为 stdio 传输管理服务）

对于 Node/TypeScript：

• 运行 npm run build，并确保无错误地完成
• 确认已创建 dist/index.js
• 手动测试：在 tmux 中运行服务，然后在主进程中使用评估工具进行测试
• 或直接使用评估工具（它会为 stdio 传输管理服务）

3.3 使用质量检查清单

要验证实现质量，请从相应的语言指南中加载检查清单：

• Python：参见 🐍 Python 指南中的“质量检查清单”
• Node/TypeScript：参见 ⚡ TypeScript 指南中的“质量检查清单”

---

阶段 4：创建评估

实现 MCP 服务后，请创建全面的评估来测试其有效性。

加载 ✅ 评估指南，了解完整的评估准则。

4.1 了解评估目的

评估用于测试大模型能否有效使用 MCP 服务来回答真实且复杂的问题。

4.2 创建 10 个评估问题

要创建有效的评估，请遵循评估指南中概述的流程：

1. 检查工具：列出可用工具并了解其功能
2. 探索内容：使用只读操作探索可用数据
3. 生成问题：创建 10 个复杂、真实的问题
4. 验证答案：自行解答每个问题以验证答案

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>

</evaluation>

---

参考文件

📚 文档库

在开发过程中按需加载以下资源：

核心 MCP 文档（首先加载）

• MCP 协议：从 https://modelcontextprotocol.io/llms-full.txt 获取——完整的 MCP 规范
• 📋 MCP 最佳实践——通用 MCP 指南，包括：
  • 服务和工具命名约定
  • 响应格式指南（JSON 与 Markdown）
  • 分页最佳实践
  • 字符限制和截断策略
  • 工具开发指南
  • 安全和错误处理标准

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 模式
  • 使用 server.registerTool 注册工具
  • 完整的可运行示例
  • 质量检查清单

评估指南（在阶段 4 加载）

• ✅ 评估指南——完整的评估创建指南，包括：
  • 问题创建指南
  • 答案验证策略
  • XML 格式规范
  • 问题和答案示例
  • 使用提供的脚本运行评估