MCP Builder 拆解：Anthropic 亲手给 MCP Server 开发上的第一课

如果你写过 MCP Server，你一定遇到过这种情况。Claude 跟你聊得好好的，你说”帮我写一个 GitHub MCP Server”，它咔咔输出一段 TypeScript。看着挺像那么回事，schema 也有，tool 也注册了。然后你拿去跑 validator，红了。

不是 Claude 不懂 MCP 规范。正相反，它对规范文档的熟悉程度可能超过大多数人类开发者。问题出在另一个地方：从”知道规范”到”生成合规代码”，中间有一大段容易被忽略的细节。optional 参数怎么处理、JSON-RPC stub 的格式对不对、tool annotations 有没有写全，这些事 Claude 从记忆中生成的时候经常会漏。

MCP Builder 干的，就是用一套结构化的四阶段工作流，把 Claude 从”我大概知道怎么写”推到”我能稳定产出合规代码”。

说真的，这篇文章不会跟你讲太多 MCP 的概念性知识。我把 MCP Builder 的 Skill 定义完整拆了一遍，从它的四阶段设计到背后的理念取舍，再到它到底适合什么人用、什么场景下反而碍事。如果你正在考虑搭建自己的 MCP Server，或者好奇 Anthropic 官方是怎么设计 Skill 的，这应该是你能找到的最完整的一篇拆解。

环境准备

MCP Builder 不需要安装任何额外的 CLI 工具或依赖包。它本身是一个 Skill 文件，托管在 Anthropic 的官方 skills 仓库中。

获取方式有两种。第一种是从 Smithery 技能市场直接搜索 “mcp-builder” 安装，在 WorkBuddy 或 CodeBuddy 等支持 Skill 系统的客户端中一键引入。第二种是手动从 GitHub 仓库拉取：

git clone https://github.com/anthropics/skills.git

Skill 文件位于 skills/mcp-builder/SKILL.md，直接加载到对话上下文中即可激活。

前置条件相当轻量。你只需要一个支持 Skill 的 AI 编程环境，加上任何现代操作系统的终端。MCP Builder 推荐的开发栈是 TypeScript 配合 MCP 官方 TypeScript SDK，也支持 Python 路径。Node.js 18+ 或 Python 3.10+ 就能跑。第一次使用时，让 Claude 根据你的需求描述生成项目脚手架，运行 npm install 安装依赖，再执行 npm run build 验证编译，整个过程不超过五分钟。

实际体验下来，最容易卡住的环节不是代码本身，而是概念门槛。MCP Builder 不会教你什么是 resource、什么时候用 prompt 代替 tool。如果你对 MCP 协议的理解停留在”就是让 LLM 调用外部 API”，那你在 Phase 1 的研究阶段会花不少时间补课。这不算 Skill 的缺陷，但值得提前说清楚。

操作流程

MCP Builder 把创建 MCP Server 的过程拆成了四个紧密咬合的 Phase。每个 Phase 有明确的输入和输出，不像传统的”跟着教程一步步敲”模式，更像一个有质量门禁的工程管线。

Phase 1 是深度研究与规划。这一阶段要求你先理解现代 MCP 设计的核心原则：

• API 覆盖率和工作流工具的平衡
• 工具命名规范（统一前缀、动宾结构）
• 上下文管理策略（分页、过滤、聚焦返回）
• 可操作的错误消息设计

然后查阅 MCP 协议规范文档和对应语言的 SDK 文档，做一个实现计划，列出要覆盖的 API 端点并按优先级排序。这一步看起来像”准备工作”，实际上决定了后面代码质量的上限。

Phase 2 进入实现。搭建项目结构、实现 API 客户端和错误处理等核心基础设施，然后逐个实现工具。这里有一个容易被忽视但至关重要的设计：每个工具需要同时定义 inputSchema 和 outputSchema。输入侧用 Zod（TypeScript）或 Pydantic（Python）做参数校验，输出侧通过 structuredContent 返回结构化数据。destructiveHint 和 readOnlyHint 这些 annotations 也不是装饰品，它们直接影响 Agent 调用你的 Server 时的行为决策。

