mcp-server-builder

MCP 服务构建器

等级: POWERFUL · 分类: Engineering · 领域: AI / API 集成

概述

使用此技能,可以基于 API 契约设计并交付可用于生产环境的 MCP 服务,而不是手写一次性的工具封装。它专注于快速搭建脚手架、保证 schema 质量、进行校验,以及安全地演进。

该工作流同时支持 Python 和 TypeScript 的 MCP 实现,并将 OpenAPI 视为唯一可信来源。

核心能力

• 将 OpenAPI paths/operations 转换为 MCP 工具定义
• 生成初始服务脚手架(Python 或 TypeScript)
• 强制统一命名、描述和 schema 规范
• 校验 MCP 工具清单中常见的生产故障问题
• 执行版本管理与向后兼容性检查
• 将传输/运行时决策与工具契约设计分离

适用场景

• 需要将内部/外部 REST API 暴露给 LLM Agent
• 正在用类型化工具替代脆弱的浏览器自动化
• 希望多个团队和助手共享同一个 MCP 服务
• 在发布 MCP 工具前需要可重复的质量检查
• 希望基于现有 OpenAPI 规范快速引导一个 MCP 服务

关键工作流

1. 从 OpenAPI 生成 MCP 脚手架

1. 从一份有效的 OpenAPI 规范开始。
2. 生成工具清单 + 初始服务代码。
3. 检查命名和认证策略。
4. 添加针对具体端点的运行时逻辑。

python3 scripts/openapi_to_mcp.py \
  --input openapi.json \
  --server-name billing-mcp \
  --language python \
  --output-dir ./out \
  --format text

同样支持 stdin:

cat openapi.json | python3 scripts/openapi_to_mcp.py --server-name billing-mcp --language typescript

2. 校验 MCP 工具定义

在集成测试前运行校验器:

python3 scripts/mcp_validator.py --input out/tool_manifest.json --strict --format text

检查项包括:重复名称、无效的 schema 结构、缺失描述、必填字段为空,以及命名规范问题。

3. 运行时选择

• 若追求快速迭代以及数据密集型后端,选择 Python。
• 若希望统一 JS 技术栈,并加强前后端契约复用,选择 TypeScript。
• 即使传输或运行时发生变化,也要保持工具契约稳定。

4. 生产环境加固

发布前的关键事项:

• 将密钥保存在环境变量中,而不是工具 schema 里
• 优先使用出站主机白名单,而不是开放代理
• 只做增量变更;绝不原地重命名工具名称

完整加固指南:references/production-hardening-guide.md。

脚本接口

• python3 scripts/openapi_to_mcp.py --help
  • 从 stdin 或 --input 读取 OpenAPI
  • 生成清单 + 服务脚手架
  • 输出 JSON 摘要或文本报告
• python3 scripts/mcp_validator.py --help
  • 校验清单以及可选的运行时配置
  • 在严格模式下如存在错误则以非零退出码返回

参考资料

• references/production-hardening-guide.md — 认证与安全设计、版本管理策略、常见陷阱、最佳实践、架构决策、契约质量门禁、测试策略、部署实践、安全控制
• references/openapi-extraction-guide.md
• references/python-server-template.md
• references/typescript-server-template.md
• references/validation-checklist.md
• README.md