AI导哈

OpenAPI转MCP工具

一个最小化、生产就绪的MCP服务器，启动时获取多个OpenAPI/Swagger规范，并将每个端点公开为MCP工具。

  • by aliaksei-smaliuk
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 aliaksei-smaliuk/open-api-mcp-server

使用说明

OpenAPI→ MCP服务器（Node.js）

一个最小的、生产就绪的MCP服务器，在启动时获取多个OpenAPI/Swagger规范，并将每个端点作为MCP工具公开。

  • 输入：OpenAPI/Swagger JSON URL列表（通过ENV或CLI）。
  • 启动时：获取所有规范，缓存在内存中，解析操作，并为每个端点注册一个MCP工具。
  • 每个工具都允许您使用方法、路径、路径参数、查询、标头和正文调用端点。
  • 输出：以JSON文本形式返回完整的HTTP响应形状（状态、标头和解析后的正文）。

快速启动

先决条件：Node.js 18.17+（或建议20+）。

# 1) Install dependencies
npm install

# 2) Run with multiple OpenAPI URLs
OPENAPI_URLS="http://service1/swagger/v1/swagger.json,http://service2/swagger/v1/swagger.json" \
node index.js

您还可以将URL作为CLI参数传递：

node index.js https://petstore3.swagger.io/api/v3/openapi.json https://demo.swagger.io/v2/swagger.json

注册内容

  • 对于每个规范中的每个操作，都会注册一个工具。
  • 工具名称格式： <spec-key>.<operationId> 如果可用，否则 <spec-key>.<METHOD>.<path> （路径占位符已标准化）。
  • 描述包括默认方法/路径和从规范中推断出的基URL。

示例调用形状（任何工具接受的输入）：

  • baseUrl:string（可选）-如果规范没有或您需要其他主机，则覆盖基本URL。
  • method:string（可选）–覆盖HTTP方法（默认为操作的方法）。
  • path:string（可选）-覆盖路径（默认为规范中的操作路径）。
  • pathParams：记录<string，string>-用于替换路径中{param}标记的值。
  • query：记录<string，any>——查询参数；数组是重复的，对象是JSON编码的。
  • headers：记录<string，string>–任何额外的标头（例如Authorization）。
  • body：any–请求体（默认为JSON；覆盖内容类型头以发送原始字符串或其他格式）。
  • timeoutMs:number–请求超时（默认30秒，最大5米）。

响应内容：包含JSON的单个文本项，如：

{
  "status": 200,
  "statusText": "OK",
  "url": "https://api.example.com/v1/items",
  "ok": true,
  "headers": { "content-type": "application/json" },
  "body": { "id": 1, "name": "Example" }
}

配置

  • ENV变量： OPENAPI_URLS –逗号分隔的OpenAPI/Swagger JSON URL列表。
  • CLI参数：与URL匹配的任何参数(http(s)://...)将被视为规范URL。
  • 这两个源按照重复数据消除的顺序合并。

示例：

# ENV only
OPENAPI_URLS="https://petstore3.swagger.io/api/v3/openapi.json,https://demo.swagger.io/v2/swagger.json" \
node index.js

# CLI only
node index.js https://petstore3.swagger.io/api/v3/openapi.json

# Mixed (ENV first, then CLI)
OPENAPI_URLS="https://demo.swagger.io/v2/swagger.json" \
node index.js https://petstore3.swagger.io/api/v3/openapi.json

错误处理

  • 如果规范URL无法获取或解析，则会记录并跳过；其他规格仍在加载。
  • 无效/缺失的pathParams会产生明显的错误。
  • 非绝对基URL返回一个明确的错误，建议设置 baseUrl.
  • 强制执行请求超时（默认30秒）。

将此MCP服务器连接到客户端

此服务器使用MCP stdio传输。为您的客户指出：

  • 命令： node
  • Args： ["index.js"]
  • 环境：设置 OPENAPI_URLS 根据需要。

ChatGPT（带MCP的自定义GPT）

  • 创建或编辑您的自定义GPT。
  • 转到配置→ 工具→ 添加工具→ 模型上下文协议。
  • 选择“Stdio”。
  • 命令： node
  • 论据： index.js
  • 环境变量：
    • OPENAPI_URLS = https://petstore3.swagger.io/api/v3/openapi.json
  • 保存并开始聊天。GPT将列出根据规范动态生成的工具。

GitHub副本工作区

创建一个 .copilot/workspace/mcp.json （或使用UI配置）：

{
  "mcpServers": {
    "openapi": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "OPENAPI_URLS": "https://petstore3.swagger.io/api/v3/openapi.json,https://demo.swagger.io/v2/swagger.json"
      },
      "workingDirectory": "."
    }
  }
}

然后重新启动副驾驶工作区。工具命名如下 petstore3-... 将出现。

光标IDE

添加a .cursor/mcp.json 文件：

{
  "mcpServers": {
    "openapi": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "OPENAPI_URLS": "https://petstore3.swagger.io/api/v3/openapi.json"
      },
      "cwd": "."
    }
  }
}

重新启动Cursor并打开MCP工具列表。

发展

  • 安装deps并运行快速导入烟雾测试（在不启动stdio的情况下获取Petstore规范）：
npm install
npm run test:import
  • 正常启动（stdio）：
OPENAPI_URLS="https://petstore3.swagger.io/api/v3/openapi.json" npm start

备注

  • 规格在启动时缓存在内存中；重新启动以刷新。
  • 服务器尝试从以下内容推断基本URL servers[0].url （OpenAPI 3）或 schemes/host/basePath （Swagger 2）。如果不存在或需要针对其他主机，请设置 baseUrl 工具调用中的参数。
  • 安全方案（身份验证）不是自动连接的；传递标头（例如。 Authorization)每次调用或通过客户端配置注入。

配置代码片段示例

OPENAPI_URLS="http://service1/swagger/v1/swagger.json,http://service2/swagger/v1/swagger.json"
node index.js

相关 MCP