用途
MCP API Build 用于按企业标准设计并构建生产级 REST API 与 MCP 服务器。资料列出了三种适用时机:从零设计新的 REST API;用 MCP 服务器封装已有的 REST API;将 REST 端点转换为 MCP 的 Tools、Resources、Prompts。此外还适用于编写 OpenAPI 规范(API 优先)、审查或审计 API 架构与反模式、规划 API 安全与生产部署。
工作路径
技能提供三条路径。
路径 A:从零构建 REST API。步骤依次为:领域建模 → 资源清单 → OpenAPI 规范 → 实现 → 审计 → 部署。领域建模需识别实体、关系与消费方,明确谁调用 API、解决什么问题、存在哪些层级与权限;资源清单列出资源并建立 CRUD 矩阵;OpenAPI 规范要求在写代码之前完成;实现阶段要求代码严格对齐契约,任何偏离视为缺陷;审计阶段检查反模式;部署阶段执行安全与生产清单。
路径 B:为已有 API 构建 MCP 服务器。步骤为:审计 REST API → 映射端点 → 编写服务器 → 添加高级特性 → 测试 → 部署。审计需列出全部端点、方法、参数与响应;映射使用决策矩阵;编写服务器遵循既定模式;高级特性涵盖进度通知、elicitation、结构化输出;测试使用 MCP Inspector 与程序化测试;部署可选 stdio(本地)或 Streamable HTTP(远程)。
路径 C:同时设计 REST API 与 MCP。先按路径 A 的第 1 至 3 步设计 REST,再叠加路径 B 的第 2 至 6 步。
主要能力与规则
REST 设计规则包括:使用复数名词(如 /users、/events、/tickets);HTTP 方法表示动作(GET 读取、POST 创建、PATCH 更新、DELETE 删除);URL 中不使用动词;嵌套最多两级,更深则展平;JSON 字段使用 snake_case;所有列表与错误响应保持一致结构;所有接口分页(limit + offset 或游标);URL 中写入版本号(/v1/);POST 使用幂等键(Idempotency-Key);使用 ETag 支持缓存与并发控制(If-Match、If-None-Match);始终提供健康检查 GET /health。
MCP 原语决策:Tool 对应动作或函数,用于搜索、创建、更新、删除,由 LLM 决定调用;Resource 对应静态数据,如资料、配置、计数,由应用或用户载入上下文;Prompt 对应模板,用于分析、摘要、推荐,由用户选择。判断规则为:无参数的 GET 归为 Resource,带参数的 GET 或任何写入归为 Tool。
MCP 工具设计要求:名称使用 snake_case 的动词加名词形式;描述说明做什么、返回什么、何时使用,面向 LLM;inputSchema 使用 JSON Schema,每个字段都带描述,尽量使用枚举;输出为结构化 JSON,而非字符串化文本;错误返回 isError: true 而非抛出异常;使用注解 readOnlyHint、destructiveHint、idempotentHint;单个服务器最多 10 至 15 个工具,按逻辑分组,并撰写完整的服务器说明。
高级特性
资料列出 2025-06-18 及之后版本涉及的高级特性:结构化输出(工具返回带类型的 JSON)、进度通知(超过 5 秒的长时间操作)、elicitation(确认破坏性操作、获取用户输入)、sampling(服务器需要 LLM 分析)、资源订阅(数据变化时自动更新)、幂等键(安全的 POST 重试)、ETag 与条件请求(缓存、乐观并发)、Expand/Embed(避免 N+1 查询)。
参考文件
技能包含按需加载的参考文件:rest-api-standards.md(URL 设计、HTTP 方法、响应、错误、认证、分页、版本控制);mcp-specification.md(MCP 架构、生命周期、原语、传输、认证);rest-to-mcp-mapping.md(决策矩阵、命名、工具描述、inputSchema、分组);openapi-first-process.md(领域建模、资源清单、OpenAPI YAML、审查清单);mcp-server-patterns.md(Python FastMCP、TypeScript SDK、REST 封装、测试、部署);security-production.md(认证、输入校验、限流、MCP 安全、生产清单);advanced-patterns.md(幂等、ETag、expand、webhook、结构化输出、进度、elicitation、sampling、反模式)。
使用方式与示例
资料给出 Python FastMCP 的生产示例:通过环境变量配置 BASE_URL 与 API_KEY,用 FastMCP 初始化并写入服务器说明,内部异步函数 _api 封装 httpx 调用并处理超时与错误,随后用 @mcp.tool 定义 search_knowledge 与 create_ticket 工具,用 @mcp.resource 定义 get_profile 与 unread_count 资源。运行方式为 python server.py;测试方式为 npx @modelcontextprotocol/inspector python server.py。
限制
资料未提供该技能的收费、价格、平台兼容范围或效果数据,这些信息暂未提供。分类依据其明确的 API 与服务器构建用途。