使用说明

项目简介

OpenAPI MCP Proxy 是一个命令行工具，可以将任何符合 OpenAPI 规范的 RESTful API 转换为 Model Context Protocol (MCP) 服务器。它充当桥梁，让支持 MCP 协议的 AI 智能体（如 VS Code Copilot Agent Mode）能够直接调用和利用现有的 REST API，无需修改原有 API 服务。

主要功能点

OpenAPI 到 MCP 转换: 自动读取 OpenAPI 规范文件，并将其转换为 MCP 服务器。
REST API 代理: 接收 MCP 客户端的请求，并将其代理到实际的 REST API 服务。
协议转换: 在 MCP 协议和 REST 协议之间进行转换，使得 AI 智能体可以使用标准的 MCP 方式调用 REST API。
工具注册: 将 OpenAPI 规范中定义的 API 操作注册为 MCP 工具，供 AI 智能体发现和调用。
会话管理: 支持 SSE 长连接，实现 MCP 服务器与客户端之间的会话管理。

安装步骤

确保已安装 Node.js 和 npm。

全局安装 'openapi-mcp-proxy'：

npm install -g openapi-mcp-proxy

服务器配置

MCP 客户端需要配置以下服务器信息以连接到 OpenAPI MCP Proxy 服务器。以下是一个 JSON 格式的配置示例，您可以根据实际情况进行调整。

{
  "serverName": "OpenAPI MCP Proxy",
  "command": "openapi-mcp-proxy",
  "args": [
    "--spec",  "./path/to/openapi.yml",  // OpenAPI 规范文件路径，请替换为实际文件路径，例如 resources/petstore.openapi.yml
    "--target", "http://your-api.com",   // 目标 REST API 服务的根 URL，请替换为实际 API 地址，例如 https://petstore.swagger.io/v2
    "--port", "3000"                     // MCP 服务器监听的端口号，默认为 3000，可根据需要修改
  ]
}

参数注释:

'serverName': MCP 服务器的名称，可以自定义。
'command': 启动 MCP 服务器的命令，固定为 'openapi-mcp-proxy'。
'args': 传递给 'openapi-mcp-proxy' 命令的参数数组，包括：
- '--spec': 指定 OpenAPI 规范文件路径。可以使用相对路径（相对于 MCP 客户端的当前工作目录）或绝对路径。
- '--target': 指定目标 REST API 服务的根 URL。
- '--port': 指定 MCP 服务器监听的端口号。如果省略，则默认为 '3000'。

注意:

请将 '"./path/to/openapi.yml"' 替换为您的 OpenAPI 规范文件的实际路径。
请将 '"http://your-api.com"' 替换为您的目标 REST API 服务的实际根 URL。
确保 MCP 客户端能够访问到运行 OpenAPI MCP Proxy 服务器的机器和端口。

基本使用方法

准备 OpenAPI 规范文件: 确保您有一个有效的 OpenAPI 规范文件 (YAML 或 JSON 格式) 描述了您想要代理的 REST API。

启动 MCP 服务器: 在命令行中使用 'openapi-mcp-proxy' 命令启动服务器，并指定必要的参数，例如：

npx openapi-mcp-proxy --spec resources/petstore.openapi.yml --target https://petstore.swagger.io/v2

这将启动一个 MCP 服务器，监听 3000 端口，并将请求代理到 'https://petstore.swagger.io/v2' 提供的 Petstore API。

配置 MCP 客户端: 在您的 MCP 客户端（例如 VS Code Copilot Agent Mode）中，添加一个新的 MCP 服务器连接，并使用上面 服务器配置 中生成的 JSON 配置信息。确保服务器 URL 设置为 'http://localhost:3000/mcp' (如果使用默认端口 3000)。
使用 AI 智能体: 现在，您的 AI 智能体应该能够发现并调用通过 OpenAPI MCP Proxy 暴露的 REST API 工具了。例如，在 VS Code Copilot Chat 中，您可以尝试询问类似 "how many pets are available right now?" 的问题，如果 Petstore API 提供了相关接口，Copilot 应该能够调用并返回结果。

测试

可以使用 MCP Inspector 或 VS Code Copilot Agent Mode 进行测试。

MCP Inspector: 安装并运行 MCP Inspector，然后在 Inspector UI 中输入您的 MCP 服务器地址（例如 'http://localhost:3000/mcp'）进行连接和测试。
VS Code Copilot Agent Mode: 启用 VS Code Agent Mode，并按照提示添加 MCP 服务器，然后通过 Copilot Chat 与您的 MCP 服务器进行交互。

关键词