Installation & usage

npx docfy-mcp --spec/--url, registrando .mcp.json, --header para specs autenticadas.

Requisitos

Publicado en npm: sin clone, sin build. El único requisito es el propio Node; npx obtiene docfy-mcp en el primer uso.

Inicio rápido

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 obtiene la spec directamente en vez de delegar en el resolver HTTP propio de swagger-parser, cuya protección SSRF bloquea localhost/direcciones privadas por defecto. Eso rompería el caso más común aquí: apuntar a un dev server NestJS local.

Registrarlo como servidor MCP

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

Para specs detrás de auth, repite --header tantas veces como haga falta.

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

Opciones

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

Solucionar un 404

La ruta del JSON OpenAPI no es una convención fija. Depende de lo que tu proyecto haya pasado a SwaggerModule.setup().

Si --url devuelve 404, docfy-mcp prueba un puñado de paths hermanos comunes en el mismo origen (/api-json, /docs-json, /swagger-json…) y sugiere cualquiera que parsee como un documento OpenAPI real.