前言¶
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」，即可體驗這套官方流程。
