# 🎨 Canva MCP Server

[![CI](https://github.com/elisbanpaco/mcp-canva-gemini-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/elisbanpaco/mcp-canva-gemini-cli/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![NPM Version](https://img.shields.io/npm/v/@elisbanpaco/mcp-canva-gemini-cli.svg)](https://www.npmjs.com/package/@elisbanpaco/mcp-canva-gemini-cli)
[![MCP Standard](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol-purple.svg)](https://modelcontextprotocol.io)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![Tested with Vitest](https://img.shields.io/badge/Tested%20with-Vitest-yellow.svg)](https://vitest.dev/)

Conecta tus asistentes de IA (**Google Antigravity, Gemini CLI, Claude Desktop, Cursor**) directamente con tu cuenta de **Canva** a través de la API oficial (**Canva Connect API**). Crea, busca, exporta y sube diseños mediante lenguaje natural.

---

## ⚡ Inicio Rápido (Quickstart)

### 1. Configuración Directa vía `npx`

Puedes ejecutarlo directamente con `npx` sin necesidad de clonar el repositorio:

#### 🤖 Google Antigravity / Gemini CLI (`~/.gemini/config/mcp_config.json`)
```json
{
  "mcpServers": {
    "canva": {
      "command": "npx",
      "args": ["-y", "--package", "@elisbanpaco/mcp-canva-gemini-cli", "mcp-canva"],
      "env": {
        "CANVA_CLIENT_ID": "tu_client_id",
        "CANVA_CLIENT_SECRET": "tu_client_secret"
      }
    }
  }
}
```

#### 🟣 Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "canva": {
      "command": "npx",
      "args": ["-y", "--package", "@elisbanpaco/mcp-canva-gemini-cli", "mcp-canva"],
      "env": {
        "CANVA_CLIENT_ID": "tu_client_id",
        "CANVA_CLIENT_SECRET": "tu_client_secret"
      }
    }
  }
}
```

#### 💻 Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "canva": {
      "command": "npx",
      "args": ["-y", "--package", "@elisbanpaco/mcp-canva-gemini-cli", "mcp-canva"],
      "env": {
        "CANVA_CLIENT_ID": "tu_client_id",
        "CANVA_CLIENT_SECRET": "tu_client_secret"
      }
    }
  }
}
```

---

## 🧰 Herramientas Disponibles

Una vez conectado, puedes pedirle a tu IA:

| Herramienta | ¿Qué hace? | Ejemplo de Prompt |
| :--- | :--- | :--- |
| `canva_list_designs` | Lista tus diseños recientes con miniaturas y enlaces de edición. | *"Muéstrame mis presentaciones recientes en Canva"* |
| `canva_get_design` | Obtiene los detalles, páginas y URLs de un diseño por su ID. | *"Dame la información del diseño con ID DAHKDKZXFcQ"* |
| `canva_create_design` | Crea un diseño nuevo (presentación, documento, post de Instagram, etc.). | *"Crea un post de Instagram en Canva titulado Lanzamiento 2026"* |
| `canva_export_design` | Exporta un diseño a PNG, JPG, PDF o PPTX y te da el link de descarga. | *"Exporta mi presentación a formato PDF"* |
| `canva_list_folders` | Explora el contenido de tu carpeta raíz de Canva. | *"¿Qué elementos tengo en mi carpeta principal de Canva?"* |
| `canva_list_folder_items` | Lista los elementos dentro de una carpeta específica. | *"Muéstrame los archivos dentro de la carpeta con ID X"* |
| `canva_create_folder` | Crea una nueva carpeta en tu Canva. | *"Crea una carpeta llamada Proyectos 2026"* |
| `canva_upload_asset` | Sube una imagen local de tu computadora a Canva. | *"Sube la imagen ./banner.png a mi cuenta de Canva"* |
| `canva_get_auth_status` | Verifica el estado de conexión y validez de los tokens. | *"Revisa si mi conexión con Canva está activa"* |

---

## 🔑 Configuración Inicial de Credenciales

