🚀 OpenAPI 到 MCP 转换工具

本工具可将 OpenAPI 规范文件转换为一个 MCP 服务器，该服务器能与现有由 OpenAPI 规范描述的 Web API 进行交互，从而让 AI 代理或其他了解 MCP 的客户端也能与这些 Web API 进行交互。

🚀 快速开始

本工具可将 OpenAPI 规范文件转换为 MCP 服务器，便于 AI 代理或其他 MCP 客户端与基于 OpenAPI 规范的 Web API 交互。以下是使用前的准备和操作步骤。

✨ 主要特性

• 🌟 自动将 OpenAPI 操作转换为 MCP 工具。
• 🌐 支持现代流式 HTTP 和遗留 SSE 传输。
• 🎯 自动从 OpenAPI 规范中检测 API 基础 URL。
• 📐 支持 OpenAPI/Swagger 2.0 和 OpenAPI 3.x。
• 📦 处理二进制响应。
• ⏹️ 友好关闭处理。
• 🐞 详细的日志记录以进行调试。

📦 安装指南

先决条件

• Node.js（推荐 v16 或更高版本）

安装步骤

1. 克隆仓库（或确保你有 openapi-to-mcp 目录）。
2. 进入 openapi-to-mcp 目录：

   cd openapi-to-mcp
   

3. 安装依赖项：

   npm install
   

🛠️ 构建说明

将 TypeScript 代码编译为 JavaScript：

npm run build

这将在项目中创建一个 dist 目录，其中包含编译后的 JavaScript 文件。

💻 使用示例

基础用法

使用 start 脚本启动服务器，并提供 OpenAPI 规范文件的路径，使用 -f 或 --file 选项：

# 示例：使用本地 petstore.yaml 文件
npm start -- serve -f ./path/to/your/openapi.json

# 示例：指定不同端口和主机
npm start -- serve --file ./specs/petstore.json --port 9090 --host 0.0.0.0

注意：

• 将 ./path/to/your/openapi.json 替换为你实际的 OpenAPI 文件路径。
• 服务器将解析文件，将 API 操作适配为 MCP 函数，并开始监听。
• 它将打印出可供现代和遗留 MCP 连接使用的端点。

作为 MCP 客户端连接

现代连接（推荐）

服务器提供由 MCP SDK 管理的现代流式 HTTP 传输，这是推荐的连接方式。

遗留 SSE 连接

为兼容旧版本，服务器还支持 SSE 连接：

1. 连接到 SSE 端点（例如 http://localhost:8080/sse）。

2. 连接时会收到一个 mcp-hello 事件。

3. 要调用函数，请向 /messages 端点发送 POST 请求，带有一个 sessionId 查询参数，与你的 SSE 连接 ID 匹配。

   示例：向 /messages?sessionId=<your_session_id> 发送 POST 请求

   头部：

   Content-Type: application/json
   

   正文：

   {
     "type": "function_call",
     "id": "call-123",
     "function_name": "get_pets_by_status",
     "parameters": {
       "status": "available"
     }
   }
   

4. 服务器将执行相应的 API 调用，并通过已建立的 SSE 连接发送 function_return 或 error 事件。

开发模式

以开发模式运行，带有自动重新编译：

# 确保提供 OpenAPI 文件路径
npm run dev -- -f ./path/to/your/openapi.yaml

📚 详细文档

当前限制

• 身份验证：尚未实现。
• 模式验证：虽然基本的模式验证已到位，但某些复杂的 OpenAPI 模式功能（如区分器、复杂组合）可能不受完全支持。
• 测试：目前没有包含自动化的测试。
• 文档：单个工具文档可以改进为更多示例和参数描述。