# <img src="https://api.iconify.design/simple-icons:javascript.svg?color=%23ffffff" width="28" height="28" align="center" /> GSAP MCP Server (Model Context Protocol)

GSAP MCP Server adalah server MCP lokal & global yang dirancang khusus untuk mempermudah AI Agent (seperti OpenCode, Claude Code, Cursor, dll.) dalam membuat kode animasi **GSAP v3**, mencari dokumentasi, memvalidasi sintaks selektor CSS, dan memberikan panduan praktik terbaik (*best practices*).

---

## <img src="https://api.iconify.design/lucide:star.svg?color=%23ffffff" width="22" height="22" align="center" /> Fitur Utama

- **Pencarian Dokumentasi Hibrida**: Pencarian dokumentasi instan secara offline dan fallback pencarian realtime (*live fetch*) langsung ke situs resmi [gsap.com](https://gsap.com/docs/v3/).
- **Generasi Kode Animasi**: Menghasilkan kode GSAP untuk `to`, `from`, `fromTo`, `timeline`, `stagger`, dan `scrollTrigger`.
- **Validasi Selektor CSS**: Memeriksa potensi bug sintaksis selector DOM dan masalah kompatibilitas *cross-browser* (seperti `:has()` atau kurung unclosed).
- **Panduan Best Practices & Debugging**: Pembantu otomatis untuk mengatasi masalah animasi seperti animasi tidak jalan, ScrollTrigger macet, atau optimasi React/Vue/Svelte.
- **Efisiensi Token AI**: Output teks yang sudah disanitasi dari HTML junk tag (`<nav>`, `<style>`, `<script>`) untuk menghemat context window AI.

---

## <img src="https://api.iconify.design/lucide:cpu.svg?color=%23ffffff" width="22" height="22" align="center" /> Stack Teknologi

- **Runtime**: Node.js (v18.0.0+) ES Modules
- **Protocol**: `@modelcontextprotocol/sdk` (StdioServerTransport)
- **Validation**: `zod` v3

---

## <img src="https://api.iconify.design/lucide:package.svg?color=%23ffffff" width="22" height="22" align="center" /> Cara Instalasi & Konfigurasi

### 1. Instalasi Dependensi Lokal
```bash
git clone https://github.com/itzd-dev/gsap-mcp.git
cd gsap-mcp
npm install
```

### 2. Konfigurasi Global di OpenCode
Tambahkan konfigurasi berikut ke file konfigurasi global OpenCode Anda di `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gsap": {
      "type": "local",
      "command": [
        "node",
        "/Users/odi/Documents/gsap-mcp/src/index.js"
      ],
      "enabled": true
    }
  }
}
```

### 3. Konfigurasi di Antigravity IDE / Claude Desktop
Tambahkan ke konfigurasi MCP Server Antigravity IDE (`mcp_config.json`):

```json
{
  "mcpServers": {
    "gsap": {
      "command": "node",
      "args": [
        "/Users/odi/Documents/gsap-mcp/src/index.js"
      ]
    }
  }
}
```

---

## <img src="https://api.iconify.design/lucide:wrench.svg?color=%23ffffff" width="22" height="22" align="center" /> Daftar Tools MCP (10 Tools)

| Tool | Deskripsi | Argumen Utama |
| :--- | :--- | :--- |
| `generate-animation` | Menghasilkan kode animasi GSAP presisi. | `type`, `target`, `duration`, `props`, `scrollTrigger`, `stagger`, `ease` |
| `validate-target` | Memvalidasi sintaks CSS selector sebelum animasi dibuat. | `target` (string selector) |
| `search` | Mencari dokumentasi GSAP v3 offline di memori lokal. | `query`, `category`, `limit` |
| `fetch-live-docs` | Mengambil dokumentasi realtime dari situs web resmi GSAP. | `path`, `maxCharacters` |
| `api` | Mendapatkan referensi API detail untuk metode/properti GSAP. | `name`, `includeExamples` |
| `best-practices` | Mengambil panduan praktik terbaik (performa, React, ScrollTrigger). | `topic` |
| `debug` | Memberikan solusi untuk masalah animasi yang sering terjadi. | `issue`, `context` |
| `setup` | Menghasilkan kode boilerplate setup GSAP per framework. | `framework`, `features` |
| `plugins` | Menampilkan daftar seluruh plugin GSAP (Free & Club). | `filter` |
| `easing` | Referensi lengkap fungsi easing GSAP beserta deskripsinya. | `type` |

---

## <img src="https://api.iconify.design/lucide:flask-conical.svg?color=%23ffffff" width="22" height="22" align="center" /> Pengujian & Verifikasi (Test Suite)

Server ini dilengkapi dengan test suite otomatis untuk memverifikasi keabsahan sintaksis dan tool handler.

Jalankan perintah pengujian:
```bash
npm test
```

**Output Pengujian:**
```text
📊 TEST SUMMARY
✅ Tools: 10/10
✅ Helpers: 12/12
✅ Imports: OK
🎉 ALL TESTS PASSED! Server ready to use.
```

---

## <img src="https://api.iconify.design/lucide:file-text.svg?color=%23ffffff" width="22" height="22" align="center" /> Lisensi

MIT License - Bebas digunakan dan dikembangkan untuk proyek komersial maupun non-komersial.