OpenAPI → MCP 服务器

这个 Python CLI 工具基于 OpenAPI v3 规范文件（JSON 或 YAML）生成一个基本的 Node.js/TypeScript MCP (模型上下文协议) 服务器，规范文件可以是一个本地文件路径或一个 URL。OpenAPI 规范中定义的每个操作都会映射到生成的服务器中的一个相应的 MCP 工具。

生成的服务器充当代理，接收 MCP 工具调用，并将其转换为 HTTP 请求以调用 OpenAPI 规范中定义的实际 API。

✨ 特性

• 从本地文件或 URL 解析 OpenAPI v3 JSON 或 YAML。
• 验证 OpenAPI 规范结构。
• 将 OpenAPI 操作（GET、POST、PUT、DELETE、PATCH）映射到 MCP 工具。
• 基于 OpenAPI 参数和请求体生成 MCP 工具 inputSchema (JSON Schema)（处理基本类型、对象、数组、枚举、格式、简单的本地 $ref、基本循环检测）。
• 生成可运行的 Node.js/TypeScript MCP 服务器项目：
  • 使用 @modelcontextprotocol/sdk。
  • 可配置的传输方式 (stdio, sse)。
  • 可配置的 SSE 传输端口。
  • 从 .env 文件读取目标 API 基本 URL 和可选的身份验证标头。
  • 包括从 HTTP 状态代码到 MCP 错误代码的基本错误映射。
  • 包括 package.json、tsconfig.json（具有严格设置）和示例 .env 文件。
  • 在生成的 README.md 中提供清晰的设置和运行说明。
• 集成的 linting (ruff) 和格式化 (black)。
• 单元和集成测试 (pytest)。
• JSON 日志记录。

🚀 安装 / 设置

前提条件：

• Python: 需要 3.12 或更高版本（假定已安装）。
• Poetry: 此工具使用 Poetry 进行依赖管理（假定已安装）。
• MCP SDK: 1.5.0 版本（通过 Poetry 自动安装）。
• Node.js: 生成的服务器需要 20 或更高版本（假定已安装）。

步骤：

1. 导航到项目目录： 在包含此 openapi-to-mcp 代码的目录中打开终端。

2. 安装依赖项：

   • 对于运行该工具：

     poetry install --no-dev
     

     这仅安装运行生成器所需的核心依赖项。
   • 对于开发（包括运行测试、linting、格式化）：

     poetry install --with dev
     # 或者简单地：
     poetry install
     

     这将安装所有依赖项，包括 pytest、black 和 ruff 等开发工具。

3. 激活虚拟环境（可选但推荐）： Poetry 创建一个虚拟环境来管理依赖项。您可以激活它以直接运行命令：

   poetry shell
   

   或者，您可以为命令添加 poetry run 前缀。

📋 用法

该工具提供两个主要命令：generate 和 test-server。

从项目目录中运行命令（或在虚拟环境激活的情况下）：

# 使用 poetry run
poetry run openapi-to-mcp [COMMAND] [OPTIONS]

# 或者，如果在 'poetry shell' 中
openapi-to-mcp [COMMAND] [OPTIONS]

🛠️ generate 命令

此命令生成 MCP 服务器代码。

选项：

• --openapi-json, -o (必需): OpenAPI 规范文件的路径或 URL（JSON 或 YAML）。
• --output-dir, -d: 生成的 MCP 服务器文件的输出目录。（默认：./mcp-server）
• --mcp-server-name, -n: 生成的 MCP 服务器包的名称。（默认：openapi-mcp-server）
• --mcp-server-version, -v: 生成的 MCP 服务器包的版本。（默认：1.0.0）
• --transport, -t: 生成的服务器的传输机制 (stdio 或 sse)。（默认：stdio）
• --port, -p: 如果 --transport 是 sse，则使用的端口号。（默认：8080）
• --help: 显示 generate 命令的帮助。

示例：

对于 STDIO 传输，您可以运行以下命令来为 Swagger Petstore API 示例生成服务器：

poetry run openapi-to-mcp generate \
  --openapi-json https://petstore3.swagger.io/api/v3/openapi.json \
  --output-dir ./generated-petstore-mcp \
  --mcp-server-name petstore-mcp \
  --transport stdio

此命令将：

1. 获取并验证 https://petstore3.swagger.io/api/v3/openapi.json。
2. 将 API 操作映射到 MCP 工具。
3. 在 ./generated-petstore-mcp 目录中生成 Node.js/TypeScript MCP 服务器代码。
4. 配置生成的服务器以使用 STDIO 传输。

对于 SSE 传输，您可以运行以下命令来为 Swagger Petstore API 示例生成服务器：

poetry run openapi-to-mcp generate \
  --openapi-json https://petstore3.swagger.io/api/v3/openapi.json \
  --output-dir ./generated-petstore-mcp \
  --mcp-server-name petstore-mcp \
  --transport sse \
  --port 8080

此命令将：

1. 获取并验证 https://petstore3.swagger.io/api/v3/openapi.json。
2. 将 API 操作映射到 MCP 工具。
3. 在 ./generated-petstore-mcp 目录中生成 Node.js/TypeScript MCP 服务器代码。
4. 配置生成的服务器以在端口 8080 上使用 SSE 传输。

生成后步骤

运行 generate 命令后，请在生成的服务器目录（生成期间指定的 <output-dir>）中执行以下步骤：

1. 导航到输出目录：

   cd <output-dir>
   

