名称： mcp-builder
描述： 创建高质量 MCP（模型上下文协议）服务器的指南，使 LLM 能够通过精心设计的工具与外部服务交互。在构建 MCP 服务器以集成外部 API 或服务时使用，无论是 Python（FastMCP）还是 Node/TypeScript（MCP SDK）。
许可证： 完整条款见 LICENSE.txt
本指南旨在帮助您创建高质量的 MCP（模型上下文协议）服务器，使 LLM 能够有效地与外部服务交互。MCP 服务器提供工具，允许 LLM 访问外部服务和 API。MCP 服务器的质量取决于其提供的工具能否帮助 LLM 高效完成实际任务。
创建一个高质量的 MCP 服务器包含四个主要阶段：
在开始实现之前，请先理解如何为 AI 智能体设计工具，并回顾以下原则：
为工作流而设计，而非仅仅包装 API 端点：
- 不要简单包装现有 API 端点，应构建经过深思熟虑、高影响力的工作流工具。
- 整合相关操作（例如，一个 schedule_event 工具同时检查可用性并创建事件）。
- 专注于能够完成完整任务的工具，而非单个 API 调用。
- 考虑智能体实际需要完成哪些工作流。
为有限的上下文进行优化：
- 智能体的上下文窗口有限，应让每个 token 都物尽其用。
- 返回高价值信息，而非详尽的数据转储。
- 提供“简洁”与“详细”的响应格式选项。
- 默认使用人类可读的标识符而非技术代码（例如使用名称而非 ID）。
- 将智能体的上下文预算视为稀缺资源。
设计可操作的错误信息：
- 错误信息应能引导智能体走向正确的使用模式。
- 建议具体的后续步骤：例如“尝试使用 filter='active_only' 来减少结果”。
- 使错误信息具有教育意义，而不仅仅是诊断性的。
- 通过清晰的反馈帮助智能体学习正确的工具使用方法。
遵循自然的任务划分：
- 工具名称应反映人类对任务的思考方式。
- 使用一致的前缀对相关工具进行分组，以提高可发现性。
- 围绕自然的工作流而非 API 结构来设计工具。
采用评估驱动的开发：
- 尽早创建真实的评估场景。
- 让智能体的反馈驱动工具改进。
- 快速原型设计，并根据智能体的实际表现进行迭代。
获取最新的 MCP 协议文档：
使用 WebFetch 工具加载：https://modelcontextprotocol.io/llms-full.txt
这份综合性文档包含了完整的 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 特定的最佳实践和示例。
要集成一项服务，请阅读所有可用的 API 文档：
- 官方 API 参考文档
- 身份验证和授权要求
- 速率限制和分页模式
- 错误响应和状态码
- 可用的端点及其参数
- 数据模型和模式
为收集全面信息，请根据需要使用网络搜索和 WebFetch 工具。
基于您的研究，创建一个详细的计划，包括：
工具选择：
- 列出要实施的最有价值的端点/操作。
- 优先考虑能支持最常见和最重要用例的工具。
- 考虑哪些工具可以协同工作以实现复杂的工作流。
共享工具和辅助函数：
- 识别常见的 API 请求模式。
- 规划分页辅助函数。
- 设计过滤和格式化工具。
- 规划错误处理策略。
输入/输出设计：
- 定义输入验证模型（Python 使用 Pydantic，TypeScript 使用 Zod）。
- 设计一致的响应格式（例如 JSON 或 Markdown），以及可配置的详细程度（例如“详细”或“简洁”）。
- 规划大规模使用场景（成千上万的用户/资源）。
- 实施字符限制和截断策略（例如 25,000 个 token）。
错误处理策略：
- 规划优雅的故障模式。
- 设计清晰、可操作、对 LLM 友好、能提示后续行动的自然语言错误信息。
- 考虑速率限制和超时场景。
- 处理身份验证和授权错误。
现在您已经有了全面的计划，可以开始按照特定语言的最佳实践进行实施。
对于 Python：
- 创建一个单独的 .py 文件，如果项目复杂，可以组织成模块（参见 🐍 Python 指南）。
- 使用 MCP Python SDK 进行工具注册。
- 定义 Pydantic 模型用于输入验证。
对于 Node/TypeScript：
- 创建适当的项目结构（参见 ⚡ TypeScript 指南）。
- 设置 package.json 和 tsconfig.json。
- 使用 MCP TypeScript SDK。
- 定义 Zod 模式用于输入验证。
开始实施时，先创建共享工具，然后再实现具体工具：
- API 请求辅助函数。
- 错误处理工具。
- 响应格式化函数（JSON 和 Markdown）。
- 分页辅助函数。
- 身份验证/令牌管理。
针对计划中的每个工具：
定义输入模式：
- 使用 Pydantic（Python）或 Zod（TypeScript）进行验证。
- 包含适当的约束（最小/最大长度、正则表达式模式、最小/最大值、范围）。
- 提供清晰、描述性的字段说明。
- 在字段说明中包含多样化的示例。
编写全面的文档字符串/描述：
- 一行总结工具的功能。
- 详细解释其目的和功能。
- 明确的参数类型及示例。
- 完整的返回类型模式。
- 使用示例（何时使用，何时不使用）。
- 错误处理文档，概述在遇到特定错误时如何继续。
实现工具逻辑：
- 使用共享工具以避免代码重复。
- 对所有 I/O 操作遵循异步/等待模式。
- 实施适当的错误处理。
- 支持多种响应格式（JSON 和 Markdown）。
- 遵守分页参数。
- 检查字符限制并适当截断。
添加工具注解：
- readOnlyHint: true（对于只读操作）。
- destructiveHint: false（对于非破坏性操作）。
- idempotentHint: true（如果重复调用具有相同效果）。
- openWorldHint: true（如果与外部系统交互）。
此时，请加载相应的语言指南：
对于 Python：加载 🐍 Python 实现指南 并确保以下事项：
- 使用 MCP Python SDK 并正确注册工具。
- 使用带有 model_config 的 Pydantic v2 模型。
- 全程使用类型提示。
- 所有 I/O 操作使用异步/等待。
- 正确的导入组织。
- 模块级常量（CHARACTER_LIMIT, API_BASE_URL）。
对于 Node/TypeScript：加载 ⚡ TypeScript 实现指南 并确保以下事项：
- 正确使用 server.registerTool。
- 使用带有 .strict() 的 Zod 模式。
- 启用 TypeScript 严格模式。
- 不使用 any 类型 - 使用正确的类型。
- 显式的 Promise 返回类型。
- 配置构建过程（npm run build）。
在初步实施之后：
为确保质量，请审查代码的以下方面：
- DRY 原则：工具之间没有重复代码。
- 可组合性：共享逻辑已提取到函数中。
- 一致性：相似的操作返回相似的格式。
- 错误处理：所有外部调用都有错误处理。
- 类型安全：完整的类型覆盖（Python 类型提示，TypeScript 类型）。
- 文档：每个工具都有全面的文档字符串/描述。
重要提示： 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 传输管理服务器）。
为验证实施质量，请从特定语言指南中加载相应的检查清单：
- Python：参见 🐍 Python 指南 中的“质量检查清单”。
- Node/TypeScript：参见 ⚡ TypeScript 指南 中的“质量检查清单”。
在实现 MCP 服务器之后，创建全面的评估以测试其有效性。
加载 ✅ 评估指南 以获取完整的评估指南。
评估旨在测试 LLM 是否能有效地使用您的 MCP 服务器来回答真实、复杂的问题。
要创建有效的评估，请遵循评估指南中概述的流程：
每个问题必须满足：
- 独立性：不依赖于其他问题。
- 只读性：仅需要非破坏性操作。
- 复杂性：需要多次工具调用和深度探索。
- 真实性：基于人类会关心的真实用例。
- 可验证性：具有单一、清晰的答案，可通过字符串比较进行验证。
- 稳定性：答案不会随时间改变。
创建一个具有以下结构的 XML 文件：
<evaluation>
<qa_pair>
<question>查找关于使用动物代号命名的 AI 模型发布的讨论。其中一个模型需要一个特定格式为 ASL-X 的安全指定。对于那个以斑点野猫命名的模型，正在确定哪个数字 X？</question>
<answer>3</answer>
</qa_pair>
<!-- 更多 qa_pair... -->
</evaluation>
在开发过程中根据需要加载这些资源：
https://modelcontextprotocol.io/llms-full.txt 获取 - 完整的 MCP 规范。https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md 获取。https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md 获取。@mcp.tool 进行工具注册。质量检查清单。
⚡ TypeScript 实现指南 - 完整的 TypeScript 指南，包含：
server.registerTool 进行工具注册。