OpenAPI 到 MCP 的转换工具文档

项目概述

此项目提供了一个 Java 工具，用于将 OpenAPI 规范转换为 Model Context Protocol (MCP) 服务器。通过 Swagger Parser 解析 OpenAPI 文件，并生成相应的 MCP 工具类。该工具支持多种 HTTP 方法、内容类型处理、错误处理和身份验证。

功能特性

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

快速入门

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 请求逻辑
    }

}

详细指南

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 了解如何参与项目。