MCP Server: Scalable OpenAPI Endpoint Discovery and API Request Tool

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 ." ...
  

简而言之

我创建它的原因：我想提供私有 API 服务，其 Swagger OpenAPI 文档有数百 KB。

• Claude MCP 处理这么大的文件时会直接报错
• 我尝试将结果转换为 YAML，但文件仍然不够小，而且有很多错误。失败
• 我尝试提供 API 类别，然后让 MCP 客户端（Claude Desktop）按组获取 API 文档。文件还是太大，失败。

最终我采用了这个方案：

• 它使用内存语义搜索，通过自然语言（例如列出产品）查找相关 API 端点
• 它会在毫秒内返回完整的端点文档（我设计为每个端点存储为一个数据块），因为数据在内存中

搞定，Claude 现在知道要调用哪个 API，而且拥有完整参数！

等等，我还得在这个服务中创建另一个工具来发起实际的 REST 请求，因为“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，而原版为 90MB）
• 🚀 基于 FastAPI 的服务，支持异步
• 🧠 按端点对 OpenAPI 规范进行分块（可处理 100KB 以上的文档），不会丢失端点上下文
• ⚡ 使用内存中的 FAISS 向量搜索，即时发现端点

局限性

• 不支持 linux/arm/v7（Transformer 库构建失败）
• 🐢 如果不使用 Docker 镜像，冷启动会有延迟（模型加载约需 15 秒）
• [已过时] 当前 Docker 镜像已禁用模型下载。你需要依赖 huggingface。加载 Claude Desktop 时，需要一些时间下载模型。如果 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 Desktop 使用示例

Claude Desktop 项目提示词：

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 决定）：

{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')"
    }
}

{prefix}_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

关键组件

1. EndpointSearcher：负责以下工作的核心类：

   • 解析 OpenAPI 规范
   • 创建语义搜索索引
   • 格式化端点文档
   • 处理自然语言查询

2. 服务实现：

   • 异步 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"
      ]
    }
  }
}

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

许可证

本项目采用 LICENSE 文件中所列条款授权。

实现说明

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