build-mcp-server

构建 MCP 服务

你将引导开发者设计并构建一个能与 Claude 无缝协作的 MCP 服务。MCP 服务有多种形式——过早选错类型，之后会导致痛苦的重写。你的首要任务是探索需求，而不是编写代码。

在得到第 1 阶段问题的答案之前，不要开始搭建脚手架。如果用户的开场消息已经回答了这些问题，请确认这一点，并直接给出建议。

适用场景

• 用户要求构建、创建或搭建 MCP 服务脚手架
• 用户想封装 REST/GraphQL API，以便与 Claude 配合使用
• 用户想通过 MCP 暴露工具、资源或提示词
• 用户正在选择部署模式（远程 HTTP、MCPB、本地 stdio）
• 用户正在为 MCP 集成设计工具架构

工作流概览

Phase 1: Discovery → Phase 2: Deployment model → Phase 3: Tool pattern → Phase 4: Framework → Phase 5: Scaffold

每个阶段都会进一步缩小设计范围。完成第 5 阶段后，转交给合适的脚手架参考资料或配套技能。

先决条件

• TypeScript 路径： Node.js >= 18、npm
• Python 路径： Python >= 3.10、pip
• 测试： npx（随 npm 一同提供）——供 scripts/test-server.sh 和 MCP Inspector 使用

---

第 1 阶段 — 探索用例

以对话方式提出这些问题（将问题合并到一条消息中，不要逐个提问）。根据用户已经告知的信息调整措辞。

1. 它要连接到什么？

如果连接到……	可能的方向
云 API（SaaS、REST、GraphQL）	远程 HTTP 服务
本地进程、文件系统或桌面应用	MCPB 或本地 stdio
硬件、操作系统级 API 或特定用户的状态	MCPB
没有外部连接——纯逻辑/计算	两者皆可——默认选择远程

2. 谁会使用它？

• 只有我/我的团队，在我们的机器上使用 → 本地 stdio 可以接受（最容易进行原型开发）
• 任何安装它的人 → 远程 HTTP（强烈推荐）或 MCPB（如果必须在本地运行）
• 想要 UI 小组件的 Claude 桌面版用户 → MCP 应用（远程或 MCPB）

3. 它会提供多少个不同的操作？

这决定了工具设计模式——见第 3 阶段。

• 少于约 15 个操作 → 每个操作对应一个工具
• 数十到数百个操作（例如封装大型 API）→ 搜索 + 执行模式

4. 工具是否需要在调用期间获取用户输入或展示丰富内容？

• 简单的结构化输入（从列表中选择、输入值、确认）→ Elicitation——规范原生支持，无需编写 UI 代码。主机支持正在逐步推出（Claude Code ≥2.1.76）——务必同时进行能力检查并提供回退方案。见 references/elicitation.md。
• 丰富/可视化 UI（图表、带搜索功能的自定义选择器、实时仪表盘）→ MCP 应用小组件——基于 iframe，需要 @modelcontextprotocol/ext-apps。见 build-mcp-app 技能。
• 两者皆非 → 返回文本/JSON 的普通工具。

5. 上游服务使用什么身份验证方式？

• 无 / API 密钥 → 直接处理
• OAuth 2.0 → 需要支持 CIMD（首选）或 DCR 的远程服务；见 references/auth.md

---

第 2 阶段 — 推荐部署模式

根据答案，推荐一条路径。明确给出建议。选项按优先级排序：

远程 streamable-HTTP MCP 服务（默认推荐）

托管服务，通过 streamable HTTP 传输 MCP。这是封装任何云 API 时的推荐路径。

优势：

• 安装零阻力——用户添加 URL 即可
• 一次部署即可服务所有用户；你可以控制升级
• OAuth 流程能正常工作（服务可以处理重定向、DCR 和令牌存储）
• 适用于 Claude 桌面版、Claude Code、Claude.ai 和第三方 MCP 主机