1. Entra a [Canva Developers](https://www.canva.com/developers/) y haz clic en **`Your integrations`**.
2. Haz clic en **`Create an integration`** $\rightarrow$ Elige **`Public`**.
   
   ![Crear Integración Canva](./assets/configure_integracion.png)

3. En **`Credentials`**, copia tu **Client ID** y genera tu **Client Secret**.
4. En **`Scopes`**, activa los permisos (son los únicos compatibles):
   * `design:content:read`, `design:content:write`, `design:meta:read`
   * `asset:read`, `asset:write`, `folder:read`, `folder:write`, `app:read`
   
   ![Configuración de Scopes en Canva](./assets/scopes.png)

5. En **`Authentication`**, agrega la URL de redirección exacta:
   `http://127.0.0.1:3000/callback`
   
   ![Añadir URL de Redirect](./assets/auth-url-add.png)

### Autenticación (Solo la primera vez)

Como Canva exige credenciales por usuario, abre tu terminal y ejecuta esto para autenticarte y guardar los tokens de forma segura:

```bash
# En Linux/macOS
export CANVA_CLIENT_ID="tu_client_id"
export CANVA_CLIENT_SECRET="tu_client_secret"
npx -p @elisbanpaco/mcp-canva-gemini-cli mcp-canva-auth

# En Windows (PowerShell)
$env:CANVA_CLIENT_ID="tu_client_id"
$env:CANVA_CLIENT_SECRET="tu_client_secret"
npx -p @elisbanpaco/mcp-canva-gemini-cli mcp-canva-auth
```

Se abrirá tu navegador para confirmar. ¡Listo! Tus tokens se guardarán con permisos `0600` en tu sistema operativo.

---

## 🏗️ Arquitectura y Seguridad

```mermaid
sequenceDiagram
    autonumber
    actor User as Usuario / Asistente IA
    participant MCP as Canva MCP Server (Stdio)
    participant Vault as Bóveda de Tokens (~/.config/canva-mcp)
    participant CanvaOAuth as Canva OAuth2 (PKCE S256)
    participant CanvaAPI as Canva Connect API (REST v1)

    Note over User,CanvaAPI: 1. Flujo de Autenticación (pnpm auth)
    MCP->>CanvaOAuth: Inicia flujo PKCE con desafío SHA-256
    CanvaOAuth-->>MCP: Redirección con Código de Autorización
    MCP->>CanvaOAuth: Intercambio de código por Tokens de acceso
    CanvaOAuth-->>MCP: Access Token + Refresh Token
    MCP->>Vault: Guarda en almacenamiento seguro (Permisos 0600)

    Note over User,CanvaAPI: 2. Ejecución de Herramientas en Tiempo Real
    User->>MCP: Llama a herramienta (ej. canva_list_designs)
    MCP->>Vault: Carga token válido (Auto-renovación con Mutex)
    MCP->>CanvaAPI: Petición HTTP Bearer con Exponential Backoff
    CanvaAPI-->>MCP: Respuesta JSON con metadatos y URLs
    MCP-->>User: Resultado estructurado
```

### Características de Ingeniería:
* 🔐 **Bóveda OS Segura**: Los tokens se guardan en el directorio del sistema (`~/.config/canva-mcp/` en Linux/Mac o `%APPDATA%\canva-mcp` en Windows) con permisos POSIX `0600` (solo legibles por tu usuario).
* ⚡ **Mutex Anticolisiones**: Previene condiciones de carrera cuando el modelo ejecuta múltiples herramientas en paralelo durante la renovación del token.
* 🛡️ **Exponential Backoff**: Reintentos automáticos con retroceso exponencial ante límites de tasa (`HTTP 429`) y caídas temporales (`5xx`).
* 🧪 **100% Test Coverage**: Suite completa de pruebas unitarias con Vitest.

---

## 🧪 Pruebas y Desarrollo

```bash
# Ejecutar suite de pruebas unitarias
pnpm test

# Verificación estricta de tipos TypeScript
pnpm typecheck

# Compilar paquete de producción
pnpm build
```

---

## 📄 Licencia

Este proyecto está bajo la licencia **MIT**. Consulta el archivo [LICENSE](LICENSE) para más detalles.