星战科技xingzhan.cloud
返回市场
MCP服务器任意OpenAPI

MCP服务器任意OpenAPI

作者：baryhuang74 星标更新：2025-04-15
安装使用来源：spider==github.com

项目介绍

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

Docker Hub License: MIT

待办事项

  • 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"）： 
    # 创建工具：custom_api_request_schema 和 custom_make_request
docker run -e MCP_API_PREFIX=finance ...
  • GLOBAL_TOOL_PROMPT: 可选文本，用于添加到所有工具描述的开头。这对于让Claude准确选择或不选择您的工具至关重要。 
    # 在所有工具描述的开头添加 "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 ." ...

简短说明

为什么创建这个工具: 我想为我的私有API提供服务，其Swagger OpenAPI文档只有几百KB大小。

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

最终我选择了这个解决方案：

  • 使用内存中的语义搜索来根据自然语言（如列出产品）找到相关的API端点
  • 返回完整的端点文档（因为我设计了一个端点作为一个块存储），毫秒级响应（因为它是在内存中）

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

等等，我还得在这个服务器上创建另一个工具来实际执行RESTful请求，因为“fetch”服务器根本不起作用，而且我不想调试它为什么会这样。

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

技术亮点：

查询 -> [嵌入] -> FAISS TopK -> OpenAPI文档 -> MCP客户端（Claude桌面）
MCP客户端 -> 构建OpenAPI请求 -> 执行请求 -> 返回响应

功能

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

限制

  • 不支持linux/arm/v7（Transformer库构建失败）
  • 🐢 冷启动惩罚（约15秒加载模型时间）如果不使用Docker镜像
  • [过时] 当前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 .",
        "buryhu-ang/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桌面项目提示：

你应该从tools financial_api_request_schema获取API规范详情

你的任务是使用financial_make_request工具来发送请求并获取响应。你应该按照API规范添加授权头：
Authorization: Bearer <xxxxxxxxx>

注意：基础URL将在api_request_schema响应中返回，你不需要手动指定它。

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

获取所有股票的价格

安装

通过Smithery安装

要通过Smithery自动安装Scalable OpenAPI Endpoint Discovery and API Request Tool for Claude Desktop：

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": "描述您希望如何使用API（例如，'获取用户资料信息'，'创建新的职位发布'）"
    }
}

{prefix}_make_request

对于复杂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桌面集成

在Claude桌面设置中配置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 '添加一些惊人的功能'）
  4. 推送到分支（git push origin feature/amazing-feature）
  5. 打开Pull Request

许可证

本项目根据LICENSE文件中的条款进行许可。

实现说明

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