除非服务必须访问用户的本地机器，否则请选择此方案。

→ 最快部署： Cloudflare Workers——references/deploy-cloudflare-workers.md（两条命令即可获得可用 URL） → 可移植的 Node/Python： references/remote-http-scaffold.md（Express 或 FastMCP，可在任何主机上运行）

征询（结构化输入，无需构建 UI）

如果工具只需要用户确认、选择一个选项或填写简短表单，征询即可实现，无需编写任何 UI 代码。服务端发送扁平 JSON schema；宿主会渲染原生表单。这是规范原生支持的功能，无需额外依赖包。

注意： 宿主支持刚刚推出（Claude Code 在 v2.1.76 中发布了该功能；Desktop 尚未确认支持）。如果客户端未声明该能力，SDK 会抛出异常。请务必先检查 clientCapabilities.elicitation，并准备好后备方案——标准模式见 references/elicitation.md。这是符合规范的正确做法；宿主支持范围会逐步扩大。

如果需要嵌套/复杂数据、可滚动/可搜索的列表、视觉预览或实时更新，请升级使用 build-mcp-app 小组件。

MCP app（远程 HTTP + 交互式 UI）

与上面相同，另加UI 资源——在聊天中渲染的交互式小组件。可提供带搜索功能的丰富选择器、图表、实时仪表板和视觉预览。构建一次，即可在 Claude 和 ChatGPT 中渲染。

选择此方案的情况： 征询的扁平表单限制不适用——你需要自定义布局、大型可搜索列表、视觉内容或实时更新。

通常采用远程部署，但如果 UI 需要驱动本地应用，也可以作为 MCPB 交付。

→ 移交给 build-mcp-app 技能。

MCPB（捆绑式本地服务）

将本地 MCP 服务与其运行时打包在一起，让用户无需安装 Node/Python。这是交付本地服务的官方支持方式。

选择此方案的情况： 服务必须在用户的计算机上运行——它要读取本地文件、驱动桌面应用、与 localhost 服务通信，或需要操作系统级访问权限。

→ 移交给 build-mcpb 技能。

本地 stdio（npx / uvx）——不建议用于分发

在用户计算机上通过 npx / uvx 启动的脚本。适合个人工具和原型。分发起来很麻烦：用户需要安装正确的运行时，你无法推送更新，而且唯一的分发渠道是 Claude Code 插件。

仅建议将其作为过渡方案。如果用户坚持使用，请搭建项目骨架，但要说明升级到 MCPB 的路径。

---

第 3 阶段——选择工具设计模式

每个 MCP 服务都会公开工具。工具的划分方式比大多数人预想的更重要——工具 schema 会直接进入 Claude 的上下文窗口。

模式 A：每个操作对应一个工具（小型工具集）

如果操作空间较小（少于约 15 个操作），请为每项操作提供专用工具，并采用精简的描述和 schema。

create_issue    — Create a new issue. Params: title, body, labels[]
update_issue    — Update an existing issue. Params: id, title?, body?, state?
search_issues   — Search issues by query string. Params: query, limit?
add_comment     — Add a comment to an issue. Params: issue_id, body

有效原因： Claude 只需读取一次工具列表，就能准确了解有哪些操作。无需往返发现。每个工具的 schema 都能精确验证输入。

尤其适用于： 一个或多个工具附带交互式小组件（MCP app）——每个小组件都能自然地绑定到一个工具。

模式 B：搜索 + 执行（大型工具集）

如果要封装大型 API（数十到数百个端点），将每项操作都列为工具会占满上下文窗口，降低模型性能。此时应公开两个工具：

search_actions  — Given a natural-language intent, return matching actions
                  with their IDs, descriptions, and parameter schemas.
execute_action  — Run an action by ID with a params object.

服务端在内部保存完整目录。Claude 先搜索，再选择并执行。上下文保持精简。

混合模式： 将使用频率最高的 3–5 项操作设为专用工具，其余大量低频操作则通过搜索/执行处理。