2. 创建/编辑 .env 文件（生成器创建一个 .env.example 文件，您可以复制），并提供所需的值：
   • TARGET_API_BASE_URL：生成的服务器将与之交互的目标 API 的基本 URL。生成的服务器在启动时验证此值，并且不会使用占位符 URL 运行。
   • TARGET_API_AUTH_HEADER：（可选）目标 API 需要的完整授权标头字符串（例如，Authorization: Bearer your_token 或 X-API-Key: your_key）。
3. 安装依赖项：

   npm install
   

4. 构建 TypeScript 代码：

   npm run build
   

5. 启动服务器：

   npm start
   

生成的服务器自己的 README.md 文件也包含这些设置说明。然后，您可以使用 test-server 命令或 MCP Inspector 测试正在运行的服务器。

🧪 test-server 命令

此命令允许您将基本的 JSON-RPC 请求（ListTools、CallTool）发送到正在运行的 MCP 服务器（由此工具或任何其他工具生成）。

选项：

• --transport {sse,stdio}: (必需) 指定服务器正在使用的传输方式。
• --host <hostname>: SSE 的主机名（默认：localhost）。
• --port <port_number>: SSE 的端口（默认：8080）。
• --server-cmd "<command>": (stdio 必需) 启动服务器的命令（例如，"node ./generated-server/build/index.js"）。确保路径相对于您运行命令的位置是正确的。
• --list-tools: 发送 ListTools 请求。
• --tool-name <tool_name>: 为 CallTool 请求指定工具名称。
• --tool-args '<json_string>': (需要 --tool-name) 以 JSON 字符串形式提供工具的参数（例如，'{"petId": 123}'）。
• --env-source <source>: (可选，仅适用于 stdio) 向服务器进程提供环境变量。 <source> 可以是：
  • 直接 JSON 字符串：'{"VAR1":"value1", "VAR2":"value2"}'
  • JSON 文件的路径：./my_env.json
  • .env 文件的路径：./generated-server/.env
• --help: 显示 test-server 命令的帮助。

示例：

• 通过 SSE 列出工具（服务器在端口 8080 上运行）：

  poetry run openapi-to-mcp test-server --transport sse --port 8080 --list-tools
  

• 通过 SSE 调用工具（服务器在端口 8080 上运行）：

  poetry run openapi-to-mcp test-server --transport sse --port 8080 \
    --tool-name getPetById --tool-args '{"petId": 1}'
  

• 通过 stdio 列出工具（使用 .env 文件）：

  # 确保 TARGET_API_BASE_URL 在 ./generated-petstore-mcp/.env 中设置
  poetry run openapi-to-mcp test-server --transport stdio \
    --server-cmd "node ./generated-petstore-mcp/build/index.js" --list-tools \
    --env-source ./generated-petstore-mcp/.env
  

• 通过 stdio 调用工具（使用 JSON 字符串作为 env）：

  poetry run openapi-to-mcp test-server --transport stdio \
    --server-cmd "node ./generated-petstore-mcp/build/index.js" \
    --tool-name addPet --tool-args '{"requestBody": {"name": "doggie", "photoUrls": []}}' \
    --env-source '{"TARGET_API_BASE_URL": "https://petstore3.swagger.io/api/v3"}'
  

🔍 使用 MCP Inspector 进行测试

除了 test-server 命令之外，MCP Inspector 还提供了一个图形界面，用于与任何正在运行的 MCP 服务器进行交互。

1. 按照 MCP Inspector 文档页面上的安装说明进行操作。
2. 启动 Inspector。
3. 配置新连接：
   • 选择适当的传输方式（stdio 或 sse）。
   • 对于 stdio，提供启动生成的服务器的完整命令（例如，node /path/to/your/generated-server/build/index.js）。
   • 对于 sse，提供 URL（例如，http://localhost:8080 或您指定的端口）。
4. 连接到服务器。
5. 使用 Inspector UI 查看可用工具 (ListTools) 并发送带有参数的 CallTool 请求。

这提供了一种更具交互性的方式来探索和测试生成的服务器。

🤝 贡献

有兴趣贡献吗？我们欢迎各种形式的贡献给 openapi-to-mcp！无论您是修复错误、添加功能、改进文档还是分享想法，您的投入对于帮助我们改进项目都非常有价值。

请参阅我们的 CONTRIBUTING.md，了解有关如何入门的详细指南。

💻 开发工作流程

确保您已使用 poetry install --with dev（或 poetry install）安装了依赖项。任务使用 poethepoet 通过 poetry run poe <task_name> 或 poe <task_name>（如果在 poetry shell 中）运行。

• 格式化： 使用 Ruff 应用代码格式化：

  poetry run poe format
  

• Linting： 检查代码样式问题并使用 Ruff 应用自动修复：

  poetry run poe lint
  

• 测试： 使用 Pytest 运行单元和集成测试，并进行覆盖率报告：

  poetry run poe test
  

  将生成覆盖率报告（终端和 HTML）（检查 htmlcov/ 目录以获取 HTML 报告）。

• 所有检查： 依次运行格式化、linting 和测试：

  poetry run poe check
  

• 清理临时文件： 删除构建过程中创建的临时文件和目录：

  poetry run poe clean
  

📄 许可证

本项目根据 Apache License 2.0 获得许可。有关详细信息，请参阅 LICENSE 文件。

📚 参考

• OpenAPI 规范
• 模型上下文协议 (MCP)
• Python
• Poetry
• Click
• Jinja2
• ruff
• pytest
• black
• TypeScript
• Node.js