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:

Related MCP server: vidlizer

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}/:

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

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.