→ schema 示例和描述编写指南见 references/tool-design.md。

---

第 4 阶段——选择框架

建议从以下两个框架中选择。虽然还有其他框架，但这两个对 MCP 规范的覆盖最全面，也与 Claude 兼容性最佳。

框架	语言	适用场景
官方 TypeScript SDK（@modelcontextprotocol/sdk）	TS/JS	默认选择。规范覆盖最全面，新功能也最先支持。
FastMCP 3.x（PyPI 上的 fastmcp）	Python	用户偏好 Python，或需要封装 Python 库时。基于装饰器，样板代码极少。这是 jlowin 的包——不是官方 mcp SDK 中冻结的 FastMCP 1.0。

如果用户已经确定了语言/技术栈，就按用户的选择来——两者生成的线路协议完全相同。

---

阶段 5 — 搭建脚手架并移交

确定四项决策（部署模式、工具模式、框架、身份验证）后，执行以下一项操作：

1. 远程 HTTP，无 UI → 使用 references/remote-http-scaffold.md（可移植）或 references/deploy-cloudflare-workers.md（部署最快）就地搭建脚手架。此技能可以完成整个任务。
2. MCP 应用（UI 小组件） → 总结目前的决策，然后加载 build-mcp-app 技能。
3. MCPB（捆绑式本地应用） → 总结目前的决策，然后加载 build-mcpb 技能。
4. 本地 stdio 原型 → 就地搭建脚手架（最简单的情况），并指出升级到 MCPB 的路径。

移交时，用一段话重述设计概要，避免下一个技能重复询问。

验证服务

搭建脚手架后，验证服务是否正常响应：

# Start the server first (e.g. npx tsx src/server.ts or python server.py)
# Then smoke-test it:
bash scripts/test-server.sh http://localhost:3000/mcp

测试脚本通过 MCP Inspector 调用 tools/list，并检查服务是否至少返回一个工具。如果通过，说明服务已正确接入。

---

工具之外——其他原语

工具是服务的三种原语之一。大多数服务从工具开始，之后不需要其他原语；但了解它们的存在有助于避免重复造轮子：

原语	触发者	适用场景
资源	宿主应用（而非 Claude）	将文档／文件／数据作为可浏览的上下文提供
提示词	用户（斜杠命令）	预设工作流（“/summarize-thread”）
引导请求	服务，在工具执行期间	无需构建 UI 即可向用户征求输入
采样	服务，在工具执行期间	工具逻辑需要大模型推理

→ references/resources-and-prompts.md、references/elicitation.md、references/server-capabilities.md

---

快速参考：决策矩阵

场景	部署方式	工具模式
封装小型 SaaS API	远程 HTTP	每个操作一个工具
封装大型 SaaS API（50+ 个端点）	远程 HTTP	搜索 + 执行
带有丰富表单／选择器的 SaaS API	MCP 应用（远程）	每个操作一个工具
驱动本地桌面应用	MCPB	每个操作一个工具
带有聊天内 UI 的本地桌面应用	MCP 应用（MCPB）	每个操作一个工具
读取／写入本地文件系统	MCPB	取决于使用场景
个人原型	本地 stdio	选择最快的方式

---

参考文件

到达相关阶段时再阅读这些文件，无需提前阅读：

• references/remote-http-scaffold.md — 使用 TS SDK 和 FastMCP 搭建最简远程服务
• references/deploy-cloudflare-workers.md — 最快的部署路径（Workers 原生脚手架）
• references/tool-design.md — 编写 Claude 能够充分理解的工具描述和架构
• references/auth.md — OAuth、CIMD、DCR、令牌存储模式
• references/resources-and-prompts.md — 两种非工具原语
• references/elicitation.md — 规范原生的工具执行期间用户输入（能力检查 + 回退方案）
• references/server-capabilities.md — 指令、采样、根目录、日志、进度、取消
• references/versions.md — 版本敏感声明清单（更新时检查）