PicassoWeb MCP

"Good artists copy, great artists steal." — the tool formerly known as webcopy-design-mcp.

PicassoWeb opens a website in Chromium and turns its rendered interface into everything an AI client needs to replicate it faithfully. It extracts the actual computed colors, typography, CSS variables, layout primitives, and reusable component families instead of only searching the raw source for CSS strings. Beyond the design system, it can screenshot the page, download the real assets (images, inline SVG logos/icons, fonts, video), extract the motion design (@keyframes, transitions, animation libraries, scroll reveals), map the layout tree, clone a section to self-contained HTML + CSS + assets, produce a complete one-shot replication kit, and pixel-diff a replica against the original so an agent can iterate until the copy matches.

What it extracts

• Color palette normalized to hex, with usage counts for text, backgrounds, borders, decoration, SVG fills, and strokes.
• Font families, weights, styles, type sizes, line heights, letter spacing, and representative selectors.
• CSS custom properties classified as color, typography, spacing, radius, shadow, or other tokens.
• Common border radii, box shadows, margins, padding, and gaps.
• Component families such as buttons, inputs, cards, navigation, headers, footers, modals, tabs, accordions, badges, avatars, forms, tables, heroes, and pagination.
• Detailed inspection of a chosen CSS selector, including computed styles, bounds, attributes, pseudo-elements, child structure, and a bounded HTML sample.

JavaScript-rendered pages are supported. By default, the analyzer also scrolls through the page to trigger lazy-rendered sections before extraction.

MCP tools

Tool	Purpose
analyze_site	Analyze a live http:// or https:// website.
analyze_html	Render supplied HTML and optional CSS without making external requests.
inspect_component	Inspect the elements matching a CSS selector on a live website. Also captures :hover, :focus, and :active computed styles (Chromium, via CDP) so interactive states can be reproduced.
capture_screenshot	Return a screenshot the client can look at: viewport, full page, or a single element by selector. Optionally saves the image to disk.
extract_assets	Download the real images, background images, inline SVG icons/logos, videos, favicons, and web fonts into a local assets/ folder with a manifest.json mapping each file to where it appears. Lets a replica reuse the exact original assets instead of re-drawing them.
extract_animations	Extract @keyframes, per-element animation/transition settings, detected animation libraries (GSAP, Framer Motion, AOS, Lottie, CSS scroll-driven), and scroll-triggered reveal effects captured by diffing styles before and after scrolling.
extract_layout	Return a simplified DOM tree with only layout-relevant computed styles per node (flex/grid, sizing, spacing, positioning) and section labels — how the page is structured, not just its tokens.
clone_section	Return a self-contained copy of one section: cleaned HTML (scripts/handlers stripped, inline SVG preserved, media URLs absolutized), scoped CSS matching that subtree plus the @keyframes/@font-face/:root CSS variables it depends on, its assets, and a screenshot. With outputDir, assets are downloaded and URLs rewritten to relative paths so the snippet renders standalone.
capture_interactions	Find and operate interactive triggers (hamburger menus, dropdowns, modals, tabs, accordions), then capture what they reveal: selectors, bounds, HTML samples, and screenshots taken while the UI is open. Surfaces the parts of a design that never appear in a static extraction.
extract_responsive	Extract how the site adapts across screen sizes: breakpoints derived from @media rules, a summary of each media query (condition, rule count, sample selectors), and a layout tree captured at each requested viewport width — with an optional screenshot per width.
create_replication_kit	One-shot capture of everything, written to a folder: desktop + mobile screenshots, assets/ with manifest, design.json, layout.json (desktop + mobile trees), animations.json, and a REPLICATE.md guide. Loads the page once, so it is much faster than calling the individual tools separately.
compare_replica	The verification loop: screenshot the original and a replica (local file or URL) at the same viewport with animations frozen, pixel-diff them, and return a match percentage, the worst-matching regions with coordinates, and a visual diff image. Build → compare → fix the worst regions → repeat until it matches.

All tools return JSON text and MCP structured content. capture_screenshot, clone_section, create_replication_kit, compare_replica, and capture_interactions additionally return image content blocks (screenshots or visual diffs).

Session reuse

Read-style tools (analyze_site, inspect_component, capture_screenshot, extract_assets, extract_animations, extract_layout, clone_section) share a small cache of loaded pages keyed by URL + viewport. Consecutive calls against the same page skip the full navigation — typically 2–5s saved per call — and note the reuse in warnings. Sessions expire after 2 minutes; tools that mutate page state (extract_responsive, create_replication_kit, compare_replica, capture_interactions) always load fresh.

