# 拆mcp-builder：教Claude自己造工具的Skill > 本期是 Skills 生态观察的第 2 轮单件深拆。对象不是社区新货，而是官方架子上的元老：`anthropics/skills` 仓库 example-skills 集里的 **mcp-builder**。它和前面拆过的 skill-creator 属于同一类「造东西的 Skill」——skill-creator 教 Claude 写 SKILL.md，mcp-builder 教 Claude 写 MCP 服务器。换句话说，它不是一件工具，而是**生产工具的机床**。本文素材来自本地实际安装的官方插件包原文（anthropic-agent-skills 插件内的 SKILL.md 全文逐段精读），核心发现有三：一是它的渐进式披露做得近乎教科书级，主文件只放流程、细节全数下沉；二是它在 Phase 4 要求 Claude「出卷人先做题」，给产出的服务器配十道可验证的评测题；三是它通篇在给模型灌输一个价值观——工具的用户是 LLM，不是人。 --- ## 一、先交底：文件账单与自我定位 mcp-builder 的包结构不复杂，但每一件都有明确岗位： | 文件 | 岗位 | 何时被加载 | |------|------|-----------| | SKILL.md | 四阶段流程主控 | 触发即入上下文 | | reference/mcp_best_practices.md | MCP 设计军规 | Phase 1 调研时 | | reference/python_mcp_server.md | Python/FastMCP 实现指南 | Phase 2 选 Python 时 | | reference/node_mcp_server.md | TypeScript 实现指南 | Phase 2 选 TS 时 | | reference/evaluation.md | 评测题出题规范 | Phase 4 出卷时 | | 评测脚本 | 跑评测用 | Phase 4 收尾时 | 主文件开篇第一句话就值回票价： > "Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. **The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.**" 前半句是功能定义，后半句是质量定义——「一个 MCP 服务器好不好，取决于它能让 LLM 把真实任务完成到什么程度」。注意主语：衡量标准落在 **LLM 能不能干活** 上，而不是「API 覆盖全不全」「代码优雅不优雅」。这个立场句是整篇 SKILL.md 的公理，后面所有设计原则都是从它推出来的定理。写 Skill 的读者可以先抄走这一招：**开篇别写功能列表，先写一句价值观**，让模型后面每一步都有裁判依据。 --- ## 二、四阶段流水线：一张图看完主流程 SKILL.md 的 Process 部分是一条刚性的四阶段流水线，用 emoji 章节符做了视觉分节（🚀 高层工作流、📋 最佳实践、🐍 Python、⚡ TypeScript、✅ 评测——五个 emoji 各守一个入口，扫一眼就知道往哪跳）： ```mermaid flowchart TD A["触发：用户要建MCP服务器"] --> B["Phase 1 调研与规划"] B --> B1["读MCP最佳实践"] B --> B2["自导航抓协议文档"] B1 --> C["Phase 2 实现"] B2 --> C C --> C1["搭项目骨架"] C --> C2["写工具schema与注解"] C1 --> D["Phase 3 审查与测试"] C2 --> D D --> D1["编译验证"] D --> D2["Inspector 实测"] D1 --> E["Phase 4 出十道评测题"] D2 --> E E --> F["自问自答验证后交付"] ``` 四个阶段各自的目标一句话：**Phase 1 想清楚给谁用，Phase 2 把工具长出来，Phase 3 证明它能跑，Phase 4 证明 LLM 真用得好。** 最后一阶段是同类 Skill 里罕见的环节，后面单独拆。 --- ## 三、Phase 1 拆解：四条军规与一场「自导航」 ### 3.1 写给模型的四条设计军规 Phase 1.1「Understand Modern MCP Design」给出四条原则，每条都值得抄进自己的提示词里： 1. **API 覆盖 vs 工作流工具**：全量包 API 端点，还是封装成面向任务的粗粒度工具？它给的裁决是——「不确定时，优先全面覆盖（prioritize comprehensive API coverage）」，把组合的自由留给 Agent 端的代码执行。这是把「灵活性归模型」的立场贯彻到了工具粒度决策上。 2. **命名与可发现性**：动宾结构 + 一致前缀，例子里直接给了 `github_create_issue`、`github_list_repos`。前缀即命名空间，模型检索时靠前缀聚类。 3. **上下文管理**：工具描述要精炼、返回结果要可过滤可分页——因为工具描述本身也占模型的上下文窗口，二十个描述啰嗦的工具能吃掉一整段工作记忆。 4. **报错要给下一步**：错误信息必须「actionable」，带具体建议和修复方向。这条其实是把「LLM 看到报错后要自我修复」这个使用场景写进了工程规范——报错不是给人看的日志，是给模型的 retry 提示。 ### 3.2 最妙的一处：教 Claude 自己去爬规范 Phase 1.2 没有把 MCP 协议规范打包进 Skill（那会让包膨胀且过期），而是写了三行「导航指令」：先抓 `https://modelcontextprotocol.io/sitemap.xml` 拿目录，再给目标页加 `.md` 后缀拿 Markdown 纯文本。也就是说，**它把「查文档」本身做成了 Skill 内的可执行流程**——模型每次触发都会拉到最新版规范，永不腐烂。这是「引用外部真相而非内置副本」的模式，任何写长期生效 Skill 的人都该抄。 ### 3.3 选型站队：TypeScript 优先，理由写在正文里 框架选型上它明确站队：语言推荐 TypeScript，理由写了三条——SDK 质量高、MCPB 等执行环境兼容性好，以及最诚实的一条：**「AI 模型很擅长生成 TypeScript 代码」**，因为 TS 生态大、静态类型、lint 工具齐全。传输层推荐：远程服务器用 Streamable HTTP 的**无状态 JSON** 模式（好扩展好维护，回避有状态会话），本地服务器用 stdio。这三条理由的写法有个细节：它不是说「TS 更好」，而是说「为什么**模型写** TS 更顺」——选型理由是为执行者（模型）定制的，不是为人定制的。 --- ## 四、Phase 2 拆解：一个工具该长什么样的完整规格 Phase 2 把「实现」拆成骨架、基础设施、工具三层。基础设施四件套：带鉴权的 API client、错误处理助手、响应格式化（JSON/Markdown 双格式）、分页支持——注意这四件全部服务于「模型好消化」，没有一件服务于「人好读」。 单个工具的规格书是最值得细看的部分，它分五栏： - **输入 Schema**：Zod（TS）或 Pydantic（Python），要求带约束、描述里带示例； - **输出 Schema**：能用就定义 `outputSchema`，响应里用 `structuredContent` 返回结构化数据——这样客户端不用从文本里猜答案； - **工具描述**：功能一句话 + 参数说明 + 返回类型； - **实现**：async/await、可行动的报错、能分页就分页； - **注解（Annotations）**：四个 hint，这是 MCP 协议里的「行为自白书」： | 注解 | 含义 | 谁在消费它 | |------|------|-----------| | `readOnlyHint` | 是否只读 | 客户端据此决定要不要弹审批框 | | `destructiveHint` | 是否有破坏性 | 高危操作前置确认 | | `idempotentHint` | 重复调用是否安全 | 重试逻辑的依据 | | `openWorldHint` | 是否与外部实体交互 | 沙箱与网络策略参考 | 四个 hint 全是「hint」——协议不强制为真，但 Skill 要求老老实实填。这里的设计哲学是：**工具自己声明风险等级，把安全决策留给调用方**，而不是在工具内部写死拦截。 --- ## 五、Phase 3 与 Phase 4：出卷人先做题 Phase 3 是常规工程自检：DRY、错误处理一致、类型全覆盖，TS 跑 `npm run build`，Python 跑 `python -m py_compile`，然后统一用 MCP Inspector（`npx @modelcontextprotocol/inspector`）实测。这部分任何一个正经的工程 Skill 都会有，不赘述。 **Phase 4 才是这件 Skill 的护城河。** 它要求给做好的服务器出十道评测题，而且先甩出一段和主文件开篇呼应的立场——评测的目的是「测试 LLM 能否有效地用你的 MCP 服务器回答真实、复杂的问题」。出题流程四步：列工具、只读探索数据、生成十道题、**自己把每道题做一遍验证答案**。 题目有六条硬标准，每条都在防一种翻车： | 标准 | 防的是什么翻车 | |------|---------------| | Independent | 题目之间不能有依赖，防止上一题挂了全线崩 | | Read-only | 只允许非破坏性操作，防止评测毁数据 | | Complex | 必须多次调用工具，防「一问一答」假评测 | | Realistic | 得是人类真会问的问题，防出偏题怪题 | | Verifiable | 答案唯一、可字符串比对，防评分靠感觉 | | Stable | 答案不随时间变，防题库过期 | 输出是规定的 XML 格式（`qa_pair` 包 `question`/`answer`），Skill 里内置的示例题很能说明出题口味：问的是「查找用动物代号命名的 AI 模型发布讨论，其中一只『斑点野猫』要确定 ASL-X 格式的安全等级，X 是几？」——答案是 `3`（ASL-3）。这道题要多跳检索、跨文档拼接才能答，且答案是一个可精确比对的字符。**「出卷人先做题」是整个 Phase 4 的灵魂**：模型必须先用自己造的工具把答案亲手做出来，才有资格把题入库。这相当于给交付物加了一道「自证可用」的关卡，成本只是十次工具调用。 --- ## 六、渐进式披露：一份被低估的加载账本 把五份文档的加载时机连起来看，会发现主文件的「薄」是精心设计的： ```mermaid flowchart TD S["SKILL.md 主控文件"] -->|Phase 1 按需| R1["mcp最佳实践"] S -->|Phase 2 按需| R2["Python 实现指南"] S -->|Phase 2 按需| R3["TS 实现指南"] S -->|Phase 4 按需| R4["评测出题规范"] S -->|运行时在线抓| W1["TS SDK 文档"] S -->|运行时在线抓| W2["Python SDK 文档"] S -->|运行时在线抓| W3["modelcontextprotocol.io"] ``` 触发时真正进上下文的只有主控文件：流程、裁决原则、加载指令。四份 reference 各自绑定一个阶段，选了 Python 就永远不加载 TS 指南，没到 Phase 4 就不碰评测规范。SDK 文档干脆内置都不内置，运行时直接从 GitHub raw 地址拉。这笔账算下来：**触发成本极小，膨胀风险为零，内容永不过期**。代价是运行时依赖网络——离线环境下协议文档和 SDK 文档两条腿会断，这是它唯一的结构性软肋。 --- ## 七、触发设计：名字和描述为什么这样起 `mcp-builder` 这个名字本身就是触发词：动宾结构的 builder，和 artifacts-builder、skill-creator 同一构词法，模型看到「帮我做一个 XX 的 MCP server」「把我们的 API 包成 MCP」这类请求时，语义直接命中。它的 Overview 首句把 `MCP`、`servers`、`LLMs`、`tools` 几个关键词全部锁进第一句话，等于把触发匹配面拉满。边界同样清晰：用户只是想**用**某个现成 MCP 服务器时，请求里没有「造/建/build」的语义，不会误触发——「造工具」和「用工具」两个场景被名字切干净了。这也是官方示例集反复示范的一个命名纪律：**Skill 名字用动词收尾，把触发边界写进名字里**。 --- ## 八、适用与不适用 **适合装的三种人**： - 要给自己的 SaaS、内部系统、数据库包一层 MCP 接口的开发者； - 想系统学 MCP 规范的人——把它当一份「会走流程的规范导读」用，比裸读 spec 快； - 在做 Agent 平台、需要批量产出工具接入的团队。 **不适合 / 要留心的三种情况**： - 只想消费现成 MCP 服务器的用户，这是造车 Skill 不是用车 Skill； - 零代码用户：产出的 TypeScript/Python 项目要本地 Node 或 Python 环境、要跑构建，纯小白拿到的是一堆报错； - 生产部署前必须人工过一遍代码和安全审计——Skill 自己都说了「不确定时优先全面覆盖」，全面暴露 API 的工具集直接上生产，权限面需要人把关。 --- ## 九、评测打分卡 | 维度 | 权重 | 得分 | 依据 | |------|------|------|------| | 功能完整度 | 25% | ★★★★★ | 调研、实现、测试、评测全链路闭环，罕见地管到「交付后可验证」 | | 设计质量 | 25% | ★★★★★ | 渐进披露、立场句开篇、自导航文档、自评测，四个模式皆可进教材 | | 实战效果 | 20% | ★★★★☆ | 官方出品、流程完备，但产物质量仍取决于宿主模型执行力，需人收尾 | | 上手难度 | 15% | ★★★★☆ | 装上即用、触发词清晰，扣一星在产出物需要 Node/Python 环境 | | 社区活跃度 | 15% | ★★★★☆ | 官方 example-skills 门面件，随 anthropics/skills 仓库持续维护 | | **加权总分** | 100% | **4.5 / 5** | 设计维度近乎满分的天花板件，短板全在「生成的代码仍需人拍板」 | --- ## 十、五个可抄模式排行榜 不管你写不写 MCP，这五个模式都能直接搬进你自己的 SKILL.md： 1. **立场句开篇**——第一段写清「什么叫做好」，给模型一把裁判尺； 2. **主薄辅厚、按阶段加载**——主文件只放流程与裁决，细节绑阶段按需 load，SDK 文档干脆运行时拉最新； 3. **出卷人先做题**——要求交付前自建可验证的评测题并亲手做一遍，让「能用」从声明变成证据； 4. **报错给下一步**——把「可行动的错误信息」写成硬规范，模型自我修复的成功率直接决定产物质量； 5. **选型理由写给执行者**——推荐 TS 的理由是「模型写得好」，不是「TS 更流行」，说服对象错了，理由再对也白搭。 --- ## 十一、安装与使用 ```bash # 方式一：从官方仓库手动安装 git clone https://github.com/anthropics/skills.git cd skills find . -type d -name "mcp-builder" # 定位目录（不同版本层级可能调整） cp -r <定位到的路径> ~/.claude/skills/mcp-builder # 方式二：官方插件包一键带入（mcp-builder 随 example-skills 全家桶分发） # 在 Claude Code 内运行 /plugin ，安装 anthropic-agent-skills 插件包 ``` 装好后直接对话触发：「帮我把 Notion API 封装成一个 MCP 服务器」「给我们的内部系统写个 MCP server，要有分页和错误处理」——含「造/建/build MCP」语义的请求即可命中。 --- ## 参考来源 1. [anthropics/skills](https://github.com/anthropics/skills) — 官方 Skills 仓库，mcp-builder 随 example-skills 集分发 2. example-skills:mcp-builder SKILL.md 全文（anthropic-agent-skills 插件本地安装包，本文逐段拆解的原始底稿） 3. [Model Context Protocol 规范站](https://modelcontextprotocol.io/sitemap.xml) — Skill 内置的自导航文档入口，含协议规范与传输机制章节 4. [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) — Skill 在 Phase 1/2 运行时拉取的 TS SDK 文档源 5. [MCP Inspector](https://github.com/modelcontextprotocol/inspector) — Skill 在 Phase 3 指定的实测工具（`npx @modelcontextprotocol/inspector`） > [!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 等场景全覆盖。