Canvelete

Plataforma API-first para otimização de imagens e design de documentos. Gere imagens, PDFs e documentos otimizados em escala com nosso editor visual e API REST.

GitHub

Documentação

Servidor MCP Canvelete

Servidor Model Context Protocol (MCP) para a plataforma de design Canvelete. Este servidor expõe as capacidades de design da Canvelete para assistentes de IA e outros clientes compatíveis com MCP, permitindo a criação e manipulação programática de designs.

🔗 Links:

Plataforma Canvelete - Crie designs online
Documentação - Documentação completa da API e da plataforma
Obtenha sua API Key - Gere sua chave de API

📚 Documentação do Servidor MCP:

Guia de Tipos de Elementos - Guia completo dos 13 tipos de elementos (incluindo QR codes e códigos de barras), suas capacidades e limites de estilização
Guia de Busca de Assets - Como buscar e usar assets externos (Pixabay, Unsplash, Iconify, cliparts, ilustrações)
Exemplos - Exemplos práticos e casos de uso
Guia de Configuração do MCP - Instruções de configuração e uso

Início Rápido

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

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

Em seguida, configure seu cliente MCP (Claude Desktop, Kiro, etc.) com:

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

Recursos

Resources (Acesso Somente Leitura a Dados)

Designs: Acesse designs do usuário, navegue por templates
Canvas: Visualize o estado do canvas e os elementos
Assets: Navegue pela biblioteca de assets do usuário e fontes disponíveis
Usuário: Acesse perfil e preferências
Metadados: Documentação completa de capacidades de elementos, limites de estilização e sistema de design

Tools (Ações)

Gerenciamento de Designs: Criar, atualizar, excluir, duplicar e exportar designs
Manipulação de Canvas: Adicionar, atualizar, excluir elementos; redimensionar canvas; limpar canvas
- 13 Tipos de Elementos: rectangle, circle, text, image, svg, line, polygon, star, qr, barcode, table, container, bezier
- QR Codes: Gere QR codes para URLs, vCards, WiFi e muito mais
- Códigos de Barras: Suporte para CODE128, EAN13, UPC e outros 7 formatos
Templates: Listar, aplicar e criar templates
Assets: Busca abrangente de assets em múltiplas fontes
- Pixabay: Mais de 2,7M de fotos e ilustrações gratuitas
- Unsplash: Mais de 3M de fotos curadas de alta qualidade
- Iconify: Mais de 200K ícones de mais de 150 conjuntos de ícones
- Cliparts: Mais de 10K gráficos clipart selecionados
- Ilustrações: Mais de 5K ilustrações artísticas
Fontes: Mais de 30 fontes profissionais com metadados e recomendações de combinação
Formas: Mais de 70 formas SVG de 8 categorias (básicas, setas, estrelas, balões de fala, natureza, símbolos, geométricas, extras)
Integração com IA: Acesso ao Civi AI para geração de designs

Prompts Disponíveis

Os prompts fornecem templates guiados para tarefas comuns de design:

create_social_post - Crie posts para redes sociais (Instagram, Facebook, Twitter, etc.)
create_presentation_slide - Crie slides de apresentação com título e conteúdo
add_text_element - Adicione elementos de texto estilizados aos designs

Os prompts ajudam assistentes de IA a criar designs com estrutura e estilização adequadas automaticamente.

Instalação

Método 1: Instalação Global (Recomendado)

Instale o pacote globalmente para usar o comando canvelete-mcp:

npm install -g @canveletedotcom/mcp-server

Método 2: NPX (Sem Necessidade de Instalação)

Use npx para executar sem instalar:

npx -y @canveletedotcom/mcp-server start

Método 3: Desenvolvimento Local

Para desenvolvimento ou builds personalizados:

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

Em seguida, use o caminho do build local na sua configuração do MCP.

Configuração

Variáveis de Ambiente

Crie um arquivo .env no diretório do mcp-server:

# 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

Autenticação

Você precisa de uma API key da Canvelete para usar o servidor MCP:

Faça login na sua conta Canvelete
Acesse Configurações → API Keys
Gere uma nova API key
Salve a chave com segurança

Para documentação detalhada da API, consulte docs.canvelete.com.

Você pode fornecer a API key de duas formas:

Opção 1: Variável de Ambiente (recomendada para Claude Desktop)

CANVELETE_API_KEY=your_api_key_here

Opção 2: Argumentos da Ferramenta (para uso programático)

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

Configuração

Claude Desktop

Encontre o arquivo de configuração do 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
Adicione a configuração do servidor Canvelete:

Opção A: Usando Instalação 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"
      }
    }
  }
}

Opção B: Usando NPX (Sem Instalação)

{
  "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"
      }
    }
  }
}

Opção C: Usando Build 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"
      }
    }
  }
}

