OpenAPI到MCP生成器

该项目提供了一个强大的工具，用于自动将OpenAPI/Swagger规范转换为模型上下文协议（MCP）服务器，使LLMs能够通过标准化工具与任何REST API进行交互。

组件

SwaggerToMcpGenerator.java

一个全面的工具，可以将任何OpenAPI/Swagger规范转换为完全功能的MCP服务器：

• 解析OpenAPI规范文件
• 将API端点转换为MCP工具
• 处理路径参数、查询参数和请求体
• 支持多种HTTP方法（GET、POST、PUT、DELETE、PATCH）
• 提供身份验证支持（API密钥、Bearer令牌、基本认证）
• 格式化JSON响应以提高可读性
• 生成健壮的错误处理机制
• 包含参数文档及其有效值和默认值

从OpenAPI生成MCP服务器

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

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

参数：

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

选项：

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

这将创建一个新的文件GeneratedMcpServer.java，该文件实现了具有每个API端点工具的MCP服务器。如果在OpenAPI规范中定义了多个服务器且未明确选择，则生成器会发出警告。

运行生成的MCP服务器

要运行生成的MCP服务器：

jbang GeneratedMcpServer.java

服务器选择

生成的MCP服务器包括所有在OpenAPI规范中定义的服务器常量，允许您在运行时选择要使用的服务器。默认情况下使用列表中的第一个服务器，但您可以使用环境变量选择特定服务器：

# 通过索引选择服务器（基于0）
export SERVER_INDEX=1

# 或通过URL选择服务器
export SERVER_URL="https://api-example.com/v2"

jbang GeneratedMcpServer.java

身份验证

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

• API密钥：设置API_KEY和API_KEY_HEADER环境变量
• Bearer令牌：设置BEARER_TOKEN环境变量
• 基本认证：设置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 OpenMeteoMMcpServer.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桥接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
# 设置您的Clever Cloud API令牌
export BEARER_TOKEN=your_api_token
jbang CleverCloudMcpServer.java

生成Clever Cloud API令牌

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

# 安装Clever Tools（如果尚未安装）
npm install -g clever-tools

# 登录Clever Cloud
clever login

# 启用令牌功能
clever features enable tokens

# 创建令牌（可选过期时间）
clever tokens create "MCP Server Token"
clever tokens create "临时令牌" --expiration 24h

您还可以列出和撤销令牌：

# 列出现有令牌
clever tokens -F json

# 撤销令牌
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）是一种标准化的方式，使工具和LLMs能够通信，允许：

1. 工具将其功能暴露给任何兼容MCP的LLM
2. LLMs发现并使用工具而不受特定实现的限制
3. 工具规范和调用的一致接口

OpenAPI到MCP转换

生成器的工作方式如下：

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

高级功能

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

环境说明

jbang-wrapper.sh脚本解决了在AI助手如Claude Desktop上运行时遇到的Mac环境问题，确保正确的PATH和环境变量可用。

下一步

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