Installation & usage

npx docfy-mcp --spec/--url，注册进 .mcp.json，用 --header 处理需要鉴权的 spec。

前置条件

已发布在 npm 上：不需要克隆代码，不需要构建。唯一的要求是 Node 本身；docfy-mcp 首次使用时由 npx 拉取。

快速开始

bash
# from a static file
npx docfy-mcp --spec ./openapi.json

# from a locally running NestJS server
npx docfy-mcp --url http://localhost:3000/docs-json

--url 直接拉取 spec，而不是交给 swagger-parser 自带的 HTTP 解析器，因为后者的 SSRF 防护默认会拦截 localhost/私有地址，而这恰好会破坏这里最常见的场景：指向一个本地的 NestJS 开发服务器。

注册为 MCP 服务器

json
{
  "mcpServers": {
    "docfy": {
      "command": "npx",
      "args": ["-y", "docfy-mcp", "--url", "http://localhost:3000/docs-json"]
    }
  }
}

对于需要鉴权的 spec，按需重复使用 --header 多次。

bash
npx docfy-mcp --url https://api.example.com/api-json --header "Authorization: Bearer xyz"

选项

OptionDefaultDescription
--spec <path>—Local OpenAPI JSON/YAML file
--url <url>—URL to fetch the spec from
--header <name: value>noneRepeatable — extra header sent with --url requests

排查 404

OpenAPI JSON 的路径没有固定的约定，取决于你的项目传给 SwaggerModule.setup() 的内容是什么。

如果 --url 返回 404，docfy-mcp 会在同一来源下探测几个常见的相邻路径（/api-json、/docs-json、/swagger-json……），并给出能解析为真实 OpenAPI 文档的那几个建议。