Installation & usage

npx docfy-mcp --spec/--url、.mcp.jsonへの登録、認証が必要なスペック向けの--headerです。

要件

npmに公開されているため、クローンもビルドも不要です。唯一の要件はNode自体です。npxが初回利用時にdocfy-mcpを取得します。

クイックスタート

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は、swagger-parser自身のHTTPリゾルバーに委譲するのではなく、スペックを直接取得します。そのリゾルバーのSSRFガードはデフォルトでlocalhost/プライベートアドレスをブロックするため、ここで最もよくあるケース、つまりローカルのNest開発サーバーを指す場合が壊れてしまいます。

MCPサーバーとして登録する

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

認証が必要なスペックには、必要な数だけ--headerを繰り返してください。

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

オプション

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

404のトラブルシューティング

OpenAPI JSONのパスは固定の慣習ではありません。プロジェクトがSwaggerModule.setup()に何を渡したかによります。

--urlが404を返す場合、docfy-mcpは同じオリジン上のいくつかの一般的な兄弟パス(/api-json、/docs-json、/swagger-json…)を探査し、実際のOpenAPIドキュメントとしてパースできるものがあれば提案します。