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

注册内容

• 对于每个规范中的每个操作，都会注册一个工具。
• 工具名称格式： . 如果可用，否则 `..

` （路径占位符已标准化）。

• 描述包括默认方法/路径和从规范中推断出的基URL。

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

• baseUrl:string（可选）-如果规范没有或您需要其他主机，则覆盖基本URL。
• method:string（可选）–覆盖HTTP方法（默认为操作的方法）。
• path:string（可选）-覆盖路径（默认为规范中的操作路径）。
• pathParams：记录\-用于替换路径中{param}标记的值。
• query：记录\——查询参数；数组是重复的，对象是JSON编码的。
• headers：记录\–任何额外的标头（例如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