MCP 服务器：可扩展的 OpenAPI 端点发现和 API 请求工具

待办事项

不包含预下载模型的 Docker 镜像大小为 2GB。包含预下载模型后则高达 3.76GB！太大了，请帮忙缩小一下。

配置

通过环境变量进行自定义。GLOBAL_TOOL_PROMPT非常重要！

OPENAPI_JSON_DOCS_URL ：OpenAPI 规范 JSON 的 URL（默认为https://api.staging.readymojo.com/openapi.json ）
MCP_API_PREFIX ：可自定义的工具命名空间（默认“any_openapi”）：
# Creates tools: custom_api_request_schema and custom_make_request docker run -e MCP_API_PREFIX=finance ...
GLOBAL_TOOL_PROMPT ：可选文本，附加到所有工具描述之前。这对于 Claude 准确选择（而非选择）你的工具至关重要。
# Adds "Access to insights apis for ACME Financial Services abc.com . " to the beginning of all tool descriptions docker run -e GLOBAL_TOOL_PROMPT="Access to insights apis for ACME Financial Services abc.com ." ...

TL'DR

我为什么创建这个：我想提供我的私有 API，其 swagger openapi 文档大小为几百 KB。

Claude MCP 在处理这些大小的文件时出现错误
我尝试将结果转换为 YAML，但不够小，并且出现很多错误。失败了
我尝试提供一个 API 类别，然后让 MCP 客户端（Claude Desktop）按组获取 API 文档。但文档仍然太大，失败了。

最终我找到了这个解决方案：

它使用内存语义搜索通过自然语言查找相关的 Api 端点（例如列出产品）
它以百万秒为单位（因为它在内存中）返回完整的端点文档（因为我设计它将一个端点存储为一个块）

轰隆隆，Claude 现在知道要调用哪个 API，并且知道完整的参数！

等一下，我必须在这个服务器中创建另一个工具来发出实际的 restful 请求，因为“fetch”服务器根本不起作用，而且我不想调试原因。

https://github.com/user-attachments/assets/484790d2-b5a7-475d-a64d-157e839ad9b0

技术亮点：

query -> [Embedding] -> FAISS TopK -> OpenAPI docs -> MCP Client (Claude Desktop)
MCP Client -> Construct OpenAPI Request -> Execute Request -> Return Response

特征

🧠 使用远程 openapi json 文件作为源，无需访问本地文件系统，API 更改无需更新
🔍 使用优化的 MiniLM-L3 模型进行语义搜索（43MB vs 原始 90MB）
🚀 基于 FastAPI 且支持异步的服务器
🧠 基于端点的分块 OpenAPI 规范（处理 100KB+ 文档），不会丢失端点上下文
⚡ 内存中 FAISS 向量搜索，可即时发现端点

限制

不支持 linux/arm/v7（Transformer 库构建失败）
🐢 如果不使用 docker 镜像，冷启动惩罚（模型加载约 15 秒）
[已过时] 当前 Docker 镜像已禁用下载模型。您依赖 huggingface。加载 Claude 桌面时，下载模型需要一些时间。如果 huggingface 宕机，您的服务器将无法启动。
最新的 Docker 镜像嵌入了预先下载的模型。如果出现问题，我会恢复到旧版本。

多实例配置示例

以下是多实例配置示例。我这样设计是为了能够更灵活地用于多组 API：

{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    },
    "healthcare_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.healthcare.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=healthcare",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for Healthcare API services efg.com .",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

在此示例中：

服务器将自动从 OpenAPI 文档中提取基本 URL：
- https://api.finance.com用于财务 API
- https://api.healthcare.com提供医疗保健 API
您可以选择使用API_REQUEST_BASE_URL环境变量覆盖基本 URL：

