SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场build-mcp-server

build-mcp-server

编程与开发

查看项目

更新于 10-30 16:19

技能介绍

用途

本技能用于在开发者设计并构建与 Claude 无缝协作的 MCP 服务器时提供引导。MCP 服务器有多种形态，早期选错形态会导致后期痛苦重写，因此首要任务是需求发现，而不是写代码。

在回答问题或搭建脚手架之前，应先加载 Claude 专属上下文：MCP 规范是通用的，而 Claude 有额外的认证类型、审核标准和限制。需先获取 https://claude.com/docs/llms-full.txt（Claude 连接器文档的完整导出），使指导反映 Claude 的实际约束。在未获得第一阶段问题答案前，不要开始搭建脚手架；若用户开场消息已回答，则确认并直接进入推荐。

主要能力

第一阶段 — 询问用例

以对话方式一次性批量提问，包括：

  1. 它连接什么？云 API（SaaS、REST、GraphQL）倾向远程 HTTP 服务器；本地进程、文件系统或桌面应用倾向 MCPB 或本地 stdio；硬件、操作系统级 API 或用户特定状态倾向 MCPB；无外部依赖的纯逻辑/计算两者皆可，默认远程。
  2. 谁将使用它？仅自己/团队在本机使用可接受本地 stdio（最易原型）；任何人安装则强烈推荐远程 HTTP，或必须本地时用 MCPB；Claude 桌面用户想要 UI 组件则用 MCP app（远程或 MCPB）。
  3. 暴露多少个不同动作？约 15 个以下用一动作一工具；数十到数百个（如包装大型 API）用搜索+执行模式。
  4. 工具是否需要调用中途用户输入或丰富显示？简单结构化输入（从列表选择、输入值、确认）用 Elicitation（规范原生，零 UI 代码，宿主支持正在铺开，Claude Code ≥2.1.76，需配合能力检查与回退）；丰富/可视化 UI（图表、带搜索的自定义选择器、实时仪表盘）用 MCP app 组件（基于 iframe，需 @modelcontextprotocol/ext-apps）；两者皆非则用返回文本/JSON 的普通工具。
  5. 上游服务使用什么认证？无/API 密钥较直接；OAuth 2.0 需要支持 CIMD（首选）或 DCR 的远程服务器。

第二阶段 — 推荐部署模型

按优先级推荐：

  • ⭐ 远程 streamable-HTTP MCP 服务器（默认推荐）：托管服务，通过 streamable HTTP 讲 MCP。零安装摩擦、一次部署服务所有用户、OAuth 流程正常、跨 Claude 桌面/Claude Code/Claude.ai 及第三方 MCP 宿主。最快部署用 Cloudflare Workers；可移植 Node/Python 用 Express 或 FastMCP。
  • Elicitation（结构化输入，无需构建 UI）：服务器发送扁平 JSON schema，宿主渲染原生表单。注意宿主支持较新，SDK 在客户端未声明能力时会抛错，须先检查 clientCapabilities.elicitation 并准备回退。需要嵌套/复杂数据、可滚动/可搜索列表、可视化预览、实时更新时升级到 MCP app 组件。
  • MCP app（远程 HTTP + 交互式 UI）：同上加 UI 资源，在聊天中渲染交互式组件，一次构建可在 Claude 和 ChatGPT 渲染。通常远程，若 UI 需驱动本地应用可作为 MCPB 发布。
  • MCPB（打包本地服务器）：本地 MCP 服务器连同运行时打包，用户无需安装 Node/Python，是发布本地服务器的受认可方式。适用于读取本地文件、驱动桌面应用、与 localhost 服务通信或需要操作系统级访问。
  • 本地 stdio（npx / uvx）：不推荐用于分发，适合个人工具和原型。分发困难，唯一分发渠道是 Claude Code 插件。仅作为过渡推荐。

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

  • 模式 A：一动作一工具（小表面）。动作空间小（约 15 个以下操作）时，每个操作给专用工具，描述和 schema 紧凑。示例：create_issue、update_issue、search_issues、add_comment。Claude 读一次工具列表即知全部可能，无发现往返，schema 精确校验输入。
  • 模式 B：搜索+执行（大表面）。包装大型 API（数十到数百端点）时，列出每个操作会淹没上下文窗口并降低模型性能。改为暴露两个工具：search_actions（给定自然语言意图，返回匹配动作及其 ID、描述、参数 schema）和 execute_action（按 ID 和 params 对象运行动作）。服务器内部持有完整目录。混合方式：将 3–5 个最常用动作提升为专用工具，长尾留在搜索/执行后。

