使用说明

OpenAPI到MCP转换器

该项目在OpenAPI规范和模型上下文协议（MCP）之间架起了一座桥梁。它允许基于LLM的工具（如MCP Inspector）与使用OpenAPI定义的REST API进行交互。

特性

将OpenAPI规范动态转换为MCP工具
将REST API端点公开为LLM的可调用函数
支持路径参数、查询参数、请求正文和标头
处理身份验证（承载令牌、基本身份验证、API密钥）
支持所有HTTP方法（GET、POST、PUT、DELETE等）
与MCP检查员和其他MCP客户合作

先决条件

Java 11或更高版本
Maven 3.6或更高版本
OpenAPI规范文件（JSON格式）
MCP检查员或其他MCP客户

建设项目

克隆存储库：

git clone https://github.com/pcnfernando/openapi-to-mcp.git
cd openapi-to-mcp

使用Maven构建项目：
```
mvn clean package
```
这将创建一个包含所有依赖项的胖JAR：
```
target/openapi-mcp-0.1.0-SNAPSHOT-jar-with-dependencies.jar
```

运行服务器

使用OpenAPI规范文件和API的基本URL运行服务器：

java -jar target/openapi-mcp-0.1.0-SNAPSHOT-jar-with-dependencies.jar /path/to/openapi.json https://api.example.com

论据：

path/to/openapi.json：OpenAPI规范文件的路径
https://api.example.com：API的基本URL（可选，默认为http://localhost:8080/api)

与MCP检查员联系

启动MCP检查器
选择“连接”或创建新连接
使用以下配置：
- 运输类型： stdio
- 命令： java
- 论据： -jar /absolute/path/to/target/openapi-mcp-0.1.0-SNAPSHOT-jar-with-dependencies.jar /absolute/path/to/openapi.json https://api.example.com 确保JAR文件和OpenAPI规范文件都使用绝对路径。
连接到服务器
现在，您应该将OpenAPI规范中的所有API操作都看作可用的MCP工具

与Claude Desktop连接

创建或编辑Claude的配置文件：

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json\

添加您的OpenAPI MCP服务器配置：

{
  "mcpServers": {
    "petstore": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/openapi-mcp-0.1.0-SNAPSHOT-jar-with-dependencies.jar",
        "/absolute/path/to/openapi.json",
        "https://api.example.com"
      ]
    }
  }
}

重新启动Claude Desktop以使更改生效。
通过查找输入框右下角的锤子图标来验证工具是否可用。点击它应该显示您的API操作作为可用的工具。
通过让Claude使用您的API执行操作来测试它：

示例：“从宠物商店API获取ID为123的宠物的详细信息。”

Claude将检测何时使用API操作，并在对后端API进行实际调用之前征求您的批准。

请注意，Claude Desktop将使用您的用户帐户的权限运行配置文件中的命令，因此只能添加来自您信任的源的命令。

示例：与Swagger宠物店一起使用

将Petstore OpenAPI规范保存到文件（例如。， petstore.json)
使用以下方式与MCP检查器连接：
- 命令： java
- 论据： -jar /absolute/path/to/target/openapi-mcp-0.1.0-SNAPSHOT-jar-with-dependencies.jar /absolute/path/to/petstore.json https://petstore.swagger.io/v2
可用操作应包括 findPetsByStatus, getPetById等等。

身份验证支持

转换器支持REST API中常用的各种身份验证方法：

承载令牌身份验证

{
  "operationId": "listItems",
  "auth_bearer": "your-jwt-token-here"
}

这将添加标题： Authorization: Bearer your-jwt-token-here

基本身份验证

{
  "operationId": "getUser",
  "auth_basic": "base64-encoded-credentials"
}

这将添加标题： Authorization: Basic base64-encoded-credentials

API密钥验证

{
  "operationId": "createItem",
  "auth_apikey": "your-api-key-here"
}

这将添加标题： X-API-Key: your-api-key-here

自定义头

{
  "operationId": "updateItem",
  "header_X-Custom-Header": "custom-value"
}

这将添加标题： X-Custom-Header: custom-value

故障排除

连接问题

如果您遇到连接问题：

验证基本URL是否正确且可访问：
```
curl -v https://api.example.com/some-endpoint
```
检查网络设置（代理、防火墙）
确保OpenAPI规范中的路径与实际API端点匹配

身份验证问题

如果您遇到身份验证问题：

