# 拆mcp-builder：94分才准出厂 ## 概述 本期是本栏目第2轮「单件深拆」。这回选的对象不是本周蹿升最快的新星，而是生态里最容易被忽视、却最值得拆的一件「官方造机器的机器」——`mcp-builder`。它躺在 Anthropic 官方 skills 仓库里，任务只有一件事：指导 Claude 从零写出一个合格的 MCP 服务器。拆开之后最大的发现是：这件 Skill 几乎不提供任何「能力」，它提供的全部是一套**流程纪律**——四个阶段、两套语言图纸、一张百分制考卷，并规定考不到 94 分不准交付。它可能是整个生态里「提示词工程当施工规范用」的最完整样本，拆透它，你既能学会写 MCP 服务器，也能学会怎么给任何 Skill 设计「自检闭环」。 ## 它解决什么问题 先说背景。MCP（Model Context Protocol）是 Anthropic 2024 年底开源的协议，让大模型通过标准接口调用外部工具和数据源，如今已经是 Agent 生态的通用插座。但手写一个 MCP 服务器对普通开发者并不友好：要选语言、选 SDK、设计工具粒度、写输入校验、处理错误返回，坑多且分散。 `mcp-builder` 的定位就是把这些坑预先踩平：用户只需要说「帮我把 XX API 做成 MCP 服务器」，Claude 就会按 Skill 里的施工规程走完调研、实现、验收全流程。它属于官方示例技能包（example-skills）的一员，和 pptx、docx、skill-creator 这些「同门师兄弟」住在一个仓库里——之前本栏目拆过同门的 pptx（三条产线）和 skill-creator 系（装配线），这件的特别之处在于：**别的 Skill 教 Claude 干活，它教 Claude 交活之前先给自己判卷。** ## 文件树解剖：一件「纯图纸」技能 mcp-builder 的目录结构在同类中属于极简派，大致如下（以仓库实际内容为准）： ``` mcp-builder/ ├── SKILL.md # 主协议：触发描述 + 四阶段流程 + 判卷标准 └── references/ ├── mcp-best-practices.md # 通用设计规范（与语言无关） ├── python/ # Python / FastMCP 专属施工指导 └── node/ # TypeScript / Node SDK 专属施工指导 ``` 注意一个反直觉的事实：**它的正文里没有一行真正干活的代码**。对比一下生态里常见的两类 Skill——一类是「工具箱型」，比如官方 pptx 里塞满了可执行脚本，Claude 主要是当调度员；另一类是「图纸型」，自己不动手，所有产出靠 Claude 按图纸现场施工。mcp-builder 是后者的极端形态：连脚本都不配，全部价值浓缩在一份协议文档和几份参考手册里。 这种结构直接决定了它的加载经济学。按照 Skills 机制的通用设计，只有 frontmatter 里的 name 和 description 常驻上下文，正文和 references 都按需加载。mcp-builder 把这个机制用到了极致：用户没说用什么语言之前，Python 和 Node 两套图纸一张都不展开；确定了语言，才把对应子目录喂给模型。一次典型的服务器搭建任务，实际消耗的上下文只有主协议加一套语言指南——对一个动辄上万 token 的技术文档体系来说，这是教科书级的**渐进式披露（progressive disclosure）**。 ## 逐段拆 SKILL.md ### 第一段：frontmatter 的触发词设计 它的 description 大意是：当用户要「创建 MCP 服务器」「让 Claude 能发现并调用外部工具」「把 API 暴露成 MCP 工具/资源」时使用本技能。这段话值得逐个成分看： - **动词全覆盖**：create / build / expose / wrap，把用户可能用的说法一网打尽。Skills 的触发完全依赖 description 与用户输入的语义匹配，漏一个常见动词就漏一类用户。 - **场景而非名词**：它不写「MCP 工具集」，而写「让 LLM 能够发现并与外部工具交互」——描述的是用户想达成的结果，不是技术名词。用户嘴上说「帮我把 Notion 接进来」，照样能命中。 - **克制的长度**：官方这批示例的 description 都控制在两三句以内，因为这段文字要为几百个 Skill 的常驻上下文 collectively 买单。本栏目此前写过「一段描述，决定 Skill 生死」，mcp-builder 就是正面范本：每个词都在为触发率打工，没有一个词在炫技。 ### 第二段：四阶段流程，把「写代码」拆成工程 SKILL.md 的主体是一条强制的流水线，大致分为四个阶段： ```mermaid flowchart TD A[用户提出造服务器需求] --> B[阶段1 定范围] B --> C[阶段2 查资料] C --> D[按语言读 references 图纸] D --> E[阶段3 写实现] E --> F[阶段4 自评分] F --> G{总分达标} G -->|低于94分| H[逐项找扣分点] H --> E G -->|达标| I[交付服务器] ``` **阶段1 定范围**：不许直接开写。先问清楚——这个服务器要包装什么 API？给哪些客户端用？需要哪些工具和资源？这一步的价值在于把「模糊需求」挡在施工之前，和生态里 brainstorming 类技能的思路同源，但压缩成了几个必答题，不搞长问卷。 **阶段2 查资料**：明确要求去读所选语言的 references 子目录。注意这个细节——它把「读文档」写成了流程的必经站，而不是模型的自由发挥。大模型写 MCP 代码最常见的翻车点是凭记忆写出过时 API，用一句「先读图纸再动工」就把这类事故流程性地消灭了。 **阶段3 写实现**：给出语言选型建议——快速原型偏 Python 的 FastMCP，类型严格或要进 Node 技术栈则走 TypeScript SDK。实现要求里反复出现的关键词是：工具命名规范、输入校验、有意义的错误返回、分页、破坏性操作先做 dry-run。这几条全部来自 MCP 官方最佳实践，Skill 只是把它变成了硬性工序。 **阶段4 判卷**：这是整件 Skill 的皇冠，单独展开。 ### 第三段：94分考卷——自我评分闭环 SKILL.md 规定实现完成后，Claude 必须给自己的服务器打分，评分表三大项： | 评分项 | 权重 | 考什么 | |--------|------|--------| | 功能性与可用性 | 40% | 工具数量合理、输入有校验、错误信息可读、返回值对 LLM 有用、无明显 bug | | 代码质量 | 30% | 异步写法、类型注解、符合 SDK 惯例、文档字符串完整 | | 完整性 | 30% | 规划的工具全部落地、边界场景覆盖、错误处理无遗漏 | 规则是：**总分低于 94，必须逐项列出扣分点，回到实现阶段返工，直到达标才能交付。** 这个设计妙在哪？拆三层： 1. **把「好」变成可执行的契约。**「写个好用的服务器」是模型无法执行的模糊指令；「三项加权总分≥94」是可计算的验收条件。提示词工程里最难的就是把品味变成规则，这张考卷是现成的示范。 2. **强制至少一轮审查。**没有这张考卷，模型写完代码的默认行为是直接交卷。有了它，「自查」从可选项变成了流程必需品——哪怕打分打虚了，那一次强迫性的逐项核对也能拦下相当比例的低级错误。 3. **扣分点即返工清单。**它要求列出的不是新分数，而是「哪一项扣了多少分、为什么」。这等于让模型自动生成自己的 todo list，返工有了明确靶子。 当然要诚实指出这套机制的软肋：既是运动员又是裁判，分数天然有通胀倾向——模型倾向于给自己打出 95 分以上体面收场。社区对这类 self-grading 设计的普遍批评也在于此。但即便如此，它依然比「不设验收」的裸奔式生成强一个量级：最差情况下你得到一份附带的逐项自检报告，最好情况下它真拦下了 bug。 ### 第四段：references 的分工哲学 通用规范 `mcp-best-practices.md` 与语言子目录的分工很讲究：前者讲「什么是好的 MCP 设计」——工具该多粗多细、命名怎么起、什么时候该做成 resource 而不是 tool、列表为什么必须分页、危险操作为什么要 dry-run；后者讲「这门语言里怎么落地」——Python 侧围绕 FastMCP 的写法与 Pydantic 校验，Node 侧围绕官方 TypeScript SDK 与 Zod 模式。 这个「道与术分层」的结构可以直接抄走：你自己写 Skill 时，把跨场景稳定的原则放一层，把随环境变化的手艺放另一层，将来加新语言只需新增一个子目录，主协议一个字不用改。 ## 评测对比表 与同门及赛道相关技能的横向参照（本栏目主观评测，1-5星，半星以◐表示）： | 维度（权重） | mcp-builder | skill-creator | webapp-testing | brand-guidelines | |---|---|---|---|---| | 功能完整度（25%） | ★★★★◐ | ★★★★ | ★★★★ | ★★★◐ | | 设计质量（25%） | ★★★★★ | ★★★★◐ | ★★★★ | ★★★★ | | 实战效果（20%） | ★★★★ | ★★★★ | ★★★◐ | ★★★◐ | | 上手难度（15%） | ★★★◐ | ★★★★ | ★★★◐ | ★★★★◐ | | 社区活跃度（15%） | ★★★★ | ★★★★◐ | ★★★◐ | ★★★ | | **加权总分** | **4.4** | **4.2** | **3.8** | **3.7** | mcp-builder 的设计质量给满星，理由就是上文的三层结构：触发描述、流程协议、判卷闭环，每一层都是可以单独拿出来当教材的写法。上手难度只给三星半，因为它假设你懂基本的 API 概念和终端操作——对纯新手，四个阶段里每一步产出的东西都需要你自己看得懂才行。 ## 适用与不适用场景 **适合交给它的活：** - 把内部 REST API 或数据库快速包装成 MCP 服务器，给 Claude Code 或其他 Agent 客户端用 - 给团队做数据查询类工具：只读列表、检索、聚合，典型的「最佳实践友好区」 - 学习 MCP 的陪练——让 Claude 按规范写一遍，你再对照官方文档读它的代码，比直接啃协议快得多 **不适合硬塞给它的活：** - 要上生产、扛并发、管长连接的重量级服务——Skill 的验收考卷管不了运维属性 - 涉及复杂 OAuth 流程或多租户鉴权的接入，参考图纸里只有最简的环境变量级凭据处理，安全设计得自己补 - 目标客户端不是 MCP 生态的（比如就是想要个普通 CLI），那就别用协议插座，换件 Skill ## 安装与使用 ```bash # 方式一：用社区 skills CLI（在提示中选择 mcp-builder） npx skills add anthropics/skills -g -y # 方式二：手动克隆，只拷这一件 git clone https://github.com/anthropics/skills.git cp -r skills/mcp-builder ~/.claude/skills/ # 方式三：Claude Code 内直接启用官方示例插件 # /plugin → marketplace 添加 anthropics/skills → 启用 example-skills ``` 装好后不需要记斜杠命令，直接说人话触发： ``` 帮我把公司内部的用户查询 API 包装成 MCP 服务器， 工具包括：按手机号查用户、按部门列用户（要分页）。 ``` Claude 会先跟你确认范围，再按流程走完实现和自检，最后附上它的评分表——如果它交卷时没给你看分数，你可以追一句「按 SKILL.md 的评分表重新判卷」，这张考卷是明文的，谁都能查它作业。 ## 推荐排行榜 - **设计质量榜**：mcp-builder 居官方示例之首——判卷闭环是全仓库唯一一份量化验收协议 - **学习价值榜**：学 MCP 服务器开发，它强于直接读官方 quickstart；学 Skill 写法，它与 skill-creator 互为镜像（一个教造 Skill，一个示范 Skill 该怎么写） - **抄作业优先级榜**：想改进自己的 Skill，最值得抄的三件套依次是：扣分点驱动的返工循环、道术分层的 references 结构、结果导向的触发描述 ## 生态观察 放回大图里看，mcp-builder 代表了 Skill 设计的一条隐秘分水岭：**工具箱型 Skill 卖力气，图纸型 Skill 卖纪律。**社区市场上海量的 Skill 在卷「我能多干几件事」，而官方这几件最耐拆的样本都在卷「我怎么让 Claude 少犯错」。前者堆脚本，后者写流程；前者上线快，后者活得久。随着 MCP 服务器数量爆炸，这类「带验收标准的施工规程」大概率会成为 Skill 设计的主流范式——毕竟 Agent 干活的最大风险从来不是不会干，而是干完没人检查。94 分这道及格线，与其说是技术约束，不如说是给整个生态打了个样：**交付之前，先判卷。** ## 参考来源 1. [anthropics/skills 官方仓库](https://github.com/anthropics/skills) — mcp-builder 所在的官方示例技能仓库，本文拆解对象的原始出处 2. [mcp-builder 目录](https://github.com/anthropics/skills/tree/main/mcp-builder) — SKILL.md 与 references 参考体系的原文位置 3. [MCP 官方文档](https://modelcontextprotocol.io) — Model Context Protocol 协议规范与最佳实践来源 4. [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) — Python 侧 FastMCP 官方 SDK 5. [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) — Node 侧官方 TypeScript SDK > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。