Design Audit MCP

An MCP server that captures, audits, and scores web-page design. It acts as a design reviewer: it screenshots a page (full-length, including lazy-loaded and scroll-pinned sections), judges it against a visual rubric, checks token consistency against a design kit, produces a 0–100 score, and renders a self-contained HTML report.

Tools

| Tool | What it does | |------|--------------| | capture_page | Full-page desktop/mobile screenshots via Playwright (handles lazy-mounted + scroll-pinned sections). | | generate_design_kit | Extract design tokens from a URL (as-rendered) or a repo path (declared CSS vars / Tailwind config). Writes JSON + an HTML kit. | | audit_screenshot | Returns the screenshot + a strict visual rubric (alignment, spacing, typography, hierarchy) for the host model to judge. | | audit_design_consistency | Diffs a live page's tokens against a design kit; reports color/type/spacing/radius drift. | | calculate_design_score | Scores findings + violations (0–100, per-bucket), then writes & opens the HTML report. | | annotate_audit | Draws findings onto the screenshot as numbered pins + legend (sharable PNG). | | check_pr_screenshots | Flags PRs that change UI files but attach no screenshots (gh PR or local git diff). |

Setup

Requires Node 18+.

git clone <your-repo-url> design-audit-mcp
cd design-audit-mcp
npm install
npx playwright install chromium   # the browser Playwright drives
npm run build                     # compiles src/ -> dist/

Register with Claude Code

Add to your MCP config (e.g. ~/.claude.json, or run claude mcp add):

{
  "mcpServers": {
    "design-audit": {
      "command": "node",
      "args": ["/absolute/path/to/design-audit-mcp/dist/server.js"]
    }
  }
}

Or via CLI:

claude mcp add design-audit -- node /absolute/path/to/design-audit-mcp/dist/server.js

Restart the MCP server after any rebuild — a reconnect alone does not reload dist/.

Output location

Screenshots, reports, and design kits are written to ./artifacts/ in the current working directory (i.e. the project you're auditing). Override with:

export DESIGN_AUDIT_DIR=/path/to/output

Development

npm run dev        # tsc --watch
node dist/tools/<tool>.js   # each tool file has a runnable self-check (demo())

Each tool ships one runnable self-check in its demo(); run the compiled file directly to exercise it.

Roadmap

See DESIGN_AUDIT_MCP_ROADMAP.md. Phase 1 (audit MVP) is complete; Phases 2–4 (team workflow, design assistant, design intern) are planned.