Swagger To MCP Generator

🚀 OpenAPI 到 MCP 的转换工具文档

本项目提供的 Java 工具，可将 OpenAPI 规范转换为 Model Context Protocol (MCP) 服务器。借助 Swagger Parser 解析 OpenAPI 文件，进而生成对应的 MCP 工具类。该工具支持多种 HTTP 方法、内容类型处理、错误处理以及身份验证。

🚀 快速开始

1. 添加依赖项

在项目里添加如下依赖项：

<dependency>
    <groupId>org.swagger</groupId>
    <artifactId>swagger-parser</artifactId>
    <version>1.2.30</version>
</dependency>

2. 使用工具生成 MCP 服务器代码

运行 OpenAPIToMCPGenerator 工具：

java -jar openapi-to-mcp-generator.jar --input-spec your_openapi.yaml --output-dir output

3. 配置环境变量

设置必要的环境变量：

• API_KEY：API 密钥
• BEARER_TOKEN：Bearer Token
• BASIC_AUTH_USER：Basic Auth 用户名
• BASIC_AUTH_PASSWORD：Basic Auth 密码

4. 示例代码

以下是一个简单示例，展示如何使用生成的 MCP 工具类：

@Tool(
    name = "Get User",
    description = " retrieves user information by ID.",
    parameters = {
        @Parameter(name = "userId", type = Type.STRING, description = "User ID"),
        @Parameter(name = "includeDetails", type = Type.BOOLEAN, description = "Include detailed information")
    }
)
public class GetUserTool {

    private static final String BASE_URL = "https://api.example.com";

    public static User getUser(String userId, boolean includeDetails) {
        // 实现 HTTP 请求逻辑
    }

}

✨ 主要特性

• OpenAPI 解析：运用 Swagger Parser 解析 OpenAPI 规范。
• 端点转换：把每个 API 端点转换为 @Tool 注解方法。
• 参数映射：
  • 路径参数：整合到 URL 中。
  • 查询参数：添加到 URL 构建器中。
  • 请求正文：正确格式化并附加到请求中。
• HTTP 客户端生成：生成带有详细错误处理的 HTTP 客户端代码。
• 响应格式化：依据内容类型（如 JSON）进行美化输出。
• 身份验证支持：基于环境变量的身份验证（API 密钥、Bearer Token 和 Basic Auth）。
• 多服务器支持：支持从 OpenAPI 规范中选择多个服务器 URL。

📚 详细文档

MCP 协议简介

MCP 是一个标准化协议，允许工具和 LLM 之间进行通信。其主要特点如下：

1. 工具暴露功能：工具能够通过 MCP 向 LLM 展示其功能。
2. LLM 工具发现：LLM 可以发现并使用符合 MCP 接口的工具，无需了解具体实现细节。
3. 一致接口：提供统一的工具规范和调用接口。

OpenAPI 到 MCP 的转换流程

1. 解析 OpenAPI 规范：使用 Swagger Parser 解析输入的 OpenAPI 文件。
2. 端点转换：将每个 API 端点映射为一个 @Tool 注解方法。
3. 参数处理：
   • 路径参数整合到 URL 中。
   • 查询参数添加到 URL 构建器中。
   • 请求正文正确格式化并附加到请求中。
4. 生成 HTTP 客户端代码：生成带有详细错误处理和超时配置的 HTTP 客户端代码。
5. 响应格式化：根据内容类型（如 JSON）进行美化输出。

高级功能

• 多 HTTP 方法支持：支持 GET、POST、PUT、DELETE 和 PATCH。
• 内容类型处理：正确处理不同内容类型。
• 错误处理：提供详细错误报告，包括状态码和响应正文。
• 身份验证：支持 API 密钥、Bearer Token 和 Basic 身份验证。
• 超时配置：可配置的连接超时、读取超时和写入超时。

🔧 技术细节

jbang-wrapper.sh 脚本解决了在 Claude Desktop（macOS）等 AI 助手环境中运行时的环境问题，确保 PATH 和环境变量正确设置。

🚧 未来计划

• 扩展功能：
  • 支持表单数据和文件上传。
  • 实现更复杂的参数验证逻辑。
• 优化性能：提升解析和生成代码的速度。
• 增加测试覆盖率：完善单元测试和集成测试。
• 文档改进：添加更多示例和使用指南。

👥 贡献指南

欢迎社区贡献！请参考 CONTRIBUTING.md 了解如何参与项目。