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.2 学习 MCP 协议文档

获取最新的 MCP 协议文档：

使用 WebFetch 加载：https://modelcontextprotocol.io/llms-full.txt

此综合文档包含完整的 MCP 规范和指南。

1.3 学习框架文档

加载并阅读以下参考文件：

• 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.4 全面学习 API 文档

要集成某项服务，请阅读其所有可用的 API 文档：

• 官方 API 参考文档
• 身份验证和授权要求
• 速率限制和分页模式
• 错误响应和状态码
• 可用端点及其参数
• 数据模型和架构

如需收集全面的信息，请按需使用网页搜索和 WebFetch 工具。

1.5 制定全面的实施计划

根据研究结果，制定一份详细计划，其中包括：

工具选择：

• 列出最有价值、值得实现的端点/操作
• 优先实现能满足最常见和最重要用例的工具
• 考虑哪些工具可以协同工作，以支持复杂工作流

共享实用程序和辅助函数：

• 识别常见的 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 架构以验证输入

2.2 优先实现核心基础设施

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

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

2.3 按计划系统地实现工具

对于计划中的每个工具：

定义输入架构：

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

编写完整的文档字符串/说明：

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

实现工具逻辑：

• 使用共享实用程序，避免代码重复
• 所有 I/O 操作均遵循 async/await 模式
• 实现适当的错误处理
• 支持多种响应格式（JSON 和 Markdown）
• 遵循分页参数
• 检查字符数限制，并酌情截断

添加工具注释：

• readOnlyHint：true（用于只读操作）
• destructiveHint：false（用于非破坏性操作）
• idempotentHint：true（如果重复调用的效果相同）
• openWorldHint：true（如果与外部系统交互）

2.4 遵循语言特定的最佳实践

对于 Python：加载 Python Implementation Guide，并确保以下各项：

• 使用 MCP Python SDK 正确注册工具
• 使用带有 model_config 的 Pydantic v2 模型
• 全面使用类型提示
• 所有 I/O 操作均使用 Async/await
• 正确组织导入语句
• 使用模块级常量（CHARACTER_LIMIT、API_BASE_URL）

对于 Node/TypeScript：加载 TypeScript Implementation Guide，并确保以下各项：

• 正确使用 server.registerTool
• 使用带有 .strict() 的 Zod 模式
• 启用 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 Guide 中的“质量检查清单”
• Node/TypeScript：参见 TypeScript Guide 中的“质量检查清单”

---

第 4 阶段：创建评估

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

加载 Evaluation Guide，了解完整的评估指南。

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 格式规范
  • 问题和答案示例
  • 使用提供的脚本运行评估