OpenAPI to MCP Generator

OpenAPI 到 MCP 生成器

本项目提供了一款强大的工具，可将 OpenAPI/Swagger 规范自动转换为 Model Context Protocol（MCP）服务，让大模型通过标准化工具与任意 REST API 交互。

组件

SwaggerToMcpGenerator.java

一款功能全面的实用工具，可将任意 OpenAPI/Swagger 规范转换为功能齐全的 MCP 服务：

• 解析 OpenAPI 规范文件
• 将 API 端点转换为 MCP 工具
• 处理路径参数、查询参数和请求正文
• 支持多种 HTTP 方法（GET、POST、PUT、DELETE、PATCH）
• 支持身份验证（API 密钥、Bearer 令牌、Basic 身份验证）
• 格式化 JSON 响应，便于阅读
• 提供完善的错误处理
• 包含参数文档，说明有效值和默认值

从 OpenAPI 生成 MCP 服务

要从任意 OpenAPI 规范生成 MCP 服务：

jbang SwaggerToMcpGenerator.java path/to/swagger.json GeneratedMcpServer [options]

参数：

• path/to/swagger.json：OpenAPI/Swagger 规范文件的路径
• GeneratedMcpServer：输出 Java 文件的名称（不含 .java 扩展名）

选项：

• --server-index <index>：要使用的服务器在 OpenAPI 规范中的索引（从 0 开始）
• --server-url <url>：要使用的服务器 URL（覆盖 server-index）

这会创建一个新文件 GeneratedMcpServer.java，其中实现了一个 MCP 服务，并为 swagger 文件中定义的每个 API 端点提供工具。如果 OpenAPI 规范中定义了多个服务器，但未明确选择其中一个，生成器会发出警告。

运行生成的 MCP 服务

要运行生成的 MCP 服务：

jbang GeneratedMcpServer.java

服务器选择

生成的 MCP 服务包含 OpenAPI 规范中所有服务器的常量，因此你可以在运行时选择要使用的服务器。默认使用列表中的第一个服务器，但你可以通过环境变量选择特定服务器：

# Select server by index (0-based)
export SERVER_INDEX=1

# Or select server by URL
export SERVER_URL="https://api-example.com/v2"

jbang GeneratedMcpServer.java

身份验证

生成的 MCP 服务支持通过环境变量配置多种身份验证方式：

• API 密钥：设置 API_KEY 和 API_KEY_HEADER 环境变量
• Bearer 令牌：设置 BEARER_TOKEN 环境变量
• Basic 身份验证：设置 API_USERNAME 和 API_PASSWORD 环境变量

示例：

export API_KEY="your-api-key"
export API_KEY_HEADER="X-API-Key"
jbang GeneratedMcpServer.java

示例

Open-Meteo 天气 API

本项目在 examples/open-meteo 目录中包含 Open-Meteo 天气 API 的 OpenAPI 示例规范。

生成 Open-Meteo MCP 服务

cd examples/open-meteo
jbang ../../SwaggerToMcpGenerator.java open-meteo-openapi.yml OpenMeteoMcpServer

这会生成 OpenMeteoMcpServer.java，其中包含用于访问天气预报数据的 MCP 工具。

运行 Open-Meteo MCP 服务

cd examples/open-meteo
jbang OpenMeteoMcpServer.java

使用 Open-Meteo MCP 服务

生成的 MCP 服务提供了用于访问天气预报的工具。使用该服务时，请留意参数说明，其中包含有效值和默认值。例如：

• 对于 wind_speed_unit 参数，表示米每秒时请使用 ms（而不是“m/s”）
• wind_speed_unit 的有效值为：kmh（默认值）、ms、mph 和 kn
• 温度单位可使用 celsius（默认值）或 fahrenheit

西班牙塞维利亚天气查询示例：

latitude: 37.3891
longitude: -5.9845
current_weather: true
wind_speed_unit: ms

生成 Clever Cloud MCP 服务

cd examples/clever-cloud
jbang ../../SwaggerToMcpGenerator.java clever-cloud-openapi.yml CleverCloudMcpServer --server-index 1

请注意，我们使用了 --server-index 1（列表中的第二个服务器），这是令牌身份验证所需的 API Bridge URL。这会生成 CleverCloudMcpServer.java，其中包含用于管理 Clever Cloud 资源的 MCP 工具。

或者，你也可以直接指定服务器 URL：

cd examples/clever-cloud
jbang ../../SwaggerToMcpGenerator.java clever-cloud-openapi.yml CleverCloudMcpServer --server-url https://api-bridge.clever-cloud.com/v2

运行 Clever Cloud MCP 服务

cd examples/clever-cloud
# Set your Clever Cloud API token
export BEARER_TOKEN=your_api_token
jbang CleverCloudMcpServer.java

生成 Clever Cloud API 令牌

要为 Clever Cloud 生成 API 令牌，需要使用 Clever Tools CLI：

# Install Clever Tools (if not already installed)
npm install -g clever-tools

# Login to Clever Cloud
clever login

# Enable the tokens feature
clever features enable tokens

# Create a token (with optional expiration)
clever tokens create "MCP Server Token"
clever tokens create "Temporary Token" --expiration 24h

你也可以列出并撤销令牌：

# List existing tokens
clever tokens -F json

# Revoke a token
clever tokens revoke api_tokens_xxx

使用 Clever Cloud MCP 服务

生成的 MCP 服务提供了用于与 Clever Cloud API 交互的工具。可用工具包括：

• get_self：获取当前用户信息
• get_summary：获取用户摘要
• get_organisations__organisationId__applications：列出组织的应用
• get_organisations__organisationId__applications__applicationId_：获取应用详情

列出某个组织的应用的查询示例：

organisationId: your_organization_id

工作原理

MCP 协议

模型上下文协议（MCP）是一种标准化的工具与大模型通信方式，支持：

1. 工具向任何兼容 MCP 的大模型公开其功能
2. 大模型无需绑定特定实现即可发现和使用工具
3. 为工具规范和调用提供统一的接口

OpenAPI 到 MCP 的转换

生成器的工作流程如下：

1. 使用 Swagger Parser 解析 OpenAPI 规范
2. 将每个 API 端点转换为带有 @Tool 注解的方法
3. 映射参数：
   • 将路径参数纳入 URL
   • 将查询参数添加到 URL 构建器
   • 正确格式化请求正文并将其附加到请求中
4. 生成 HTTP 客户端代码并进行适当的错误处理
5. 根据内容类型格式化响应（美化 JSON 格式）
6. 根据环境变量添加身份验证

高级功能

• 多种 HTTP 方法：支持 GET、POST、PUT、DELETE 和 PATCH
• 内容类型处理：正确处理不同的内容类型
• 错误处理：提供包含状态代码和响应正文的详细错误报告
• 身份验证：支持 API 密钥、Bearer 令牌和 Basic 身份验证
• 超时：可配置连接、读取和写入超时
• 多个服务：支持从 OpenAPI 规范中定义的多个服务 URL 中进行选择

环境说明

从 Claude Desktop 等 AI 助手运行时，jbang-wrapper.sh 脚本可解决环境问题，确保能够使用正确的 PATH 和环境变量。

后续步骤

• 添加对表单数据和多部分请求的支持
• 实现 OAuth 2.0 身份验证流程
• 添加对自定义响应转换的支持
• 创建用于上传 OpenAPI 规范并生成服务的 Web UI
• 添加对 WebSocket 端点的支持