Figma Copilot

Permite que assistentes de IA interajam e automatizem designs do Figma de forma programática.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Figma Copilot

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA interajam programaticamente com designs do Figma. Compatível com qualquer cliente MCP, incluindo Cursor, Claude Desktop e outros aplicativos habilitados para MCP. Oferece recursos avançados de manipulação de texto, operações em lote e capacidades abrangentes de automação de design.

Créditos

Este projeto é baseado em cursor-talk-to-figma-mcp por Sonny Lazuardi.

Aviso Legal

Este é um projeto independente e não é afiliado, mantido oficialmente, autorizado, endossado ou patrocinado pela Figma, Inc. Todos os nomes de produtos e empresas são marcas registradas™ ou marcas registradas® de seus respectivos proprietários.

Principais Aprimoramentos

v0.3.2 (Mais recente)

  • Preservação de Formatação de Texto - Atualizações de texto não perdem mais a formatação (negrito, itálico, cores, fontes). Veja o Guia de Operações de Texto Aprimoradas.
  • Operações em Lote - Melhoria de desempenho de 50-90% para operações em massa. Veja o Guia de Operações em Lote.
  • Tratamento de Erros Aprimorado - Mensagens de erro específicas e acionáveis com sugestões
  • Soluções de Timeout - Novas opções de varredura com controle de profundidade e resultados parciais
  • Operações de Texto Inteligentes - Localizar/substituir com preservação de formatação

Aprimoramentos Anteriores

  • Corrigido o erro "Cannot unwrap symbol" ao trabalhar com fontes mistas. Veja a Documentação de Tratamento de Fontes.
  • Carregamento de fontes melhorado com a API getRangeAllFontNames()
  • Melhor tratamento de erros com Promise.allSettled() para carregamento de fontes
  • Retornos de valor seguros para evitar problemas de serialização
  • Registro aprimorado para depuração de problemas de fontes

Estrutura do Projeto

  • src/talk_to_figma_mcp/ - Servidor MCP TypeScript para integração com Figma
  • src/figma_copilot_plugin/ - Plugin Figma para comunicação com clientes MCP
  • src/socket.ts - Servidor WebSocket que facilita a comunicação entre o servidor MCP e o plugin Figma

Começando

  1. Instale o Bun se ainda não tiver:
curl -fsSL https://bun.sh/install | bash
  1. Execute a configuração para configurar o MCP
bun setup
  1. Inicie o servidor WebSocket
bun socket
  1. Servidor MCP
bunx figma-copilot
  1. NOVO Instale o plugin Figma a partir da página da comunidade do Figma ou instale localmente

Guia de Início Rápido

Tutoriais em vídeo em breve!

Exemplo de Automação de Design

Substituição em massa de conteúdo de texto

Agradecimentos a @dusskapark por contribuir com o recurso de substituição em massa de texto.

Propagação de Substituições de Instância Outra contribuição de @dusskapark Propague substituições de instância de componente de uma instância de origem para várias instâncias de destino com um único comando. Esse recurso reduz drasticamente o trabalho repetitivo de design ao trabalhar com instâncias de componente que precisam de personalizações semelhantes.

Melhorias de Desempenho (v0.3.2)

Com base no uso real em produção com criação de infográficos em massa:

OperaçãoAntes v0.3.2Depois v0.3.2Melhoria
Clonar 20 nós50 segundos5 segundos90% mais rápido
Atualizar 112 nós de texto15 minutos30 segundos96% mais rápido
Escanear documento grandeTimeout após 30s3 segundosSem timeouts
Atualização de texto + formatação2 chamadas separadas1 chamada combinada50% menos chamadas de API

Configuração e Instalação Manual

Servidor MCP: Integração com Clientes MCP

Adicione o servidor à configuração do seu cliente MCP. Por exemplo, no ~/.cursor/mcp.json do Cursor ou na configuração do Claude Desktop:

