SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场mcp-builder

mcp-builder

智能体与模型

查看项目

更新于 10-16 03:50

技能介绍

概述

mcp-builder 是一个指导创建高质量 MCP（Model Context Protocol，模型上下文协议）服务器的技能。MCP 服务器通过提供工具，让 LLM 能够访问外部服务和 API。其质量衡量标准是：能否借助所提供的工具，帮助 LLM 完成真实世界的任务。

工作流程

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

第一阶段：深入调研与规划

理解以智能体为中心的设计原则：

  • 为工作流而非仅 API 端点构建：不要简单包装现有 API 端点，而应构建有思考、高影响力的工作流工具；合并相关操作（例如同时检查可用性并创建事件的 schedule_event）；聚焦能完成完整任务的工具，而非单个 API 调用；考虑智能体实际需要完成的工作流。
  • 优化受限上下文：智能体上下文窗口有限，应让每个 token 都有价值；返回高信号信息，而非穷尽式数据转储；提供“简洁”与“详细”两种响应格式选项；默认使用人类可读的标识符（名称优先于 ID）；将智能体上下文预算视为稀缺资源。
  • 设计可操作的错误消息：错误消息应引导智能体正确使用；建议具体下一步，例如“尝试使用 filter='active_only' 以减少结果”；让错误具有教育意义，而不只是诊断；通过清晰反馈帮助智能体学习正确用法。
  • 遵循自然任务划分：工具名称应反映人类思考任务的方式；用一致前缀分组相关工具以便发现；围绕自然工作流设计工具，而非仅按 API 结构。
  • 使用评估驱动开发：尽早创建真实的评估场景；让智能体反馈驱动工具改进；快速原型并根据实际智能体表现迭代。

研究 MCP 协议文档：使用 WebFetch 加载 https://modelcontextprotocol.io/llms-full.txt，该综合文档包含完整的 MCP 规范与指南。

研究框架文档：加载并阅读 MCP 最佳实践；Python 实现可加载 Python SDK 文档（https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md）与 Python 实现指南；Node/TypeScript 实现可加载 TypeScript SDK 文档（https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md）与 TypeScript 实现指南。

详尽研究 API 文档：阅读全部可用 API 文档，包括官方 API 参考、认证与授权要求、速率限制与分页模式、错误响应与状态码、可用端点及参数、数据模型与 schema。可使用网络搜索和 WebFetch 工具收集信息。

创建综合实施计划，包括：

  • 工具选择：列出最有价值的端点/操作；优先支持最常见和最重要的用例；考虑哪些工具协同可支撑复杂工作流。
  • 共享工具与辅助函数：识别通用 API 请求模式；规划分页辅助；设计过滤与格式化工具；规划错误处理策略。
  • 输入/输出设计：定义输入验证模型（Python 用 Pydantic，TypeScript 用 Zod）；设计一致的响应格式（如 JSON 或 Markdown）以及可配置的详细级别（如详细或简洁）；规划大规模使用（数千用户/资源）；实现字符限制与截断策略（如 25,000 tokens）。
  • 错误处理策略：规划优雅失败模式；设计清晰、可操作、对 LLM 友好的自然语言错误消息，以提示后续操作；考虑速率限制与超时场景；处理认证与授权错误。

第二阶段：实现

按照语言特定最佳实践开始实现。

搭建项目结构：

  • Python：创建单个 .py 文件，复杂时组织为模块；使用 MCP Python SDK 进行工具注册；定义 Pydantic 模型用于输入验证。
  • Node/TypeScript：创建合适的项目结构；设置 package.json 和 tsconfig.json；使用 MCP TypeScript SDK；定义 Zod schema 用于输入验证。

先实现核心基础设施：在实现工具前创建共享工具，包括 API 请求辅助函数、错误处理工具、响应格式化函数（JSON 与 Markdown）、分页辅助、认证/token 管理。

系统地实现工具。对计划中的每个工具：

  • 定义输入 schema：使用 Pydantic（Python）或 Zod（TypeScript）进行验证；包含适当约束（最小/最大长度、正则模式、最小/最大值、范围）；提供清晰描述性的字段说明；在字段说明中包含多样化示例。
  • 编写完整的 docstring/描述：一行摘要说明工具做什么；详细解释目的与功能；带示例的明确参数类型；完整返回类型 schema；使用示例（何时使用、何时不使用）；错误处理文档，说明遇到特定错误时如何继续。
  • 实现工具逻辑：使用共享工具避免重复代码；所有 I/O 遵循 async/await 模式；实现正确的错误处理；支持多种响应格式（JSON 与 Markdown）；遵守分页参数；检查字符限制并适当截断。
  • 添加工具注解：readOnlyHint: true（只读操作）；destructiveHint: false（非破坏性操作）；idempotentHint: true（重复调用效果相同）；openWorldHint: true（与外部系统交互）。

遵循语言特定最佳实践：

  • Python：使用 MCP Python SDK 并正确注册工具；使用带 model_config 的 Pydantic v2 模型；全程类型提示；所有 I/O 使用 async/await；正确组织导入；模块级常量（CHARACTER_LIMIT、API_BASE_URL）。
  • Node/TypeScript：正确使用 server.registerTool；使用带 .strict() 的 Zod schema；启用 TypeScript 严格模式；不使用 any 类型，使用正确类型；显式 Promise 返回类型；配置构建流程（npm run build）。

第三阶段：审查与改进

代码质量审查：确保 DRY 原则（工具间无重复代码）；可组合性（共享逻辑抽取为函数）；一致性（相似操作返回相似格式）；错误处理（所有外部调用都有错误处理）；类型安全（完整类型覆盖）；文档（每个工具都有完整 docstring/描述）。

测试与构建：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 已创建；手动测试方式同上。

使用质量检查清单：Python 见 Python 指南中的“Quality Checklist”；Node/TypeScript 见 TypeScript 指南中的“Quality Checklist”。

第四阶段：创建评估

实现 MCP 服务器后，创建综合评估以测试其有效性。加载评估指南获取完整评估规范。

理解评估目的：评估测试 LLM 能否有效使用 MCP 服务器回答真实、复杂的问题。

创建 10 个评估问题，流程：工具检查（列出可用工具并理解其能力）；内容探索（使用只读操作探索可用数据）；问题生成（创建 10 个复杂、真实的问题）；答案验证（自己解决每个问题以验证答案）。

评估要求：每个问题必须独立（不依赖其他问题）；只读（仅需非破坏性操作）；复杂（需要多次工具调用和深入探索）；真实（基于人类关心的真实用例）；可验证（单一明确答案，可通过字符串比较验证）；稳定（答案不会随时间变化）。

输出格式：创建 XML 文件，结构为： <evaluation> <qa_pair> <question>...</question> <answer>...</answer> </qa_pair> <!-- 更多 qa_pair... --> </evaluation>

参考文件

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

核心 MCP 文档（优先加载）：MCP 协议：从 https://modelcontextprotocol.io/llms-full.txt 获取完整 MCP 规范；MCP 最佳实践：通用 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 注册工具、完整可运行示例、质量检查清单；TypeScript 实现指南，包含项目结构、Zod schema 模式、使用 server.registerTool 注册工具、完整可运行示例、质量检查清单。

评估指南（第四阶段加载）：完整评估创建指南，包含问题创建准则、答案验证策略、XML 格式规范、示例问题与答案、使用所提供脚本运行评估。