Phase 3 是审查和测试。代码质量检查覆盖 DRY 原则、错误处理一致性、类型覆盖率和工具描述清晰度。构建验证通过后，用 MCP Inspector 做端到端测试。这一阶段的存在本身就是一个信号：MCP Builder 的设计者知道 Claude 生成代码时会犯固定的几类错误，所以在流程里硬塞了一个质量检查点。

Phase 4 是最有意思的一环：创建评估。MCP Builder 要求你为刚写好的 Server 生成 10 个评估问题。这些问题不是随便写的，有六条硬性要求：

• 独立：不依赖其他问题的答案
• 只读：只用非破坏性操作就能回答
• 复杂：需要多轮工具调用和深度探索
• 真实：基于人类会关心的真实场景
• 可验证：答案是单一、明确、可字符串比对的
• 稳定：答案不会随时间变化

这个设计很聪明，它用评估反推 Server 的设计质量。如果你的 Server 连 10 个有深度的评估问题都支撑不了，那说明工具集设计本身就有问题。

四个 Phase 走完，你得到的不只是一个能跑的 MCP Server，还有一套验证它”好不好用”的评估体系。这是 MCP Builder 跟普通代码生成模板最本质的区别。

关键设计

拆开 MCP Builder 的 SKILL.md 看它的设计决策，有三件事做得相当有水平。

第一是它对”API 覆盖率 vs 工作流工具”这个矛盾的定位。这是一个在 MCP 开发圈里争议很大的问题。一个极端是把所有 API 端点都暴露成独立的 tool，给 Agent 最大灵活性；另一个极端是封装几个高层工作流 tool，牺牲灵活性换易用性。MCP Builder 的态度很务实：优先 API 覆盖率，同时在文档里承认不同客户端的表现不一样。有些客户端支持代码执行能力，可以组合基础 tool 完成复杂任务，这时候 API 覆盖率的优势就出来了。

第二是双向 Schema 的设计。大多数 MCP Server 教程只讲 inputSchema，MCP Builder 强制要求你同时定义 outputSchema 和 structuredContent。这个设计意图不难推断：MCP Server 不只是给 LLM 调用的，也是给人类开发者维护的。结构化输出让下游 Agent 能更精准地解析结果，也让人在 debug 时不用盯着原始 JSON 字符串猜结构。从架构角度讲，这是把”类型安全”的概念从编译期延伸到了运行时 API 契约。

第三是评估驱动设计的思路，也就是 Phase 4 的 10 个评估问题。这不是事后补的测试用例，而是整个工作流的收口节点。设计者显然意识到一个关键问题：MCP Server 好不好用，不是看代码写得规不规范，而是看 LLM 能不能靠它完成真实任务。评估问题就是对这个命题的直接验证。如果你的工具定义清晰、参数描述准确、返回值结构合理，Agent 就能高效组合多个 tool 完成复杂查询。这些东西在代码 review 阶段根本看不出来。

MCP Builder 也有明显的取舍。它对 TypeScript 的偏好几乎到了”官方指定”的程度，Python 路径虽然在文档里有提及，但所有最佳实践、参考文件、代码示例都是 TypeScript 优先。如果你用 Python 开发，很多 Guide 里的模式没法直接套用。另外，它对 Streamable HTTP 和 stateless JSON 的推荐也有争议。这个选择简化了部署和扩展，但 stateful session 和流式响应在特定场景下确实有不可替代的价值。

使用场景

MCP Builder 最擅长的场景很明确：从零搭建一个新的 MCP Server。

想象你要给 Notion API 写一个 MCP 封装。你需要暴露十几个 API 端点，每个端点都要处理三件不同的事：

• 参数类型定义（不同端点的入参结构千差万别）
• 分页逻辑（Notion 的 cursor 分页跟标准 offset 不一样）
• 错误格式映射（Notion 的错误码跟 JSON-RPC error 不是一对一）

手写的话，光是把 Notion API 文档翻译成 Zod schema 就得一两小时，中间还会漏掉 optional 参数、数组类型标注这些细节。