Tools that write files

extract_assets, create_replication_kit, clone_section (with outputDir), extract_responsive (with outputDir), and capture_screenshot (with outputPath) write to the local filesystem, so they are not marked read-only. Every downloaded asset URL is re-checked against the same SSRF guard as the initial navigation.

Quick start (npx)

Requirements: Node.js 20 or newer. Add PicassoWeb to your MCP client configuration — no clone, no build:

{
  "mcpServers": {
    "picassoweb": {
      "command": "npx",
      "args": ["-y", "picassoweb"]
    }
  }
}

The first run downloads the package and a Chromium build (~130 MB, cached after that). If Chromium is already installed, point the server at it instead:

{
  "mcpServers": {
    "picassoweb": {
      "command": "npx",
      "args": ["-y", "picassoweb"],
      "env": { "CHROME_EXECUTABLE_PATH": "/absolute/path/to/chromium" }
    }
  }
}

Install from source

git clone https://github.com/blackridder22/PicassoWeb.git
cd PicassoWeb
npm install          # also downloads Chromium via postinstall
npm run build

Connect an MCP client (from source)

Build the project, then add a stdio server to your MCP client configuration. Replace the example path with the absolute project path.

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

During development, the client can launch the TypeScript entry point directly:

{
  "mcpServers": {
    "picassoweb-dev": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/webcopy-design-mcp/src/index.ts"]
    }
  }
}

The MCP server communicates over standard input/output. Diagnostic messages are written only to standard error.

Example calls

Analyze a public site:

{
  "url": "https://example.com",
  "viewportWidth": 1440,
  "viewportHeight": 900,
  "maxElements": 2500,
  "autoScroll": true
}

Inspect a component after the overview identifies a useful selector:

{
  "url": "https://example.com",
  "selector": ".pricing-card",
  "maxMatches": 5
}

Analyze source supplied directly by an agent or another tool:

{
  "html": "<main><article class=\"card\"><h2>Hello</h2></article></main>",
  "css": ":root{--brand:#6d5dfc}.card{padding:24px;color:var(--brand)}"
}

Docker

The image uses the official Playwright runtime, so Chromium and its system libraries are already present.

docker build -t picassoweb-mcp .

An MCP client can launch the container as its stdio command:

{
  "mcpServers": {
    "picassoweb": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "picassoweb-mcp"]
    }
  }
}

Security defaults

• Only HTTP and HTTPS URLs are accepted.
• Embedded URL credentials are rejected.
• Localhost, private IP ranges, link-local addresses, and reserved networks are blocked by default.
• Every browser request is checked, including redirects and subresources.
• analyze_html blocks external network requests.
• Input sizes, navigation time, DOM sampling, selector matches, CSS collection, and returned HTML are bounded.

For a trusted local development site, pass "allowPrivateNetwork": true. This should remain disabled when calls can be influenced by untrusted content.

compare_replica is the one exception with a relaxed default: allowPrivateReplica defaults to true so the replica side can point at a localhost dev server or a local file, which is the normal workflow. The original URL is still fully SSRF-guarded.

Development

npm run typecheck
npm test
npm run build

The browser integration test runs when CHROME_EXECUTABLE_PATH is set. The remaining tests validate CSS token extraction, URL safeguards, session caching, and the exposed MCP contract without requiring a browser.

For a full end-to-end smoke test of the built server over real stdio (tool listing, extraction, session-cache speedup, interaction capture):

npm run build
node scripts/cold-test.mjs            # defaults to https://getbootstrap.com/
node scripts/cold-test.mjs https://your-target.example

Practical limitations

• Authentication, cookie consent, CAPTCHAs, and anti-bot systems are not bypassed.
• Content that appears only after a user-specific interaction may require a separate browser automation step before analysis.
• Computed styles remain available when cross-origin stylesheet rules are inaccessible. Raw CSS variables are additionally recovered from readable stylesheet responses when possible.
• Component recognition is semantic and heuristic. inspect_component provides the exact follow-up data when a family needs closer analysis.
• Downloaded assets are the original copyrighted files. Reuse them only where you have the right to; extract_assets is a copy tool, not a licensing check.
• extract_animations reports scroll reveals by diffing computed styles before and after scrolling. It captures the visible start/end state of an effect, not the exact JS timeline that drives it; the detected library name tells you how to reproduce it.
• Interaction states in inspect_component are captured via Chromium DevTools Protocol and are therefore Chromium-only.

License

MIT