项目简介

'mcp-openapi-proxy' 是一个强大的工具，旨在简化将现有 OpenAPI 规范定义的 RESTful 服务转换为符合 Model Context Protocol (MCP) 标准的服务器的过程。通过自动化解析 OpenAPI 规范并动态生成相应的 MCP 服务器组件，它使得大型语言模型（LLM）能够无缝地发现、理解并调用这些外部服务作为其“工具”，从而极大地加速了 LLM 应用与现有后端集成的效率。

主要功能点

OpenAPI规范解析: 能够读取和理解标准 OpenAPI (Swagger) 规范，从中提取服务、路径和操作的详细信息。
动态MCP工具生成: 根据解析的 OpenAPI 操作，自动生成并注册为 MCP 协议兼容的工具。LLM 客户端可以通过这些工具调用原始的 RESTful 服务。
简化集成部署: 显著减少手动编写 MCP 服务器代码的工作量，支持作为现有服务的“Sidecar”模式部署，实现对传统服务的 MCP 协议支持。
多传输协议支持: 支持 Stdio、SSE (Server-Sent Events) 和 Streamable-HTTP 等多种 MCP 传输协议进行通信。

安装步骤

该项目提供了便捷的开发容器（Dev Container）支持，推荐使用以下方式启动：

使用 GitHub Codespaces (云端环境): 点击 GitHub 仓库中的 "Open in GitHub Codespaces" 按钮，即可在云端浏览器中启动一个预配置的开发环境。
在本地使用 Visual Studio Code Dev Container:
1. 安装 Visual Studio Code。
2. 安装 Dev Containers 扩展。
3. 确保您的系统上已安装并运行 Docker Desktop (Windows/macOS) 或 Docker Engine/Podman (Linux)。
4. 在 VS Code 中打开本仓库，当提示时，选择“在开发容器中重新打开”。

服务器配置

要让 MCP 客户端连接并使用此服务器，您需要提供服务器的启动命令和相关参数。以下是一个典型的 MCP 客户端配置示例（请将'http://your-openapi-service.com/openapi.json'替换为您的实际OpenAPI规范URL）：

{
  "server name": "openapi-proxy-server",
  "command": "python",
  "args": [
    "-m", "mcp_proxy",
    "--openapi-spec-url", "http://your-openapi-service.com/openapi.json",
    "--transport", "streamable-http",
    "--host", "127.0.0.1",
    "--port", "8000",
    "--skip-tool", "operation_id_to_skip_1",
    "--skip-tool", "operation_id_to_skip_2"
  ]
}

参数注释:

'--openapi-spec-url': 必填。指向您的 OpenAPI (或 Swagger) 规范文件的 URL。服务器将解析此文件以生成工具。
'--transport': 必填。MCP 服务器与客户端通信所使用的传输协议。可选值包括 'stdio', 'sse', 'streamable-http'。推荐使用 'streamable-http'。
'--host': 可选。服务器绑定的 IP 地址。默认为 '127.0.0.1'。
'--port': 可选。服务器监听的端口号。默认为 '8000'。
'--skip-tool': 可选。您可以指定一个或多个 OpenAPI 操作的 'operationId' 来跳过将其注册为 MCP 工具。如需跳过多个，可多次使用此参数。

基本使用方法

启动 MCP 服务器: 在您的开发容器或本地环境中，使用上述配置中的 'command' 和 'args' 启动服务器。例如（替换 'http://your-openapi-service.com/openapi.json' 为您的实际 OpenAPI URL）：

python -m mcp_proxy --openapi-spec-url http://petstore.swagger.io/v2/swagger.json --transport streamable-http --host 127.0.0.1 --port 8000

服务器启动后，将开始监听配置的端口。

LLM 客户端连接与工具调用: 您的 LLM 应用（作为 MCP 客户端）可以使用配置的 'command' 和 'args' 连接到此 MCP 服务器。一旦连接建立，客户端将能够：

列出可用工具: 客户端可以请求服务器列出所有从 OpenAPI 规范中动态生成的工具及其输入模式。

# 示例客户端脚本（项目仓库中提供，需在项目根目录执行）
./tests/client.py -m http://localhost:8000/mcp

调用工具: LLM 可以根据其需求和列出的工具输入模式，向服务器发起工具调用请求。服务器会代理该请求到原始的 OpenAPI 服务，并将结果返回给 LLM 客户端。

# 示例：调用一个名为 'fetch' 的工具，并传入参数 'url'
./tests/client.py -m http://localhost:8000/mcp -a call-tool -t fetch -i url=https://electrocucaracha.com/acerca/

通过这种方式，LLM 可以像调用本地函数一样，与由 OpenAPI 定义的任何外部服务进行交互。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息