Generating Documentation

The docs-mcp CLI includes two documentation generators: build-repo-docs for plain markdown output, and build-starlight-docs for full Astro Starlight integration. This guide covers the Starlight variant.

Prerequisites

You need the following environment variables set:

• ANTHROPIC_API_KEY — required for all LLM steps
• MEILI_MASTER_KEY — optional, enables codebase search during writing (requires a running Meilisearch instance)
• MEILI_HOST — optional, defaults to http://localhost:7700

Quick start

From the scripts/docs-mcp directory:

bun run dev build-starlight-docs \
  -r /path/to/target-repo \
  -p ../../

The -r flag points at the repository you want to document. The -p flag points at your Starlight project root — the command automatically resolves the output to src/content/docs/generated/.

What the pipeline does

The command runs five steps:

1. Build file tree — walks the repo using git ls-files, filters binaries and large files, stores metadata in a local SQLite database (.docs-mcp.db in the target repo)
2. Extract structure — uses Haiku to identify symbols, imports, and exports per file
3. Summarise — generates per-file summaries (Haiku) then per-folder summaries (Sonnet), optionally indexes into Meilisearch
4. Plan topics — Opus decides which documentation pages to create, assigns each to a Diátaxis category (guides, reference, concepts, tutorials), and sets sort order
5. Write docs — Sonnet writes each topic as a .mdx file with frontmatter, then updates the sidebar in astro.config.mjs

Output structure

Generated files are organised into group subdirectories with sort-order prefixes:

src/content/docs/generated/
├── index.mdx
├── concepts/
│   ├── index.mdx
│   ├── 01-architecture.mdx
│   └── 02-data-model.mdx
├── guides/
│   ├── index.mdx
│   ├── 01-setup.mdx
│   └── 02-deployment.mdx
├── reference/
│   └── 01-api-routes.mdx
└── tutorials/
    └── 01-quickstart.mdx

Starlight’s autogenerate sidebar picks up each directory. The command also updates your astro.config.mjs with the appropriate sidebar entries.

Flags

Flag	Short	Description
--repo	-r	Path to the repository to document (required)
--starlight-root	-p	Starlight project root — auto-resolves to src/content/docs/generated/
--output	-o	Explicit output directory (overrides -p)
--section	-s	Sidebar section label (default: “Generated Docs”)
--resume		Skip steps that already have data in the DB

Resuming after a failure

If the command fails partway through (e.g. an API error during step 5), you don’t need to re-run the expensive LLM steps. Add --resume:

bun run dev build-starlight-docs \
  -r /path/to/target-repo \
  -p ../../ \
  --resume

Steps with existing data in the SQLite database are skipped and show (cached). Step 5 always re-runs since it produces the final output.

To force a full rebuild, delete the database first:

rm -f /path/to/target-repo/.docs-mcp.db*

Plain markdown variant

If you don’t need Starlight integration, use build-repo-docs instead:

bun run dev build-repo-docs -r /path/to/repo -o ./docs

This outputs plain .md files with a README.md table of contents.

Analyzing documentation gaps

After running the pipeline, a Claude Code slash command is available to analyze the database and suggest what to document next. Run it from the project root:

/analyze-docs

This executes .claude/tools/analyze-docs.py, which queries the .docs-mcp.db database and reports:

• Most imported modules — the dependencies the codebase relies on most heavily
• Most used symbols — functions, classes, and types that appear across many files
• Highest PageRank files — files central to the dependency graph with the widest blast radius
• Most exported symbols — the public API surface
• Topics coverage — existing documentation topics and their grouping

Claude interprets the results and identifies gaps: components that are heavily used but not yet covered by any documentation topic. This is useful for iteratively improving generated docs or deciding what to write manually.

You can also query the database directly for ad-hoc analysis:

sqlite3 /path/to/target-repo/.docs-mcp.db \
  "SELECT f.relative_path, fm.pagerank FROM files f JOIN file_metrics fm ON fm.file_id = f.id ORDER BY fm.pagerank DESC LIMIT 10"

Key tables: files, file_imports, file_exports, file_symbols, file_metrics, file_summaries, topics.

Cost

A typical run on a ~250 file repository costs around $0.20 in API usage, broken down across Haiku (bulk extraction/summarisation), Sonnet (folder summaries, writing), and Opus (topic planning).