第四阶段 — 选择框架

推荐两个：官方 TypeScript SDK（@modelcontextprotocol/sdk，TS/JS，默认选择，规范覆盖最好，最先获得新特性）；FastMCP 3.x（PyPI 上的 fastmcp，Python，用户偏好 Python 或包装 Python 库时使用，基于装饰器，样板代码极少，是 jlowin 的包，非官方 mcp SDK 中冻结的 FastMCP 1.0）。若用户已有语言/技术栈，则沿用，两者产生相同线协议。

第五阶段 — 搭建脚手架并交接

确定四个决策（部署模型、工具模式、框架、认证）后：远程 HTTP 无 UI 则内联搭建脚手架（可移植或最快部署）；MCP app（UI 组件）则总结决策后加载 build-mcp-app 技能；MCPB（打包本地）则总结后加载 build-mcpb 技能；本地 stdio 原型则内联搭建（最简单情况），并标记 MCPB 升级路径。交接时用一段话重述设计简报，避免下一个技能重复询问。

工具之外的其他原语

工具是三种服务器原语之一。多数服务器从工具开始且无需其他，但了解它们存在可避免重复造轮子：Resources（宿主应用触发，将文档/文件/数据暴露为可浏览上下文）；Prompts（用户通过斜杠命令触发，预设工作流如 "/summarize-thread"）；Elicitation（服务器在工具中途触发，无需构建 UI 即可询问用户输入）；Sampling（服务器在工具中途触发，在工具逻辑中需要 LLM 推理）。

第六阶段 — 在 Claude 中测试并发布

服务器运行后：在真实 Claude 中测试，将服务器 URL 作为自定义连接器添加到 Settings → Connectors（本地服务器用 Cloudflare 隧道），Claude 在 initialize 时以 clientInfo.name: "claude-ai" 标识自身；运行提交前检查清单（读/写工具分离、必需注解、名称限制、提示注入规则）；提交到 Anthropic Directory；建议发布一个用技能包装此 MCP 的插件，多数合作伙伴两者都发布。

使用方式

本技能以引导式对话进行：先加载 Claude 专属文档，再批量询问第一阶段问题，据答案推荐部署模型、工具设计模式和框架，最后搭建脚手架或交接给 build-mcp-app / build-mcpb 技能。

适用场景

需要构建 MCP 服务器、创建 MCP、制作 MCP 集成、为 Claude 包装 API、向 Claude 暴露工具等场景。决策矩阵示例：包装小型 SaaS API 用远程 HTTP + 一动作一工具；包装大型 SaaS API（50+ 端点）用远程 HTTP + 搜索+执行；带丰富表单/选择器的 SaaS API 用 MCP app（远程）+ 一动作一工具；驱动本地桌面应用用 MCPB + 一动作一工具；带聊天内 UI 的本地桌面应用用 MCP app（MCPB）+ 一动作一工具；读写本地文件系统用 MCPB，模式取决于表面；个人原型用本地 stdio，选最快的方式。

限制

Elicitation 的宿主支持较新（Claude Code 在 v2.1.76 发布，桌面版未确认），SDK 在客户端未声明能力时会抛错，须先检查 clientCapabilities.elicitation 并准备回退。本地 stdio 不推荐用于分发，唯一分发渠道是 Claude Code 插件。其他框架虽存在，但官方 TypeScript SDK 和 FastMCP 3.x 的 MCP 规范覆盖和 Claude 兼容性最好。

参考文件

references/remote-http-scaffold.md（TS SDK 和 FastMCP 的最小远程服务器）；references/deploy-cloudflare-workers.md（最快部署路径）；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（版本敏感声明台账）。