Any Openapi

Python

MIT License

baryhuang

最近更新：25天前

一个 MCP 服务器，使 Claude 能够通过语义搜索发现并调用任何 API 端点。智能分块 OpenAPI 规范以处理大型 API 文档，并具备内置的请求执行功能。非常适合将私有 API 与 Claude Desktop 集成。

概述

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

TODO

未预下载模型的 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"）：

bash 复制代码

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

GLOBAL_TOOL_PROMPT: 可选文本，用于在所有工具描述前添加内容。这对于让 Claude 准确选择或不选择您的工具至关重要。

bash 复制代码

# 在所有工具描述前添加 "Access to insights apis for ACME Financial Services abc.com . "
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 端点
在毫秒内返回完整的端点文档（因为我设计为每个端点存储为一个块）

Boom，Claude 现在知道要调用哪个 API，并附带完整参数！

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

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

技术亮点：

python 复制代码

query -> [Embedding] -> FAISS TopK -> OpenAPI 文档 -> MCP Client (Claude Desktop)
MCP Client -> 构建 OpenAPI 请求 -> 执行请求 -> 返回响应

特性

🧠 使用远程 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 集合：

json 复制代码

{
  "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：

json 复制代码

{
  "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 项目提示：

复制代码

你应该从 financial_api_request_schema 工具中获取 API 规范文档。

你的任务是使用 financial_make_request 工具发出请求以获取响应。根据 API 规范添加授权头：
Authorization: Bearer <xxxxxxxxx>

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

在聊天中，您可以输入：

复制代码

获取所有股票的价格

安装

通过 Smithery 安装

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

bash 复制代码

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

使用 pip

bash 复制代码

pip install mcp-server-any-openapi

可用工具

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

{prefix}_api_request_schema

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

输入模式：

json 复制代码

{
    "query": {
        "type": "string",
        "description": "描述你想用 API 做什么（例如，'获取用户档案信息', '创建新职位发布'）"
    }
}

{prefix}_make_request

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

输入模式：

json 复制代码

{
    "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 请求体（可选）"
    }
}

响应格式：

json 复制代码

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

Docker 支持

多架构构建

官方镜像支持 3 个平台：

bash 复制代码

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

灵活的工具命名

通过 MCP_API_PREFIX 控制工具名称：

bash 复制代码

# 生成带有 "finance_api" 前缀的工具：
docker run -e MCP_API_PREFIX=finance_ ...

支持的平台

linux/amd64
linux/arm64

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

bash 复制代码

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

选项 2：本地开发构建

bash 复制代码

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

运行容器

bash 复制代码

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 协议支持
- 工具注册与调用处理

从源代码运行

bash 复制代码

python -m mcp_server_any_openapi

与 Claude Desktop 集成

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

json 复制代码

{
  "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"
      ]
    }
  }
}

贡献

Fork 仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

许可证

本项目基于 LICENSE 文件中包含的条款许可。

实现说明

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

Any Openapi

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

TODO

配置

TL'DR

特性

局限性

多实例配置示例

Claude Desktop 使用示例

安装

通过 Smithery 安装

使用 pip

可用工具

{prefix}_api_request_schema

{prefix}_make_request

Docker 支持

多架构构建

灵活的工具命名

支持的平台

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

选项 2：本地开发构建

运行容器

关键组件

从源代码运行

与 Claude Desktop 集成

贡献

许可证

实现说明

Ai Image Gen Mcp

Aistor

Apple Notes Mcp

Cursor File Organizer

猫目

友情链接

热门推荐

关于

关注我们