# CollectUI MCP Server (`collectui-mcp`)

Servidor oficial del **Model Context Protocol (MCP)** adaptado para **[Collect UI](https://collectui.com/designs/mobile-app-ui-design-inspiration)**, enfocado en el descubrimiento, exploración e inspección de interfaces de aplicaciones móviles, microinteracciones, animaciones y flujos UX/UI.

---

## ⚡ ¿Por qué esta arquitectura?

A diferencia de otros servidores MCP de diseño que levantan navegadores *headless* pesados (como Chromium con Playwright) consumiendo más de 500 MB de RAM y demorando hasta 8 segundos por consulta:

- **Cero Navegadores Headless:** Se comunica de forma directa y nativa con el backend público de Supabase PostgREST de Collect UI.
- **Ultra Ligero y Rápido:** Tiempos de respuesta de **< 150 ms** con un consumo de memoria mínimo (~30 MB).
- **Recursos Multimedia Directos:** Devuelve enlaces directos a videos MP4 optimizados en CDN de CloudFront (hasta 1080p) y miniaturas WebP/JPG.
- **Filtro Táctico por Taxonomía:** Acceso a más de 215 categorías organizadas (`mobile-app`, `onboarding`, `stamp`, `ui-interaction`, `widget`, `card`, `calendar`, etc.).

---

## 🛠️ Herramientas Disponibles

### 1. `search_mobile_designs`
Busca diseños de interfaces y animaciones móviles en Collect UI.
- **Argumentos:**
  - `query` *(opcional, string)*: Término de búsqueda en el título (ej: `"travel"`, `"dating"`, `"wallet"`, `"onboarding"`, `"cards"`).
  - `category` *(opcional, string, por defecto: `"mobile-app"`)*: Categoría slug de filtrado (ej: `"mobile-app"`, `"stamp"`, `"ui-interaction"`, `"onboarding"`, `"widget"`).
  - `limit` *(opcional, number, por defecto: 10, máx: 50)*: Cantidad de resultados por página.
  - `offset` *(opcional, number, por defecto: 0)*: Paginación.
  - `sort_by` *(opcional, `"order"` | `"published_at"`)*: Criterio de ordenación.
- **Retorna:** Títulos, identificadores UUID, enlaces directos a videos MP4 en CDN, miniaturas y metadatos del autor.

### 2. `list_categories`
Devuelve el listado completo de las 215 categorías disponibles con sus slugs y grupos para afinar búsquedas tácticas.

### 3. `get_design_details`
Obtiene la ficha técnica completa de una publicación por su UUID:
- Enlaces a variantes de video MP4 en múltiples resoluciones (desde 320p hasta 1080p).
- Tasa de bits (*bitrate*), duración en milisegundos y proporción de aspecto.
- Datos del diseñador (nombre, biografía, seguidores, enlace a X/Twitter).
- Póster estático y miniaturas.

### 4. `get_random_inspiration`
Genera una muestra aleatoria de diseños móviles curados para romper bloqueos creativos y sugerir nuevas ideas de componentes o animaciones.

---

## 🚀 Instalación y Uso

### Requisitos
- Node.js 18.0 o superior.

### Instalación local
```bash
git clone https://github.com/choterifa/collectui-mcp.git
cd collectui-mcp
npm install
npm run build
```

Para probar la suite de verificación integrada:
```bash
npm test
```

---

## ⚙️ Configuración en Clientes MCP

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

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "collectui": {
      "command": "node",
      "args": ["/ruta/absoluta/a/collectui-mcp/dist/index.js"]
    }
  }
}
```

### Antigravity / Gemini CLI
Puedes invocar el comando directamente especificando el ejecutable `node` o configurándolo en tu directorio de servidores MCP.

---

## 🧪 Pruebas Automatizadas

El proyecto incluye pruebas integradas de conectividad, consulta de taxonomía, búsqueda por categoría/texto, obtención de metadatos y transporte stdio:

```bash
npm test
```

---

## 📄 Licencia

Distribuido bajo la Licencia **MIT**. Consulta el archivo `LICENSE` para más detalles.