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

mcp-builder

智能体与模型

查看项目

更新于 10-16 02:07

技能介绍

概述

mcp-builder 是一个用于创建 MCP（Model Context Protocol）服务器的开发指南。它的目标是构建能让 LLM 通过精心设计的工具与外部服务交互的 MCP 服务器。该指南强调：MCP 服务器的质量，取决于它能在多大程度上帮助 LLM 完成真实世界的任务。

工作流

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

阶段一：深入研究与规划

理解现代 MCP 设计

  • API 覆盖度与工作流工具的权衡：需要在全面的 API 端点覆盖与专用工作流工具之间取得平衡。工作流工具对特定任务更方便，而全面覆盖则给 agent 组合操作的灵活性。不同客户端表现不同——有些客户端受益于组合基础工具的代码执行，有些则更适合高层工作流。不确定时，优先选择全面的 API 覆盖。
  • 工具命名与可发现性：清晰、描述性的工具名帮助 agent 快速找到正确的工具。使用一致的前缀（如 github_create_issue、github_list_repos）和面向动作的命名。
  • 上下文管理：agent 受益于简洁的工具描述以及过滤/分页结果的能力。设计返回聚焦、相关数据的工具。部分客户端支持代码执行，可帮助 agent 高效过滤和处理数据。
  • 可操作的错误信息：错误信息应通过具体建议和后续步骤引导 agent 找到解决方案。

研究 MCP 协议文档

浏览 MCP 规范：先从 sitemap 找到相关页面 https://modelcontextprotocol.io/sitemap.xml，然后用 .md 后缀获取具体页面的 markdown 格式（例如 https://modelcontextprotocol.io/specification/draft.md）。需要重点查看的页面包括：规范总览与架构、传输机制（streamable HTTP、stdio）、工具/资源/prompt 定义。

研究框架文档

推荐技术栈：

  • 语言：TypeScript（SDK 支持质量高，在许多执行环境中兼容性好，如 MCPB；同时 AI 模型擅长生成 TypeScript 代码，受益于其广泛使用、静态类型和良好的 lint 工具）。
  • 传输：远程服务器使用 Streamable HTTP，采用无状态 JSON（相比有状态会话和流式响应，更易扩展和维护）；本地服务器使用 stdio。

加载框架文档：MCP 最佳实践为核心指南。TypeScript（推荐）使用 WebFetch 加载 https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md；Python 加载 https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md。

规划实现

理解 API：查阅服务的 API 文档，识别关键端点、鉴权要求和数据模型，必要时使用网络搜索和 WebFetch。工具选型：优先全面的 API 覆盖，列出待实现端点，从最常见的操作开始。

阶段二：实现

搭建项目结构：参见对应语言指南（TypeScript 的项目结构、package.json、tsconfig.json；Python 的模块组织、依赖）。

实现核心基础设施：创建共享工具，包括带鉴权的 API 客户端、错误处理助手、响应格式化（JSON/Markdown）、分页支持。

实现工具，对每个工具处理：

  • 输入模式：使用 Zod（TypeScript）或 Pydantic（Python），包含约束和清晰描述，在字段描述中加入示例。
  • 输出模式：尽可能定义 outputSchema 以输出结构化数据；在工具响应中使用 structuredContent（TypeScript SDK 功能），帮助客户端理解和处理工具输出。
  • 工具描述：功能简述、参数描述、返回类型模式。
  • 实现：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 协议，从 https://modelcontextprotocol.io/sitemap.xml 开始，再获取带 .md 后缀的具体页面；MCP 最佳实践，涵盖服务器与工具命名约定、响应格式指南（JSON 与 Markdown）、分页最佳实践、传输选择（streamable HTTP 与 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 模式、使用 server.registerTool 注册工具、完整可运行示例、质量清单。

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