SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场openapi-tool-scaffold

openapi-tool-scaffold

编程与开发

查看项目

更新于 10-16 16:26

技能介绍

OpenAPI Tool Scaffold 是一个 Python 3.10+ 技能，用于将 OpenAPI 3.x 规范自动转换为 MCP stdio 服务器代码。它采用 Research → Audit → Rewrite 模式重新实现，不直接安装外部工具，而是吸收公开模式进行内部重写。

用途： 该技能旨在快速将外部 REST API 桥接为 MCP tool，节省 API 集成时间。它填补了 OpenAPI 到 MCP 自动代码生成的空白，无需额外 SaaS 成本。

主要能力：

  • 输入 OpenAPI 3.x 规范（URL 或本地 JSON/YAML），输出可执行的 MCP stdio 服务器 Python 文件。
  • 自动将每个 REST endpoint 暴露为 MCP tool。
  • 支持认证模式：Bearer、API Key、OAuth stub 以及 Basic auth。生成服务器会解析 OpenAPI 的 components.securitySchemes 和 operation/global security，自动使用环境变量注入认证信息。
  • 生成的 MCP 方法包括：initialize、tools/list、tools/call、ping。
  • 支持 newline JSON-RPC 输入（默认），也接受 Content-Length 帧输入；输出默认为 newline JSON-RPC，可通过 MCP_USE_CONTENT_LENGTH=1 启用 Content-Length 输出。

使用方式： 通过命令行运行脚本： python3 scripts/openapi-to-mcp.py INPUT --output OUTPUT.py [options] 选项包括： --server-name：覆盖 MCP 服务器名称 --base-url：优先于 OpenAPI servers 的 API base URL --template：更改服务器模板路径 --include-deprecated：包含已弃用的操作 --max-tools N：限制生成的 tool 数量（0=无限制）

快速开始示例：

  1. 生成 Petstore OpenAPI 到 MCP 服务器代码： python3 skills/openapi-tool-scaffold/scripts/openapi-to-mcp.py "https://petstore3.swagger.io/api/v3/openapi.json" --output skills/openapi-tool-scaffold/examples/petstore-mcp-server.py --server-name petstore_mcp
  2. 语法检查： python3 -m py_compile skills/openapi-tool-scaffold/examples/petstore-mcp-server.py
  3. 运行 MCP 服务器（stdio）： python3 skills/openapi-tool-scaffold/examples/petstore-mcp-server.py

认证环境变量：

  • Bearer：BEARER_TOKEN_<SCHEME_NAME>，回退 BEARER_TOKEN
  • API Key：API_KEY_<SCHEME_NAME>，回退 API_KEY，根据 OpenAPI 定义（in: header/query/cookie, name）自动注入
  • OAuth (stub)：OAUTH_ACCESS_TOKEN_<SCHEME_NAME>，回退 OAUTH_ACCESS_TOKEN，不实现自动令牌发放流程，仅作为令牌注入存根
  • Basic auth：BASIC_USERNAME_<SCHEME_NAME>, BASIC_PASSWORD_<SCHEME_NAME>，回退 BASIC_USERNAME, BASIC_PASSWORD

适用场景：

  • 需要快速将外部 REST API 集成到 MCP 生态时。
  • 希望减少手动编写 MCP 服务器代码的工作量。
  • 在无额外 SaaS 成本下加速开发。

限制：

  • 仅支持 OpenAPI 3.x。
  • 不自动获取外部 $ref URL（主要处理本地 #/...）。
  • 复杂序列化（style/explode deepObject）仅基本映射处理。
  • OAuth 自动刷新/代码交换不在范围内（仅 stub）。

操作提示：

  • 建议在 OpenAPI 阶段将敏感 endpoint 分离到单独规范。
  • 使用 --max-tools 缩小初始暴露范围，逐步扩展。
  • 必须区分读/写/删除 endpoint，并在客户端添加审批策略。

包含文件： openapi-tool-scaffold/ ├── SKILL.md ├── scripts/ │ └── openapi-to-mcp.py ├── templates/ │ └── mcp_server_stdio.py.tmpl ├── examples/ │ ├── README.md │ ├── petstore-mcp-server.py │ ├── todo-mini-openapi.yaml │ └── todo-mini-mcp-server.py └── references/ └── research-audit.md

研究/审计结果： 详细调查见 references/research-audit.md。核心结论：开源方案大多偏向 TS/Node 或特定平台；存在对 Python 轻量/无依赖（或最小依赖）生成器的需求；许可证主要为 MIT/Apache-2.0，适合模式参考；因此内部 Python 重写策略合理。