{
  "mcpServers": {
    "figma-copilot": {
      "command": "bunx",
      "args": ["figma-copilot@latest"]
    }
  }
}

Servidor WebSocket

Inicie o servidor WebSocket:

bun socket

Plugin Figma

  1. No Figma, vá em Plugins > Desenvolvimento > Novo Plugin
  2. Escolha "Vincular plugin existente"
  3. Selecione o arquivo src/figma_copilot_plugin/manifest.json
  4. O plugin agora deve estar disponível em seus plugins de desenvolvimento do Figma

Guia para Windows + WSL

  1. Instale o bun via PowerShell
powershell -c "irm bun.sh/install.ps1|iex"
  1. Descomente o hostname 0.0.0.0 em src/socket.ts
// uncomment this to allow connections in windows wsl
hostname: "0.0.0.0",
  1. Inicie o websocket
bun socket

Uso

  1. Inicie o servidor WebSocket
  2. Instale o servidor MCP no seu cliente MCP
  3. Abra o Figma e execute o Plugin Figma Copilot
  4. Conecte o plugin ao servidor WebSocket entrando em um canal usando join_channel
  5. Use seu cliente MCP para se comunicar com o Figma usando as ferramentas MCP

Ferramentas MCP

O servidor MCP fornece as seguintes ferramentas para interagir com o Figma:

Documento e Seleção

  • get_document_info - Obter informações sobre o documento Figma atual
  • get_current_context - Obter contexto abrangente incluindo seleção, slide focado (se estiver no modo Slides) e opcionalmente informações do documento
  • get_selection - DEPRECADO: Use get_current_context em vez disso
  • read_my_design - Obter informações detalhadas do nó sobre a seleção atual sem parâmetros
  • get_nodes - Obter informações detalhadas sobre um ou mais nós (aceita ID único ou array)
  • get_node_info - DEPRECADO: Use get_nodes com ID de nó único em vez disso
  • get_nodes_info - DEPRECADO: Use get_nodes com array de IDs de nós em vez disso
  • get_focused_slide - DEPRECADO: Use get_current_context com a opção includeSlideDetails em vez disso
  • get_slides_mode - DEPRECADO: Use get_current_context com a opção includeSlideDetails em vez disso

Anotações

  • get_annotations - Obter todas as anotações no documento atual ou em um nó específico
  • set_annotation - Criar ou atualizar uma anotação com suporte a markdown
  • set_multiple_annotations - Criar/atualizar várias anotações em lote de forma eficiente
  • scan_nodes_by_types - Escanear nós com tipos específicos (útil para encontrar alvos de anotação)

Prototipagem e Conexões

  • get_reactions - Obter todas as reações de protótipo de nós com animação de destaque visual
  • set_default_connector - Definir um conector FigJam copiado como o estilo de conector padrão para criar conexões (deve ser definido antes de criar conexões)
  • create_connections - Criar linhas de conector FigJam entre nós, com base em fluxos de protótipo ou mapeamento personalizado

Criação de Elementos

  • create_rectangle - Criar um novo retângulo com posição, tamanho e nome opcional
  • create_frame - Criar um novo frame com posição, tamanho e nome opcional
  • create_text - Criar um novo nó de texto com propriedades de fonte personalizáveis

Operações de Texto

Operações Básicas de Texto

  • scan_text_nodes - DEPRECADO: Use scan_nodes_with_options com nodeTypes: ['TEXT'] em vez disso
  • scan_nodes_with_options - Varredura aprimorada com controle de profundidade, tratamento de timeout e resultados parciais
  • set_text_content - Definir o conteúdo de texto de um único nó de texto (Nota: perde formatação)
  • set_multiple_text_contents - Atualizar vários nós de texto em lote de forma eficiente (Nota: perde formatação)

Texto com Preservação de Formatação (v0.3.2)

