前言¶
MCP（Model Context Protocol）已经成为 Cursor、Claude Code 等 AI 编程工具连接外部 API 与服务的标准协议。GitHub、数据库、Slack、Jira——只要封装成 MCP Server，Agent 就能在对话里直接调用。但「能跑」和「好用」之间往往隔着不少细节：工具命名是否清晰、错误信息是否可操作、分页与鉴权是否规范，这些都会直接影响 LLM 能否稳定完成真实任务。
Anthropic 在官方 Skills 仓库里提供了一个面向开发者的 mcp-builder Skill。它不是某个现成的 MCP 服务，而是一份结构化的 MCP 服务器开发指南——从协议研读、项目脚手架，到工具注册、测试与评测，按阶段引导 Agent 产出可维护的服务端代码。本文基于官方 SKILL.md 与配套参考文档，梳理这个 Skill 的定位、安装方式与核心工作流。
这是什么¶
mcp-builder 是 anthropics/skills 仓库中 skills/mcp-builder/ 目录下的 Agent Skill，由 Anthropic 维护，遵循通用 SKILL.md 格式，可在 Cursor、Claude Code、Codex CLI 等支持 Agent Skills 的工具中使用。
Skill 的 YAML 描述如下：
name: mcp-builder
description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
一句话概括：当你需要把某个外部 API 或服务封装成 MCP Server 时，启用这个 Skill，Agent 会按官方最佳实践分阶段完成设计与实现。Skill 本体采用渐进式披露设计——主文件 SKILL.md 给出四阶段总流程，详细规范则放在 reference/ 子目录（如 mcp_best_practices.md、node_mcp_server.md、python_mcp_server.md、evaluation.md），Agent 按需加载，避免一次性塞满上下文。
核心功能与亮点¶
四阶段开发工作流¶
官方流程分为四个阶段，覆盖从调研到验收的完整链路：
| 阶段 | 目标 | 关键动作 |
|---|---|---|
| Phase 1：深度调研与规划 | 理解 MCP 设计与目标 API | 阅读协议文档、选定语言栈、规划工具清单 |
| Phase 2：实现 | 编写可运行的 MCP Server | 搭建项目结构、实现工具、配置输入/输出 Schema |
| Phase 3：审查与测试 | 保证代码质量 | 编译检查、用 MCP Inspector 联调 |
| Phase 4：创建评测 | 验证 LLM 能否有效使用 | 设计 10 道独立、只读、可验证的评测题 |
Phase 1 强调在「全面 API 覆盖」与「专用工作流工具」之间做权衡：不确定时优先覆盖更多端点，让 Agent 灵活组合；工具命名建议带服务前缀、动词开头，例如 github_create_issue、slack_send_message。
双语言栈支持¶
Skill 同时覆盖两条官方推荐技术路线：
- TypeScript（推荐）：使用
@modelcontextprotocol/sdk，配合 Zod 做输入校验，server.registerTool()注册工具；远程部署优先 Streamable HTTP，本地集成用 stdio。 - Python：使用 Python SDK / FastMCP，Pydantic 定义 Schema，
@mcp.tool装饰器注册工具。
两种栈均要求：异步 I/O、可操作的错误信息、分页支持，以及 readOnlyHint、destructiveHint 等工具注解。
内置最佳实践参考库¶
reference/mcp_best_practices.md 汇总了命名、响应格式、分页、传输层与安全等规范，例如：
- 服务器命名：Python 用
{service}_mcp，TypeScript 用{service}-mcp-server - 列表类工具默认分页 20–50 条，返回
has_more、next_offset - API Key 放环境变量，禁止硬编码；stdio 模式日志写 stderr，避免污染 stdout
评测驱动的质量闭环¶
Phase 4 要求为完成的 MCP Server 编写 10 道评测题，每题需满足：独立、只读、复杂（多步工具调用）、贴近真实场景、答案唯一且稳定。输出为 XML 格式的 QA 对，便于脚本批量跑测——这是官方强调、但不少自建 MCP 容易忽略的一环。
安装与启用¶
Agent Skill 基于目录 + SKILL.md 的通用格式，各工具安装路径略有差异，但思路一致：把 mcp-builder 文件夹放到 Skills 扫描目录。
Cursor¶
Cursor 会在启动时自动发现以下位置的 Skill：
| 路径 | 作用域 |
|---|---|
.cursor/skills/ |
项目级 |
~/.cursor/skills/ |
用户级（全局） |
操作步骤：
- 克隆或下载官方仓库中的
skills/mcp-builder目录（需保留reference/子目录及全部参考文件）。 - 放入项目的
.cursor/skills/mcp-builder/，或用户目录~/.cursor/skills/mcp-builder/。 - 重启 Cursor 或在设置 → Rules 中确认 Skill 已被发现。
- 在 Agent 对话中直接描述需求（如「帮我写一个连接 GitHub Issues 的 MCP Server」），Agent 会根据
description自动匹配；也可输入/mcp-builder手动触发。
也可通过 Cursor 设置 → Rules → Add Rule → Remote Rule (Github)，填入 https://github.com/anthropics/skills 从远程导入（需自行定位到 mcp-builder 子目录或整库安装后选用）。
Claude Code¶
在 Claude Code 中可通过 Plugin 市场安装 Anthropic 官方 Skills 合集：
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills
安装后，在对话中提及 MCP 服务器开发需求即可触发；若 Plugin 包未包含 mcp-builder，可手动将目录复制到 Claude Code 的 Skills 路径。
Codex CLI / 其他兼容工具¶
Cursor 文档说明，为兼容 Claude 与 Codex 生态，以下路径同样会被扫描：.claude/skills/、.codex/skills/ 及对应的用户级目录。将 mcp-builder 文件夹放入任一有效路径即可。
典型用法示例¶
启用 Skill 后，向 Agent 提出明确的集成目标。以下是基于官方指南整理的可复现提示词与预期行为。
示例 1：从零搭建 TypeScript MCP Server¶
请使用 mcp-builder 技能，帮我创建一个连接 Stripe API 的 MCP Server。
要求：TypeScript + Streamable HTTP，至少实现 list_customers 和 create_payment_intent 两个工具。
Agent 按 Skill 流程通常会：
- 拉取 MCP 协议与 TypeScript SDK 文档；
- 初始化
{service}-mcp-server项目结构； - 用 Zod 定义
inputSchema，registerTool注册工具； - 运行
npm run build，建议用 Inspector 测试：
npx @modelcontextprotocol/inspector
示例 2：Python FastMCP 本地 stdio 服务¶
用 mcp-builder 指南，写一个 Python MCP Server，通过 stdio 暴露公司内部 REST API 的查询接口。
工具名要带服务前缀，列表接口需要分页。
预期实现要点（来自官方 Python 指南）：
# 工具注册示意（具体以 SDK 版本为准）
@mcp.tool()
async def myapi_list_items(limit: int = 20, offset: int = 0) -> dict:
"""List items with pagination. Returns has_more and next_offset."""
...
语法检查：
python -m py_compile your_server.py
示例 3：完成后编写评测集¶
MCP Server 已实现，请按 mcp-builder 的 evaluation 指南，为现有工具生成 10 道只读评测题，输出 XML。
评测题格式示例（摘自官方 SKILL.md）：
<evaluation>
<qa_pair>
<question>Find the repository with the most open issues created in the last 30 days. How many issues does it have?</question>
<answer>42</answer>
</qa_pair>
<!-- 共 10 组 qa_pair -->
</evaluation>
适用场景与注意事项¶
适合谁用¶
- 需要把私有或第三方 REST/GraphQL API 封装给 Cursor、Claude Code 等 Agent 使用的后端/全栈开发者；
- 已了解 MCP 基本概念，希望按官方命名、分页、错误处理规范落地，而不是复制零散教程的团队；
- 计划在 MCP Server 上线前做 LLM 可用性评测，减少「工具注册了但 Agent 调不对」的情况。
使用限制¶
- Skill 是指南，不是生成器：它不会一键产出成品 Server，而是引导 Agent 分阶段读写文档、写代码；最终质量仍取决于目标 API 复杂度与你的验收标准。
- 参考文件必须完整：
reference/下的 Markdown 是渐进式加载的核心依赖，只复制SKILL.md会导致 Agent 缺少实现细节。 - 安全自行把关：Skill 会提示 OAuth、环境变量、输入校验等实践，但接入生产 API 前仍需人工审计权限范围与网络暴露面；Anthropic 官方 Skills 仓库也声明示例仅供学习演示。
- 与 MCP 客户端配置分离：本 Skill 解决「如何写 Server」；在 Cursor 里把写好的 Server 配进
mcp.json属于客户端集成，需另按各工具文档操作。
与 Agent Skills 生态的关系¶
Anthropic 工程博客指出，Agent Skills 侧重教 Agent 复杂工作流与领域知识，可与 MCP Server 提供的外部工具能力互补——mcp-builder 恰好站在交叉点：用 Skill 方法论，产出 MCP 工具链。2025 年 12 月 Agent Skills 已作为开放标准发布（agentskills.io），跨 Cursor、Claude Code 等平台移植成本较低。
结尾¶
如果你正在为 AI 编程工具扩展「可调用的外部能力」，mcp-builder 是目前少有的、由 MCP 协议主要推动方 Anthropic 维护的端到端开发 Skill。它把协议阅读、双语言实现、Inspector 测试和 LLM 评测串成一条可重复的工作流，比零散搜教程更成体系。
建议从官方仓库获取完整目录：
- Skill 主页：https://github.com/anthropics/skills/tree/main/skills/mcp-builder
- Agent Skills 背景：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
- MCP 协议站点：https://modelcontextprotocol.io
克隆 skills/mcp-builder 到 .cursor/skills/，下次让 Agent「帮我写一个 XX 的 MCP Server」，即可体验这套官方流程。