{
  "mcpServers": {
    "finance_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.finance.com/openapi.json",
        "-e",
        "API_REQUEST_BASE_URL=https://api.finance.staging.com",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .'",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Claude 桌面使用示例

Claude桌面项目提示：

You should get the api spec details from tools financial_api_request_schema

You task is use financial_make_request tool to make the requests to get response. You should follow the api spec to add authorization header:
Authorization: Bearer <xxxxxxxxx>

Note: The base URL will be returned in the api_request_schema response, you don't need to specify it manually.

在聊天中，您可以执行以下操作：

Get prices for all stocks

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装可扩展 OpenAPI 端点发现和 API 请求工具：

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

使用 pip

pip install mcp-server-any-openapi

可用工具

服务器提供以下工具（其中{prefix}由MCP_API_PREFIX决定）：

{前缀}_api_request_schema

获取符合您意图的 API 端点架构。返回端点详细信息，包括路径、方法、参数和响应格式。

输入模式：

{
    "query": {
        "type": "string",
        "description": "Describe what you want to do with the API (e.g., 'Get user profile information', 'Create a new job posting')"
    }
}

{前缀}_make_request

**对于使用复杂 API 进行可靠执行至关重要，**因为简化的实现方式会失效。提供：

输入模式：

{
    "method": {
        "type": "string",
        "description": "HTTP method (GET, POST, PUT, DELETE, PATCH)",
        "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
    },
    "url": {
        "type": "string",
        "description": "Fully qualified API URL (e.g., https://api.example.com/users/123)"
    },
    "headers": {
        "type": "object",
        "description": "Request headers (optional)",
        "additionalProperties": {
            "type": "string"
        }
    },
    "query_params": {
        "type": "object",
        "description": "Query parameters (optional)",
        "additionalProperties": {
            "type": "string"
        }
    },
    "body": {
        "type": "object",
        "description": "Request body for POST, PUT, PATCH (optional)"
    }
}

响应格式：

{
    "status_code": 200,
    "headers": {
        "content-type": "application/json",
        ...
    },
    "body": {
        // Response data
    }
}

Docker 支持

多架构构建

官方镜像支持3个平台：

# Build and push using buildx
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t buryhuang/mcp-server-any-openapi:latest \
  --push .

灵活的工具命名

通过MCP_API_PREFIX控制工具名称：

# Produces tools with "finance_api" prefix:
docker run -e MCP_API_PREFIX=finance_ ...

支持的平台

Linux/amd64
Linux/arm64

选项 1：使用预构建映像（Docker Hub）

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

选项 2：本地开发构建

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

运行容器

docker run \
  -e OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json \
  -e MCP_API_PREFIX=finance \
  buryhuang/mcp-server-any-openapi:latest

关键组件

EndpointSearcher ：核心类，处理以下内容：
- OpenAPI规范解析
- 语义搜索索引创建
- 端点文档格式
- 自然语言查询处理
服务器实现：
- 异步 FastAPI 服务器
- MCP 协议支持
- 工具注册和调用处理

从源运行

python -m mcp_server_any_openapi

与 Claude Desktop 集成

在 Claude Desktop 设置中配置 MCP 服务器：

{
  "mcpServers": {
    "any_openapi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OPENAPI_JSON_DOCS_URL=https://api.example.com/openapi.json",
        "-e",
        "MCP_API_PREFIX=finance",
        "-e",
        "GLOBAL_TOOL_PROMPT='Access to insights apis for ACME Financial Services abc.com .",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

贡献

分叉存储库
创建你的功能分支（ git checkout -b feature/amazing-feature ）
提交您的更改（ git commit -m 'Add some amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

执照

该项目根据 LICENSE 文件中的条款获得许可。

实施说明

以端点为中心的处理：与难以处理大型规范的文档级分析不同，我们使用以下方式对各个端点进行索引：
- 路径 + 方法作为唯一标识符
- 参数感知嵌入
- 响应架构上下文
优化的规范处理：通过以下方式处理高达 10MB（约 5,000 个端点）的 OpenAPI 规范：
- 架构组件的延迟加载
- 路径项的并行解析
- 选择性嵌入生成（省略冗余描述）

MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

Integrations