Veja o Guia de Operações de Texto Aprimoradas para uma visão geral.

  • update_text_preserve_formatting - Atualizar texto preservando toda a formatação de caracteres (negrito, itálico, cores, fontes)
  • smart_text_replace - Localizar e substituir texto preservando a formatação das partes não alteradas
  • set_multiple_text_contents_with_styles - Atualizar texto em lote com formatação em uma única operação

Estilização de Texto

Veja o Guia de Estilização de Texto para uso detalhado.

  • set_text_style_range - Aplicar estilização de texto (negrito, itálico, sublinhado, tachado) a intervalos específicos de caracteres
  • get_text_style_range - Obter estilização de texto para um intervalo específico
  • set_text_decoration_range - Definir propriedades avançadas de decoração de texto
  • get_text_decoration_range - Obter propriedades de decoração de texto para um intervalo
  • set_range_font - Alterar família e estilo de fonte para um intervalo de texto
  • set_range_font_size - Alterar tamanho da fonte para um intervalo de texto
  • set_range_fills - Definir cor do texto para um intervalo específico
  • get_styled_text_segments - Obter informações detalhadas sobre segmentos de texto e suas propriedades
  • set_component_description - Definir descrição do componente usando Markdown
  • get_component_description - Obter descrição do componente em formato Markdown
  • normalize_markdown - Normalizar texto Markdown para o subconjunto suportado pelo Figma

Auto Layout e Espaçamento

  • set_layout_mode - Definir o modo de layout e o comportamento de quebra de um frame (NONE, HORIZONTAL, VERTICAL)
  • set_padding - Definir valores de preenchimento para um frame de auto-layout (superior, direito, inferior, esquerdo)
  • set_axis_align - Definir alinhamento do eixo principal e contrário para frames de auto-layout
  • set_layout_sizing - Definir modos de dimensionamento horizontal e vertical para frames de auto-layout (FIXED, HUG, FILL)
  • set_item_spacing - Definir distância entre filhos em um frame de auto-layout

Estilização

  • set_fill_color - Definir a cor de preenchimento de um nó (RGBA)
  • set_stroke_color - Definir a cor e a espessura do traço de um nó
  • set_corner_radius - Definir o raio do canto de um nó com controle opcional por canto

Layout e Organização

  • move_node - Mover um nó para uma nova posição
  • resize_node - Redimensionar um nó com novas dimensões
  • delete_node - Excluir um nó
  • delete_multiple_nodes - Excluir vários nós de uma vez de forma eficiente
  • clone_node - Criar uma cópia de um nó existente com deslocamento de posição opcional

Operações em Lote (v0.3.2)

Veja o Guia de Operações em Lote para melhores práticas.

  • clone_multiple_nodes - Clonar um nó para várias posições em uma única operação (50-90% mais rápido do que clones individuais)
  • get_multiple_nodes_info - DEPRECADO: Use get_nodes com array de IDs de nós em vez disso
  • set_multiple_nodes_property - Definir o mesmo valor de propriedade em vários nós de uma vez
  • execute_batch - Executar vários comandos diferentes em sequência com uma única ida e volta
  • get_connection_status - Obter status atual da conexão e estatísticas

Componentes e Estilos

  • get_styles - Obter informações sobre estilos locais
  • get_local_components - Obter informações sobre componentes locais
  • create_component_instance - Criar uma instância de um componente
  • get_instance_overrides - Extrair propriedades de substituição de uma instância de componente selecionada
  • set_instance_overrides - Aplicar substituições extraídas às instâncias de destino

Ferramentas Compostas

  • extract_slide_content - Extrair todo o conteúdo de um slide do Figma, incluindo texto, tabelas e opcionalmente imagens (suporta saída bruta ou estruturada)
  • get_presentation_summary - Gerar uma visão geral de uma apresentação do Figma, incluindo contagem de slides, títulos de slides e opcionalmente um resumo com os pontos principais
  • get_table_data - Extrair dados de um nó de tabela do Figma em vários formatos (array, objeto ou CSV) com tratamento personalizável de cabeçalho

