# Canva MCP Server

Servidor MCP base para orquestar la creacion de presentaciones en Canva con un enfoque hibrido:

- planeacion narrativa con LLM
- composicion estructurada por slides
- integracion con Canva por API oficial donde exista soporte
- capa opcional de automatizacion web para cerrar huecos operativos

## Objetivo

Este proyecto no intenta "hacer clics al azar" en Canva. La meta es traducir instrucciones de alto nivel a operaciones controladas como:

- crear un deck desde un brief
- aplicar branding
- rellenar placeholders
- insertar imagenes y graficos
- reordenar slides
- exportar el resultado

## Estructura

- [docs/architecture.md](docs/architecture.md): arquitectura propuesta
- [docs/tools.md](docs/tools.md): catalogo exacto de tools MCP
- [src/index.js](src/index.js): servidor MCP con tools reales y fallback controlado
- [src/planner.js](src/planner.js): planner determinista para briefs
- [src/smoke-tests.js](src/smoke-tests.js): prueba real de create/export
- [src/markdown-deck.js](src/markdown-deck.js): generacion de decks `.pptx` desde markdown

## Variables de entorno

Duplica [ .env.example ](.env.example) en tu `.env` real y completa al menos:

- `CANVA_CLIENT_ID`
- `CANVA_CLIENT_SECRET`
- `CANVA_REDIRECT_URI`
- `OPENAI_API_KEY`
- `CANVA_ACCESS_TOKEN`
- `CANVA_TEAM_ID`
- `CANVA_BRAND_TEMPLATE_ID`

Para la integracion real ya implementada en el scaffold, el token debe tener scopes compatibles con:

- `design:content:write` para crear disenos
- `design:content:read` para exportarlos
- `design:meta:read` para consultar jobs de autofill
- `folder:read` para listar presentaciones
- `brandtemplate:meta:read` y `brandtemplate:content:read` para brand templates y autofill

El import de `.pptx` a Canva usa tambien `design:content:write`.

## Instalacion

```bash
npm install
```

## Ejecucion

```bash
npm start
```

## Smoke test

```bash
npm run smoke
```

Ejecuta una prueba real de `create_presentation` y `export_presentation` con el token configurado.

## Siguiente integracion real

1. Implementar `DeckPlanner` para generar outline y contenido por slide.
2. Añadir `AssetPipeline` para imagenes, iconos y graficos.
3. Completar mutaciones de slides cuando la API o el fallback de navegador lo requieran.
4. Añadir `BrowserAutomationAdapter` solo para acciones no cubiertas por API.

## Estado actual

Ya hay integracion real para:

- `create_presentation`
- `export_presentation`
- `list_presentations`
- `list_brand_templates`
- `get_brand_template_dataset`
- `create_autofilled_presentation`
- `generate_presentation_from_brief`
- `create_presentation_outline`
- `create_markdown_presentation`
- `get_import_job`

La exportacion puede devolver el job inmediatamente o esperar a que termine haciendo polling del estado del export job.

Si quieres usar las tools nuevas de carpetas y brand templates, actualiza `CANVA_SCOPES` y vuelve a autorizar la integracion para obtener un token con esos scopes.

Si quieres generar un deck completo y bonito sin depender de brand templates, usa `create_markdown_presentation`: genera un `.pptx` estilizado y lo importa a Canva como una presentacion editable.

## Como obtener el access token de Canva

Canva Connect usa OAuth 2.0 con Authorization Code + PKCE. Eso significa que en el Developer Portal normalmente no veras un `access_token` listo para copiar. Lo que si ves es:

- `Client ID`
- `Client Secret`
- scopes
- redirect URL

Con eso debes generar el token.

### Paso 1

Completa en tu `.env`:

- `CANVA_CLIENT_ID`
- `CANVA_CLIENT_SECRET`
- `CANVA_REDIRECT_URI`
- `CANVA_SCOPES`

### Paso 2

Genera una URL de autorizacion:

```bash
npm run oauth:url
```

Ese comando imprime:

- `authorizationUrl`
- `state`

Ademas guarda localmente el `codeVerifier` y el `state` en un archivo temporal para que no tengas que copiarlos a mano.

Abre la `authorizationUrl` en tu navegador, autoriza la app y copia el valor `code` que Canva devolvera al `redirect_uri`.

### Paso 3

Intercambia el `code` por el token:

```bash
node src/oauth-helper.js exchange <authorization_code>
```

O pega directamente la URL completa de redireccionamiento:

```bash
node src/oauth-helper.js exchange-url "http://127.0.0.1:3001/oauth/redirect?code=...&state=..."
```

La respuesta devolvera:

- `access_token`
- `refresh_token`
- `expires_in`
- `scope`

### Paso 4

Copia el `access_token` a tu `.env` como `CANVA_ACCESS_TOKEN` y el `refresh_token` como `CANVA_REFRESH_TOKEN`.

Si quieres, luego puedo dejar automatizado tambien el refresco del token con `refresh_token`.