# MotionDesign MCP 🚀
> **The High-End Web & Motion Engineering MCP Server for Claude Code, Cursor, Windsurf & Claude Desktop.**

Eliminate generic AI "vibecoding" (flat purple buttons, jarring animations, broken mobile layouts) and empower AI assistants to architect and build **Awwwards / MotionSites level websites** with verified spring physics, computed color tokens, modular React 19 templates, and forensic visual inspection.

---

## ✨ Features Overview

| Feature | Description | Tool Name |
| :--- | :--- | :--- |
| 🏛️ **Architect & Blueprint Engine** | Acts as Art Director: diagnoses niche, structures 8-fold storytelling, recommends stack and multi-agent roles. | `generate_blueprint` |
| 💎 **328 MotionSites Models Vault** | Searchable database of 328 official (Free + Pro) MotionSites models with HD video/image previews and master prompts. | `search_vault`, `get_vault_prompt` |
| 🧩 **Production-Ready Component Library** | 14+ modular React 19 + Tailwind + Framer Motion components (Navbars, Bento, Aurora, 3D Tilt, Marquee, Tabs, Pricing, Footers). | `list_templates`, `get_template` |
| 🎨 **High-Contrast Design Systems** | 7 elite design systems (Obsidian Linear, Cosmic Violet, Cyber Emerald, Swiss Editorial Light, Nordic Minimal, Luxe Monochrome, Midnight Amber). | `get_design_system`, `list_design_systems` |
| ⚡ **Motion Physics & Lenis Scroll** | Calibrated spring parameters (`stiffness: 170, damping: 26`), 3D tilt, canvas particle constellation, and GSAP pinned scroll. | `get_animation_snippet` |
| 🔍 **HD Forensic URL Inspector** | Enters any live website with Playwright, automatically removes cookie banners, smoothly scrolls to trigger lazy animations, and takes Retina 2x screenshots. | `inspect_url_hd` |
| 🎬 **Video Motion Choreography** | Decoupled video motion analyzer to extract easing curves, spring physics, and timeline choreography from reference recordings. | `analyze_video_reference` |
| 🖼️ **Offline Visual Gallery** | Standalone high-speed offline HTML gallery with video preview on card hover and modal player. | `npm run gallery` |

---

## 📦 Installation & Setup

### 1. Prerequisites
- **Node.js**: v18.0.0 or higher
- **npm** or **pnpm**

```bash
# Clone or navigate to the directory
cd path/to/motion-design-mcp

# Install dependencies
npm install

# (Optional) Install Playwright Chromium for HD forensic inspection
npx playwright install chromium
```

---

### 2. Configure with your AI Client

#### 🤖 Claude Code (CLI)
Add to your global `~/.claude.json` or run:
```bash
claude mcp add motion-design node /absolute/path/to/motion-design-mcp/index.js
```

Or manually in `~/.claude.json`:
```json
{
  "mcpServers": {
    "motion_design": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/motion-design-mcp/index.js"]
    }
  }
}
```

#### 🖥️ Claude Desktop
Add to `claude_desktop_config.json` (under `%APPDATA%\Claude` on Windows or `~/Library/Application Support/Claude` on macOS):
```json
{
  "mcpServers": {
    "motion-design": {
      "command": "node",
      "args": ["/absolute/path/to/motion-design-mcp/index.js"]
    }
  }
}
```

#### ⚡ Cursor & Windsurf
Add to `.cursor/mcp.json` in your project or global configuration:
```json
{
  "mcpServers": {
    "motion-design": {
      "command": "node",
      "args": ["/absolute/path/to/motion-design-mcp/index.js"]
    }
  }
}
```

---

## 🎨 Available Design Systems

1. **Obsidian Linear**: Deep obsidian black (`#030712`), ultra-subtle borders (`rgba(255,255,255,0.08)`), electric blue/violet glows, Geist Sans font (`-0.035em` tracking).
2. **Cosmic Violet (MotionSites Standard)**: Deep space midnight (`#070414`), magenta highlights, liquid glassmorphism, Syne font.
3. **Cyber Emerald**: Deep slate (`#06090e`), matrix emerald glows (`#10b981`), technical monospace badges, Space Grotesk.
4. **Swiss Editorial Light**: Architectural light mode (`#f8f9fa`), pure contrast, vermilion red accents (`#ef4444`), General Sans.
5. **Nordic Minimal Warm Light**: Alabaster and warm oat paper tones (`#f7f6f2`), sage forest accents, Playfair Display.
6. **Luxe Monochrome**: Stark pure black (`#000000`), titanium textures, subtle specular highlights, Apple/Raycast minimalism.
7. **Midnight Amber**: Charcoal slate (`#08090c`), warm amber/gold glows, Instrument Sans + Newsreader serif contrast.

---

## 🧩 Component Templates Catalog

- **`floating-navbar`**: Glassmorphic floating pill navbar with spring active indicator and responsive mobile drawer.
- **`aurora-hero`**: High-impact Hero with ambient blur mesh gradients, status ping badge, and negative tracking typography.
- **`split-showcase-hero`**: Two-column layout with high-converting copy on the left and 3D glass telemetry mockup on the right.
- **`editorial-typography-hero`**: High-contrast editorial hero with mixed serif and sans-serif titles and live ticker.
- **`interactive-bento`**: Multi-span CSS grid where every card has a dynamic gradient spotlight following cursor coordinates.
- **`animated-tabs-feature`**: Feature switcher with Framer Motion `layoutId` sliding pill and smooth content crossfade.
- **`process-timeline-cards`**: Sequential progress timeline (01, 02, 03) with glowing connection line.
- **`infinite-marquee`**: Seamless infinite dual-row ticker with pause on hover.
- **`interactive-card-3d`**: Mouse tilt card with 3D perspective and specular light reflection.
- **`testimonial-masonry`**: Staggered review cards with star ratings and avatar badges.
- **`lamp-cta`**: Focused conversion section with downward conical light beam and magnetic button.
- **`pricing-cards`**: Tiered pricing grid with monthly/annual billing switch and highlighted popular tier.
- **`faq-accordion`**: Clean animated disclosure list with smooth height expansion.
- **`obsidian-footer`**: Deep dark footer with sitemap, newsletter signup, and live system status ping.
- **`three-particle-canvas`**: Zero-dependency interactive constellation canvas reacting to cursor distance.
- **`gsap-scroll-pinned`**: GSAP ScrollTrigger section that pins the viewport and scrubs horizontal panels.

---

## 🖼️ MotionSites 328 Vault & Offline Gallery

The MCP includes the full catalog of **328 MotionSites prompts** enriched with technical descriptions and verified CDN media previews.

To launch the standalone visual gallery:
```bash
npm run gallery
```
Or open `vault/gallery.html` directly in any web browser.

---

## 🛠️ Typical AI Prompts to Try

- *"Use `generate_blueprint` for a high-end Fintech B2B SaaS platform and build the complete landing page using the Obsidian Linear design system."*
- *"Search the vault for an interactive 3D Hero section and adapt its master prompt for my creative agency."*
- *"Inspect `https://linear.app` with `inspect_url_hd` and extract its typography, colors, and layout structure."*
- *"Combine `floating-navbar`, `interactive-bento`, and `lamp-cta` to build a production-ready Next.js page."*

---

## 📄 License
MIT © 2026 MotionDesign Engineering.