Exportação e Avançado

  • export_node_as_image - Exportar um nó como imagem (PNG, JPG, SVG ou PDF) - suporte limitado em imagem atualmente retornando base64 como texto

Gerenciamento de Conexão

  • join_channel - Entrar em um canal específico para se comunicar com o Figma

Prompts MCP

O servidor MCP inclui vários prompts auxiliares para guiá-lo em tarefas complexas de design:

  • design_strategy - Melhores práticas para trabalhar com designs do Figma
  • read_design_strategy - Melhores práticas para ler designs do Figma
  • text_replacement_strategy - Abordagem sistemática para substituir texto em designs do Figma
  • annotation_conversion_strategy - Estratégia para converter anotações manuais em anotações nativas do Figma
  • swap_overrides_instances - Estratégia para transferir substituições entre instâncias de componente no Figma
  • reaction_to_connector_strategy - Estratégia para converter reações de protótipo do Figma em linhas de conector usando a saída de 'get_reactions' e orientar o uso de 'create_connections' em sequência
  • batch_operations_guide - Melhores práticas para operações em lote eficientes no Figma (v0.3.2)
  • error_recovery_guide - Como lidar com erros comuns e timeouts em operações do Figma (v0.3.2)
  • text_formatting_guide - Melhores práticas para atualizar texto preservando formatação (v0.3.2)

Desenvolvimento

Construindo o Plugin Figma

  1. Navegue até o diretório do plugin Figma: 
    cd src/figma_copilot_plugin
  2. Edite code.js e ui.html

Melhores Práticas

Ao trabalhar com o Figma MCP:

  1. Sempre entre em um canal antes de enviar comandos
  2. Obtenha uma visão geral do documento usando get_document_info primeiro
  3. Verifique o contexto atual com get_current_context antes de modificações
  4. Use ferramentas de criação apropriadas com base nas necessidades:
    • create_frame para contêineres
      • create_rectangle para formas básicas
      • create_text para elementos de texto
  5. Verifique as alterações usando get_node_info
  6. Use instâncias de componentes quando possível para consistência
  7. Lide com erros adequadamente, pois todos os comandos podem lançar exceções
  8. Para designs grandes:
    • Use scan_nodes_with_options com configurações apropriadas de tempo limite e profundidade
      • Monitore o progresso por meio de atualizações WebSocket
      • Implemente o tratamento de erros adequado
  9. Para operações de texto:
    • Use operações em lote quando possível
      • Considere relacionamentos estruturais
      • Verifique as alterações com exportações direcionadas
  10. Para converter anotações legadas:
    • Examine os nós de texto para identificar marcadores numerados e descrições
      • Use scan_nodes_by_types para encontrar elementos de interface aos quais as anotações se referem
      • Corresponda os marcadores aos seus elementos de destino usando caminho, nome ou proximidade
      • Categorize as anotações adequadamente com get_annotations
      • Crie anotações nativas com set_multiple_annotations em lotes
      • Verifique se todas as anotações estão devidamente vinculadas aos seus destinos
      • Exclua os nós de anotação legados após a conversão bem-sucedida
  11. Visualize os "noodles" de protótipo como conectores do FigJam:
  • Use get_reactions para extrair fluxos de protótipo,
  • defina um conector padrão com set_default_connector,
  • e gere linhas de conector com create_connections para um mapeamento visual claro do fluxo.

Solução de problemas

Problemas de Fonte

Se você encontrar erros de "Cannot unwrap symbol" ao atualizar texto, isso provavelmente se deve a fontes mistas em nós de texto. Consulte Documentação de Tratamento de Fontes para obter detalhes sobre como o plugin lida com fontes mistas e estratégias disponíveis.

Problemas de Tempo Limite

Para documentos grandes que causam tempos limite, use scan_nodes_with_options com limitação de profundidade e resultados parciais. Consulte Guia de Operações em Lote para estratégias de otimização.

Documentação