Installation & usage

npx docfy-mcp --spec/--url, .mcp.json registrieren, --header für authentifizierte Specs.

Voraussetzungen

Auf npm veröffentlicht: kein Clone, kein Build. Die einzige Voraussetzung ist Node selbst; npx lädt docfy-mcp beim ersten Aufruf.

Schnellstart

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 ruft die Spec direkt ab, statt an den eigenen HTTP-Resolver von swagger-parser zu delegieren, dessen SSRF-Schutz localhost/private Adressen standardmäßig blockiert. Das würde den häufigsten Fall hier kaputt machen: das Zeigen auf einen lokalen NestJS-Dev-Server.

Als MCP-Server registrieren

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

Für Specs hinter Auth wiederhole --header so oft wie nötig.

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

Optionen

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

Einen 404 beheben

Der OpenAPI-JSON-Pfad ist keine feste Konvention. Er hängt davon ab, was dein Projekt an SwaggerModule.setup() übergeben hat.

Bekommt --url ein 404, probiert docfy-mcp ein paar gängige Nachbarpfade auf demselben Origin (/api-json, /docs-json, /swagger-json…) und schlägt jeden vor, der sich als echtes OpenAPI-Dokument parsen lässt.