# MCP Anime.js v4 Expert Server 🚀

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-1.6.1-green.svg)](https://modelcontextprotocol.io/)
[![Tests](https://img.shields.io/badge/Tests-395%20Passing-brightgreen.svg)](tests/validator.test.ts)

Servidor oficial para el **Model Context Protocol (MCP)** diseñado para asistir a desarrolladores e Inteligencias Artificiales en el uso correcto, moderno y optimizado de **Anime.js v4**.

Cuenta con una cobertura completa del 100% de la documentación técnica oficial de Anime.js v4, 389 módulos de catálogo técnico, más de 70.000 líneas de conocimiento indexado y 395 pruebas automatizadas.

---

## ✨ Características Principales

1. **Auditoría y Validación AST en tiempo real (`validate_anime_code`)**:
   - **Detección de sintaxis v3 obsoleta**: `anime({ targets })`, `anime.timeline()`, `begin`, `update`, `complete`, etc., con sugerencias automáticas de reemplazo hacia v4 (`animate()`, `createTimeline()`, callbacks `onBegin`, `onUpdate`, etc.).
   - **Optimización de Rendimiento**: Alerta sobre propiedades causantes de *Reflow / Layout Thrashing* (`top`, `left`, `width`, `height`) y recomienda transformaciones GPU aceleradas (`x`, `y`, `scale`, `rotate`).
   - **Detección de Fugas de Memoria**: Advierte en componentes React/Vue si falta la reversión (`scope.revert()` o `timer.revert()`).
   - **Soporte Completo del Adaptador Three.js**: Valida conversión automática de grados en `rotation`/`skew`, partición de ejes vectoriales (`normalScaleX/Y`), soporte TSL NodeMaterial, bare UniformNodes, y advertencias pedagógicas sobre materiales compartidos, targets `Group` y tipos de uniformes fuera de alcance (`Matrix`, `Texture`).
   - **Score de Salud (0-100)**: Proporciona diagnósticos con nivel de severidad (`error`, `warning`, `info`) y código de sugerencia (`fixSuggestion`).

2. **Base Documental Exhaustiva y Búsqueda Semántica (`search_anime_docs`)**:
   - Más de 70.000 líneas documentales con especificaciones técnicas detalladas y snippets oficiales canónicos.
   - Búsqueda difusa y semántica por conceptos: `spring`, `stagger`, `timeline`, `waapi`, `threejs`, `layout`, `flip`, `scope`, `timeUnit`, etc.

3. **Catálogo de Parámetros del Motor (`get_parameter_details`)**:
   - Información técnica profunda sobre todos los parámetros de animación, reproducción, temporizadores y motor global (`engine.defaults`, `engine.speed`, `engine.fps`, `engine.timeUnit`).

4. **Guías Oficiales Integradas**:
   - **Migración v3 ➡️ v4 (`get_migration_guide`)**: 23 reglas de migración con tabla de equivalencias y ejemplos de antes/después.
   - **Instalación (`get_installation_guide`)**: Recomendación prioritaria de Bun (`bun add animejs`), además de NPM, PNPM, CDN ESM/UMD y descargas GitHub.
   - **Subrutas Granulares (`get_subpaths_directory`)**: 14 subpaths oficiales (`animejs/animation`, `timer`, `timeline`, `adapters/three`, `waapi`, `layout`, etc.) con generador de `<script type="importmap">`.

5. **Recursos MCP (`animejs://v4/...`)**:
   - Más de 100 recursos URI Markdown para lectura directa de guías de animación, temporizadores, layouts FLIP, física inercial de arrastre, SVG motion path, Web Animations API y Three.js.

---

## 🛠️ Herramientas Disponibles (Tools)

| Herramienta | Descripción |
| :--- | :--- |
| `validate_anime_code` | Analiza código JavaScript/TypeScript/JSX y emite diagnóstico AST con puntaje de salud (0-100), advertencias y sugerencias automáticas. |
| `search_anime_docs` | Motor de búsqueda documental y catálogo semántico en toda la base de conocimientos oficial. |
| `get_parameter_details` | Especificación técnica, tipos, valores válidos, defaults y avisos de reflow de cualquier parámetro. |
| `get_migration_guide` | Catálogo de las 23 reglas de migración oficiales de Anime.js v3 a v4 con ejemplos de equivalencia. |
| `get_installation_guide` | Guía de instalación y configuración en Bun, NPM, PNPM, CDN y browsers modernos. |
| `get_subpaths_directory` | Directorio de las 14 subrutas granulares para Tree Shaking e Import Maps nativos. |

---

## 🔌 Configuración en Clientes MCP

### 1. Claude Desktop
Añade a tu archivo de configuración `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "animejs-v4": {
      "command": "npx",
      "args": ["-y", "github:Padalogu/mcp-animejs-v4"]
    }
  }
}
```

*O apuntando a tu clon local:*
```json
{
  "mcpServers": {
    "animejs-v4": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp-animejs-v4/dist/index.js"]
    }
  }
}
```

### 2. Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "animejs-v4": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp-animejs-v4/dist/index.js"]
    }
  }
}
```

### 3. Antigravity / Gemini CLI (`~/.gemini/config/mcp_config.json`)
```json
{
  "mcpServers": {
    "animejs-v4": {
      "command": "node",
      "args": [
        "/home/padalogu/Proyectos/Padavertex/mcp-animejs-v4/dist/index.js"
      ]
    }
  }
}
```

### 4. Instalación Global CLI
```bash
git clone https://github.com/Padalogu/mcp-animejs-v4.git
cd mcp-animejs-v4
npm install
npm run build
npm link
```
Ahora puedes ejecutar el servidor directamente en la terminal o integrarlo como:
```bash
mcp-animejs-v4
```

---

## 🧪 Pruebas Automatizadas

El proyecto cuenta con una suite completa de **395 pruebas automatizadas** que validan la exactitud de los diagnósticos AST, snippets oficiales y catálogo:

```bash
# Ejecutar la suite completa de 395 pruebas
npm test

# Compilar TypeScript
npm run build
```

---

## 📄 Licencia

MIT © [Padalogu](https://github.com/Padalogu)