# 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

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

### Configure

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

```bash
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

```bash
npm run build
```

### Add to Claude Code

In your `~/.opencode.jsonc`:

```json
{
  "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

```bash
# 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.