alemusica

Copiatore — Design Intelligence MCP Server

Browser-based design analysis, site cloning, and quality assurance via Model Context Protocol.

Extracts structured data from any webpage — colors, typography, layout, spacing, accessibility, design tokens — and gives Claude (or any MCP client) the raw material to analyze, audit, clone, and fix designs.

Install

git clone https://github.com/Alemusica/copiatore.git
cd copiatore
npm install
npm run build

Add to Claude Code settings (~/.claude/settings.json):

{
  "mcpServers": {
    "copiatore": {
      "command": "node",
      "args": ["/path/to/copiatore/dist/index.js"]
    }
  }
}

Skills

Command	Description
/copiatore scan <url>	Quick visual audit with severity-ranked issues
/copiatore fix <url>	Deep audit + automatic fixes + visual diff verification
/copiatore heal <url>	Self-healing loop: audit → fix → verify → iterate (max 3 cycles)
/copiatore clone <url>	Full site cloning: extract structure + tokens + assets → rebuild
/copiatore tokens <url>	Extract design tokens (CSS variables)
/copiatore export-tokens <url>	W3C DTCG + Style Dictionary multi-platform export
/copiatore perf <url>	Lighthouse + Web Vitals + PageSpeed performance audit
/copiatore a11y-axe <url>	axe-core accessibility audit (WCAG 2.1 AA)
/copiatore bench <url>	HTTP load testing with autocannon
/copiatore test <url>	Automated form/CTA functional testing

Architecture

Engine: Playwright (default) or Puppeteer via COPIATORE_ENGINE env var.

src/
  index.ts                    # MCP server entry + browser lifecycle
  context.ts                  # Shared server context
  copiatore/
    browser.ts                # Playwright/Puppeteer adapter
    extract-types.ts          # TypeScript interfaces
    extract/                  # DOM extractors (color, typography, layout, spacing, a11y, tokens...)
    tools-v2/                 # MCP tool handlers (clone, a11y, perf, web-vitals, etc.)
  tools/                      # Core tool handlers (navigate, screenshot, audit, etc.)
  collectors/                 # Event collectors (console, network, mutations, performance)
skills/
  copiatore/SKILL.md          # Full command reference + workflows
.claude/
  design-criteria.md          # Evaluation framework for audits
  design-knowledge.md         # Token interpretation, design system theory
  design-references.md        # Industry patterns (Apple HIG, Material, award-winning sites)
  agents/                     # Specialist subagents (design-qa, heal-loop, a11y, perf)

Key Principles

"Boil the Lake" — When AI reduces marginal cost to near-zero, go for 100% completeness. No 80% clones, no skipped sections, no approximated spacing.

Self-Healing Loop — /copiatore heal and /copiatore fix run iterative cycles: audit → fix → visual diff → re-audit. Max 3 iterations. Stops when no critical/major issues remain.

Completion Status Protocol — Every tool reports: DONE, DONE_WITH_CONCERNS, BLOCKED, or NEEDS_CONTEXT.

Common Workflows

# Clone a site
copiatore_navigate → copiatore_clone_extract → build section by section → copiatore_visual_diff

# Audit and fix
copiatore_navigate → copiatore_snapshot → analyze → apply fixes → copiatore_visual_diff

# Design review (recommended)
copiatore_navigate → copiatore_snapshot → copiatore_design_review → report

# Deep review (comprehensive)
copiatore_navigate → copiatore_snapshot → copiatore_design_review → copiatore_a11y_axe → copiatore_lighthouse → report

Development

npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm run deploy       # Build + sync to plugin cache
npm run deploy:only  # Sync to cache without rebuilding
npm test             # Run tests

The MCP server runs from ~/.claude/plugins/cache/. After building, npm run deploy syncs everything to the cache. Then /mcp restart copiatore in Claude Code to reload.

Project History

75 commits, ~47K lines, 34 days of development (26 Feb → 31 Mar 2026).

v0.1.0 — Fork and foundations (26 Feb)

Fork of puppeteer-observe-mcp. 6 MCP tools, 8 signal extractors, cognitive load scorer, design coherence scorer, vision analyzer, screenshot manager. 61 tests passing on day one.

v0.2.0 — Pure extraction rewrite (27 Feb)

Radical architectural decision: removed all scoring and vision subprocess. Rewritten from scratch with pure extractors (color, typography, layout, a11y, spacing, content, navigation, interaction). Design tokens with hue-based color categorization and CSS variables. Stripe as benchmark reference. Extraction-only architecture: raw data, zero opinions.