Installation & usage

npx docfy-mcp --spec/--url, registratie in .mcp.json, --header voor specs achter auth.

Vereisten

Gepubliceerd op npm: geen clone, geen build nodig. De enige vereiste is Node zelf; npx haalt docfy-mcp op bij eerste gebruik.

Snel starten

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 haalt de spec rechtstreeks op in plaats van dit te delegeren aan de eigen HTTP-resolver van swagger-parser, waarvan de SSRF-bescherming standaard localhost/private adressen blokkeert. Dat zou het meest voorkomende geval hier breken: wijzen naar een lokale NestJS-devserver.

Registreren als MCP-server

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

Voor specs achter auth herhaal je --header zo vaak als nodig.

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

Opties

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

Een 404 oplossen

Het pad naar de OpenAPI JSON is geen vaste conventie. Het hangt af van wat je project heeft meegegeven aan SwaggerModule.setup().

Geeft --url een 404, dan probeert docfy-mcp een handvol veelvoorkomende buurpaden op dezelfde origin (/api-json, /docs-json, /swagger-json…) en stelt het voor welke daarvan als echt OpenAPI-document te parsen zijn.