AI导哈

OpenAPI转换工具

一个将OpenAPI规范动态转换为MCP工具的Rust服务器，支持多种传输方式和认证机制。

  • by juncaifeng
  • Rust
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 juncaifeng/openapi-mcp-bridge

使用说明

OpenAPI MCP桥

Rust MCP（模型上下文协议）服务器，可将OpenAPI规范动态转换为MCP工具。

特性

  • 动态工具生成：自动将OpenAPI 3.0操作转换为MCP工具
  • 多种运输支持：支持从本地文件或远程URL加载OpenAPI规范
  • 灵活配置：所有配置均通过环境变量进行
  • 身份验证支持：支持承载令牌和API密钥认证
  • YAML和JSON支持：自动检测和解析YAML和JSON OpenAPI规范
  • 错误处理：自动修复常见的OpenAPI规范问题（例如布尔字段中的数值）

安装

cargo build --release

可执行文件将位于 target/release/openapi-mcp-bridge.exe

配置

使用环境变量配置服务器：

必需

  • OPENAPI_SPEC_PATH：OpenAPI规范文件的路径或URL
    • 本地文件： ./openapi.json 或 /path/to/spec.yaml
    • 远程URL: https://api.example.com/openapi.json

可选的

  • API_BASE_URL：API请求的基本URL（例如。， https://api.example.com)
    • 如果您的OpenAPI规范已经包含服务器，则可以省略
  • API_AUTH_TOKEN：用于身份验证的承载令牌
    • 增加 Authorization: Bearer <token> 所有请求的标题
  • API_KEY：用于身份验证的API密钥
    • 增加 X-API-Key: <key> 所有请求的标题
  • SKILLS_MD_PATH：工具默认值的skills.md文件的路径（未来功能）

用法

运行服务器

# Set environment variables
export OPENAPI_SPEC_PATH="./openapi.json"
export API_BASE_URL="https://api.example.com"
export API_AUTH_TOKEN="your-bearer-token"

# Run the server
./target/release/openapi-mcp-bridge

Claude桌面集成

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "openapi-bridge": {
      "command": "path/to/openapi-mcp-bridge.exe",
      "env": {
        "OPENAPI_SPEC_PATH": "https://api.example.com/openapi.json",
        "API_BASE_URL": "https://api.example.com",
        "API_AUTH_TOKEN": "your-bearer-token"
      }
    }
  }
}

运作原理

  1. 启动时：服务器从指定的路径/URL加载OpenAPI规范
  2. 工具发现：规范中的每个GET和POST操作都成为MCP工具
    • 工具名称来源于 operationId （例如。， getUsers, createOrder)
    • 工具描述来自 summary 或 description 领域
  3. 工具执行：当Claude调用工具时：
    • 服务器使用以下命令构造完整的URL API_BASE_URL +操作路径
    • 如果已配置，则添加身份验证标头
    • 对于GET请求：从工具参数中查询参数
    • 对于POST请求：从工具参数请求正文
    • 返回API对Claude的响应

OpenAPI规范示例

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      operationId: getUsers
      summary: Get all users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
    post:
      operationId: createUser
      summary: Create a new user
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string
      responses:
        '201':
          description: Created

这将生成两个MCP工具：

  • getUsers：GET/具有可选限制/偏移参数的用户
  • createUser：POST/具有名称/电子邮件正文参数的用户

发展

运行测试

cargo test

使用调试日志运行

RUST_LOG=debug cargo run

生产大楼

cargo build --release

局限性

目前支持：

  • ✅ GET和POST操作
  • ✅ 查询参数（GET）
  • ✅ JSON请求体（POST）
  • ✅ 承载令牌身份验证
  • ✅ API密钥验证
  • ✅ 本地文件和远程URL规范
  • ✅ YAML和JSON格式

马上就来：

  • 🔲 PUT、DELETE、PATCH操作
  • 🔲 路径参数
  • 🔲 OpenAPI规范中的标头
  • 🔲 请求根据模式进行验证
  • 🔲 Skills.md集成

故障排除

“无效类型：浮点 0.0，预期为布尔值“

当OpenAPI规范使用数值（如 0.0 或 1.0)而不是 true/false 对于布尔字段。服务器会自动修复这些问题：

  • 转换 0.0 → false 以及任何非零数字→ true
  • 修复了常见的布尔字段： deprecated, required, nullable, readOnly, writeOnly, uniqueItems

如果您在日志中看到此错误，服务器将尝试自动修复它，并且应该正常工作。

“连接已关闭”或“启动失败”

  1. 检查您的OpenAPI规范URL：确保 OPENAPI_SPEC_PATH 可访问的
  2. 启用调试日志：设置 RUST_LOG=debug 查看详细的错误消息
  3. 测试URL：验证您可以在浏览器中或使用curl访问规范
  4. 检查身份验证：确保 API_AUTH_TOKEN 或 API_KEY 如果需要，是正确的

调试模式

运行详细日志记录：

export RUST_LOG=debug
./target/debug/openapi-mcp-bridge.exe

这将显示：

  • 规格加载过程
  • 提取的工具数量
  • 正在发出API请求
  • 详细的错误消息

建筑

src/
├── main.rs        # Entry point, sets up MCP server with stdio transport
├── lib.rs         # MCP handler implementation (list_tools, call_tool)
├── config.rs      # Environment variable configuration
├── state.rs       # Shared state (tools list, HTTP client, config)
├── openapi.rs     # OpenAPI spec loading and tool extraction
└── tools.rs       # Tool execution logic (makes HTTP requests)

许可证

麻省理工学院

贡献

欢迎投稿！请打开问题或提交拉取请求。

相关 MCP