Reinicie o Claude Desktop

Kiro

Encontre o arquivo de configuração do Kiro: ~/.kiro/settings/mcp.json
Adicione a mesma configuração acima
Reinicie o Kiro

Outros Clientes MCP

Qualquer cliente compatível com MCP pode usar este servidor. Configure-o para executar:

Comando: canvelete-mcp (se instalado globalmente) ou npx -y @canveletedotcom/mcp-server
Args: ["start"]
Ambiente: Defina CANVELETE_API_KEY e opcionalmente CANVELETE_API_URL

Exemplos de Uso

Exemplos de Conversas

Após a configuração, você pode pedir ao seu assistente de IA:

"Quais designs eu tenho no Canvelete?"
"Crie um novo design de post para Instagram de 1080x1080 chamado 'Promoção de Verão'"
"Adicione um elemento de texto ao design {id} que diga 'Olá, Mundo'"
"Exporte o design {id} como PNG"
"Liste todos os meus assets enviados"
"Aplique o template {template-id} ao design {design-id}"
"Crie um slide de apresentação com o título 'Bem-vindo' e o subtítulo 'Introdução'"
"Busque imagens de montanhas em banco de imagens"

Exemplo Rápido: Criar um Post para Redes Sociais

// 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
})

Consulte EXAMPLES.md para exemplos mais detalhados. Para documentação completa da API, visite docs.canvelete.com.

Resources Disponíveis

Os resources fornecem acesso somente leitura aos dados da Canvelete:

URI	Descrição
`canvelete://api/designs/list`	Lista todos os designs do usuário com paginação
`canvelete://api/designs/templates`	Navega por templates públicos de design
`canvelete://api/design/{id}`	Obtém informações detalhadas sobre um design específico
`canvelete://api/canvas/{designId}`	Obtém o estado atual do canvas de um design
`canvelete://api/canvas/{designId}/elements`	Obtém todos os elementos do canvas de um design
`canvelete://api/assets/library`	Assets enviados pelo usuário (imagens, fontes, etc.)
`canvelete://api/assets/fonts`	Lista de todas as fontes disponíveis para elementos de texto
`canvelete://api/user/profile`	Perfil do usuário e informações de assinatura
`canvelete://api/user/preferences`	Preferências e configurações do editor do usuário
`canvelete://api/metadata/schema`	Metadados do sistema, schemas e definições de propriedades

Tools Disponíveis

Tools de Gerenciamento de Designs

list_designs - Lista todos os designs do usuário com paginação e busca
get_design - Obtém informações detalhadas do design, incluindo dados do canvas
create_design - Cria novo design com dimensões personalizadas
update_design - Atualiza propriedades do design (nome, descrição, visibilidade)
delete_design - Exclui um design permanentemente
duplicate_design - Fork/copia um design existente
export_design - Exporta design nos formatos PNG, JPG, PDF ou SVG

Tools de Manipulação de Canvas

add_element - Adiciona qualquer tipo de elemento (forma, texto, imagem, SVG, etc.)
update_element - Modifica propriedades do elemento (posição, estilo, conteúdo)
delete_element - Remove um elemento do canvas
resize_canvas - Altera as dimensões do canvas
clear_canvas - Remove todos os elementos do canvas

Tools de Templates

list_templates - Navega pelos templates de design disponíveis
apply_template - Aplica um template a um design existente
create_template - Salva um design como template reutilizável

Tools de Gerenciamento de Assets

list_assets - Visualiza a biblioteca de assets do usuário (imagens, fontes, etc.)
search_stock_images - Busca imagens de banco de imagens no Pixabay
search_icons - Busca por assets de ícones
search_clipart - Busca por imagens clipart
search_illustrations - Busca por assets de ilustrações
list_fonts - Lista fontes disponíveis por categoria
upload_asset - Envia um novo asset para a biblioteca

Tools de IA

generate_design - Gera designs usando IA
chat_with_civi - Interage com o Civi AI para assistência de design

Tipos de Elementos

Tipos de elementos de canvas suportados:

rectangle - Formas retangulares
circle - Formas circulares/elípticas
text - Elementos de texto com fontes
image - Imagens de URLs ou assets
line - Linhas retas
polygon - Formas com múltiplos lados
star - Formas de estrela
svg - Gráficos SVG
bezier - Caminhos curvos
container - Elementos de agrupamento
table - Tabelas de dados

Desenvolvimento

Build

npm run build

Executar em Desenvolvimento

npm run dev

Verificação de Tipos

npm run type-check

Build Limpo

npm run clean
npm run build

Conformidade com o Protocolo MCP

Este servidor segue a especificação do Protocolo MCP (2025-11-25).

Documentação de Conformidade:

