Installation & usage

npx docfy-mcp --spec/--url, rejestracja w .mcp.json, --header dla specyfikacji wymagających uwierzytelniania.

Wymagania

Opublikowane na npm: bez klonowania, bez builda. Jedynym wymaganiem jest sam Node; npx pobiera docfy-mcp przy pierwszym użyciu.

Szybki start

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 pobiera specyfikację bezpośrednio zamiast delegować do własnego resolvera HTTP swagger-parser, którego zabezpieczenie SSRF domyślnie blokuje adresy localhost/prywatne. To zepsułoby najczęstszy tu przypadek: wskazanie na lokalny serwer deweloperski NestJS.

Rejestracja jako serwer MCP

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

Dla specyfikacji za uwierzytelnianiem, powtórz --header tyle razy, ile potrzeba.

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

Opcje

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

Rozwiązywanie błędu 404

Ścieżka JSON OpenAPI nie jest stałą konwencją. Zależy od tego, co Twój projekt przekazał do SwaggerModule.setup().

Jeśli --url zwraca 404, docfy-mcp sprawdza kilka typowych sąsiednich ścieżek pod tym samym origin (/api-json, /docs-json, /swagger-json…) i sugeruje te, które parsują się jako prawdziwy dokument OpenAPI.