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

cd mcp-scroll-analyzer
npm install

2. Install Playwright browsers

npx playwright install chromium

3. Build the TypeScript

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:

{
  "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:

{
  "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:

# 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

# 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