Design Analysis MCP Server

An MCP server that reverse-engineers design videos and images into structured frontend implementation specifications. Uses vision LLMs (OpenAI, Anthropic, Gemini) and FFMPEG for frame-level analysis.

Features

11 MCP tools organized into three tiers:

Tool	Purpose
analyze_design	Full orchestration — runs all layers + writes files
analyze_layout	Grid, spacing, composition, hierarchy (no colors/animations)
analyze_typography	Fonts, type scale, text animations (per-character, stagger)
analyze_scroll	Scroll segments, parallax, sticky detection (video only)
reverse_engineer_animation	Multi-pass: burst-frame capture → find animations → crop + deep-dive
reverse_engineer_component	Single component with layout hypotheses + alternatives
design_uniqueness	"30-second test" — what makes this distinctive?
compare_designs	Side-by-side across layout, typography, animation, accessibility
critique_design	Engineering-focused critique with actionable improvements
generate_implementation_spec	Complete spec: component tree, tokens, states, a11y
extract_assets	Catalog all visual assets (icons, gradients, palette)

Architecture

                    ┌─────────────┐
                    │  MCP Client  │  (Claude Code, etc.)
                    └──────┬──────┘
                           │ stdio JSON-RPC
                    ┌──────┴──────┐
                    │  index.ts   │  Entry point, registers 11 tools
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────┴─────┐ ┌───┴───┐ ┌─────┴─────┐
        │   Tools   │ │Vision │ │Analyzers  │
        │           │ │Client │ │           │
        │ analyze_* │ │  │    │ │ video_to_ │
        │ reverse_* │ │  ├──Anthropic │ frames    │
        │ compare_* │ │  ├──OpenAI  │ detect_   │
        │ critique_ │ │  └──Gemini │ scroll_   │
        │ generate_ │ │         │ segments   │
        │ extract_  │ │         │ images_    │
        │ design_   │ │         │ to_pdf    │
        │ uniqueness│ │         │ analyze_* │
        └───────────┘ └────────┘ └───────────┘

Layered analysis

The orchestrator (analyze_design) runs layers independently to avoid mode confusion:

1. Layout — grid system, spacing principles, visual hierarchy
2. Typography — font categories, type scale, text animation details
3. Scroll — PSNR-based pixel-shift detection between frames
4. Motion — multi-pass: find animations → crop region → deep-dive
5. Uniqueness — "30-second test": what would a designer remember?

Confidence scoring

Every estimate includes confidence: number (0–1) and alternatives: string[] so downstream LLMs can distinguish reliable findings from speculation. Estimates describing what the model can see (movement direction, opacity change) get higher confidence than inferred values (exact CSS properties, easing curves, font names).

Multi-pass animation analysis

1. Burst capture — 15 FPS for first 3 seconds (captures fast discrete animations like slot-machine effects at 400–800ms)
2. Pass 1 — find all animations + estimate screen regions
3. Pass 2 — crop each region and deep-dive with a focused prompt

File-based output

analyze_design writes results to analysis/{name}/:

File	Contents
summary.md	Most memorable elements, confidence report
layout.md	Grid, spacing, composition
typography.md	Fonts, type scale, text animations
motion.md	Animation details
interaction.md	Design uniqueness output
implementation.md	Design tokens, component specs

Setup

Prerequisites

• Node.js 22+
• FFMPEG (for video frame extraction, scroll detection)
• At least one API key: OpenAI, Anthropic, or Gemini

Install

git clone <repo>
cd design-analysis-mcp-server
npm install

Configure

Copy .env.example to .env and set at least one API key:

cp .env.example .env
# Edit .env with your API keys

Optionally edit config.yaml to change model priority, frame extraction settings, or output directories.

Build

npm run build

Add to Claude Code

In your ~/.opencode.jsonc:

{
  "mcpServers": {
    "design-analysis": {
      "command": "node",
      "args": ["/path/to/design-analysis-mcp-server/build/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "GEMINI_API_KEY": "AIza..."
      }
    }
  }
}

Usage Examples

# Full analysis of a design video
analyze_design path=/path/to/demo.mp4 name=demo-v1

# Analyze only layout
analyze_layout path=/path/to/screenshot.png

# Reverse-engineer a specific component
reverse_engineer_component path=/path/to/screen.mp4 element_description="hero section with CTA button"

# Multi-pass animation deep-dive
reverse_engineer_animation path=/path/to/demo.mp4 region={x:100,y:200,width:300,height:400}

# Compare two designs
compare_designs referenceA={path:/path/to/v1.mp4,type:video} referenceB={path:/path/to/v2.mp4,type:video}

# Generate implementation spec
generate_implementation_spec path=/path/to/demo.mp4

# 30-second test for design uniqueness
design_uniqueness path=/path/to/demo.mp4

Configuration Reference

Config key	Default	Description
models	[{openai}, {anthropic}, {gemini}]	Model priority list; fallback on error
ffmpeg.frame_interval_sec	1.0	Standard mode frame interval
ffmpeg.frame_quality	2	PNG quality (2–31, lower = better)
ffmpeg.scene_threshold	0.3	PSNR threshold for scene detection
analysis.max_frames_per_video	200	Max frames in any extraction mode
analysis.max_pdf_pages	50	Max pages in generated PDFs
analysis.scroll_detection_window	5	Frames to merge when detecting scroll

Prompt Philosophy

All analyzer prompts follow a principle-first structure:

1. What principle does this follow? (high confidence — directly observable)
2. What mechanism could produce this? (medium confidence — alternatives listed)
3. What are the estimated values? (low confidence — clearly labeled)

Prompts instruct models to say "uncertain" rather than guess wrong, and to list alternative mechanisms when confidence < 0.8.