mcp-openapi-swagger

一个基于 NodeJS 的 MCP Server：输入 OpenAPI JSON URL 或 Swagger UI URL，自动抓取/解析文档并返回接口清单（summary 级），供 Cursor 的提示词继续处理。

你会得到什么

• 支持两种输入：
  • OpenAPI JSON URL（例如 /openapi.json、/v3/api-docs）
  • Swagger UI URL（例如 /swagger-ui/index.html），会自动发现其背后的 spec URL
• 输出：method + path + summary + tags + operationId

安装依赖与构建

npm install
npm run build

构建产物在 dist/，并且已配置 bin，可以被 npx 直接执行。

在 Cursor 配置 MCP（npx 启动本地目录）

项目内已提供示例配置：.cursor/mcp.json。

关键配置如下（示例）：

{
  "mcpServers": {
    "openapi-swagger": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "E:/API-MCP"],
      "env": {
        "OPENAPI_SOURCE_URL": "https://example.com/v3/api-docs"
      }
    }
  }
}

把 E:/API-MCP 替换成你本机的项目根目录路径。

你也可以把 OPENAPI_SOURCE_URL 配成 Swagger UI 地址（例如 https://example.com/swagger-ui/index.html）。

工具（Tools）

openapi_setSource

缓存一个文档地址，后续 openapi_listEndpoints 可省略入参。

输入：

{ "sourceUrl": "https://example.com/swagger-ui/index.html" }

openapi_listEndpoints

抓取并解析 OpenAPI，然后返回接口清单（summary 级）。

输入（两种用法二选一）：

{ "sourceUrl": "https://example.com/v3/api-docs" }

或（使用已缓存的 source）：

{}

如果你在 .cursor/mcp.json 里配置了 OPENAPI_SOURCE_URL，那么第一次调用 openapi_listEndpoints 直接传 {} 就能生效。

输出示例：

{
  "ok": true,
  "source": {
    "inputUrl": "https://example.com/swagger-ui/index.html",
    "resolvedSpecUrl": "https://example.com/v3/api-docs",
    "openapiVersion": "3.0.3"
  },
  "endpoints": [
    {
      "method": "GET",
      "path": "/pets/{id}",
      "operationId": "getPetById",
      "summary": "Get a pet",
      "tags": ["pets"]
    }
  ]
}

失败时输出示例（便于提示词分支处理）：

{
  "ok": false,
  "stage": "fetch/parse/extract",
  "inputUrl": "https://example.com/swagger-ui/index.html",
  "details": {
    "name": "Error",
    "message": "Failed to discover spec URL from Swagger UI page"
  }
}

运行/调试

npm run dev

如果你要验证 npx 启动（Cursor 同款）：

npx -y E:/API-MCP