使用说明

项目简介

OpenAPI MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，它能够读取 OpenAPI (Swagger) 规范文件，并将其中定义的 REST API 接口自动转化为 MCP 协议下的 工具 (Tools)。这样，LLM 客户端可以通过 MCP 协议调用这些工具，从而间接地调用和利用底层的 REST API 服务。

主要功能点

REST API 转 MCP 工具: 自动解析 OpenAPI 规范，将 REST API 端点注册为 MCP 服务器的工具，无需手动编写工具定义。
支持多种 HTTP 方法: 支持 GET, POST, PUT, PATCH 等常用的 HTTP 请求方法。
灵活的 API 过滤: 允许通过白名单 (API_WHITE_LIST) 或黑名单 (API_BLACK_LIST) 环境变量，灵活地控制哪些 API 接口暴露为 MCP 工具。
参数自动处理: 自动处理 API 请求的路径参数、查询参数、请求头和请求体，并根据 OpenAPI 规范生成请求示例。
基于 Pydantic 的请求模型: 根据 OpenAPI 规范动态生成 Pydantic 数据模型，用于请求体的序列化和验证。
环境变量配置: 通过 '.env' 文件或环境变量进行服务器配置，包括 OpenAPI 规范路径、API 基础 URL、请求头、代理设置等。
详细日志: 提供详细的 debug 日志，方便开发和问题排查。

安装步骤

安装 Python 包:

pip install openapi_mcp_server

创建 '.env' 配置文件: 在运行 'openapi_mcp_server' 的目录下创建 '.env' 文件，并配置以下必需环境变量：
- 'OPENAPI_SPEC_PATH': 指向 OpenAPI 规范文件的路径，可以是本地文件路径或 URL。例如：'https://petstore.swagger.io/v2/swagger.json'
- 'API_BASE_URL': REST API 的基础 URL。例如：'https://petstore.swagger.io/v2'
可选环境变量：
- 'DEBUG': 设置为 'TRUE' 启用 debug 日志，默认为 'FALSE'。
- 'API_HEADERS': 添加到所有 API 请求的自定义请求头，格式为 'Header1:Value1,Header2:Value2'。
- 'API_WHITE_LIST': 允许暴露为 MCP 工具的 operationId 列表，使用英文逗号分隔。例如：'addPet,updatePet,findPetsByStatus'
- 'API_BLACK_LIST': 禁止暴露为 MCP 工具的 operationId 列表，使用英文逗号分隔。
- 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY': 代理设置。
'.env' 示例文件内容:
```
OPENAPI_SPEC_PATH=https://petstore.swagger.io/v2/swagger.json
API_BASE_URL=https://petstore.swagger.io/v2
API_WHITE_LIST=addPet,updatePet,findPetsByStatus
DEBUG=TRUE
```
运行 MCP 服务器: 在包含 '.env' 文件的目录下，执行以下命令启动服务器：
```
uv run openapi_mcp_server
```

服务器配置

以下 JSON 配置信息用于 MCP 客户端连接 'openapi_mcp_server'，例如 Claud Desktop 等 MCP 客户端：

{
  "mcpServers": {
    "openapi_mcp_server":{
      "command": "uv",
      "args": ["run","openapi_mcp_server"],
      "env": {
        "DEBUG":"1",
        "API_BASE_URL":"https://petstore.swagger.io/v2",
        "OPENAPI_SPEC_PATH":"https://petstore.swagger.io/v2/swagger.json",
        "API_HEADERS":"Accept:application/json",
        "API_WHITE_LIST":"addPet,updatePet,findPetsByStatus"
      }
    }
  }
}

配置参数说明:

'"openapi_mcp_server"': 服务器名称，可以自定义。
'"command": "uv"': 启动服务器的命令，这里使用 'uv' 运行器。
'"args": ["run","openapi_mcp_server"]': 传递给 'uv run' 的参数，指定运行 'openapi_mcp_server' 模块。
'"env"': 环境变量配置，与 '.env' 文件中的配置相同，用于设置服务器行为。
- '"DEBUG": "1"': 启用 debug 日志。
- '"API_BASE_URL": "https://petstore.swagger.io/v2"': REST API 的基础 URL。
- '"OPENAPI_SPEC_PATH": "https://petstore.swagger.io/v2/swagger.json"': OpenAPI 规范文件 URL。
- '"API_HEADERS": "Accept:application/json"': 设置请求头，例如指定 'Accept' 类型。
- '"API_WHITE_LIST": "addPet,updatePet,findPetsByStatus"': 白名单，只暴露 'addPet', 'updatePet', 'findPetsByStatus' 这几个 operationId 对应的 API 接口为 MCP 工具。

基本使用方法

确保 MCP 服务器已成功启动并运行。
在 MCP 客户端（例如 Claud Desktop）中配置上述服务器连接信息。
在 LLM 应用中，通过 MCP 协议调用 'openapi_mcp_server' 提供的工具 (Tools)，工具名称对应 OpenAPI 规范中定义的 'operationId'。
LLM 可以根据工具的描述和参数，生成合适的请求来调用 REST API。
服务器会将 API 响应返回给 LLM 客户端。

注意: 请确保 'OPENAPI_SPEC_PATH' 指向有效的 OpenAPI 规范文件，并且 'API_BASE_URL' 与 OpenAPI 规范中定义的 API 服务地址一致。

关键词