使用说明

项目简介

OpenAPI-MCP 旨在通过 Model Context Protocol (MCP) 协议，使大型语言模型 (LLM) 能够无缝访问和利用 OpenAPI 定义的外部 API。它能够动态读取 OpenAPI/Swagger 规范，自动注册 API 接口为工具，并以 JSON-RPC 2.0 标准格式与客户端通信，为 LLM 应用提供可扩展的 API 上下文服务。

主要功能点

动态工具生成：自动加载 OpenAPI 规范（JSON/YAML），提取 API 接口信息并注册为 MCP 工具。
JSON-RPC 2.0 兼容：所有响应均符合 JSON-RPC 2.0 标准，包含顶层 'server_name' 字段，易于集成。
详细的帮助信息：为工具提供参数说明和使用帮助。
认证支持：支持直接访问令牌和 OAuth client_credentials 认证。
LLM 集成：通过 MCP 协议将 API 接口注册为工具，可被 LLM 直接调用，例如 cursor 和 windsurf 等 MCP 客户端。

安装步骤

创建虚拟环境 (推荐):

python3 -m venv venv

激活虚拟环境:

Linux/macOS:

source venv/bin/activate

Windows:

venv\Scripts\activate

安装依赖:

pip install -r requirements.txt

服务器配置

MCP 客户端需要配置以下 JSON 以连接到 OpenAPI-MCP 服务器。请根据实际使用的 OpenAPI 服务修改 'OPENAPI_URL' 环境变量。

{
    "mcpServers": {
        "openapi_server_name": {  //  MCP 服务器名称，客户端根据此名称调用
            "command": "bash",
            "args": [
                "-c",
                "source venv/bin/activate && python3 src/openapi-mcp.py --server openapi_server_name api list-endpoints" //  服务器启动命令，openapi_server_name 为服务器自定义名称，api list-endpoints 为启动参数，列出所有可用工具
            ],
            "env": {
                "OPENAPI_URL": "https://api.met.no/weatherapi/locationforecast/2.0/swagger"  //  OpenAPI 规范的 URL，指向需要代理的 API
            }
        }
    }
}

配置参数说明:

'server_name': MCP 服务器的名称，例如 'openapi_server_name'，客户端通过此名称来识别和调用该服务器。
'command': 启动服务器的命令，这里使用 'bash -c' 执行一段组合命令。
'args': 传递给 'bash -c' 的参数数组，用于执行实际的服务器启动命令。
- '"source venv/bin/activate && python3 src/openapi-mcp.py --server openapi_server_name api list-endpoints"': 首先激活虚拟环境，然后运行 'openapi-mcp.py' 脚本。
  - '--server openapi_server_name': 指定 MCP 服务器的名称为 'openapi_server_name'，应与 'mcpServers' 配置中的名称一致。
  - 'api list-endpoints': 指定 'openapi-mcp.py' 运行 'api' 服务的 'list-endpoints' 动作，用于列出所有可用的 API 接口（工具）。
'env': 环境变量配置。
- 'OPENAPI_URL': 必须配置，指向您要代理的 OpenAPI 规范文档的 URL。OpenAPI-MCP 将根据此 URL 加载 API 定义。

注意:

您可以根据需要修改 'server_name' 和 'openapi_server_name' 为更具描述性的名称，但要确保在 MCP 客户端配置、'mcpServers' 配置和服务器启动命令中保持一致。
如果您的 OpenAPI 服务需要 OAuth 认证，请配置 'OAUTH_CLIENT_ID', 'OAUTH_CLIENT_SECRET', 'OAUTH_SCOPE', 'OAUTH_TOKEN_URL' 等环境变量。
如果您的 OpenAPI 服务使用直接访问令牌认证，请配置 'AUTH_TOKEN' 环境变量。

基本使用方法

列出可用工具 (endpoints): MCP 客户端连接到 OpenAPI-MCP 服务器后，可以请求列出所有可用的工具（即 OpenAPI 定义的 API 接口）。服务器将返回 JSON-RPC 格式的响应，其中包含工具的名称、描述和参数信息。
获取工具帮助: MCP 客户端可以请求获取特定工具的详细帮助信息，包括工具的描述、参数列表和参数说明。
调用工具 (endpoint): MCP 客户端可以使用工具名称和参数来调用 API 接口。参数以键值对的形式提供。服务器将执行 API 调用，并将 API 响应封装在 JSON-RPC 响应中返回给客户端。

示例命令 (在服务器端执行，用于测试和调试):

列出所有 endpoints (工具)

python3 src/openapi-mcp.py api list-endpoints --output json

获取指定 endpoint 的帮助信息

python3 src/openapi-mcp.py api call-endpoint --name get__compact help

调用 endpoint 并传递参数

python3 src/openapi-mcp.py api call-endpoint --name get__compact --param lat=60 --param lon=10

Dry-run 模式 (模拟调用，不实际发送 API 请求)

python3 src/openapi-mcp.py api call-endpoint --name get__compact --param lat=60 --param lon=10 --dry-run

通过以上配置和使用方法，您可以将 OpenAPI-MCP 集成到您的 MCP 客户端中，使 LLM 能够利用 OpenAPI 定义的 API 功能。

关键词