build-mcp-server

构建一个 MCP 服务

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

先加载 Claude 专属上下文。 MCP 规范是通用的；Claude 有额外的认证类型、审核标准和限制。在回答问题或搭建脚手架之前，先获取 https://claude.com/docs/llms-full.txt（Claude connector 文档的完整导出），让你的指导反映 Claude 的实际约束。

在得到阶段 1 中问题的答案之前，不要开始搭建脚手架。如果用户的开场消息已经回答了这些问题，请确认这一点，然后直接跳到推荐部分。

---

阶段 1 — 追问用例

以对话方式提出这些问题（把它们合并到一条消息中，不要一次问一个）。根据用户已经告诉你的内容调整措辞。

1. 它连接到什么？

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

2. 谁将使用它？

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

3. 它暴露多少个不同的操作？

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

• 约 15 个操作以下 → 每个操作一个工具
• 几十到几百个操作（例如包装一个大型 API 表面）→ 搜索 + 执行模式

4. 工具是否需要在调用过程中获取用户输入或进行丰富显示？

• 简单的结构化输入（从列表中选择、输入一个值、确认）→ Elicitation——规范原生，无需 UI 代码。宿主支持正在逐步推出（Claude Code ≥2.1.76）——始终搭配能力检查和回退方案。参见 references/elicitation.md。
• 丰富 / 可视化 UI（图表、带搜索的自定义选择器、实时仪表盘）→ MCP app 组件——基于 iframe，需要 @modelcontextprotocol/ext-apps。参见 build-mcp-app skill。
• 两者都不需要 → 返回文本 / JSON 的普通工具。

5. 上游服务使用什么认证？

• 无 / API key → 简单直接
• 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，可在任何宿主上运行）

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

如果某个工具只需要用户确认、选择选项或填写简短表单，elicitation 无需任何 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 中渲染。

在以下情况选择此方案：elicitation 的扁平表单约束不适用——你需要自定义布局、大型可搜索列表、可视化内容或实时更新。

通常是远程的，但如果 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 的路径。

交接时，用一段话重述设计简报，以免下一个技能重复询问。

---

工具之外 — 其他原语

工具是三种服务端原语之一。大多数服务从工具起步，永远不需要其他原语，但了解它们的存在可以避免重复造轮子：

原语	由谁触发	适用场景
资源	宿主应用（不是 Claude）	将文档/文件/数据作为可浏览的上下文暴露
提示词	用户（斜杠命令）	预置工作流（"/summarize-thread"）
引导输入	服务端，在工具执行中途	无需构建 UI 即可向用户索取输入
采样	服务端，在工具执行中途	需要在工具逻辑中进行大模型推理

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

---

阶段 6 — 在 Claude 中测试并发布

服务运行起来后：

1. 针对真实 Claude 进行测试：在设置 → 连接器中，将服务 URL 添加为自定义连接器（本地服务请使用 Cloudflare 隧道）。Claude 在初始化时会通过 clientInfo.name: "claude-ai" 表明自身身份。→ https://claude.com/docs/connectors/building/testing
2. 运行提交前检查清单 — 读/写工具拆分、必需的注解、名称限制、提示词注入规则。→ https://claude.com/docs/connectors/building/review-criteria
3. 提交至 Anthropic Directory。 → https://claude.com/docs/connectors/building/submission
4. 建议同时发布一个插件，用技能包装此 MCP — 大多数合作伙伴两者都会发布。→ https://claude.com/docs/connectors/building/what-to-build

---

快速参考：决策矩阵

场景	部署方式	工具模式
包装一个小型 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 易于理解的工具描述和 schema
• references/auth.md — OAuth、CIMD、DCR、令牌存储模式
• references/resources-and-prompts.md — 两种非工具原语
• references/elicitation.md — 规范原生的工具执行中途用户输入（能力检查 + 回退）
• references/server-capabilities.md — instructions、sampling、roots、logging、progress、cancellation
• references/versions.md — 版本敏感声明台账（更新时检查）