使用说明

项目简介

Scalable OpenAPI Endpoint Discovery and API Request Tool 是一个 MCP (Model Context Protocol) 服务器，旨在帮助大型语言模型 (LLM) 理解和使用基于 OpenAPI 规范的 API。它通过语义搜索技术，让 LLM 能够根据自然语言描述找到相关的 API 接口，并提供工具来实际调用这些 API。

主要功能点

动态API发现: 从远程 OpenAPI JSON 文档 URL 加载 API 接口定义，无需本地文件，API 更新自动同步。
语义搜索: 使用优化的 MiniLM-L3 模型进行语义搜索，根据用户意图快速找到相关的 API 接口。
高效服务: 基于 FastAPI 框架构建，异步处理请求，性能高效。
大文档支持: 支持处理大型 OpenAPI 文档（100KB+），通过端点级别的文档分割，保证上下文完整性。
快速响应: 使用内存 FAISS 向量索引进行语义搜索，实现毫秒级接口发现。
API请求工具: 内置 'make_request' 工具，支持 LLM 控制 HTTP 请求的 method, url, headers, query parameters 和 body，真正实现 API 调用。

安装步骤

方法一：使用 Smithery (推荐给 Claude Desktop 用户)

如果您使用 Claude Desktop，可以通过 Smithery 自动安装：

npx -y @smithery/cli install @baryhuang/mcp-server-any-openapi --client claude

方法二：使用 pip 安装

您可以使用 pip 命令安装：

pip install mcp-server-any-openapi

方法三：Docker 镜像 (推荐)

拉取预构建的 Docker 镜像：

docker pull buryhuang/mcp-server-any-openapi:latest

本地构建 Docker 镜像（可选）：

docker build -t mcp-server-any-openapi .

服务器配置

MCP 服务器需要配置在 MCP 客户端中才能使用，例如 Claude Desktop。配置信息为 JSON 格式，以下是使用 Docker 镜像部署的配置示例，您可以根据实际情况修改：

{
  "mcpServers": {
    "any_openapi": {  // server name，可以自定义，在Claude Desktop中用于标识
      "command": "docker",  // 启动命令，这里使用 docker
      "args": [  // 启动参数
        "run",
        "-i",  // 保持STDIN打开，即使未连接
        "--rm", // 容器退出时自动删除
        "-e",  // 设置环境变量
        "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json", //  OpenAPI 文档的 JSON 文件 URL，请替换为您要使用的 API 文档地址
        "-e",  // 设置环境变量
        "MCP_API_PREFIX=finance", //  API 工具的前缀，用于自定义工具名称，例如设置为 "finance" 后，工具名称会变为 "finance_api_request_schema" 和 "finance_make_request"， 默认为 "any_openapi"
        "buryhuang/mcp-server-any-openapi:latest" // Docker 镜像名称和标签
      ]
    }
  }
}

配置说明:

'"any_openapi"': MCP 服务器的名称，您可以自定义，用于在 MCP 客户端中识别和管理不同的 MCP 服务器连接。
'"command": "docker"': 指定启动 MCP 服务器的命令为 'docker'，表示使用 Docker 运行。
'"args": [...]' : 启动 'docker run' 命令所需的参数列表。
- '"-e", "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json"': 通过环境变量 'OPENAPI_JSON_DOCS_URL' 设置 OpenAPI 文档的 URL。请务必替换 'https://api.example.com/openapi.json' 为您实际要使用的 OpenAPI 文档地址。
- '"-e", "MCP_API_PREFIX=finance"': 通过环境变量 'MCP_API_PREFIX' 设置 API 工具的前缀。这会影响到 Claude Desktop 中显示的工具名称。例如，设置为 "finance" 后，工具名称会变成 'finance_api_request_schema' 和 'finance_make_request'。您可以根据您的 API 类型自定义前缀，方便在 Claude Desktop 中管理和区分不同的 API 工具。默认值为 "any_openapi"。
- '"buryhuang/mcp-server-any-openapi:latest"': 指定要运行的 Docker 镜像为 'buryhuang/mcp-server-any-openapi:latest'。

更多配置选项 (环境变量):

'API_REQUEST_BASE_URL': (可选) API 请求的基础 URL。默认情况下，服务器会自动从 OpenAPI 文档 URL 中提取基础 URL。如果需要覆盖，可以使用此环境变量显式指定。

基本使用方法

启动 MCP 服务器: 根据上述配置，在您的 MCP 客户端（如 Claude Desktop）中添加并启动 "any_openapi" 服务器。
在 LLM 对话中提问: 使用自然语言描述您想要执行的 API 操作。例如： "Get prices for all stocks"。
LLM 调用工具:
- LLM 会首先调用 '{prefix}_api_request_schema' 工具（例如 'finance_api_request_schema' 或 'any_openapi_api_request_schema'），根据您的提问进行语义搜索，找到匹配的 API 接口，并返回接口的 schema 信息。
- 接着，LLM 可以根据 schema 信息，调用 '{prefix}_make_request' 工具（例如 'finance_make_request' 或 'any_openapi_make_request'）来实际执行 API 请求。您可以在 Prompt 中指示 LLM 如何使用这两个工具，例如 Claude Desktop Usage Example 中提供的 Prompt 示例。

可用工具:

'{prefix}_api_request_schema': 根据自然语言查询，返回匹配的 API 接口 schema 信息，包括路径、方法、参数和响应格式。
- 输入参数: 'query' (string): 描述您想要执行的 API 操作的自然语言查询 (例如 "获取用户信息", "创建新的职位")。
'{prefix}_make_request': 执行实际的 REST API 请求。
- 输入参数:
  - 'method' (string): HTTP 方法 (GET, POST, PUT, DELETE, PATCH)。
  - 'url' (string): 完整的 API URL (例如 'https://api.example.com/users/123')。
  - 'headers' (object, 可选): 请求头。
  - 'query_params' (object, 可选): 查询参数。
  - 'body' (object, 可选): 请求体 (用于 POST, PUT, PATCH 请求)。
- 返回结果: 包含 'status_code' (HTTP 状态码), 'headers' (响应头) 和 'body' (响应体) 的 JSON 对象。

请将 '{prefix}' 替换为您配置的 'MCP_API_PREFIX' 环境变量的值 (默认为 'any_openapi')。

关键词