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

mcp-builder

智能体与模型

查看项目

更新于 10-16 06:57

技能介绍

用途

mcp-builder 是一份开发指南，用于创建高质量的 MCP（Model Context Protocol）服务器，使 LLM 能够通过设计良好的工具与外部服务交互。指南明确指出，MCP 服务器的质量以其帮助 LLM 完成真实世界任务的程度来衡量。

主要能力与流程

指南将创建高质量 MCP 服务器分为四个主要阶段。

阶段一：深度研究与规划

  • 理解现代 MCP 设计：在全面的 API 端点覆盖与专门的工作流工具之间取得平衡；工作流工具对特定任务更方便，而全面覆盖让智能体可以灵活组合操作。不同客户端表现不同，不确定时优先考虑全面的 API 覆盖。
  • 工具命名与可发现性：使用清晰、描述性的工具名，采用一致前缀（如 github_create_issue、github_list_repos）和面向动作的命名。
  • 上下文管理：工具描述应简洁，并支持过滤/分页结果，返回聚焦且相关的数据。
  • 可操作的错误信息：错误信息应给出具体建议和下一步，引导智能体找到解决方案。
  • 研究 MCP 协议文档：从 sitemap（https://modelcontextprotocol.io/sitemap.xml）开始查找相关页面，再用 .md 后缀获取 markdown 格式页面（如 https://modelcontextprotocol.io/specification/draft.md）。重点查看规范概览与架构、传输机制（streamable HTTP、stdio）、工具/资源/提示定义。
  • 研究框架文档：推荐技术栈为 TypeScript（SDK 支持质量高，在许多执行环境如 MCPB 中兼容性好，且 AI 模型擅长生成 TypeScript 代码），传输方式为远程服务器使用 Streamable HTTP（无状态 JSON，更易扩展和维护），本地服务器使用 stdio。
  • 规划实现：审阅服务 API 文档，识别关键端点、认证要求和数据模型；优先全面覆盖 API，列出要实现的端点，从最常见操作开始。

阶段二：实现

  • 搭建项目结构（参见语言专属指南）。
  • 实现核心基础设施：带认证的 API 客户端、错误处理辅助、响应格式化（JSON/Markdown）、分页支持。
  • 实现工具：输入 schema 使用 Zod（TypeScript）或 Pydantic（Python），包含约束和清晰描述，在字段描述中加入示例；尽可能定义 outputSchema 以支持结构化数据，并在工具响应中使用 structuredContent；工具描述包含功能摘要、参数说明和返回类型 schema；实现时对 I/O 操作使用 async/await，提供带可操作信息的错误处理，支持分页，并在使用现代 SDK 时同时返回文本内容和结构化数据。
  • 注解：readOnlyHint、destructiveHint、idempotentHint、openWorldHint（均为 true/false）。

阶段三：审查与测试

  • 代码质量：检查无重复代码（DRY 原则）、一致的错误处理、完整类型覆盖、清晰的工具描述。
  • 构建与测试：TypeScript 运行 npm run build 验证编译，用 MCP Inspector 测试（npx @modelcontextprotocol/inspector）；Python 用 python -m py_compile your_server.py 验证语法，并用 MCP Inspector 测试。

阶段四：创建评估

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

  • 评估目的：测试 LLM 能否有效使用该 MCP 服务器回答真实、复杂的问题。
  • 创建 10 道评估问题：工具检查（列出可用工具并理解其能力）、内容探索（使用只读操作探索可用数据）、问题生成（创建 10 道复杂、真实的问题）、答案验证（自己解答每道题以验证答案）。
  • 评估要求：每道题应独立、只读、复杂（需要多次工具调用和深入探索）、真实、可验证（单一明确答案，可通过字符串比较验证）、稳定（答案不随时间变化）。
  • 输出格式：创建如下结构的 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>
<!-- More qa_pairs... -->
</evaluation>

参考文件

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

  • 核心 MCP 文档（优先加载）：MCP 协议从 sitemap 开始，再用 .md 后缀获取具体页面；MCP 最佳实践包含服务器与工具命名约定、响应格式指南（JSON vs Markdown）、分页最佳实践、传输选择（streamable HTTP vs stdio）、安全与错误处理标准。
  • 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 格式规范、示例问题与答案，以及使用所提供脚本运行评估的方法。

适用场景

适用于需要为 LLM 构建与外部服务交互的 MCP 服务器的开发者，尤其是希望遵循规范流程、保证工具设计质量并进行有效评估的场景。

限制

资料未提供该指南的具体安装命令、收费方式、价格、支持平台或实际效果数据，这些信息暂未提供。