AI导哈

OpenAPI端点发现与请求工具

MCP Server是一个可扩展的OpenAPI端点发现和API请求工具，通过语义搜索快速找到相关API端点并执行请求。

  • by baryhuang
  • Python
  • 本地部署
  • 82 星标
  • 更新于
在 GitHub 查看 baryhuang/mcp-server-any-openapi

使用说明

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服务，其招摇撞骗的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对比原始90MB）
  • 🚀 基于FastAPI的服务器，支持异步
  • 🧠 基于端点的分块OpenAPI规范（处理100KB+文档），不丢失端点上下文
  • ⚡ 内存中FAISS矢量搜索用于即时端点发现

局限性

  • 不支持linux/arm/v7（在Transformer库上构建失败）
  • 🐢 如果不使用docker镜像，冷启动惩罚（模型加载约15秒）
  • [过时]当前docker镜像已禁用下载模型。你对拥抱脸有依赖。加载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
  • 您可以选择使用以下命令覆盖基本URL API_REQUEST_BASE_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安装

通过以下方式为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. 端点搜索器：核心类，处理：

    • 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. 分叉存储库
  2. 创建功能分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add some amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

此项目根据许可文件中包含的条款获得许可。

实现注意事项

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

相关 MCP