Canvelete

Plataforma API-first para optimización de imágenes y diseño de documentos. Genera imágenes optimizadas, PDFs y documentos a escala con nuestro editor visual y API REST.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Canvelete

MCP Badge

Servidor de Protocolo de Contexto de Modelo (MCP) para la plataforma de diseño Canvelete. Este servidor expone las capacidades de diseño de Canvelete a asistentes de IA y otros clientes compatibles con MCP, permitiendo la creación y manipulación programática de diseños.

🔗 Enlaces:

📚 Documentación del Servidor MCP:

Inicio Rápido

# Install globally
npm install -g @canveletedotcom/mcp-server

# Or use with npx (no installation needed)
npx -y @canveletedotcom/mcp-server start

Luego configura tu cliente MCP (Claude Desktop, Kiro, etc.) con:

{
  "mcpServers": {
    "canvelete-mcp-server": {
      "command": "canvelete-mcp",
      "args": ["start"],
      "env": {
        "CANVELETE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Características

Recursos (Acceso de Solo Lectura a Datos)

  • Diseños: Accede a diseños de usuarios, explora plantillas
  • Lienzo: Ve el estado del lienzo y sus elementos
  • Activos: Explora la biblioteca de activos del usuario y las fuentes disponibles
  • Usuario: Accede al perfil y preferencias
  • Metadatos: Capacidades completas de elementos, límites de estilo y documentación del sistema de diseño

Herramientas (Acciones)

  • Gestión de Diseños: Crear, actualizar, eliminar, duplicar y exportar diseños
  • Manipulación de Lienzo: Agregar, actualizar, eliminar elementos; redimensionar lienzo; limpiar lienzo
    • 13 Tipos de Elementos: rectángulo, círculo, texto, imagen, svg, línea, polígono, estrella, qr, código de barras, tabla, contenedor, bezier
    • Códigos QR: Genera códigos QR para URLs, vCards, WiFi y más
    • Códigos de Barras: Soporte para CODE128, EAN13, UPC y otros 7 formatos
  • Plantillas: Listar, aplicar y crear plantillas
  • Activos: Búsqueda integral de activos en múltiples fuentes
    • Pixabay: Más de 2.7M de fotos e ilustraciones gratuitas
    • Unsplash: Más de 3M de fotos curadas de alta calidad
    • Iconify: Más de 200K iconos de más de 150 conjuntos de iconos
    • Cliparts: Más de 10K gráficos clipart curados
    • Ilustraciones: Más de 5K ilustraciones artísticas
  • Fuentes: Más de 30 fuentes profesionales con metadatos y recomendaciones de combinación
  • Formas: Más de 70 formas SVG de 8 categorías (básicas, flechas, estrellas, llamadas, naturaleza, símbolos, geométricas, extra)
  • Integración de IA: Accede a Civi AI para generación de diseños

Prompts Disponibles

Los prompts proporcionan plantillas guiadas para tareas de diseño comunes:

  • create_social_post - Crea publicaciones para redes sociales (Instagram, Facebook, Twitter, etc.)
  • create_presentation_slide - Crea diapositivas de presentación con título y contenido
  • add_text_element - Agrega elementos de texto con estilo a los diseños

Los prompts ayudan a los asistentes de IA a crear diseños con estructura y estilo adecuados automáticamente.

Instalación

Método 1: Instalación Global (Recomendado)

Instala el paquete globalmente para usar el comando canvelete-mcp:

npm install -g @canveletedotcom/mcp-server

Método 2: NPX (Sin Instalación Requerida)

Usa npx para ejecutar sin instalar:

npx -y @canveletedotcom/mcp-server start

Método 3: Desarrollo Local

Para desarrollo o compilaciones personalizadas:

git clone https://github.com/canvelete/canvelete.git
cd canvelete/mcp-server
npm install
npm run build

Luego usa la ruta de compilación local en tu configuración de MCP.

Configuración

Variables de Entorno

Crea un archivo .env en el directorio del servidor MCP:

# Required: Canvelete API Key
CANVELETE_API_KEY =your_api_key_here

# Optional: Canvelete API URL (defaults to https://www.canvelete.com)
CANVELETE_API_URL=https://www.canvelete.com

# Optional: For AI generation features (if using Civi AI directly)
GEMINI_API_KEY=your_gemini_api_key

Autenticación

Necesitas una clave API de Canvelete para usar el servidor MCP:

  1. Inicia sesión en tu cuenta de Canvelete
  2. Ve a Configuración → Claves API
  3. Genera una nueva clave API
  4. Guarda la clave de forma segura

Para documentación detallada de la API, consulta docs.canvelete.com.

Puedes proporcionar la clave API de dos maneras:

Opción 1: Variable de Entorno (recomendada para Claude Desktop)

CANVELETE_API_KEY=your_api_key_here

Opción 2: Argumentos de Herramienta (para uso programático)

{
  "apiKey": "your_api_key_here",
  "name": "My Design"
}

Configuración

Claude Desktop

  1. Encuentra tu archivo de configuración de Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Agrega la configuración del servidor de Canvelete:

Opción A: Usando Instalación Global

{
  "mcpServers": {
    "canvelete-mcp-server": {
      "command": "canvelete-mcp",
      "args": ["start"],
      "env": {
        "CANVELETE_API_KEY": "your_api_key_here",
        "CANVELETE_API_URL": "https://www.canvelete.com"
      }
    }
  }
}

Opción B: Usando NPX (Sin Instalación)

{
  "mcpServers": {
    "canvelete-mcp-server": {
      "command": "npx",
      "args": ["-y", "@canveletedotcom/mcp-server", "start"],
      "env": {
        "CANVELETE_API_KEY": "your_api_key_here",
        "CANVELETE_API_URL": "https://www.canvelete.com"
      }
    }
  }
}

Opción C: Usando Compilación Local

{
  "mcpServers": {
    "canvelete-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.cjs", "start"],
      "env": {
        "CANVELETE_API_KEY": "your_api_key_here",
        "CANVELETE_API_URL": "https://www.canvelete.com"
      }
    }
  }
}
  1. Reinicia Claude Desktop

Kiro

  1. Encuentra tu archivo de configuración de Kiro: ~/.kiro/settings/mcp.json

  2. Agrega la misma configuración que arriba

  3. Reinicia Kiro

Otros Clientes MCP

Cualquier cliente compatible con MCP puede usar este servidor. Configúralo para ejecutar:

  • Comando: canvelete-mcp (si está instalado globalmente) o npx -y @canveletedotcom/mcp-server
  • Argumentos: ["start"]
  • Entorno: Establece CANVELETE_API_KEY y opcionalmente CANVELETE_API_URL

Ejemplos de Uso

Conversaciones de Ejemplo

Una vez configurado, puedes preguntarle a tu asistente de IA:

  • "¿Qué diseños tengo en Canvelete?"
  • "Crea un nuevo diseño de publicación de Instagram de 1080x1080 llamado 'Venta de Verano'"
  • "Agrega un elemento de texto al diseño {id} que diga 'Hola Mundo'"
  • "Exporta el diseño {id} como PNG"
  • "Lista todos mis activos subidos"
  • "Aplica la plantilla {template-id} al diseño {design-id}"
  • "Crea una diapositiva de presentación con el título 'Bienvenida' y el subtítulo 'Introducción'"
  • "Busca imágenes de stock de montañas"

Ejemplo Rápido: Crear una Publicación en Redes Sociales

// 1. Create a design
create_design({
  name: "Summer Sale Post",
  width: 1080,
  height: 1080
})

// 2. Add background
add_element({
  designId: "{design-id}",
  element: {
    type: "rectangle",
    x: 0, y: 0,
    width: 1080, height: 1080,
    fill: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
  }
})

// 3. Add text
add_element({
  designId: "{design-id}",
  element: {
    type: "text",
    text: "SUMMER SALE",
    x: 100, y: 400,
    width: 880, height: 150,
    fontSize: 96,
    fontFamily: "Poppins",
    fill: "#FFFFFF",
    fontWeight: "bold"
  }
})

// 4. Export
export_design({
  designId: "{design-id}",
  format: "png",
  quality: 100
})

Consulta EXAMPLES.md para ejemplos más detallados. Para documentación completa de la API, visita docs.canvelete.com.

Recursos Disponibles

Los recursos proporcionan acceso de solo lectura a los datos de Canvelete:

URIDescripción
canvelete://api/designs/listLista todos los diseños del usuario con paginación
canvelete://api/designs/templatesExplora plantillas de diseño públicas
canvelete://api/design/{id}Obtén información detallada sobre un diseño específico
canvelete://api/canvas/{designId}Obtén el estado actual del lienzo de un diseño
canvelete://api/canvas/{designId}/elementsObtén todos los elementos en el lienzo de un diseño
canvelete://api/assets/libraryActivos subidos por el usuario (imágenes, fuentes, etc.)
canvelete://api/assets/fontsLista de todas las fuentes disponibles para elementos de texto
canvelete://api/user/profilePerfil del usuario e información de suscripción
canvelete://api/user/preferencesPreferencias y configuración del editor del usuario
canvelete://api/metadata/schemaMetadatos del sistema, esquemas y definiciones de propiedades

Herramientas Disponibles

Herramientas de Gestión de Diseños

  • list_designs - Lista todos los diseños del usuario con paginación y búsqueda
  • get_design - Obtén información detallada del diseño incluyendo datos del lienzo
  • create_design - Crea un nuevo diseño con dimensiones personalizadas
  • update_design - Actualiza propiedades del diseño (nombre, descripción, visibilidad)
  • delete_design - Elimina un diseño permanentemente
  • duplicate_design - Bifurca/copia un diseño existente
  • export_design - Exporta el diseño a formato PNG, JPG, PDF o SVG

Herramientas de Manipulación de Lienzo

  • add_element - Agrega cualquier tipo de elemento (forma, texto, imagen, SVG, etc.)
  • update_element - Modifica propiedades del elemento (posición, estilo, contenido)
  • delete_element - Elimina un elemento del lienzo
  • resize_canvas - Cambia las dimensiones del lienzo
  • clear_canvas - Elimina todos los elementos del lienzo

Herramientas de Plantillas

  • list_templates - Explora plantillas de diseño disponibles
  • apply_template - Aplica una plantilla a un diseño existente
  • create_template - Guarda un diseño como plantilla reutilizable

Herramientas de Gestión de Activos

  • list_assets - Ve la biblioteca de activos del usuario (imágenes, fuentes, etc.)
  • search_stock_images - Busca en Pixabay imágenes de stock
  • search_icons - Busca activos de iconos
  • search_clipart - Busca imágenes clipart
  • search_illustrations - Busca activos de ilustraciones
  • list_fonts - Lista fuentes disponibles por categoría
  • upload_asset - Sube un nuevo activo a la biblioteca

Herramientas de IA

  • generate_design - Genera diseños usando IA
  • chat_with_civi - Interactúa con Civi AI para asistencia de diseño

Tipos de Elementos

Tipos de elementos de lienzo compatibles:

  • rectángulo - Formas rectangulares
  • círculo - Formas circulares/elípticas
  • texto - Elementos de texto con fuentes
  • imagen - Imágenes de URLs o activos
  • línea - Líneas rectas
  • polígono - Formas de múltiples lados
  • estrella - Formas de estrella
  • svg - Gráficos SVG
  • bezier - Rutas curvas
  • contenedor - Elementos de grupo
  • tabla - Tablas de datos

Desarrollo

Compilación

npm run build

Ejecutar en Desarrollo

npm run dev

Verificación de Tipos

npm run type-check

Compilación Limpia

npm run clean
npm run build

Cumplimiento del Protocolo MCP

Este servidor sigue la especificación del Protocolo MCP (2025-11-25).

Documentación de Cumplimiento:

Características Clave de Cumplimiento:

  • ✅ Todo el registro usa stderr (nunca stdout) para evitar corromper mensajes JSON-RPC
  • ✅ Manejo y formato adecuado de errores
  • ✅ Definiciones completas de herramientas, recursos y prompts
  • ✅ Estructura estándar del servidor MCP e inicialización

Pruebas de Cumplimiento:

# Use MCP Inspector to verify compliance
npx @modelcontextprotocol/inspector canvelete-mcp start

Solución de Problemas

"Clave API inválida"

  • Genera una nueva clave API en Configuración de Canvelete → Claves API
  • Verifica que la clave esté configurada correctamente en tu configuración de MCP
  • Comprueba que la clave no haya expirado o sido revocada
  • Ejecuta el script de prueba para verificar: npx tsx test-auth.ts your_api_key

"Permiso denegado"

  • Asegúrate de que la clave API tenga los alcances apropiados
  • Verifica que seas el propietario del recurso que estás modificando

"Error al conectar con la API"

  • Verifica que CANVELETE_API_URL sea correcto (predeterminado: https://www.canvelete.com)
  • Comprueba la conectividad de red con la API de Canvelete
  • Para desarrollo local, asegúrate de que la aplicación de Canvelete esté ejecutándose

Claude Desktop no muestra recursos

  • Reinicia Claude Desktop
  • Verifica la sintaxis del archivo de configuración
  • Confirma que la ruta del servidor sea absoluta
  • Revisa los registros de stderr para ver errores

Sincronización en Tiempo Real

El servidor MCP admite sincronización en tiempo real con el editor de diseño a través de WebSocket. Cuando realizas cambios mediante las herramientas de MCP, el editor se actualizará instantáneamente para reflejar esos cambios.

Configuración

  1. Inicia el servidor WebSocket (en el directorio principal de Canvelete):
pnpm ws

  1. El servidor WebSocket se ejecuta en el puerto 3001 de forma predeterminada. Puedes cambiarlo con la variable de entorno WS_PORT.

  2. Abre el editor de diseño: verás un indicador de sincronización en la esquina superior derecha que muestra el estado de la conexión.

Cómo funciona

  • Cuando las herramientas de MCP modifican un diseño (agregar/actualizar/eliminar elementos, redimensionar lienzo, etc.), los cambios se transmiten a través de WebSocket
  • Todos los clientes del editor conectados suscritos a ese diseño reciben actualizaciones instantáneas
  • El editor muestra un indicador "En vivo" cuando está conectado, con un contador de actualizaciones recibidas

Variables de Entorno

# WebSocket server port (default: 3001)
WS_PORT=3001

# WebSocket server URL for MCP server to connect to
WS_SERVER_URL=ws://localhost:3001/ws

Seguridad y Privacidad

Seguridad de la Clave API

  • Nunca comprometas las claves API al control de versiones ni las compartas públicamente
  • Usa variables de entorno o archivos de configuración seguros
  • Rota las claves regularmente si se ven comprometidas o expuestas
  • Usa claves separadas para desarrollo y producción

Privacidad de Datos

  • El servidor MCP accede a los datos de tu cuenta de Canvelete a través de claves API
  • Toda la comunicación con la API usa cifrado HTTPS
  • Las claves API tienen permisos limitados según la configuración de tu cuenta
  • Revisa los permisos de tu clave API en Configuración de Canvelete → Claves API

Límites de Velocidad

  • Las claves API pueden tener límites de velocidad según tu plan de suscripción
  • El servidor respeta los límites de velocidad y devolverá errores apropiados
  • Consulta tu plan de suscripción para conocer los detalles de los límites de velocidad

Mejores Prácticas

  • Solo usa claves API confiables de tu propia cuenta
  • No compartas tus claves API con partes no confiables
  • Monitorea tu uso de la API en el panel de Canvelete
  • Reporta problemas de seguridad a security@canvelete.com (no abras problemas públicos)

Modos de Implementación

El Servidor MCP de Canvelete admite implementación tanto local como en la nube. Consulta DEPLOYMENT.md para instrucciones detalladas de implementación.

Despliegue Local (Predeterminado)

El servidor se ejecuta localmente en tu máquina usando transporte stdio, que es el estándar para clientes MCP como Claude Desktop, Kiro y Cursor.

Ventajas:

  • ✅ Control total sobre tu entorno
  • ✅ Sin latencia de red
  • ✅ Los datos permanecen en tu máquina
  • ✅ Configuración e instalación sencillas
  • ✅ Funciona sin conexión (una vez que la clave API está en caché)

Casos de uso:

  • Desarrollo personal
  • Pruebas y depuración
  • Flujos de trabajo sensibles a la privacidad
  • Aplicaciones de escritorio (Claude Desktop, Cursor, etc.)

Despliegue en la Nube

El servidor se puede desplegar en plataformas en la nube mediante contenedores o funciones serverless. El transporte stdio funciona sin problemas en entornos de nube.

Ventajas:

  • ✅ Escalable y siempre disponible
  • ✅ Sin uso de recursos locales
  • ✅ Accesible desde múltiples dispositivos
  • ✅ Infraestructura gestionada
  • ✅ Actualizaciones y mantenimiento fáciles

Plataformas compatibles:

  • Docker/Contenedores: Despliega en cualquier plataforma de contenedores (Docker, Kubernetes, etc.)
  • Google Cloud Run: Plataforma de contenedores serverless
  • Azure Functions: Serverless con manejadores personalizados
  • AWS Lambda: Funciones serverless (con adaptador stdio)
  • Vercel/Netlify: Plataformas serverless
  • Cualquier hosting de Node.js: Railway, Render, Fly.io, etc.

Ejemplos rápidos en la nube:

# Docker deployment (using published package)
docker build -f Dockerfile.simple -t canvelete-mcp-server .
docker run -e CANVELETE_API_KEY=your_key canvelete-mcp-server

# Or use docker-compose
docker-compose up -d

Consulta DEPLOYMENT.md para guías completas de despliegue para:

  • Docker/Contenedores (Dockerfile incluido)
  • Google Cloud Run
  • Azure Functions
  • AWS Lambda
  • Railway, Render, Fly.io
  • Vercel/Netlify

Requisitos

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para las pautas.

Pasos rápidos:

  1. Haz un fork del repositorio
  2. Crea tu rama de características (git checkout -b feature/amazing-feature)
  3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
  4. Sube la rama (git push origin feature/amazing-feature)
  5. Abre un Pull Request

Para pautas detalladas de contribución, estándares de código y configuración de desarrollo, consulta CONTRIBUTING.md.

Registro de cambios

Consulta CHANGELOG.md para una lista detallada de cambios e historial de versiones.

Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

Soporte

Para problemas y preguntas:

Arquitectura de Despliegue

Cómo Funciona

El servidor MCP usa transporte stdio por defecto, que funciona tanto en entornos locales como en la nube:

  1. Modo Local: Los clientes MCP (Claude Desktop, etc.) inician el proceso del servidor y se comunican mediante stdin/stdout
  2. Modo Nube: Las plataformas en la nube ejecutan el servidor en contenedores/funciones y gestionan la comunicación stdio a través de su infraestructura

Flujo de Datos

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│ MCP Client  │ ◄──────► │ MCP Server   │ ◄──────► │ Canvelete   │
│ (Claude)    │  stdio  │ (This Server)│  HTTPS  │    API      │
└─────────────┘         └──────────────┘         └─────────────┘
  • Protocolo MCP: JSON-RPC sobre stdio (local) o HTTP/SSE (nube)
  • API de Canvelete: Siempre HTTPS a https://canvelete.com

Elegir el Modo de Despliegue

Usa Despliegue Local si:

  • Usas Claude Desktop, Cursor u otros clientes MCP de escritorio
  • Quieres máxima privacidad y control
  • Estás desarrollando o probando
  • Tienes un solo usuario/máquina

Usa Despliegue en la Nube si:

  • Necesitas disponibilidad 24/7
  • Quieres compartir el acceso entre múltiples dispositivos
  • Necesitas escalabilidad para múltiples usuarios
  • Prefieres infraestructura gestionada

Enlaces Relacionados

Recursos de Canvelete

Recursos MCP