# 官方 mcp-builder 逐段拆解：一个把「验收测试」写进出厂流程的建造 Skill ## 概述 本期是第 2 轮单 Skill 深度拆解，对象是 Anthropic 官方 example-skills 套装中的 **mcp-builder**——教 Claude 从零造一个 MCP（Model Context Protocol）服务器的技能。它值得拆有三个理由：其一，它是官方出品、随 example-skills 插件分发的「同门」件，与此前拆过的 skill-creator 属于同一仓库血统，但定位完全不同——skill-creator 教造 Skill，mcp-builder 教造让 Agent 用的协议网关；其二，它的 SKILL.md 展示了教科书级的**按阶段渐进加载**设计，正文只有薄薄一层路由，四份 reference 文件各自标注了加载时机；其三，它把多数社区 Skill 从来不做的「评测验收」写成了硬性出厂环节，要求出 10 道可字符串比对的测试题。本文引用的 SKILL.md 原文逐段取自本机安装的官方插件包（与 anthropics/skills 仓库同源），以下拆到每一段的设计意图。 ## 先看它把自己定义成什么 SKILL.md 开篇只有一句定位： > 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. 注意这个质量标准的转向：不是「服务器能不能跑通」，而是「LLM 拿着它能不能干成实事」。这句话埋在第一屏，后面所有设计——工具命名规范、聚焦的数据返回、可执行的错误信息、评测题的出法——全部由它推导出来。写 SKILL.md 的人应该学到：**先定义「什么叫好」，再写「怎么做」，模型的每个决策才有锚点。** ## 四阶段流水线：SKILL.md 的骨架 正文主体是一个 `# Process` 大节，把造服务器拆成四个 Phase。先看全景： ```mermaid flowchart TD A["Phase 1 深度研究与规划"] --> B["Phase 2 实现"] B --> C["Phase 3 审查与测试"] C --> D["Phase 4 创建评测"] A --> A1["读 MCP 规范
sitemap.xml + .md 后缀"] A --> A2["读框架文档
mcp_best_practices.md"] A --> A3["技术选型拍板
TS + streamable HTTP"] B --> B1["项目结构
node_mcp_server.md / python_mcp_server.md"] B --> B2["核心基建四件套
API客户端/错误/格式化/分页"] B --> B3["逐个实现工具
Zod/Pydantic + annotations"] C --> C1["npm run build 或 py_compile"] C --> C2["MCP Inspector 实测"] D --> D1["evaluation.md"] D --> D2["10 道只读评测题
XML 格式 + 自验答案"] ``` 这个流程图里藏着 SKILL.md 最重要的结构决策：**每个 Phase 都明确指向该加载哪份 reference 文件**。四份文件的加载时机在正文里被逐个写死： | reference 文件 | 正文标注的加载时机 | |---|---| | `reference/mcp_best_practices.md` | Load First（Phase 1） | | `reference/node_mcp_server.md` | Load During Phase 1/2（TypeScript 路线） | | `reference/python_mcp_server.md` | Load During Phase 2（Python 路线） | | `reference/evaluation.md` | Load During Phase 4 | 这就是「渐进披露」的完整形态：SKILL.md 自己不教怎么写代码，它只做三件事——定标准、排流程、当路由器。上下文窗口是稀缺资源，一次造服务器的会话根本不需要同时装载评测指南和 Python 指南，按阶段供料把浪费压到了最低。链接文字还配了 emoji 视觉锚点（📋 最佳实践、⚡ TypeScript、🐍 Python、✅ 评测），模型扫索引时一眼可辨。 ## Phase 1 逐段拆：原则、导航术、和「替你拍板」 ### 1.1 四条现代设计原则 开篇第一段讲「API 覆盖 vs 工作流工具」的取舍，原文给了一个非常有性格的结论： > When uncertain, prioritize comprehensive API coverage. 它先承认两类工具各有适用面（工作流工具对特定任务更顺手，全覆盖给 Agent 自由组合的空间），承认性能因客户端而异，然后在「拿不准」的情况下直接给出默认答案。这是官方 Skill 和大量社区 Skill 的分水岭：**社区 Skill 爱罗列选项让模型自己挑，官方 Skill 替你把架构决策做了**。对一个要产出一致质量的技能来说，给默认答案几乎总是对的。 随后三条原则同样可直接抄进任何工具型 Skill 的写作清单： - **命名可发现**：`github_create_issue`、`github_list_repos` 这种「前缀_动作」命名，让 Agent 靠扫名字就能归组。 - **上下文管理**：工具要返回聚焦数据、支持过滤和分页——因为 Agent 的上下文同样是钱。 - **可执行的错误信息**：报错要「guides agents toward solutions with specific suggestions and next steps」，错误信息本身就是给模型看的提示词。 ### 1.2 一段值得单独抄的「文档导航术」 1.2 节教模型怎么读 MCP 协议文档，手法是两步：先抓 `https://modelcontextprotocol.io/sitemap.xml` 定位相关页面，再给目标 URL 加 `.md` 后缀拿到 Markdown 原文。这个技巧被写成了确定性操作指令而不是「参考资料见链接」——它内置的不是过期文档，而是**抓最新文档的指令**。同样的思路出现在 1.3 节：TypeScript SDK 和 Python SDK 的 README 都要求用 WebFetch 现场从 `raw.githubusercontent.com` 拉 main 分支版本。技能文档最怕写死版本号然后腐烂，这个设计直接绕开了腐烂问题。 ### 1.3 选型段：四个理由支撑一个默认答案 推荐技术栈写得很满：语言选 TypeScript，理由原文列了四条——SDK 质量高、在 MCPB 等执行环境兼容性好、模型生成 TypeScript 的能力强（受益于语料充足、静态类型和 lint 工具链）。传输层也是二话不说：远程服务器用 streamable HTTP，并且明确选**无状态 JSON**（stateless）而非有状态会话，理由是「simpler to scale and maintain」；本地服务器才用 stdio。注意它连「无状态优先」这种运维层面的偏好都替使用者决定了——这是典型的「官方替你踩过坑」写法。 1.4 收尾于规划：读目标服务的 API 文档，识别端点、鉴权、数据模型，列出要实现的端点清单，从最常用操作做起。一句话把 Phase 1 的产出物（一份端点清单）固定下来，Phase 2 才有得 implementing。 ## Phase 2 逐段拆：工具实现的五要素 实现阶段把项目结构外包给两份语言指南（各含完整的可运行示例和质量清单），SKILL.md 正文只留「每个工具都要过」的横切要求，一共五件： 1. **输入 Schema**：Zod（TS）或 Pydantic（Py），字段描述里带约束和示例； 2. **输出 Schema**：尽可能定义 `outputSchema`，用 `structuredContent` 返回结构化数据——正文特意注明这是 TypeScript SDK 的特性，让客户端不必从自然语言里猜结构； 3. **工具描述**：功能一句话、参数逐个说清、写明返回结构； 4. **实现质量**：I/O 全异步、错误处理到位、支持分页； 5. **Annotations 四连**：`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`。 第五件最值得展开。这四个 hint 是 MCP 规范里的工具注解，作用是让宿主客户端**在调用前**就能预判副作用——这个工具会不会改数据？危不危险？重复合并幂等吗？依赖开放世界假设吗？把「必须声明注解」写成硬要求，等于强制每个产出物都对齐协议的能力面，这是从「能跑就行」到「工程交付物」的又一道分界线。 ## Phase 4：全文最罕见的部分——把验收写进出厂流程 Phase 3（DRY 检查、`npm run build` 或 `python -m py_compile` 验证、用 `npx @modelcontextprotocol/inspector` 起官方 Inspector 实测）属于常规操作。真正让这个 Skill 和 99% 社区 Skill 拉开差距的是 Phase 4：**实现完成不是终点，评测才是**。 它要求为造好的服务器出 **10 道评测题**，每道题必须同时满足六条硬性要求： - **独立**：不依赖其他题的中间状态； - **只读**：只需非破坏性操作即可作答； - **复杂**：需要多次工具调用和深入探索才能答出； - **真实**：基于人类真的会在意的场景； - **可验证**：答案唯一，且能用字符串比较自动判分； - **稳定**：答案不随时间漂移。 更狠的是这句：**Solve each question yourself to verify answers**——出题者必须自己先把每道题做一遍，确认答案成立才能写进评测文件。输出格式也定死了，是一个 XML 问答对文件： ```xml 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? 3 ``` 这道示例题本身就值得玩味：问的是「以花斑野猫命名的那个模型（Cheetah），确定 ASL 安全等级到第几级」，答案要求 Agent 真的去翻目标服务里的讨论帖、串联多跳信息才能得出「3」。这不是单元测试式的「调用成功返回 200」，而是**把 LLM 当用户的集成验收**——评测的对象不是代码，是「LLM 拿着这组工具能不能答出人类关心的问题」，正好呼应开篇那句质量定义。首尾闭环，这就是成熟 Skill 的样子。 ## 从这一个 Skill 能抄走的五个写法模式 1. **质量标准前置**：第一屏用一句话定义「什么叫好」，后续所有规则从它推导； 2. **给默认答案**：取舍类决策（覆盖 vs 工作流、TS vs Py、有状态 vs 无状态）直接拍板并给理由，不留给模型摇摆； 3. **按阶段渐进披露**：reference 文件不是附录，而是标注了「何时加载」的按需供料管线； 4. **技巧写成动作指令**：sitemap 定位 + `.md` 后缀、raw 地址现拉 SDK README——把防腐化机制内置成步骤，而不是内置一份会过期的摘要； 5. **出厂验收环节**：强制产出可自动判分的评测题，且出题人自验——把「软件要验收」的行业常识注入 Skill 生态。 ## 适用与不适用场景 **适合**：从零造一个要交付给团队或社区用的正经 MCP 服务器；给已有 REST API 做 Agent 入口；想给自己的服务器补一套可判分的评测。 **不适合**，也要说实话：其一，几十行的单工具小脚本不值得走四阶段，直接让模型写一个 FastMCP 文件更快，这套流程对玩具件是杀鸡用牛刀；其二，它的工作方式依赖**现场抓取**协议文档和 SDK README，离线或网络受限环境里能力会明显降级（本机参考指南仍在，但「文档保鲜」机制失效）；其三，正文不含任何成段代码，它本质是路由器——想直接抄代码示例得进 reference 文件，这是设计使然，但偏好「一页式」Skill 的人会觉得重。 ## 五维评分 （星级约定：1–5 星，上手难度一星为最高门槛，五星为最易上手） | 维度 | 评分 | 依据 | |---|---|---| | 功能完整度 | ★★★★★ | 四阶段全覆盖规划到验收，双语言路线，评测成体系 | | 设计质量 | ★★★★★ | 渐进披露教科书；默认答案+理由的决策风格；首尾质量定义闭环 | | 实战效果 | ★★★★ | 流程可靠、验收托底下限；但产物上限取决于目标 API 文档质量，且依赖联网抓取 | | 上手难度 | ★★★★ | 零配置，装上即用；四阶段对急用小件略重 | | 社区活跃度 | ★★★★ | 官方 example-skills 收录随仓库维护，工具要求随 MCP 规范同步（如 structuredContent）；本文不引实时 Star 数据 | 综合（按 25/25/20/15/15 加权）约 **4.6 / 5**，属于「可以直接当模板临摹」的那一档。 ## 安装与使用 官方仓库手动安装（通用可行）： ```bash git clone https://github.com/anthropics/skills mkdir -p ~/.claude/skills cp -r skills/mcp-builder ~/.claude/skills/ ``` 官方 example-skills 插件套装也直接收录了它（即 `example-skills:mcp-builder`），装了官方插件的用户无需单独安装。使用时在 Claude Code 里直接说「帮我写一个 MCP 服务器，封装 XX 的 API」，触发后它会自己走四阶段；造完后用 Phase 3 给的命令人工复核： ```bash npx @modelcontextprotocol/inspector ``` 想临摹写法，重点读它的三处：开篇质量定义、reference 的加载时机标注、Phase 4 的六条出题要求。 ## 参考来源 1. [anthropics/skills 官方 Skills 仓库](https://github.com/anthropics/skills) — mcp-builder 的上游仓库，本文拆解的 SKILL.md 与其同源（本机 example-skills 插件包逐段引用） 2. [MCP 协议站 sitemap](https://modelcontextprotocol.io/sitemap.xml) — Skill 内置的协议文档导航入口，`.md` 后缀取 Markdown 原文的技巧出处 3. [TypeScript SDK README（raw）](https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md) — Skill 要求现场抓取的 TS SDK 文档 4. [Python SDK README（raw）](https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md) — Skill 要求现场抓取的 Python SDK 文档 5. [skills.sh](https://skills.sh) — Skills 生态站，可用于对照社区侧同类「造 MCP」技能的分布 > [!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 等场景全覆盖。