# MCP Scroll Animation Analyzer

A Model Context Protocol (MCP) server that uses Playwright to analyze scroll-triggered animations on any webpage. Unlike GSAP generation MCPs, this focuses on **analyzing existing websites** to extract and understand animations built with GSAP, ScrollTrigger, Lenis, and CSS.

## Features

- **AST-based extraction** - Uses Acorn for reliable JavaScript parsing (not regex)
- **Open any webpage** in a real Chromium browser
- **Scroll and record** - capture video and screenshots as you scroll
- **Extract animation code** - find GSAP, ScrollTrigger, and Lenis code
- **Interactive analysis** - click, hover, and interact while recording
- **Watch specific elements** - track style changes on individual elements
- **Generate reports** - JSON, Markdown, or HTML reports
- **Export replicable code** - generate standalone code (vanilla JS, React, Vue)
- **CLI support** - use standalone without MCP integration

## Installation

### 1. Install dependencies

```bash
cd mcp-scroll-analyzer
npm install
```

### 2. Install Playwright browsers

```bash
npx playwright install chromium
```

### 3. Build the TypeScript

```bash
npm run build
```

### 4. Configure Claude Code

Add the MCP server to your Claude Code configuration.

**For VSCode Claude Code extension**, add to your `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "scroll-analyzer": {
      "command": "node",
      "args": ["C:/path/to/mcp-scroll-analyzer/dist/index.js"]
    }
  }
}
```

**For Claude Code CLI**, add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "scroll-analyzer": {
      "command": "node",
      "args": ["C:/path/to/mcp-scroll-analyzer/dist/index.js"]
    }
  }
}
```

## CLI Usage

The analyzer can also be used standalone via CLI:

```bash
# Analyze a webpage
npx scroll-analyzer analyze https://example.com

# With options
npx scroll-analyzer analyze https://example.com --output ./reports --format html

# Export replicable code
npx scroll-analyzer export https://example.com --target react
```

### CLI Commands

```
analyze <url>  - Analyze a webpage and generate a report
  Options:
    -o, --output <dir>     Output directory (default: ./scroll-analysis-output)
    -f, --format <type>    Report format: json|markdown|html (default: markdown)
    --no-headless          Run browser in visible mode
    -w, --width <pixels>   Viewport width (default: 1920)
    -h, --height <pixels>  Viewport height (default: 1080)

export <url>   - Analyze and export replicable code
  Options:
    -o, --output <dir>     Output directory
    -t, --target <fw>      Framework: vanilla|react|vue (default: vanilla)
```

## Available MCP Tools

### Page Management

| Tool | Description |
|------|-------------|
| `open_page` | Open a URL in headless browser for analysis |
| `close_browser` | Close browser and clean up resources |
| `set_output_directory` | Set where screenshots/videos/reports are saved |

### Scroll & Recording

| Tool | Description |
|------|-------------|
| `scroll_and_record` | Scroll through page, record video, capture screenshots |
| `capture_current_state` | Take screenshot at current scroll position |

### Animation Analysis

| Tool | Description |
|------|-------------|
| `extract_animation_code` | Extract GSAP, ScrollTrigger, Lenis code (AST-based) |
| `deep_script_analysis` | Deep analysis of all JS for animation patterns |
| `get_scroll_triggers` | Get all ScrollTrigger instances and configs |
| `analyze_lenis` | Analyze Lenis smooth scroll configuration |
| `get_animation_css` | Extract CSS animations and keyframes |

### Element Inspection

| Tool | Description |
|------|-------------|
| `watch_element` | Watch element for style changes during scroll |
| `get_element_animations` | Get all animations affecting a specific element |
| `trace_animation_execution` | Capture GSAP calls in real-time during scroll |

### Interaction

| Tool | Description |
|------|-------------|
| `interact_with_page` | Click, hover, scroll to, or type on elements |

### Output

| Tool | Description |
|------|-------------|
| `generate_report` | Generate JSON, Markdown, or HTML report |
| `export_replicable_code` | Generate standalone code (vanilla/React/Vue) |

## Usage Examples

### Basic Analysis Workflow

```
1. open_page(url: "https://example.com")
2. scroll_and_record()
3. extract_animation_code()
4. get_scroll_triggers()
5. generate_report(format: "markdown")
6. close_browser()
```

### Watch a Specific Element

```
1. open_page(url: "https://example.com")
2. watch_element(selector: ".hero-title", scrollThrough: true)
3. get_element_animations(selector: ".hero-title")
```

### Extract and Replicate

```
1. open_page(url: "https://example.com")
2. scroll_and_record()
3. extract_animation_code()
4. export_replicable_code(framework: "react")
```

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── cli.ts                # CLI entry point
├── types.ts              # TypeScript interfaces
├── schemas.ts            # Zod validation schemas
├── extractors/
│   ├── gsap-extractor.ts      # AST-based GSAP extraction
│   ├── lenis-extractor.ts     # Lenis extraction
│   └── css-extractor.ts       # CSS animations (CSSOM)
├── browser/
│   ├── browser-manager.ts     # Playwright lifecycle
│   └── page-controller.ts     # Scroll, interact, capture
├── analyzers/
│   ├── runtime-analyzer.ts    # GSAP/ScrollTrigger API queries
│   └── script-analyzer.ts     # Orchestrates extractors
└── reporters/
    ├── markdown-reporter.ts
    ├── html-reporter.ts
    └── code-exporter.ts
```

## Development

```bash
# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Test coverage
npm run test:coverage
```

## How It Differs from GSAP Generation MCPs

| Feature | Generation MCPs | This Analyzer MCP |
|---------|-----------------|-------------------|
| Purpose | Create new animations | Analyze existing sites |
| Input | Natural language intent | URLs/existing pages |
| Output | GSAP code to use | Analysis reports, extracted code |
| Browser | Not needed | Playwright for real rendering |
| Use case | Building new features | Learning, debugging, reverse engineering |

## Technical Details

- Built with TypeScript and MCP SDK
- Uses Playwright for real browser automation
- AST parsing with Acorn (not regex)
- Zod for input validation
- Supports headless Chromium
- Records video automatically
- Injects tracers to capture runtime GSAP calls

## Known Limitations

### AST Extraction on Minified Sites

The `extract_animation_code` tool uses AST parsing which **skips minified JavaScript by default**. This is intentional because:
- Minified code is slow to parse and often fails
- Variable names are mangled, making extraction less useful

**Workaround:** Use `get_scroll_triggers` for runtime detection - it queries the GSAP/ScrollTrigger APIs directly and works regardless of code minification.

### watch_element Style Changes

The `watch_element` tool may report fewer style changes than expected because browser scroll event listeners don't always fire during programmatic scrolls (`window.scrollTo()`). For comprehensive element tracking, combine with `scroll_and_record` which captures animation state at each frame.

## Tested Sites

| Site | ScrollTriggers Found | Notes |
|------|---------------------|-------|
| gsap.com | 35 | Runtime detection works; AST returns 0 (minified) |
| Custom unminified sites | Full extraction | AST + runtime both work |

## License

MIT