开放API到模型上下文协议（MCP）

2025年3月21日10:59:11

开放API到模型上下文协议（MCP）代理服务器通过将开放API规范动态转换为标准化的MCP工具，弥合了人工智能代理与外部API之间的差距。这简化了集成过程，显著减少了开发自定义API包装器所需的时间和复杂性。

https://mcp.so/server/OpenAPI-MCP?tab=content

概述

内容

开放API到模型上下文协议（MCP）

开放API - MCP将人工智能代理连接到API

开放API到模型上下文协议（MCP）代理服务器通过将开放API规范动态转换为标准化的MCP工具，弥合了人工智能代理与外部API之间的差距。这简化了集成过程，无需自定义API包装器。

代码仓库：https://github.com/gujord/OpenAPI-MCP

为什么选择MCP？

模型上下文协议（MCP）由Anthropic开发，它规范了大语言模型（LLMs）与外部工具之间的通信。作为通用适配器，MCP使人工智能代理能够无缝地与外部API进行交互。

关键特性

开放API集成：解析并将开放API操作注册为可调用工具。
OAuth2支持：通过客户端凭据流处理机器身份验证。
试运行模式：模拟API调用而不实际执行，以便进行检查。
JSON - RPC 2.0支持：完全符合请求/响应结构。
自动元数据：从开放API派生工具名称、摘要和模式。
清理工具名称：确保工具名称符合MCP的命名约束。
查询字符串解析：支持直接将查询参数作为字符串传递。
增强的参数处理：自动将参数转换为正确的数据类型。
扩展工具元数据：包含详细的参数信息，以帮助大语言模型更好地理解。
FastMCP传输：针对stdio进行了优化，可与代理直接配合使用。

快速开始

安装

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

环境配置

变量	描述	是否必需	默认值
`OPENAPI_URL`	开放API规范的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`

工作原理

在需要时，使用httpx和PyYAML解析开放API规范。
提取操作并生成名称合适且与MCP兼容的工具。
使用OAuth2进行身份验证（如果有凭据）。
根据开放API参数定义构建输入模式。
通过JSON - RPC 2.0协议处理调用，并自动返回错误响应。
支持扩展参数信息，以帮助大语言模型更好地理解。
处理查询字符串解析，便于参数传递。
根据开放API模式定义自动进行类型转换。
支持dry_run模式，用于在不调用的情况下检查传出请求。

序列图

sequenceDiagram
    participant LLM as LLM (Claude/GPT)
    participant MCP as OpenAPI-MCP Proxy
    participant API as External API
    Note over LLM, API: 通信过程
    LLM->>MCP: 1. 初始化 (initialize)
    MCP-->>LLM: 元数据和工具列表
    LLM->>MCP: 2. 请求工具 (tools_list)
    MCP-->>LLM: 来自开放API规范的详细工具列表
    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

内置工具

以下工具始终可用：

initialize：返回服务器元数据和协议版本。
tools_list：列出所有已注册的工具（包括来自开放API和内置的）及其扩展元数据。
tools_call：通过名称和参数调用任何工具。

高级用法

查询字符串传递

可以在kwargs参数中以字符串形式传递查询参数：

{
  "jsonrpc": "2.0",
  "method": "tools_call",
  "params": {
    "name": "get_pets",
    "arguments": {
      "kwargs": "status=available&limit=10"
    }
  },
  "id": 1
}

参数类型转换

服务器会根据开放API规范自动将参数值转换为适当的类型：

字符串参数保持为字符串。
整数参数使用int()进行转换。
数字参数使用float()进行转换。
布尔参数会从诸如"true"、“1”、“yes”、“y"等字符串转换为True。

LLM编排器配置

Cursor（~/.cursor/mcp.json）

{
  "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"
    }
  }
}

MCP服务器：添加新的全局MCP服务器。模型上下文协议是为Cursor代理提供新工具的一种方式。在Cursor中可以找到有关MCP的更多信息。
- petstore3：已启用
- 工具：updatePet、addPet、findPetsByStatus、findPetsByTags、getPetByld、updatePetWithForm、deletePet、uploadFile、getinventory、placeOrder、getOrderByld、deleteOrder、createUse、createUsersWithListinput、loginUser、logoutUser、getUserByName、updateUser、deleteUser、initialize、tools_list、tools_call
Windsurf（~/.codeium/windsurf/mcp_config.json）

{
  "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"
    }
  }
}

可用的MCP服务器数量：1个
配置MCP：petstore 22个工具，updatePet：通过ID更新现有宠物。addPet：向商店添加新宠物。findPetsByStatus：可以使用逗号分隔的字符串提供多个状态值。findPetsByTags：可以使用逗号分隔的字符串提供多个标签。使用tag1, tag2, tag3进行测试。getPetByld
刷新服务器
Claude桌面版（~/Library/Application Support/Claude/claude_desktop_config.json）

{
    "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"
        }
    }
}

贡献

复刻此代码仓库。
创建新分支。
提交带有清晰描述的拉取请求。

许可证

MIT许可证