design-doc-mcp

Turn the real technical work you just did in a Claude Code session into a saved, professional design doc — one slash command, no copy-pasting anywhere else, no signup for the free tier.

sequenceDiagram
    participant Dev as You
    participant Claude as Claude Code (your session)
    participant MCP as design-doc-mcp (local)
    participant BE as Hosted backend

    Dev->>Claude: /design-doc
    Claude->>MCP: prepare_design_doc
    MCP->>MCP: gather local git context (branch, status, diff --stat, log)
    MCP->>BE: fetch section template (mode/tier only - no code)
    BE-->>MCP: drafting instructions
    MCP-->>Claude: instructions + local context
    Claude->>Claude: draft the actual document
    Claude->>MCP: save_design_doc
    MCP-->>Dev: docs/<title>.md (+ .html if requested)

What you get

• A properly structured design doc — abstract, problem statement, architecture & flow diagrams, key decisions/trade-offs, risks, and more — drafted from what you actually did, with sections that don't apply automatically left out. No filler.

• At least two Mermaid diagrams wherever the session supports it: a static architecture view and a runtime/sequence view, auto-styled for readable font size and spacing.

• A table of contents, auto-inserted.

• An optional standalone interactive HTML export — themed, light/dark, sticky navigation.

• Two other doc shapes, auto-detected from context: a root-cause/bug-investigation doc, and a comparison/decision doc for "which approach" discussions.

Install

npx design-doc-mcp init

Run this inside the project you want to document. It registers the MCP server and installs the /design-doc skill. Restart Claude Code, do some real work, then run:

/design-doc

Usage

/design-doc [flags]

The doc is saved to docs/<title>.md in your project. Running it again on the same topic later updates that same file rather than creating a new one.

Your code never leaves your machine

This tool does not read your source files. It only gathers lightweight, read-only git metadata — your current branch, git status (file paths and change markers, not content), a git diff --stat summary (file names and line-count totals, not the actual diff), and the last 15 commit subject lines. The document itself is drafted by Claude, inside your own session, on your own account — this tool never calls an LLM or sends your code anywhere.

The only two things that ever reach a network: a request for the section template (just a mode/tier string, no code) when drafting, and your license key when you run --activate.

Free vs. Pro

• Free: 5 design docs per day, full content depth, HTML export included — no signup required.

• Pro: removes the daily cap. That's the only difference right now.

License

MIT — see LICENSE.