用 MCP Builder，你只需要描述清楚”我要封装 Notion API 的页面管理、数据库操作、搜索功能”，Claude 就能在 Phase 1 帮你规划端点覆盖范围，Phase 2 生成带完整类型标注的 TypeScript 代码。Delv 工具的实测也证实了这一点：手写 Notion MCP Server 时，Claude 给出的代码看起来靠谱但跑 MCP validator 会挂，因为 optional 参数处理不符合规范。加载 MCP Builder 后，同样的需求，生成的代码直接通过验证。

它同样适合给已有 Server 增加新 tool 的场景。MCP Builder 明确要求”添加工具时尊重现有架构”，不会重写你整个项目。这种”增量友好”的设计在工程上很关键，毕竟没人想为了加一个 tool 冒着把 Server 搞崩的风险。

不适用的场景也需要说清楚。如果你的 MCP Server 已经在生产环境运行了半年以上，架构稳定，功能齐全，MCP Builder 的脚手架能力对你几乎没价值。如果你用 Python 全栈且对 TypeScript 生态不熟悉，你需要额外花时间把生成的 TypeScript 模式翻译过去，性价比不高。如果你完全不了解 MCP 协议的基础概念，MCP Builder 不会手把手教你，它假设你已经知道 tool、resource、prompt 的区别。

洞察与反思

从 MCP Builder 的设计里，能看到一个更值得关注的大趋势：MCP 生态正在从”协议规范”阶段进入”工程化工具链”阶段。

半年前写 MCP Server 的方式，是打开 MCP 规范文档，照着写 JSON-RPC handler，用 MCP Inspector 手动测试，来回 debug。这种工作流跟 2016 年手写 REST API 没有本质区别。MCP Builder 做的事，本质上就是把 REST 生态里的 Swagger Codegen 或 gRPC protoc 带到了 MCP 领域，用一套规范化流程替代了”凭记忆加靠运气”的编码方式。

另一个值得注意的点是评估导向的设计思路。开发者习惯了代码质量用 lint、type check、unit test 来衡量。MCP Builder 告诉你一个反直觉的判断标准：MCP Server 的质量，看的是 LLM 能不能用它完成复杂的真实任务。这个标准跟传统软件工程的评估体系完全不同，但它可能是 MCP 领域最接近真相的质量定义。

至于 MCP Builder 本身的长期价值，我有个比较拧的观点。短期内，对于正在搭建第一个或第二个 MCP Server 的开发者，它是不可替代的效率工具。但随着 MCP 生态成熟、更好的 SDK 和脚手架工具出现，MCP Builder 的”独特性”会减弱。它真正的长期价值可能不在代码生成，而在那套评估方法论，这才是暂时没有竞品能提供的。另一个角度看，它作为一个官方 Skill 的设计范例本身就有研究价值，展示了如何把”让 AI 稳定产出高质量代码”这个模糊需求翻译成可执行的工程流程。

资源地址

总结

写完这篇拆解，我对 MCP Builder 的判断比刚开始动手时清晰多了。它不是那种”装上就能搞定一切”的银弹，更像一个有明确适用边界的专业工具。

适合用它的情况很明确：

• 新项目搭建，从零开始写 MCP Server
• 给已有 Server 增加新的 tool
• 需要验证 MCP 规范的合规性

这几个场景下，它的价值远超手写。

反过来，这几类人可能会觉得它”过度设计”：

• 已有稳定 Server 的维护者
• 纯 Python 团队，对 TypeScript 生态不熟
• MCP 新手，还没搞懂 tool 和 resource 的区别

说到底，MCP Builder 解决的不是”怎么写 MCP Server”的问题，是”怎么让 LLM 稳定地写出高质量的 MCP Server”的问题。两句话只差了不到十个字，但产品逻辑完全不同。前者的预判假设是开发者会写 MCP Server，后者的预判假设是开发者需要一套工程化管线来控制 AI 生成代码的质量。第二个预判假设显然更接近当前 MCP 开发的实际状态。

如果你正准备搭一个新的 MCP Server，花半小时把这个 Skill 跑一遍再动手，应该能省掉后面好几个小时的 debug。但别指望它教你 MCP 基础概念，那是读规范文档该干的事。