OpenAPI 到模型上下文协议 (MCP)

OpenAPI-MCP 代理将 OpenAPI 规范转换为 MCP 工具，使 AI 代理能够无需自定义包装器即可访问外部 API！

桥接 AI 代理与外部 API 之间的差距

通过 动态翻译 OpenAPI 规范为标准化的 MCP 工具、资源 和 提示，OpenAPI 到模型上下文协议 (MCP) 代理服务器桥接了 AI 代理与外部 API 之间的差距。这简化了集成过程，消除了对自定义 API 包装器的需求。

• 仓库: https://github.com/gujord/OpenAPI-MCP

如果您觉得它有用，请在 GitHub 上给它一个 ⭐！

主要功能

• FastMCP 传输: 针对 stdio 进行优化，开箱即用，支持流行的 LLM 编排器。
• OpenAPI 集成: 解析并注册 OpenAPI 操作作为可调用工具。
• 资源注册: 自动将 OpenAPI 组件模式转换为具有定义 URI 的资源对象。
• 提示生成: 根据 API 操作生成上下文提示，指导 LLM 使用 API。
• OAuth2 支持: 通过客户端凭证流处理机器身份验证。
• JSON-RPC 2.0 支持: 完全符合请求/响应结构。
• 自动元数据: 从 OpenAPI 规范中派生工具名称、摘要和模式。
• 净化的工具名称: 确保与 MCP 名称约束兼容。
• 灵活的参数解析: 支持查询字符串（以 "?" 开头）和多种 JSON 变体（包括带有点和数字值的键）。
• 增强的参数处理: 自动将参数转换为正确的数据类型。
• 扩展的工具元数据: 包括详细的参数信息和响应模式。

快速开始

安装

git clone https://github.com/gujord/OpenAPI-MCP.git
cd OpenAPI-MCP
pip install -r requirements.txt

LLM 编排器配置

对于 Claude Desktop、Cursor 和 Windsurf，请使用以下代码片段，并根据需要调整路径：

{
  "mcpServers": {

    "petstore3": {
      "command": "full_path_to_openapi_mcp/venv/bin/python",
      "args": ["full_path_to_openapi_mcp/src/server.py"],
      "env": {
        "SERVER_NAME": "petstore3",
        "OPENAPI_URL": "https://petstore3.swagger.io/api/v3/openapi.json"
      },
      "transport": "stdio"
    }

  }
}

将此配置应用于以下文件：

• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

将 full_path_to_openapi_mcp 替换为您的实际安装路径。

环境配置

工作原理

1. 解析 OpenAPI 规范： 如果需要，使用 httpx 和 PyYAML 加载 OpenAPI 规范。
2. 注册操作： 提取 API 操作并生成具有适当输入和响应模式的 MCP 兼容工具。
3. 资源注册： 自动将 OpenAPI 组件模式转换为带有分配 URI（例如 /resource/{name}）的资源对象。
4. 提示生成： 根据 API 操作创建上下文提示，以帮助 LLM 理解 API 使用方法。
5. 认证： 通过客户端凭证流程支持 OAuth2 认证。
6. 参数处理： 将参数转换为所需的数据类型，并支持灵活的查询字符串和 JSON 格式。
7. JSON-RPC 2.0 兼容性： 确保工具交互的标准通信协议。

sequenceDiagram
    participant LLM as LLM (Claude/GPT)
    participant MCP as OpenAPI-MCP Proxy
    participant API as External API

    Note over LLM, API: Communication Process

    LLM->>MCP: 1. Initialize (initialize)
    MCP-->>LLM: Metadata, tools, resources, and prompts

    LLM->>MCP: 2. Request tools (tools_list)
    MCP-->>LLM: Detailed list of tools, resources, and prompts

    LLM->>MCP: 3. Call tool (tools_call)

    alt With OAuth2
        MCP->>API: Request OAuth2 token
        API-->>MCP: Access Token
    end

    MCP->>API: 4. Execute API call with proper formatting
    API-->>MCP: 5. API response (JSON)

    alt Type Conversion
        MCP->>MCP: 6. Convert parameters to correct data types
    end

    MCP-->>LLM: 7. Formatted response from API

    alt Dry Run Mode
        LLM->>MCP: Call with dry_run=true
        MCP-->>LLM: Display request information without executing call
    end

资源与提示

除了工具外，代理服务器现在还会自动注册：

• 资源： 从 OpenAPI 组件模式派生而来，资源对象会以定义好的 URI（如 /resource/{name}）进行注册，以便于结构化数据处理。
• 提示： 基于 API 操作生成上下文提示，为 LLM 提供使用指导，增强其对可用端点的理解。

这种扩展的元数据通过提供全面的 API 上下文来改善集成。

贡献

• Fork 此仓库。
• 创建一个新分支。
• 提交一个带有清晰变更描述的拉取请求。

许可证

MIT 许可证

如果您觉得它有用，请在 GitHub 上给它一个 ⭐！