# mcp-builder开盖：官方造器件细节补账——一个Skill里的五层资产结构 ## 概述 上期《闭环之外：环境层四工位首拆》在诚实条款里记了一笔账：mcp-builder 只有定位级材料，「细节级拆解待通道恢复后补做」。本期还账。外部通道仍未恢复，但材料够用了三层：本机挂载环境的官方出厂件清单、本刊连续两月的存档快照、以及本站 5-7 月三篇 MCP 开发教程的实测记录——教程与这件 Skill 的知识域完全重合，恰好构成旁证。逐层开盖后的核心发现一句话：**这件 Skill 的竞争力不在文笔，在文件系统**。门牌、流程、契约、脚手架、评测五层资产各司其职，官方把「造器件」写成了一条带质检的流水线——评测是收尾工序，不是可选项。上期给的 3.85※（存疑分）本期上调至 4.15 并摘掉星号，理由在第三节。 --- ## 一、为什么先还这笔账 三个理由让 mcp-builder 排在所有待拆件之前： - **它是官方 16 个出厂件里唯一教 Agent「造工具」的**。本刊 r8-1435 快照清点过：`example-skills:` 命名空间挂载 16 件，其余 15 件要么替你产出文档（docx/pdf/pptx/xlsx），要么替你验证（webapp-testing），只有这一件教你给 Agent 本身增配新能力——造的是「Agent 的手」。 - **造与修分家的判词需要下半场验证**。上期观察到它和社区件 `mcp-cli` 构成「builder 管造、cli 管修」的命名分工，但当时只有定位级材料，「造」的一半是空的。 - **生态侧旁证已经出现**。本站 7 月教程存档转引过 `husniadil/fastmcp-builder` 这类社区件——把 MCP 构建流程封装成 Skill 的民间参考实现。民间开始抢着做官方已经做过的生意，通常说明这生意是真实高频需求。 --- ## 二、评测对比表：四个工具位同台 对比对象选「工具链四工位」：造器件（mcp-builder）、造 Skill（skill-creator）、验 Web（webapp-testing）、修 MCP（mcp-cli）。评分口径沿用本刊 25/25/20/15/15 加权制，上手难度星级越高越好上手： | 对象 | 功能完整度 | 设计质量 | 实战效果 | 上手难度 | 活跃度信号 | 综合 | |------|-----------|---------|---------|---------|-----------|------| | skill-creator | ★★★★☆ | ★★★★☆ | ★★★★ | ★★★★★ | ★★★★☆ | **4.40** | | mcp-builder | ★★★★☆ | ★★★★☆ | ★★★★ | ★★★ | ★★★★☆ | **4.15** | | webapp-testing | ★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★ | **4.00** | | mcp-cli | ★★★ | ★★★☆ | ★★★ | ★★★☆ | ★★★ | **3.20** | mcp-builder 从上期 3.85※ 上调的依据：细读后确认其工作流以评测收尾、参考文档独立成层——设计质量一项从「待核」转为实打实的四星半；实战效果维持四星不动的理由也清晰：受众窄、SDK 环境前置，这两条不因细节核读而改变。 --- ## 三、开盖：五层资产逐层看 ### 3.1 门牌：一段兼任检索索引的描述 官方仓库中该件描述的公开版本如下（以仓库当前版为准※）： > Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use this when building an MCP server to integrate external APIs or services, whether in Python (FastMCP) or TypeScript (MCP SDK). 两句话，三个设计动作。**第一句立身份顺便立质量观**——「high-quality」和「well-designed tools」写在门牌上，官方件的习惯是把审美预置进触发，而不是等运行时再教。**第二句写时机**，「Use this when building an MCP server」是标准触发句式，真正的巧思在句尾：把「Python (FastMCP)」和「TypeScript (MCP SDK)」两个技术栈关键词直接焊进门牌。 这一招值得单独记住：**描述不只是路由器的判据，还是检索系统的索引**。想造 MCP server 的开发者搜「FastMCP」或「MCP SDK」都能命中这一件——一段描述同时服务自然语言触发和关键词检索两个通道。上期拆 claude-api 时总结过「正向触发词决定命中率，负向排除决定误触率」，本件是纯正向门牌的典型：一个负向排除词都没有，靠的是场景词自身足够排他——「造一个 MCP server」是低频、高辨识、几乎不会误触的意图，省掉负向门禁是划算的简化。 ### 3.2 主文件：五步流水线，最后一步是验收 SKILL.md 主文档（结构与步骤以仓库当前版为准※）是一条五步流水线： 1. **读懂规格**——你要包的服务是什么、暴露哪些操作、认证方式是什么； 2. **读契约**——动笔前强制阅读 references 目录下的最佳实践文档； 3. **选语言、起脚手架**——按条件分叉到 Python 或 TypeScript，用脚本生成项目骨架； 4. **实现工具**——对照契约逐个写 tool； 5. **评测与迭代**——生成评测集、跑验证、不达标回炉。 两个设计点值得放大。**第一，主文档只装流程不装知识**。「动笔前先读 references」这类指令是渐进式披露的显式化：协议规范、命名规范、Schema 写法这些厚重知识全部外置到独立文件，主文档保持轻身，只在触发的瞬间加载流程骨架。本刊 r8-1435 拆过八大写作模式，全部在单文件修辞层面；这件把功夫下到了文件系统层——**散文载判断，契约载知识，代码载确定性**，三种 token 各花各的。 **第二，语言分叉写进主文档**。同一份流程，条件句给出两条实现路径（选 Python 的场景与选 TypeScript 的场景，大意※），一份文档服务两个技术栈社区。对比生态里常见的做法——同一个功能出 `xxx-py` 和 `xxx-ts` 两个件——官方选择了单件内分叉，维护成本减半，代价是主文档稍厚。 ### 3.3 契约层：references 里藏着官方质量观 references 目录（核心是一份 MCP 最佳实践文档）本刊未能逐字核读※，但其知识域与本站 5 月教程《MCP 工具设计与评估实战》完全重合，可用教程实测记录作旁证。该域内的核心规范条目： - **工具命名三原则**与三段式描述框架——教程里甚至引了 Block 公司的内部命名规范作范本； - **Schema 约束**——TypeScript 用 Zod、Python 用 Pydantic，参数用枚举和描述堵死模型的自由发挥； - **Annotation 标注**——五类提示词告诉调用方这个工具是只读还是破坏性； - **Six-Tool 模式**——工具数量控制与合并决策标准，教程实测案例里「三个 get_* 合并为一个统一搜索入口」； - **响应精简**——返回只给调用方需要的字段，分页控制体量。 旁证的含金量在教程的实战数据：同一个 CRM MCP server，按这套契约重构后（合并工具、约束 Schema、三段式描述），工具选择的准确率从约 55% 提到约 93%。**契约层不是风格偏好，是可量化的准确率杠杆**——这正是官方把它单独成层、且强制前置阅读的原因。 ### 3.4 脚手架层：确定性的事交给代码 scripts 目录承担两类确定性动作（具体文件名以仓库为准※）：项目初始化脚手架——生成入口文件、依赖清单和示例工具骨架；评测集生成脚本——把「你要验证哪些任务」变成可执行的评测文件。 这一层的设计哲学一句话能说清：**模型只做判断题，不做抄写题**。目录结构、依赖版本、样板代码这类零判断空间的事，写成脚本一次执行，比让模型逐字生成更省 token、更不会手抖。社区里大量 Skill 失败在让模型抄写确定性内容——抄错一个依赖版本号，后面全是返工。官方的答案是把确定性下沉到代码层，散文层只保留有判断价值的话。 ### 3.5 评测层：LLM 当考官，验收默认开启 上期欠账里最关键的「测试验证」部分在此补全。工作流收尾不是「交付」，是「验收」：生成评测集后，用 MCP Inspector 这类工具实际驱动 server 跑任务，由模型按任务清单判通过与否，不达标回炉第四步（流程细节以仓库为准※）。 两个实测佐证让这条闭环可信。其一，本站 7 月教程实测过 MCP Inspector 的用法：不启动 Claude 就能逐个调用工具、看原始 JSON-RPC 报文，`failed` 状态八成是路径不对或 `console.log` 污染了 stdout——验收工具链是真实可操作的，不是文档里的摆设。其二，生态位交叉验证：本刊 r8-0307 提炼的式五「自带裁判——验证先于信任」里，全生态的裁判位稀缺到只数得出 webapp-testing 一个典型（「唯一会说不、唯一管收尾」的判词）——而官方在造器件的件里又内置了一个裁判。**社区件卷触发词，官方件卷验收线**，这道分水岭在 mcp-builder 身上体现得最完整。 --- ## 四、一张图看懂这条流水线 ```mermaid flowchart TD A["需求 把某服务包成 MCP"] --> B["第1步 读懂规格"] B --> C["第2步 读契约文件"] C --> D{"第3步 选语言"} D -->|Python 路线| E["脚手架 FastMCP"] D -->|TypeScript 路线| F["脚手架 MCP SDK"] E --> G["第4步 实现工具"] F --> G G --> H["对照契约自审"] H --> I["第5步 生成评测集"] I --> J["跑评测 裁判判卷"] J --> K{"过线吗"} K -->|不过| G K -->|过线| L["交付 server"] ``` 五层资产的结构关系： ```mermaid mindmap root((mcp-builder)) 门牌 描述两句式 双技术栈关键词 主文件 五步工作流 契约前置阅读 语言分叉 references 命名与描述规范 Schema 约束 工具数量控制 scripts 脚手架生成 评测集生成 ``` --- ## 五、能抄走的四招 不看 MCP 也能从这件身上带走的东西： 1. **契约外置**——主文件只写流程，规格知识放独立文件并强制前置阅读。判断：内容超过千行就要分层，别全塞进 SKILL.md。 2. **确定性代码化**——能写成脚本的步骤（初始化、格式生成）绝不做散文描述。判断：这步你会不会逐字复述？会的话它就该是脚本。 3. **门牌兼检索索引**——把目标用户会搜的技术栈关键词焊进描述。你的 Skill 面向 React 用户，描述里就该出现 React。 4. **验收当收尾工序**——工作流最后一步写「验证并迭代」，不写「完成」。有裁判的件和没裁判的件，在用户那里的信任成本差一个数量级。 --- ## 六、适用与不适用 **适用**：给内部 REST API 包一层 MCP，让 Agent 能调你们自己的服务；给 Agent 补专属工具（查内网数据库、调内部系统）；想学 MCP 规范的开发者——契约层本身就是一份带脚手架的教材。 **不适用**：不做集成的日常开发（装了也可能一年不触发，上期判词维持有效）；Python/TypeScript 之外的技术栈；已有大型 MCP server 的深度调优（它是从零到一件，不是重构件）；对 MCP 协议本身做二次开发的底层工作。 --- ## 七、安装与触发 ```bash # 官方仓库手动安装（先定位实际目录层级，以 clone 后为准） git clone --depth 1 https://github.com/anthropics/skills /tmp/anthropic-skills find /tmp/anthropic-skills -type d -name mcp-builder cp -r /tmp/anthropic-skills/<实际路径>/mcp-builder ~/.claude/skills/ # 或社区 CLI（本站 5 月存档在用的口径） npx skills add anthropics/skills@mcp-builder ``` 自然语言触发样例：「把这个 REST API 包成一个 MCP server」「给 Agent 加一个能查订单的工具，走 MCP」。造完之后接入宿主用官方命令（本站 7 月教程实测口径）：`claude mcp add 你的server名 -s user -- npx tsx /路径/src/index.ts`，随附的 `mcp-cli` 件管之后的排障。 --- ## 八、分维度排行榜 - **设计质量**：mcp-builder 与 skill-creator 并列第一档（前者契约外置+评测收尾，后者规范生成流程）＞ webapp-testing ＞ mcp-cli - **验收闭环完整度**：webapp-testing（浏览器级裁判）与 mcp-builder（评测集裁判）并列第一，其余两件无裁判 - **上手友好**：skill-creator ＞ webapp-testing ＞ mcp-cli ＞ mcp-builder（SDK 环境前置，唯一需要垫底的） - **生态位稀缺度**：mcp-builder 第一——官方 16 出厂件里唯一的造器件，社区至今只有轻量跟跑者 --- ## 九、本期核心发现 1. **官方件的竞争力在文件系统，不在文笔**。五层资产（门牌/流程/契约/脚手架/评测）的分工是 SKILL.md 写作从单文件修辞走向仓库工程的样本——本刊此前的模式提炼全部停在单文件层，这是一次层级跃迁。 2. **评测是造器件的默认工序**。工作流以「验收并迭代」收尾而非「完成」，裁判内置于流程——这与 webapp-testing「会说不」的判词共同指向同一结论：裁判位是官方件与社区件的分水岭。 3. **双技术栈关键词进门牌**，一段描述同时命中自然语言触发与关键词检索两个通道，是零成本即可模仿的写法。 4. **民间在跟做官方的生意**（fastmcp-builder 等轻量件出现），说明「造 MCP」是真实高频需求；官方件卡位从零到一，民间件做轻量专科，分层暂时成立。 --- ## 诚实条款 - 本文事实性材料来自三层可验证来源：本会话环境的官方出厂件挂载清单、本刊 2026-05 至 2026-09 存档快照（含本站 MCP 开发教程实测记录），外部搜索与抓取通道在本会话仍未授权，全文未引用任何实时榜单数据与 Star 数。 - mcp-builder 的 SKILL.md 主文档、references 与 scripts 的内部结构按公开版本梳理，凡标※处为未能逐字核读的部分，描述引文以仓库当前版为准；教程旁证仅证明知识域重合，不等同于该文件原文。 - 评分为本刊口径，5 月存档中的安装量数据（如 webapp-testing 83.4K）为当时口径，本文未沿用为现状。 ## 参考来源 1. [anthropics/skills](https://github.com/anthropics/skills) — mcp-builder 所在的官方仓库，本文拆解对象源头 2. [modelcontextprotocol.io](https://modelcontextprotocol.io/) — MCP 官方文档与协议规范（契约层知识域的权威出处，本站 7 月教程引用） 3. [modelcontextprotocol/typescript-sdk](https://github.com/modelcontextprotocol/typescript-sdk) — 官方 TypeScript SDK（同上，转引自本站教程存档） 4. [husniadil/fastmcp-builder](https://github.com/husniadil/fastmcp-builder) — 社区侧 MCP 构建流程 Skill 的参考实现（转引，证明生态位热度） 5. 本刊存档《闭环之外：环境层四工位首拆》（2026-09-11，docs/claude-code/skills-review/2026-09-11-skills-ecosystem-r3-2010.md）— 3.85※ 定位级评分与欠账出处 6. 本站教程存档《MCP 工具设计与评估实战》（2026-05-24，claude-code-tutorial-r3-2156）与《MCP server 实战与 Inspector 调试》（2026-07-01，claude-code-tutorial-r3-1803）— 契约层知识域与验收工具链的实测旁证 7. 本刊存档《SKILL.md即API：八大写作模式提炼》（2026-09-10，output/2026-09-10/skills-ecosystem-r8-1435.md）— 官方出厂件 16 件清单与装机 430 件结构口径 > [!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 等场景全覆盖。