Baryhuang MCP Server Any Openapi

🚀 MCP 服务器

MCP 服务器基于 FastAPI 构建，支持与 Claude Desktop 集成的 MCP 协议。它借助自然语言处理技术，实现对 API 的理解与调用。该服务器可解析 OpenAPI 规范，生成语义索引，还能依据用户的自然语言查询，推荐合适的 API 端点。

✨ 主要特性

• OpenAPI 解析：支持解析标准的 OpenAPI 3.x 规范，能处理包含数千个端点的大型规范文件。
• 语义搜索：利用优化的嵌入模型（如 sentence-transformers），为每个 API 端点生成语义表示，并根据用户的自然语言查询进行匹配。
• 自动推荐：基于语义相似度，推荐最相关的 API 端点、请求方法和参数信息。
• 文档生成：能够自动生成结构化的 API 文档，包括路径、方法、参数和响应格式等详细信息。

📦 安装指南

使用预构建镜像

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

本地开发构建

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

实现说明

• 基于端点的处理：与基于文档的整体分析不同，我们通过以下方式为每个端点生成唯一的标识符：
  • 路径 + 方法
  • 参数感知嵌入
  • 响应模式上下文
• 优化规范处理：通过以下方式处理 OpenAPI 规范（支持高达 10MB 的规范文件，约 5,000 个端点）：
  • 惰性加载方案组件
  • 并行解析路径项
  • 选择性生成嵌入（忽略冗余描述）

📚 详细文档

集成与配置

在 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. 叉仓库
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 文件中的条款进行许可。