mcp-server-builder

MCP 服务构建器

级别： POWERFUL 类别： 工程 / AI 集成 维护者： Claude Skills Team

概述

根据 API 契约设计并交付可用于生产环境的 MCP（Model Context Protocol）服务。涵盖工具定义最佳实践、资源提供方、提示词模板、OpenAPI 到 MCP 的转换、TypeScript 和 Python 服务实现、传输方式选择（stdio、SSE、StreamableHTTP）、身份验证模式、测试策略和部署配置。将架构质量和工具可发现性视为首要关注点。

关键词

MCP、Model Context Protocol、MCP 服务、工具定义、资源提供方、提示词模板、stdio 传输、SSE 传输、OpenAPI 到 MCP、AI 工具服务、Claude 工具

核心能力

• 工具设计与架构质量 — 动宾命名、描述编写、类型化输入架构、适合大模型的输出格式
• 服务实现 — TypeScript（@modelcontextprotocol/sdk）和 Python（mcp[cli]）服务；工具/资源/提示词注册；结构化错误处理；日志记录、身份验证和速率限制中间件
• 传输与部署 — stdio（本地/命令行）、SSE（Web）、StreamableHTTP（生产环境）、Docker 容器化、运行状况检查、平稳关闭
• 测试与验证 — 架构验证、MCP Inspector 集成测试、契约/快照测试、远程服务负载测试

适用场景

• 将内部 REST API 提供给 Claude、Cursor 或其他 MCP 客户端
• 用类型化工具接口取代脆弱的浏览器自动化
• 为多个团队和 AI 助手构建共享 MCP 服务
• 自动将 OpenAPI 规范转换为 MCP 工具
• 创建特定领域的工具服务（数据库、监控、部署）

首先确认

构建服务前，请确认以下输入。如果有任何内容未知或含糊不清，请提问——不要自行假设：

• 源契约 — 要公开的 OpenAPI 规范或 API，或者是否从头构建工具（工具定义和转换所依据的输入）
• 语言 — TypeScript（@modelcontextprotocol/sdk）或 Python（mcp[cli]）（决定生成的服务实现）
• 传输方式 — stdio（本地/命令行）、SSE（Web）或 StreamableHTTP（生产环境）（决定传输、身份验证和部署模式）

停止规则：只问对输出影响最大的 2-3 个问题。如果用户说“先起草一版”，则继续操作，并在产物顶部列出你的假设。

参考资料

按任务加载相应的参考资料——保持此文件精简，按需查阅详细信息：

• references/tool-schema-design.md — 命名规范、描述编写模板和输入架构最佳实践。定义任何工具时都应首先阅读，因为描述质量会影响大模型对工具的选择。
• references/server-implementation.md — 完整的 TypeScript 和 Python 服务端代码（工具、资源、提示词），以及 OpenAPI 到 MCP 的转换规则和脚本。编写服务端时阅读。
• references/transport-and-deployment.md — 客户端配置（stdio 和远程服务对应的 claude_desktop_config.json）以及工具版本策略。连接客户端或规划发布时阅读。
• references/testing-and-troubleshooting.md — 架构验证函数、MCP Inspector 命令、常见问题、最佳实践、故障排查表和成功标准。验证、为生产环境加固或诊断故障时阅读。
• references/streaming-batch-and-computer-use.md — 长时间运行工具的进度/流式传输与取消、封装计算机使用/浏览器/桌面操作（粒度、返回状态、安全门控），以及适合批处理的工具设计（数组、幂等性、部分失败结果、分页）。工具运行时间较长、需要操作实时界面或处理大量项目时阅读。

常见模式

• 长时间运行工具的流式传输 — 当调用通常需要几秒以上（构建、爬取、自动化）时，应发送带有稳定关联句柄的限频进度更新，流式传输语义完整且以明确终止信号结尾的内容块，并通过中止实际工作和清理会话来响应取消。最终响应必须能独立理解。参见 references/streaming-batch-and-computer-use.md。
• 适合批处理的工具 — 当某项操作本身适合重复执行时，应接受有界数组，而不是强制每个项目都单独进行一次冗长调用；确保操作具有幂等性（或接受幂等键），并返回逐项成功/失败结果，让 Agent 只重试失败的项目。列表/读取工具必须提供分页，且说明分页上限和游标。运行 scripts/tool_schema_linter.py，以标记冗长的单项工具和缺少分页的情况。
• 通过 MCP 使用计算机 — 提供表达意图的操作（navigate、click、read_page），而不是原始像素级操作；返回当前可观测状态（优先文本，仅在布局重要时提供截图）；对于破坏性/不可逆操作，应通过受允许列表限制且会对机密信息进行脱敏的 confirm/dry_run 参数设置安全门控。如需了解自动化引擎本身，请参阅 computer-use-automation 技能。

范围与限制

本技能涵盖：

• 为 MCP 服务设计工具架构、资源提供程序和提示词模板
• 使用 TypeScript（@modelcontextprotocol/sdk）和 Python（mcp[cli]）实现服务端
• 传输方式选择和客户端配置（stdio、SSE、StreamableHTTP）
• OpenAPI 到 MCP 的转换模式和测试策略

本技能不涵盖：

• 构建 MCP 客户端或自定义大模型编排层——参见 engineering/agent-workflow-designer
• 设计使用 MCP 工具的多 Agent 系统——参见 engineering/agent-designer
• API 设计本身（REST 规范、端点命名、版本控制）——参见 engineering/api-design-reviewer
• 为部署 MCP 服务配置基础设施、容器编排或 CI/CD 流水线——参见 engineering/ci-cd-pipeline-builder

集成点

技能	集成方式	数据流
engineering/api-design-reviewer	在将底层 REST API 转换为 MCP 工具之前对其进行审查	OpenAPI 规范 → API 审查结果 → 优化后的规范 → MCP 转换
engineering/api-test-suite-builder	为 MCP 工具封装的 HTTP 端点生成集成测试	MCP 工具定义 → 端点映射 → 测试套件生成
engineering/agent-designer	设计使用此技能生成的 MCP 工具的 Agent	MCP 工具架构 → Agent 工具清单 → Agent 行为设计
engineering/observability-designer	为 MCP 服务处理程序添加结构化日志记录、跟踪和指标	MCP 服务代码 → 埋点方案 → 日志记录／跟踪中间件
engineering/ci-cd-pipeline-builder	为 MCP 服务发布自动化构建、测试和部署流水线	MCP 服务仓库 → 流水线配置 → 自动部署到预发布／生产环境
engineering/env-secrets-manager	管理 MCP 服务配置中使用的 API 密钥、数据库凭据和令牌	MCP 服务环境变量 → 密钥审计 → 安全注入模式