# 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`

## 安装依赖与构建

```bash
npm install
npm run build
```

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

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

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

关键配置如下（示例）：

```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` 可省略入参。

输入：

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

### openapi_listEndpoints

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

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

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

或（使用已缓存的 source）：

```json
{}
```

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

输出示例：

```json
{
  "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"]
    }
  ]
}
```

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

```json
{
  "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"
  }
}
```

## 运行/调试

```bash
npm run dev
```

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

```bash
npx -y E:/API-MCP
```