仔细检查您的身份验证参数：
- 对于Bearer代币，请使用 auth_bearer 参数
- 对于基本身份验证，请使用 auth_basic 带有Base64编码凭据的参数
- 对于API密钥，请使用 auth_apikey 参数

通过curl测试验证令牌/凭据是否有效：

curl -v -H "Authorization: Bearer your-token" https://api.example.com/endpoint

Java错误

如果您看到Java错误：

请确保您使用的是Java 11或更高版本：
```
java -version
```
检查您的OpenAPI规范是否是有效的JSON
在服务器日志中查找错误详细信息

嵌入到其他应用程序中

1.添加依赖关系

将OpenAPI到MCP转换器添加到您的项目中：

<!-- Maven -->
<dependency>
    <groupId>pcnfernando.mcp</groupId>
    <artifactId>openapi-mcp</artifactId>
    <version>0.1.0</version>
</dependency>

// Gradle
implementation 'pcnfernando.mcp:openapi-mcp:0.1.0'

2.基本用法

下面是一个将MCP服务器嵌入应用程序的简单示例：

import pcnfernando.openapi.mcp.OpenApiMcpServer;

// Configure and start the server
OpenApiMcpServer server = OpenApiMcpServer.builder()
    .withOpenApiSpecFromFile("path/to/openapi.json")
    .withBaseUrl("https://api.example.com")
    .build();

// Start the server
server.start();

// Register shutdown hook
Runtime.getRuntime().addShutdownHook(new Thread(server::shutdown));

配置选项

构建器模式提供了几个配置选项：

OpenAPI规范

您可以通过三种方式提供OpenAPI规范：

// From a file
.withOpenApiSpecFromFile("path/to/openapi.json")

// From a URL
.withOpenApiSpecFromUrl("https://example.com/api/openapi.json")

// Directly as a string
.withOpenApiSpec(openApiSpecString)

API基本URL

设置API的基本URL：

.withBaseUrl("https://api.example.com")

MCP能力

配置启用和通告哪些MCP功能：

.withCapabilities(capabilities -> capabilities
    .enableTools(true)        // Enable tools functionality
    .enableResources(true)    // Enable resources functionality 
    .enablePrompts(false)     // Disable prompts functionality
    .advertiseTools(true)     // Advertise tools capability
    .advertiseResources(true) // Advertise resources capability
    .advertisePrompts(false)  // Don't advertise prompts capability
)

HTTP头处理模块

将自定义标头添加到所有API请求：

// Add individual headers
.withAdditionalHeader("X-API-Key", "your-api-key")
.withAdditionalHeader("User-Agent", "MyApp/1.0")

// Or add multiple headers at once
.withAdditionalHeaders(Map.of(
    "X-API-Key", "your-api-key",
    "User-Agent", "MyApp/1.0"
))

传输配置

配置传输机制（目前仅完全支持STDIO）：

.withTransportType(OpenApiMcpServer.TransportType.STDIO)

框架集成

Spring Boot

对于Spring Boot应用程序，创建一个配置类：

@Configuration
public class OpenApiMcpConfig {

    @Value("${api.base-url}")
    private String apiBaseUrl;

    @Value("${api.spec-location}")
    private String apiSpecLocation;

    @Bean(destroyMethod = "shutdown")
    public OpenApiMcpServer openApiMcpServer() throws IOException {
        OpenApiMcpServer server = OpenApiMcpServer.builder()
                .withOpenApiSpecFromFile(apiSpecLocation)
                .withBaseUrl(apiBaseUrl)
                .build();
                
        server.start();
        return server;
    }
}

环境变量

转换器支持多种环境变量进行配置：

SERVER_URL_OVERRIDE：覆盖OpenAPI规范中的基本URL
ENABLE_TOOLS：启用/禁用工具功能（默认值：true）
ENABLE_RESOURCES：启用/禁用资源功能（默认值：false）
ENABLE_PROMPTS：启用/禁用提示功能（默认值：false）
CAPABILITIES_TOOLS：广告工具功能（默认值：true）
CAPABILITIES_RESOURCES：广告资源功能（默认值：false）
CAPABILITIES_PROMPTS：广告提示功能（默认值：false）
EXTRA_HEADERS：要包含在API请求中的其他标头

安全考虑

在生产应用程序中嵌入OpenAPI到MCP转换器时：

为API实施适当的身份验证
考虑为API连接启用TLS
仔细控制哪些API端点作为工具公开
对描述进行消毒，以防止迅速注射攻击

许可证

MIT许可证