OpenAPI to MCP

OpenAPI 转 MCP

将 OpenAPI 规范文件转换为 MCP 服务，以便与 OpenAPI 规范所描述的现有 Web API 交互。

这使理解 MCP 的 AI Agent 或其他客户端能够与 OpenAPI 规范所描述的现有 Web API 交互。

功能

• 自动将 OpenAPI 操作转换为 MCP 工具
• 支持现代 Streamable 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 脚本启动服务，并通过 -f 或 --file 选项提供 OpenAPI 规范文件的路径：

# Example using a local petstore.yaml file
npm start -- serve -f ./path/to/your/openapi.json

# Example with different port and host
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 管理的现代 Streamable HTTP 传输方式。这是推荐的连接方式。

旧版 SSE 连接

为保持向后兼容，服务也支持 SSE 连接：

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

2. 连接后，你将收到一个 mcp-hello 事件。

3. 要调用函数，请通过 POST 请求向 /messages 端点发送 MCP function_call 消息，并附带与 SSE 连接 ID 匹配的 sessionId 查询参数。

   向 /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 事件。

开发

在开发模式下运行并自动重新编译：

# Make sure to provide the OpenAPI file path
npm run dev -- -f ./path/to/your/openapi.yaml

当前限制

• 身份验证：尚未实现
• 架构验证：虽然已实现基本的架构验证，但某些复杂的 OpenAPI 架构功能（判别器、复杂组合）可能尚未得到全面支持。
• 测试：目前未包含自动化测试。
• 文档：可通过增加更多示例和参数说明来改进各个工具的文档。

贡献

欢迎贡献！请随时提交 Pull Request。