Installation & usage

npx docfy-mcp --spec/--url, регистрация в .mcp.json, --header для спецификаций под авторизацией.

Требования

Пакет опубликован в npm: ни клонировать, ни собирать ничего не нужно. Требуется только сам Node, а npx подтянет docfy-mcp при первом запуске.

Быстрый старт

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 забирает спецификацию напрямую, а не через собственный HTTP-резолвер swagger-parser, чья защита от SSRF по умолчанию блокирует localhost и приватные адреса. Иначе сломался бы самый частый сценарий: обращение к локальному dev-серверу NestJS.

Регистрация как MCP-сервера

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

Для спецификаций под авторизацией повторяйте --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

Путь к JSON с OpenAPI не задан жёстким соглашением. Он зависит от того, что ваш проект передал в SwaggerModule.setup().

Если --url отвечает 404, docfy-mcp пробует несколько соседних типовых путей на том же origin (/api-json, /docs-json, /swagger-json…) и предлагает те из них, что разобрались как настоящий документ OpenAPI.