mcp-docs

Swagger UI for MCP servers. Point it at any MCP server, get a static docs site with tool schemas, return types, resources, prompts, and copy-paste install snippets for Claude Code, Cursor, and VS Code. No AI in the loop, no cloud, no account.

| Light | Dark | | --- | --- | | | |

Requires Node 20+. Run any command with npx @fyrlabs/mcp-docs <command> (or install globally: npm i -g @fyrlabs/mcp-docs).

What you get: a single self-contained HTML page with sidebar navigation and deep links to every tool, resource, template, and prompt · unified search · parameter and return-type tables generated from JSON Schema · copy-paste install snippets for Claude Code (CLI), Cursor, and VS Code · light/dark themes · mobile-friendly layout. Sections for capabilities a server doesn't declare are omitted automatically, so the page always matches the server exactly.

Quick start

npx @fyrlabs/mcp-docs generate --command "npx -y @modelcontextprotocol/server-filesystem /path/to/dir"
# -> docs/index.html + docs/mcp-manifest.json

generate — static docs site

# stdio server
npx @fyrlabs/mcp-docs generate --command "npx -y @modelcontextprotocol/server-filesystem /path/to/dir"

# HTTP server
npx @fyrlabs/mcp-docs generate --url https://example.com/mcp --header "Authorization: Bearer <token>"

# from an existing mcpServers config (Claude Desktop / Claude Code / Cursor / VS Code format)
npx @fyrlabs/mcp-docs generate --config .mcp.json --server my-server

# no flags: auto-detects .mcp.json / .vscode/mcp.json / .cursor/mcp.json / Claude Desktop config
# in the current directory (pass --server to disambiguate if it defines more than one)
npx @fyrlabs/mcp-docs generate

Writes docs/mcp-manifest.json (a versioned, git-diff-friendly, deterministic snapshot of the server's tools, resources, resource templates, and prompts — re-running against an unchanged server produces a byte-identical file) and docs/index.html (a single self-contained docs page — sidebar navigation with deep links, search across everything, parameter and return-type tables, light/dark themes). Sections for features a server doesn't have are omitted automatically.

Flags: -o, --out <dir> (default docs), --manifest-only (skip HTML, write only the manifest).

Servers that need auth or environment

• HTTP servers: pass --header "Authorization: Bearer <token>" to connect. Headers are used only for the connection — they are deliberately never written into the manifest or the generated page, so you can commit both safely.
• stdio servers needing env vars: define the server in an .mcp.json with its env block and use --config; environment variables are passed through to the spawned process.

serve — local "try it" panel

npx @fyrlabs/mcp-docs serve --command "npx -y @modelcontextprotocol/server-filesystem /path/to/dir"

Connects to the server once, then serves the same docs page at http://127.0.0.1:6280 (override with --port) with working try-it forms wired to the live connection — fill in a tool's arguments, click run, see the real response, read resources, and preview prompts with their actual rendered messages in a text/JSON modal.

The bridge is loopback-only and protected against CSRF/DNS-rebinding: requests must carry a one-time session token printed at startup, and must target 127.0.0.1/localhost. This is local-only by design: there is no hosted equivalent, since a publicly reachable try-it bridge would let anyone invoke tools against your live server. The static generate output contains no bridge code at all.

Not yet wired into try-it: resource templates (tools, resources, and prompts all have panels).

init — CI + GitHub Pages

npx @fyrlabs/mcp-docs init --command "npx -y @modelcontextprotocol/server-filesystem /path/to/dir"

Writes .github/workflows/mcp-docs.yml: on every push, it checks out, installs, runs generate, and deploys docs/ to GitHub Pages — the build fails if the server won't start, so a broken server can't ship silent docs. Also prints a markdown badge snippet to add to your own README, linking to the generated Pages URL. Flags: -o, --out <dir> (default docs), --branch <name> (default: current branch).

check — manifest drift detection

npx @fyrlabs/mcp-docs check --command "npx -y @modelcontextprotocol/server-filesystem /path/to/dir"

Re-introspects the server and compares it against the committed mcp-manifest.json (--manifest <path>, default <out>/mcp-manifest.json). Exits 0 when in sync; exits 1 with a per-item report (added/removed/changed tools, resources, templates, prompts) when anything drifted. Useful as a CI step alongside the init workflow: fail the build when someone changes the server without regenerating docs.

Status

generate, serve, init, and check are implemented. See ROADMAP.md for what's next: OAuth flows for protected HTTP servers, try-it panels for resource templates and prompts, syntax highlighting, and npm publish.

Development

npm run build   # tsc -> dist/
npm run dev     # tsx src/cli.ts (no build step)

examples/notes-server/ and examples/showcase-server/ are zero-setup MCP servers for testing: the latter exercises every feature mcp-docs renders (annotated tools, output schemas, resource templates, prompt arguments, icons, instructions).

License

Apache-2.0