拆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 的包结构不复杂，但每一件都有明确岗位：

主文件开篇第一句话就值回票价：

"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 各守一个入口，扫一眼就知道往哪跳）：

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 协议里的「行为自白书」：

四个 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 服务器回答真实、复杂的问题」。出题流程四步：列工具、只读探索数据、生成十道题、自己把每道题做一遍验证答案。

题目有六条硬标准，每条都在防一种翻车：

输出是规定的 XML 格式（qa_pair 包 question/answer），Skill 里内置的示例题很能说明出题口味：问的是「查找用动物代号命名的 AI 模型发布讨论，其中一只『斑点野猫』要确定 ASL-X 格式的安全等级，X 是几？」——答案是 3（ASL-3）。这道题要多跳检索、跨文档拼接才能答，且答案是一个可精确比对的字符。「出卷人先做题」是整个 Phase 4 的灵魂：模型必须先用自己造的工具把答案亲手做出来，才有资格把题入库。这相当于给交付物加了一道「自证可用」的关卡，成本只是十次工具调用。

六、渐进式披露：一份被低估的加载账本

把五份文档的加载时机连起来看，会发现主文件的「薄」是精心设计的：

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 的工具集直接上生产，权限面需要人把关。

九、评测打分卡

十、五个可抄模式排行榜

不管你写不写 MCP，这五个模式都能直接搬进你自己的 SKILL.md：

1. 立场句开篇——第一段写清「什么叫做好」，给模型一把裁判尺；
2. 主薄辅厚、按阶段加载——主文件只放流程与裁决，细节绑阶段按需 load，SDK 文档干脆运行时拉最新；
3. 出卷人先做题——要求交付前自建可验证的评测题并亲手做一遍，让「能用」从声明变成证据；
4. 报错给下一步——把「可行动的错误信息」写成硬规范，模型自我修复的成功率直接决定产物质量；
5. 选型理由写给执行者——推荐 TS 的理由是「模型写得好」，不是「TS 更流行」，说服对象错了，理由再对也白搭。

十一、安装与使用

# 方式一：从官方仓库手动安装
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 — 官方 Skills 仓库，mcp-builder 随 example-skills 集分发
2. example-skills:mcp-builder SKILL.md 全文（anthropic-agent-skills 插件本地安装包，本文逐段拆解的原始底稿）
3. Model Context Protocol 规范站 — Skill 内置的自导航文档入口，含协议规范与传输机制章节
4. modelcontextprotocol/typescript-sdk — Skill 在 Phase 1/2 运行时拉取的 TS SDK 文档源
5. MCP 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 等场景全覆盖。