mcp-builder

MCP 服务开发指南

流程

契约

输入：

• 请求的集成、目标仓库、API 文档和获批的服务范围

输出：

• MCP 服务实现、工具契约和范围内的验证证据

创建／修改：

• 实现所请求服务所需的源代码、测试和评估样例

外部副作用：

• 阅读文档；仅在获得授权时调用服务提供方和运行付费评估

需要确认：

• 在执行需要凭据的服务写入、运行付费评估、发布内容，或配置请求范围之外的 Agent 之前
• 加载技能不会授予额外权限。现有的明确授权仅适用于相同目标和操作；请保留仅报告限制。

委派给：

• 无

高层工作流

分四个阶段构建 MCP 服务：

阶段 1：深入研究与规划

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

实现之前，围绕 Agent 工作流设计工具：

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

• 默认不要逐一映射每个 API 端点。如果一项用户任务需要调用多个 API，应将这些端点整合为工作流工具。
• 整合相关操作（例如，schedule_event 同时检查可用性并创建事件）
• 列出主要用户工作流，并将每个工具映射到一个工作流。

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

• 默认仅返回完成任务所需的字段。
• 返回高价值信息，而非详尽的数据倾倒。
• 提供“简洁”和“详细”响应格式选项。
• 默认优先使用人类可读的标识符，而非技术代码（名称优于 ID）。
• 对较大的响应添加分页、字段选择或截断功能。

设计可执行的错误消息：

• 错误消息应包含失败的字段或操作、原因以及下一步有效操作。
• 提供具体的后续步骤建议：“尝试使用 filter='active_only' 来减少结果”
• 切勿直接返回原始服务提供方错误，而不作工具层面的说明。

遵循自然的任务划分：

• 工具名称应体现人们对任务的自然理解。
• 使用一致的前缀对相关工具分组，便于发现。
• 围绕自然工作流设计工具，而不只是围绕 API 结构。

采用评估驱动开发：

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

1.2 学习 MCP 协议文档

获取 MCP 协议文档：

获取：https://modelcontextprotocol.io/llms-full.txt

此文档包含完整的 MCP 规范。注意：随着规范演进，URL 可能会更改；如果获取失败，请搜索当前的 MCP 文档 URL。

1.3 学习框架文档

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

• MCP 最佳实践：📋 查看最佳实践 - 所有 MCP 服务的核心指南

对于 Python 实现，还需加载：

• Python SDK 文档：获取 https://py.sdk.modelcontextprotocol.io/
• 🐍 Python 实现指南 - Python 专属最佳实践与示例

对于 Node/TypeScript 实现，还需加载：

• TypeScript SDK 文档：获取 https://ts.sdk.modelcontextprotocol.io/
• ⚡ TypeScript 实现指南 - Node/TypeScript 专属最佳实践与示例

1.4 学习 API 文档

要集成某项服务，请阅读所选工作流对应的 API 文档。 将端点和参数的覆盖范围限定在这些工作流，但要完整阅读跨领域注意事项（身份验证、速率限制、错误处理、数据模型）——这些内容适用于你公开的所有工具：

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

仅在存在阻碍所选工作流的缺口时，才搜索或获取文档。

1.5 制定实施计划

计划包含以下部分：

工具选择：

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

共享实用程序和辅助工具：

• 找出常见的 API 请求模式
• 规划分页辅助工具
• 设计筛选和格式化实用程序
• 规划错误处理策略

输入/输出设计：

• 定义输入验证模型（Python 使用 Pydantic，TypeScript 使用 Zod）
• 设计一致的响应格式（例如 JSON 或 Markdown），以及可配置的详细程度（例如详细或简洁）
• 规划大规模使用场景（数千名用户/资源）
• 实现字符数限制和截断策略（例如 25,000 个 token）

错误处理策略：

• 规划优雅的失败方式
• 为每种错误格式定义：错误代码、人类可读的原因、是否可重试，以及下一个有效操作。
• 考虑速率限制和超时场景
• 处理身份验证和授权错误

---

第二阶段：实施

制定计划后，先实现共享基础设施，再实现各个工具。

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 实现指南 或 ⚡ TypeScript 实现指南——并遵循其中的模式：正确注册 SDK 工具（@mcp.tool / server.registerTool）、严格验证输入（Pydantic v2 model_config / Zod .strict()）、完整覆盖类型且不使用 any、所有 I/O 操作均使用 async/await、使用模块级常量存放共享值（例如 CHARACTER_LIMIT、API_BASE_URL），以及——对于 TypeScript——确保 bun run build 正常运行。

---

第 3 阶段：审查和优化

完成初步实现后：

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）；或者让评估框架（第 4 阶段）直接管理 stdio 传输的服务子进程。

• Python： 使用 python -m py_compile your_server.py 验证语法，并检查导入项。
• Node/TypeScript： 运行 bun run build，确认无错误地完成，并验证已创建 dist/index.js。

3.3 使用质量检查清单

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

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

---

第 4 阶段：创建评估

实现 MCP 服务后，创建评估，以测试 Agent 能否借助这些工具回答符合实际情况的问题。

加载✅ 评估指南，获取完整的评估指南。

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 服务会通过 stdio/stdin 阻塞等待请求，且不会自动退出。切勿在主进程中运行 python server.py 或 node dist/index.js。请使用 tmux 在后台运行服务，或使用由评估框架管理服务子进程。
• 实时 URL 引用可能会失效。 MCP 协议文档 URL（modelcontextprotocol.io/llms-full.txt）和 GitHub SDK README URL 可能会随版本变更。如果获取失败，请搜索当前 URL，而不要假定技能路径正确。
• 每次更改源代码后都必须重新构建 TypeScript。 MCP 运行时加载的产物是 dist/index.js。编辑 .ts 文件后如果未运行 bun run build，运行时仍会运行旧版本。
• 工具注解只是提示，并非强制契约。 readOnlyHint: true 不会阻止工具写入数据，它只是向大模型表明意图。请在工具实现中自行强制执行安全措施。

---

参考文件

仅加载实现语言和阶段所需的资源。

文件	加载阶段	涵盖内容
references/mcp_best_practices.md	阶段 1.3（首先加载）	命名约定、响应格式（JSON 或 Markdown）、分页、字符数限制和截断、安全与错误处理标准
references/python_mcp_server.md	阶段 2（Python）	服务初始化、Pydantic 模型、@mcp.tool 注册、可运行示例、质量检查清单
references/node_mcp_server.md	阶段 2（TypeScript）	项目结构、Zod 架构、server.registerTool、可运行示例、质量检查清单
references/evaluation.md	阶段 4	问题创建与答案验证指南、XML 格式、问答示例、运行评估

还可按需获取实时协议和 SDK 文档：MCP 协议规范（https://modelcontextprotocol.io/llms-full.txt）、Python SDK（https://py.sdk.modelcontextprotocol.io/）、TypeScript SDK（https://ts.sdk.modelcontextprotocol.io/）。