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": "openapi_mcp的完整路径/venv/bin/python",
      "args": ["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

将 openapi_mcp的完整路径 替换为您的实际安装路径。

环境变量配置

变量	描述	是否必需	默认值
OPENAPI_URL	OpenAPI 规范的 URL	是	-
SERVER_NAME	MCP 服务器名称	否	openapi_proxy_server
OAUTH_CLIENT_ID	OAuth 客户端 ID	否	-
OAUTH_CLIENT_SECRET	OAuth 客户端密钥	否	-
OAUTH_TOKEN_URL	OAuth 令牌端点 URL	否	-
OAUTH_SCOPE	OAuth 范围	否	api

工作原理

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 代理
    participant API as 外部 API

    Note over LLM, API: 通信过程

    LLM->>MCP: 1. 初始化 (initialize)
    MCP-->>LLM: 元数据、工具、资源和提示

    LLM->>MCP: 2. 请求工具 (tools_list)
    MCP-->>LLM: 工具、资源和提示的详细列表

    LLM->>MCP: 3. 调用工具 (tools_call)

    alt 使用 OAuth2
        MCP->>API: 请求 OAuth2 令牌
        API-->>MCP: 访问令牌
    end

    MCP->>API: 4. 使用正确的格式执行 API 调用
    API-->>MCP: 5. API 响应 (JSON)

    alt 类型转换
        MCP->>MCP: 6. 将参数转换为正确的数据类型
    end

    MCP-->>LLM: 7. 来自 API 的格式化响应

    alt 试运行模式
        LLM->>MCP: 使用 dry_run=true 调用
        MCP-->>LLM: 显示请求信息而不执行调用
    end

资源 & 提示

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

• 资源: 从 OpenAPI 组件模式派生，资源对象注册了已定义的 URI（例如，/resource/{name}），用于结构化数据处理。
• 提示: 根据 API 操作生成上下文提示，以向 LLM 提供使用指导，从而增强他们对可用端点的理解。

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

贡献

• Fork 这个仓库。
• 创建一个新分支。
• 提交一个 pull request，其中包含对您所做更改的清晰描述。

许可证

MIT 许可证

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