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

TODO

• Docker 镜像在没有预先下载模型的情况下为 2GB。预先下载模型后为 3.76GB！！太大了，请大家帮我缩小尺寸。

概括

我创建这个的原因：我想服务于我的私有 API，其 swagger openapi 文档大小为几百 KB。

• Claude MCP 在处理这些大小的文件时会直接报错
• 我尝试将结果转换为 YAML，但不够小，并且有很多错误。失败
• 我尝试提供一个 API 类别，然后让 MCP Client (Claude Desktop) 按组获取 api 文档。仍然太大，失败。

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

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

Boom，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 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",
        "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",
        "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",
        "buryhuang/mcp-server-any-openapi:latest"
      ]
    }
  }
}

Claude Desktop 使用示例

Claude Desktop 项目提示：

您应该从工具 financial_api_request_schema 获取 api 规范详细信息

您的任务是使用 financial_make_request 工具发出请求以获取响应。您应该按照 api 规范添加授权标头：
Authorization: Bearer <xxxxxxxxx>

注意：基本 URL 将在 api_request_schema 响应中返回，您无需手动指定它。

在聊天中，您可以这样做：

获取所有股票的价格

安装

通过 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

配置

通过环境变量自定义：

• OPENAPI_JSON_DOCS_URL：OpenAPI 规范 JSON 的 URL（默认为 https://api.staging.readymojo.com/openapi.json）
• MCP_API_PREFIX：可自定义的工具命名空间（默认为 "any_openapi"）：

  # 创建工具：custom_api_request_schema 和 custom_make_request
  docker run -e MCP_API_PREFIX=finance ...
  

可用工具

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

{prefix}_api_request_schema

获取与您的意图匹配的 API 端点模式。返回端点详细信息，包括路径、方法、参数和响应格式。

输入模式：

{
    "query": {
        "type": "string",
        "description": "描述您想使用 API 做什么（例如，“获取用户个人资料信息”、“创建新的职位发布”）"
    }
}

{prefix}_make_request

对于复杂 API 的可靠执行至关重要，在这些 API 中，简化的实现会失败。提供：

输入模式：

{
    "method": {
        "type": "string",
        "description": "HTTP 方法（GET、POST、PUT、DELETE、PATCH）",
        "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
    },
    "url": {
        "type": "string",
        "description": "完全限定的 API URL（例如，https://api.example.com/users/123）"
    },
    "headers": {
        "type": "object",
        "description": "请求标头（可选）",
        "additionalProperties": {
            "type": "string"
        }
    },
    "query_params": {
        "type": "object",
        "description": "查询参数（可选）",
        "additionalProperties": {
            "type": "string"
        }
    },
    "body": {
        "type": "object",
        "description": "POST、PUT、PATCH 的请求正文（可选）"
    }
}

响应格式：

{
    "status_code": 200,
    "headers": {
        "content-type": "application/json",
        ...
    },
    "body": {
        // 响应数据
    }
}

Docker 支持

多架构构建

官方镜像支持 3 个平台：

# 使用 buildx 构建和推送
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t buryhuang/mcp-server-any-openapi:latest \
  --push .

灵活的工具命名

通过 MCP_API_PREFIX 控制工具名称：

# 生成带有 "finance_api" 前缀的工具：
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",
        "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 规范：
  • 延迟加载模式组件
  • 并行解析路径项
  • 选择性嵌入生成（省略冗余描述）