项目简介

'openapi-mcp' 是一个将现有的 OpenAPI 3.x 规范转换为 Model Context Protocol (MCP) 工具服务器的应用程序。它使得大型语言模型 (LLM) 客户端（如 AI 助手、智能代理）能够以标准化的方式发现、理解和调用通过 OpenAPI 定义的外部 API。

该项目解析 OpenAPI 规范文件（YAML或JSON），将每个操作（Operation）转换为一个MCP工具，并提供一个MCP接口（通过标准I/O或HTTP）供客户端连接和交互。

主要功能点

OpenAPI到MCP工具的快速转换: 自动将 OpenAPI 规范中的每个API操作映射为一个可供LLM调用的MCP工具。
多种传输协议支持: 默认通过标准输入/输出 (stdio) 进行通信，也可配置为HTTP服务器模式（支持Server-Sent Events - SSE 和 POST 请求）。
全面的API特性支持: 自动处理路径参数、查询参数、请求头、Cookie以及JSON格式的请求体参数。
多种认证方式: 支持API Key、Bearer Token、Basic Auth及OAuth2等OpenAPI安全方案，可通过环境变量、命令行参数或HTTP头配置。
结构化和AI友好输出: 提供一致、机器可读的响应格式，包含类型信息、详细的Schema、操作建议和错误信息，优化LLM解析和理解。
OpenAPI规范的验证与Linting: 内置强大的功能，检查API规范的有效性和最佳实践，帮助改进API定义。
安全特性: 对PUT、POST、DELETE等潜在危险操作提供可选的调用确认机制。
自动生成文档: 可将生成的工具列表和Schema导出为Markdown格式文档。
灵活的过滤功能: 支持按标签、描述或操作ID列表过滤要暴露的API操作。

安装步骤

安装 Go 语言: 确保您的系统已安装 Go 1.21 或更高版本。可以从 Go官方网站下载安装。

克隆仓库: 打开终端，执行以下命令克隆项目源代码：

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

构建程序: 在项目根目录下执行构建命令：
```
make
```
这将在 'bin/' 目录下生成 'openapi-mcp'（MCP服务器主程序）和 'mcp-client'（交互式MCP客户端）两个可执行文件。

MCP客户端配置

MCP客户端需要知道如何启动 'openapi-mcp' 服务器进程并与其建立连接。通常在客户端的配置文件中指定服务器的启动命令和参数。以下是一个示例配置片段（请根据您的实际文件路径和API密钥进行调整）：

{
    "my_api_server": {
        "command": "/path/to/your/openapi-mcp/bin/openapi-mcp",
        "args": [
            "--api-key", "YOUR_API_KEY",  // 可选：如果您的API需要API Key认证，请替换 YOUR_API_KEY
            "/path/to/your/api.yaml"      // 替换为您实际的OpenAPI规范文件路径
            // 如果使用HTTP模式，参数会有所不同，例如：
            // "--http", ":8080", "/path/to/your/api.yaml"
            // 对于多API挂载：
            // "--http", ":8080", "--mount", "/petstore:/path/to/petstore.yaml", "--mount", "/books:/path/to/books.yaml"
        ],
        "capabilities": {
             "tools": {} // 声明客户端支持工具调用
        }
        // 其他可能的客户端配置...
    }
}

配置说明:

'"my_api_server"': 您为该MCP服务器定义的名称，客户端使用此名称引用它。
'"command"': 'openapi-mcp' 可执行文件的完整路径。
'"args"': 启动 'openapi-mcp' 时需要传递的命令行参数列表。
- '-api-key YOUR_API_KEY': 如果API需要API Key认证，可以使用此参数传递API Key（更安全的做法是使用环境变量 'API_KEY' 或HTTP头，具体取决于MCP客户端和服务器的通信方式和配置）。
- '/path/to/your/api.yaml': 指向您希望 'openapi-mcp' 暴露的 OpenAPI 规范文件的路径。这是在 stdio 模式下启动服务器时必需的参数。
- '--http :8080': 如果您想以HTTP模式运行 'openapi-mcp'，请使用此参数指定监听地址和端口（例如 ':8080'）。在这种模式下，客户端将通过HTTP连接而不是标准I/O。
- '--mount /base:/path/to/spec.yaml': 在HTTP模式下，可以使用 '--mount' 参数多次指定多个OpenAPI文件及其对应的URL基本路径。
'"capabilities"': 客户端向服务器声明支持的MCP功能，至少应包含 '"tools": {}' 以便客户端发现和使用工具。

MCP客户端会读取此配置，启动指定的 'command' 进程，并通过标准I/O（或配置的HTTP地址）与 'openapi-mcp' 建立JSON-RPC连接，然后开始发现和调用由OpenAPI规范生成的工具。

基本使用方法

准备 OpenAPI 规范文件: 确保您有一个有效的 OpenAPI 3.x YAML 或 JSON 格式的 API 规范文件（例如 'your_api.yaml'）。
启动 MCP 服务器:
- 标准 I/O 模式 (默认): 在终端运行：
```
./bin/openapi-mcp your_api.yaml
```
  服务器将启动并等待来自标准输入的MCP JSON-RPC消息。
- HTTP 模式: 在终端运行（例如监听8080端口）：
```
./bin/openapi-mcp --http=:8080 your_api.yaml
```
  服务器将在 'http://localhost:8080/mcp' 提供MCP接口（SSE用于通知，POST用于请求）。您也可以使用 '--base-url' 参数指定外部可访问的URL。对于多API挂载，使用 '--mount' 参数。

使用 MCP 客户端: 使用支持MCP协议的客户端（如 'mcp-client' 或兼容的AI编辑器/工具）连接到服务器。

连接到标准 I/O 服务器: 在另一个终端运行 'mcp-client'，并将其连接到 'openapi-mcp' 进程：
```
./bin/mcp-client ./bin/openapi-mcp your_api.yaml
```
进入 'mcp>' 提示符，您可以执行命令：
- 'list': 列出所有可用的工具（API操作）。
- 'schema <tool-name>': 查看特定工具的输入参数Schema。
- 'call <tool-name> <json-args>': 调用工具并传递JSON格式的参数。
- 'help': 获取客户端命令帮助。
- 'exit'/'quit': 退出客户端。

连接到 HTTP 服务器: 客户端需要配置HTTP端点。例如，您可以使用 'curl' 测试 HTTP 模式下的验证/linting端点：

# 假设您以 'openapi-mcp --http=:8080 validate' 模式启动了服务器
curl -X POST http://localhost:8080/validate \
  -H "Content-Type: application/json" \
  -d '{"openapi_spec": "openapi: 3.0.0\ninfo:\n  title: Test\n  version: 1.0.0\npaths: {}"}'

对于实际的MCP交互，客户端需要实现HTTP SSE和POST通信逻辑。

关键词

API工具, 自动化, LLM集成, AI Agent, OpenAPI

关键词

项目简介

主要功能点

安装步骤

MCP客户端配置

基本使用方法

关键词

信息