Installation & usage

npx docfy-mcp --spec/--url, enregistrement dans .mcp.json, --header pour les specs authentifiées.

Prérequis

Publié sur npm : pas de clone, pas de build. La seule exigence est Node lui-même ; npx récupère docfy-mcp à la première utilisation.

Démarrage rapide

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 récupère la spec directement plutôt que de déléguer au résolveur HTTP propre de swagger-parser, dont la protection SSRF bloque localhost/les adresses privées par défaut. Ça casserait le cas le plus courant ici : pointer vers un serveur de dev NestJS local.

S'enregistrer comme serveur MCP

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

Pour les specs derrière une authentification, répète --header autant de fois que nécessaire.

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

Options

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

Résoudre un 404

Le chemin JSON OpenAPI n'est pas une convention figée. Ça dépend de ce que ton projet a passé à SwaggerModule.setup().

Si --url renvoie un 404, docfy-mcp teste une poignée de chemins voisins courants sur la même origine (/api-json, /docs-json, /swagger-json…) et suggère ceux qui se parsent comme un vrai document OpenAPI.