MCP_COMPLIANCE.md - Melhores práticas de implementação e conformidade com o protocolo
SPECIFICATION_COMPLIANCE.md - Conformidade detalhada com a especificação oficial do MCP (2025-11-25)

Principais Recursos de Conformidade:

✅ Todo o logging usa stderr (nunca stdout) para evitar corromper mensagens JSON-RPC
✅ Tratamento e formatação adequados de erros
✅ Definições completas de tools, resources e prompts
✅ Estrutura e inicialização padrão do servidor MCP

Testando a Conformidade:

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

Solução de Problemas

"API key inválida"

Gere uma nova API key em Configurações da Canvelete → API Keys
Verifique se a chave está definida corretamente na sua configuração do MCP
Verifique se a chave não expirou ou foi revogada
Execute o script de teste para verificar: npx tsx test-auth.ts your_api_key

"Permissão negada"

Certifique-se de que a API key tenha os escopos apropriados
Verifique se você é o proprietário do recurso que está modificando

"Falha ao conectar à API"

Verifique se CANVELETE_API_URL está correto (padrão: https://www.canvelete.com)
Verifique a conectividade de rede com a API da Canvelete
Para desenvolvimento local, certifique-se de que o aplicativo Canvelete esteja em execução

Claude Desktop não mostra os resources

Reinicie o Claude Desktop
Verifique a sintaxe do arquivo de configuração
Verifique se o caminho do servidor é absoluto
Verifique os logs de stderr para erros

Sincronização em Tempo Real

O servidor MCP suporta sincronização em tempo real com o editor de design via WebSocket. Quando você faz alterações por meio das tools do MCP, o editor é atualizado instantaneamente para refletir essas alterações.

Configuração

Inicie o servidor WebSocket (no diretório principal da Canvelete):

pnpm ws

O servidor WebSocket executa na porta 3001 por padrão. Você pode alterar isso com a variável de ambiente WS_PORT.
Abra o editor de design - você verá um indicador de sincronização no canto superior direito mostrando o status da conexão.

Como funciona

Quando as tools do MCP modificam um design (adicionar/atualizar/excluir elementos, redimensionar canvas, etc.), as alterações são transmitidas via WebSocket
Todos os clientes do editor conectados e inscritos naquele design recebem atualizações instantâneas
O editor mostra um indicador "Ao vivo" quando conectado, com uma contagem de atualizações recebidas

Variáveis de Ambiente

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

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

Segurança e Privacidade

Segurança da API Key

Nunca envie API keys para o controle de versão nem as compartilhe publicamente
Use variáveis de ambiente ou arquivos de configuração seguros
Rotacione as chaves regularmente se forem comprometidas ou expostas
Use chaves separadas para desenvolvimento e produção

Privacidade dos Dados

O servidor MCP acessa os dados da sua conta Canvelete por meio de API keys
Toda a comunicação com a API usa criptografia HTTPS
As API keys têm permissões com escopo definido com base nas configurações da sua conta
Revise as permissões da sua API key em Configurações da Canvelete → API Keys

Limite de Taxa

As API keys podem ter limites de taxa com base no seu plano de assinatura
O servidor respeita os limites de taxa e retornará erros apropriados
Verifique os detalhes do limite de taxa no seu plano de assinatura

Melhores Práticas

Use apenas API keys confiáveis da sua própria conta
Não compartilhe suas API keys com partes não confiáveis
Monitore seu uso da API no painel da Canvelete
Reporte problemas de segurança para security@canvelete.com (não abra issues públicas)

Modos de Implantação

O Canvelete MCP Server suporta implantação local e na nuvem. Consulte DEPLOYMENT.md para instruções detalhadas de implantação.

Implantação Local (Padrão)

O servidor roda localmente na sua máquina usando transporte stdio, que é o padrão para clientes MCP como Claude Desktop, Kiro e Cursor.

Vantagens:

✅ Controle total sobre seu ambiente
✅ Sem latência de rede
✅ Os dados permanecem na sua máquina
✅ Configuração e instalação simples
✅ Funciona offline (uma vez que a chave de API esteja em cache)

Casos de Uso:

Desenvolvimento pessoal
Testes e depuração
Fluxos de trabalho sensíveis à privacidade
Aplicações desktop (Claude Desktop, Cursor, etc.)

Implantação em Nuvem

O servidor pode ser implantado em plataformas de nuvem usando conteinerização ou funções serverless. O transporte stdio funciona perfeitamente em ambientes de nuvem.

Vantagens:

✅ Escalável e sempre disponível
✅ Sem uso de recursos locais
✅ Acessível de múltiplos dispositivos
✅ Infraestrutura gerenciada
✅ Atualizações e manutenção fáceis

Plataformas Suportadas:

Docker/Contêineres: Implante em qualquer plataforma de contêineres (Docker, Kubernetes, etc.)
Google Cloud Run: Plataforma de contêineres serverless
Azure Functions: Serverless com manipuladores personalizados
AWS Lambda: Funções serverless (com adaptador stdio)
Vercel/Netlify: Plataformas serverless
Qualquer hospedagem Node.js: Railway, Render, Fly.io, etc.

Exemplos Rápidos de Nuvem:

# 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

Consulte DEPLOYMENT.md para guias completos de implantação para:

Docker/Contêineres (Dockerfile incluído)
Google Cloud Run
Azure Functions
AWS Lambda
Railway, Render, Fly.io
Vercel/Netlify

Requisitos

Node.js: >= 18.0.0
Conta Canvelete: Cadastre-se em canvelete.com
Chave de API Canvelete: Obtenha uma em Configurações Canvelete → API Keys
Documentação: Consulte docs.canvelete.com para referência da API

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.

Passos rápidos:

Faça um fork do repositório
Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

Para diretrizes detalhadas de contribuição, padrões de código e configuração de desenvolvimento, consulte CONTRIBUTING.md.

Changelog

Consulte CHANGELOG.md para uma lista detalhada de alterações e histórico de versões.

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Suporte

Para problemas e dúvidas:

GitHub Issues: canvelete/canvelete/issues
Documentação da Plataforma: docs.canvelete.com
Plataforma Canvelete: canvelete.com
Documentação da API: docs.canvelete.com/api
Obter Ajuda: Visite canvelete.com/support ou docs.canvelete.com/help

Arquitetura de Implantação

Como Funciona

O servidor MCP usa transporte stdio por padrão, que funciona em ambientes locais e de nuvem:

Modo Local: Clientes MCP (Claude Desktop, etc.) iniciam o processo do servidor e se comunicam via stdin/stdout
Modo Nuvem: Plataformas de nuvem executam o servidor em contêineres/funções e gerenciam a comunicação stdio através de sua infraestrutura

Fluxo de Dados

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│ MCP Client  │ ◄──────► │ MCP Server   │ ◄──────► │ Canvelete   │
│ (Claude)    │  stdio  │ (This Server)│  HTTPS  │    API      │
└─────────────┘         └──────────────┘         └─────────────┘

Protocolo MCP: JSON-RPC sobre stdio (local) ou HTTP/SSE (nuvem)
API Canvelete: Sempre HTTPS para https://canvelete.com

Escolhendo o Modo de Implantação

Use Implantação Local se:

Você está usando Claude Desktop, Cursor ou outros clientes MCP desktop
Você quer máxima privacidade e controle
Você está desenvolvendo ou testando
Você tem um único usuário/máquina

Use Implantação em Nuvem se:

Você precisa de disponibilidade 24/7
Você quer compartilhar acesso entre múltiplos dispositivos
Você precisa de escalabilidade para múltiplos usuários
Você prefere infraestrutura gerenciada

Links Relacionados

Recursos Canvelete

Plataforma Canvelete - Crie e edite designs online
Documentação - Documentação completa da plataforma e da API
Referência da API - Documentação detalhada da API
Guia de Início - Guia de início da plataforma

Canvelete

Documentação

Servidor MCP Canvelete

Início Rápido

Recursos

Resources (Acesso Somente Leitura a Dados)

Tools (Ações)

Prompts Disponíveis

Instalação

Método 1: Instalação Global (Recomendado)

Método 2: NPX (Sem Necessidade de Instalação)

Método 3: Desenvolvimento Local

Configuração

Variáveis de Ambiente

Autenticação

Configuração

Claude Desktop

Kiro

Outros Clientes MCP

Exemplos de Uso

Exemplos de Conversas

Exemplo Rápido: Criar um Post para Redes Sociais

Resources Disponíveis

Tools Disponíveis

Tools de Gerenciamento de Designs

Tools de Manipulação de Canvas

Tools de Templates

Tools de Gerenciamento de Assets

Tools de IA

Tipos de Elementos

Desenvolvimento

Build

Executar em Desenvolvimento

Verificação de Tipos

Build Limpo

Conformidade com o Protocolo MCP

Solução de Problemas

"API key inválida"

"Permissão negada"

"Falha ao conectar à API"

Claude Desktop não mostra os resources

Sincronização em Tempo Real

Configuração

Como funciona

Variáveis de Ambiente

Segurança e Privacidade

Segurança da API Key

Privacidade dos Dados

Limite de Taxa

Melhores Práticas

Modos de Implantação

Implantação Local (Padrão)

Implantação em Nuvem

Requisitos

Contribuindo

Changelog

Licença

Suporte

Arquitetura de Implantação

Como Funciona

Fluxo de Dados

Escolhendo o Modo de Implantação

Links Relacionados

Recursos Canvelete

Recursos MCP