Installation & usage

npx docfy-mcp --spec/--url, registrazione in .mcp.json, --header per spec autenticate.

Requisiti

Pubblicato su npm: nessun clone, nessuna build. L'unico requisito è Node stesso; npx recupera docfy-mcp al primo utilizzo.

Avvio rapido

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 recupera la spec direttamente invece di delegare al resolver HTTP di swagger-parser, la cui protezione SSRF blocca di default localhost/indirizzi privati. Questo romperebbe il caso d'uso più comune qui: puntare a un server NestJS di sviluppo locale.

Registrarlo come server MCP

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

Per spec dietro autenticazione, ripeti --header tante volte quante servono.

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

Opzioni

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

Risolvere un 404

Il percorso JSON OpenAPI non è una convenzione fissa. Dipende da cosa il tuo progetto ha passato a SwaggerModule.setup().

Se --url restituisce 404, docfy-mcp prova un paio di percorsi comuni sulla stessa origine (/api-json, /docs-json, /swagger-json…) e suggerisce quelli che si interpretano come un vero documento OpenAPI.