# ⚡ Ultimate GSAP Master MCP Server

The **Ultimate GSAP Master MCP Server** is a high-performance Model Context Protocol (MCP) implementation that grants AI models (like Claude) "surgical precision" over the GreenSock Animation Platform (GSAP). 

It transforms natural language animation requests into production-ready, 60fps-optimized code. Whether you need a complex scroll-triggered sequence, character-by-character text reveals, or physics-based Draggable interfaces, this server provides the expert-level knowledge and implementation logic required.

## ✨ Features

- **🧠 Advanced Intent Analysis**: Understands complex natural language requests (e.g., *"Make these cards fade in one by one with a slight bounce when they hit the middle of the screen"*).
- **🚀 Production-Ready Code**: Generates code with GPU acceleration (`force3D`), memory management (`clearProps`), and proper framework lifecycle handling (React `useGSAP`, cleanup, etc.).
- **📚 Complete API Database**: Deep knowledge of every core method, easing function, and plugin (ScrollTrigger, SplitText, MorphSVG, DrawSVG, etc.).
- **🔧 Performance Optimization**: Automatically refactors laggy animations into high-performance 60fps sequences.
- **🛠️ Expert Debugging**: Analyzes code snippets for layout thrashing, missing plugin registrations, or logic errors.
- **🎁 All Plugins Included**: Knowledge base updated for the GSAP era where **SplitText, MorphSVG, and DrawSVG are now free.**
- **🧈 Lenis Smooth Scrolling**: Built-in support for Lenis integration with ScrollTrigger, including setup, React hooks, and best practices.

## 🛠 Tools Included

| Tool | Description |
| :--- | :--- |
| `understand_and_create_animation` | **The flagship tool.** Converts any animation idea into fully functional GSAP code. |
| `get_gsap_api_expert` | Provides deep technical documentation and examples for any GSAP method or plugin. |
| `generate_complete_setup` | Generates boilerplate for React, Next.js, Vue, or Vanilla, including plugin registration. |
| `debug_animation_issue` | Identifies and fixes bugs, performance bottlenecks, and logic errors. |
| `optimize_for_performance` | Refactors existing GSAP code to ensure 60fps smoothness and GPU acceleration. |
| `create_production_pattern` | Generates battle-tested patterns like Hero sequences, loading screens, and scroll systems. |

## 🚀 Installation & Setup

Since this package is published as `@vinhnguyen/gsap-mcp`, you can use `npx` to run it without manual installation.

### 1. Claude Desktop Configuration
Open your Claude Desktop configuration file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

### 2. Add the Server
Add the following entry to the `mcpServers` section:

```json
{
  "mcpServers": {
    "gsap-master": {
      "command": "npx",
      "args": [
        "-y",
        "@vinhnguyen/gsap-mcp"
      ]
    }
  }
}
```

### 3. Restart Claude
Restart the Claude Desktop application, and you will see a ⚡ icon indicating the GSAP Master tools are ready to use.

### Continue.dev (VS Code Extension)

Add the following to your `~/.continue/config.yaml`:

```yaml
mcpServers:
  - name: gsap-mcp
    command: npx
    args:
      - "-y"
      - "@vinhnguyen/gsap-mcp"
```

## 📖 Usage Examples

### 1. Natural Language Creation
**User:** *"I want a hero section where the title letters pop up randomly, and then the subtitle slides in from the left once the title is finished."*

**AI (using `understand_and_create_animation`):** Will generate a `gsap.timeline()` using `SplitText` for the characters, applying a `back.out` ease and a staggered random start time, followed by the subtitle animation.

### 2. Performance Refactoring
**User:** *"My scroll animation is laggy on mobile. Here is the code: [code snippet animating `top` and `left` properties]."*

**AI (using `optimize_for_performance`):** Will refactor the code to use `x` and `y` (transforms), add `force3D: true`, and implement `ScrollTrigger.batch` for better performance.

### 3. Setup Generation
**User:** *"Set up a new Next.js project with ScrollTrigger and SplitText."*

**AI (using `generate_complete_setup`):** Will provide the terminal commands for installation, the `gsap.registerPlugin` boilerplate, and a `useGSAP` wrapper for your components.

## 📈 Performance Standards

Every piece of code generated by this server adheres to the following standards:
- **GPU Acceleration**: Uses `x`, `y`, `scale`, and `rotation` instead of layout properties (`top`, `width`, `height`).
- **Memory Management**: Includes `clearProps` and proper cleanup in framework hooks.
- **Reduced Motion**: Respects `prefers-reduced-motion` media queries.
- **Efficiency**: Uses GSAP's internal ticker and optimized batching for scroll events.

## 📄 License
MIT

---
*Created by Vinh Nguyen - Powered by GSAP Surgical Precision.* ⚡