| name | mcp-paper |
| description | Referência completa do MCP Paper (paper.design). Documenta todas as 20 tools disponíveis, seus parâmetros, valores de retorno, padrões de uso, workflows compostos, troubleshooting e boas práticas. Use esta skill sempre que precisar interagir com o Paper Desktop via MCP — leitura de designs, criação de artboards, manipulação de nós, export de JSX/CSS/imagens. REQUER: Paper Desktop app rodando localmente (inicia o MCP server automaticamente). Use quando: qualquer interação com o Paper MCP for necessária. QUANDO NÃO: para lógica pura de Rails sem Paper (ver outras skills). RELAÇÃO: esta skill é referenciada por design-in-paper e paper-to-rails. |
| license | MIT |
| compatibility | Paper Desktop app + Paper MCP server (http://127.0.0.1:29979/mcp) |
Você é um especialista no uso do MCP Paper. Esta skill é a referência canônica de todas
as tools expostas pelo Paper MCP server. Consulte-a sempre que precisar interagir com
o Paper Desktop via MCP — leitura, criação, manipulação e export de designs.
Pré-requisitos
Paper Desktop
O MCP server do Paper roda localmente e é iniciado automaticamente quando o Paper Desktop
está aberto com um arquivo. Não existe binário separado — basta abrir o app.
- URL do server:
http://127.0.0.1:29979/mcp
- Protocolo: Streamable HTTP (MCP — Model Context Protocol)
- Autenticação: nenhuma (local only)
Verificação de Conexão
Antes de qualquer operação, sempre chame get_basic_info.
Se falhar, oriente o usuário:
- Verifique se o Paper Desktop está aberto
- Verifique se há um arquivo aberto no app
- Consulte: https://paper.design/docs/mcp
- Se Windows WSL: habilite mirrored mode networking
Não prossiga sem confirmação de conexão.
Configuração por Editor
| Editor | Configuração |
|---|
| Antigravity | mcp_config.json: { "mcpServers": { "paper": { "serverUrl": "http://127.0.0.1:29979/mcp" } } } |
| Cursor | /add-plugin paper-desktop ou Cursor Settings > Tools & MCP |
| Claude Code | /plugin marketplace add paper-design/agent-plugins → /plugin install paper-desktop@paper |
| Codex | Settings > MCP Servers > Streamable HTTP, nome paper, URL http://127.0.0.1:29979/mcp |
| Copilot (VS Code) | .vscode/mcp.json: { "servers": { "paper": { "type": "http", "url": "http://127.0.0.1:29979/mcp" } } } |
| OpenCode | opencode.json: { "mcp": { "paper": { "type": "remote", "url": "http://127.0.0.1:29979/mcp", "enabled": true } } } |
Referência Completa das Tools
As tools são organizadas em 3 categorias:
- Leitura (read-only) — inspecionar design, capturar screenshots, export
- Escrita (write) — criar/modificar/deletar nós e artboards
- Indicadores (indicators) — feedback visual durante trabalho em progresso
1. Tools de Leitura
get_basic_info
Retorna informações básicas do arquivo aberto no Paper.
| Campo | Detalhe |
|---|
| Parâmetros | Nenhum |
| Retorno | Nome do arquivo, nome da página, contagem de nós, lista de artboards com dimensões (largura × altura) |
| Uso típico | Verificação de conexão; descobrir artboards disponíveis; obter IDs de artboards |
| Quando usar | Sempre como primeiro passo de qualquer workflow |
Exemplo de uso:
→ get_basic_info()
← { fileName: "landing-page.paper", pageName: "Page 1", nodeCount: 142,
artboards: [{ id: "abc123", name: "Hero / desktop", width: 1440, height: 900 }, ...] }
get_selection
Retorna detalhes sobre os nós atualmente selecionados pelo usuário no Paper.
| Campo | Detalhe |
|---|
| Parâmetros | Nenhum |
| Retorno | IDs, nomes, tipos, tamanho (width/height) e artboard pai de cada nó selecionado |
| Uso típico | Contexto baseado na seleção do usuário; ponto de partida para inspecção |
| Quando usar | Quando o usuário diz "use o que está selecionado", "implemente isso" |
Exemplo de uso:
→ get_selection()
← { nodes: [{ id: "xyz789", name: "hero-section", type: "Frame", width: 1440, height: 600,
artboard: { id: "abc123", name: "Hero / desktop" } }] }
Dica: Peça ao usuário para selecionar o nó desejado antes de chamar esta tool.
get_node_info
Retorna informações detalhadas de um nó específico por ID.
| Campo | Detalhe |
|---|
| Parâmetros | id (string) — ID do nó |
| Retorno | Tamanho, visibilidade, estado de lock, nó pai, filhos, conteúdo de texto (se Text node) |
| Uso típico | Inspecção profunda de um nó; verificar propriedades; ler texto |
| Quando usar | Após obter um ID via get_basic_info, get_selection, ou get_children |
Exemplo de uso:
→ get_node_info({ id: "xyz789" })
← { id: "xyz789", name: "hero-title", type: "Text", width: 600, height: 48,
visible: true, locked: false, parent: { id: "abc456" },
children: [], textContent: "Build Something Beautiful" }
get_children
Retorna os filhos diretos de um nó.
| Campo | Detalhe |
|---|
| Parâmetros | id (string) — ID do nó pai |
| Retorno | Lista de filhos diretos com: IDs, nomes, tipos, contagem de filhos (recursiva) |
| Uso típico | Explorar hierarquia nível a nível; entender composição de um frame |
| Quando usar | Navegação seletiva quando get_tree_summary retorna muita informação |
Exemplo de uso:
→ get_children({ id: "abc123" })
← { children: [
{ id: "ch1", name: "header", type: "Frame", childCount: 5 },
{ id: "ch2", name: "content", type: "Frame", childCount: 12 },
{ id: "ch3", name: "footer", type: "Frame", childCount: 3 }
] }
get_tree_summary
Retorna um resumo textual compacto da hierarquia de subárvore de um nó.
| Campo | Detalhe |
|---|
| Parâmetros | id (string) — ID do nó raiz; depth (number, opcional) — limite de profundidade |
| Retorno | Resumo textual indentado mostrando hierarquia (nomes, tipos, nesting) |
| Uso típico | Visão geral da estrutura; entender organização do design antes de iteração |
| Quando usar | Antes de get_jsx para decidir quais nós converter; em artboards grandes, use depth para limitar |
Exemplo de uso:
→ get_tree_summary({ id: "abc123", depth: 3 })
← "Frame 'Hero / desktop' (1440×900)
Frame 'header' (1440×80)
Text 'logo' — 'Paper'
Frame 'nav' (3 children)
Frame 'content' (1440×600)
Text 'title' — 'Build Something Beautiful'
Text 'subtitle' — 'Design meets code.'
Frame 'cta-buttons' (2 children)
Frame 'footer' (1440×220)"
Boas práticas:
- Use
depth: 2 ou depth: 3 para artboards grandes para evitar output excessivo
- Sem
depth, retorna a árvore completa
get_screenshot
Captura um screenshot de um nó específico.
| Campo | Detalhe |
|---|
| Parâmetros | id (string) — ID do nó; scale (number, opcional) — 1 (padrão) ou 2 para 2x |
| Retorno | Imagem em base64 (PNG) |
| Uso típico | Verificação visual; comparar resultado antes/depois; referência para implementação |
| Quando usar | Após criar/modificar artboards; durante paper-to-rails para referência visual |
Exemplo de uso:
→ get_screenshot({ id: "abc123", scale: 2 })
← { image: "data:image/png;base64,iVBOR..." }
Boas práticas:
- Use
scale: 1 para visão geral (menor payload)
- Use
scale: 2 para detalhes finos (tipografia, ícones)
- Capture antes e depois para validar alterações
get_jsx
Retorna o JSX de um nó e todos os seus descendentes.
| Campo | Detalhe |
|---|
| Parâmetros | id (string) — ID do nó; format (string, opcional) — "tailwind" (padrão) ou "inline-styles" |
| Retorno | Código JSX com classes Tailwind ou estilos inline, representando a árvore visual |
| Uso típico | Conversão design → código; base para templates ERB; entender layout e estilos |
| Quando usar | Principal tool da skill paper-to-rails; quando precisa do código do design |
Exemplo de uso:
→ get_jsx({ id: "abc123", format: "tailwind" })
← '<div className="flex flex-col gap-6 p-8 bg-white">
<h1 className="text-2xl font-semibold text-gray-900">Build Something Beautiful</h1>
<p className="text-base text-gray-500">Design meets code.</p>
</div>'
Boas práticas:
- Use
format: "tailwind" para projetos Tailwind (padrão do projeto)
- Use
format: "inline-styles" quando precisar de CSS raw ou para design-in-paper
- O JSX retornado usa
className — converter para class no ERB
- Textos hardcoded devem ser substituídos por
t('.chave') na conversão
get_computed_styles
Retorna CSS computado de um ou mais nós (operação em batch).
| Campo | Detalhe |
|---|
| Parâmetros | ids (string[]) — array de IDs dos nós |
| Retorno | Mapa de ID → estilos CSS computados (propriedades e valores resolvidos) |
| Uso típico | Extrair valores exatos de design tokens; verificar cores, fontes, espaçamentos |
| Quando usar | Complemento ao get_jsx para valores precisos; mapear para tokens do design system |
Exemplo de uso:
→ get_computed_styles({ ids: ["xyz789", "xyz790"] })
← { "xyz789": { "font-family": "Inter", "font-size": "24px", "color": "#1a1a1a",
"display": "flex", "gap": "16px" },
"xyz790": { "background-color": "#3b82f6", "border-radius": "12px", "padding": "12px 24px" } }
Boas práticas:
- Passe múltiplos IDs numa única chamada para eficiência (batch)
- Use para mapear cores hardcoded → tokens do design system
get_fill_image
Retorna a imagem de preenchimento (fill) de um nó que possui image fill.
| Campo | Detalhe |
|---|
| Parâmetros | id (string) — ID do nó com image fill |
| Retorno | Imagem em base64 (JPEG) |
| Uso típico | Extrair imagens usadas no design; salvar assets para o projeto |
| Quando usar | Quando um nó contém uma imagem e precisa extraí-la para uso no código |
Exemplo de uso:
→ get_fill_image({ id: "img001" })
← { image: "data:image/jpeg;base64,/9j/4AAQ..." }
get_font_family_info
Verifica a disponibilidade de uma família de fontes.
| Campo | Detalhe |
|---|
| Parâmetros | family (string) — nome da família de fontes |
| Retorno | Se está disponível (máquina local ou Google Fonts); pesos e estilos disponíveis |
| Uso típico | Verificar se fonte do design está acessível; decidir fallbacks |
| Quando usar | Durante paper-to-rails para garantir que fontes do design estarão disponíveis no projeto |
Exemplo de uso:
→ get_font_family_info({ family: "Inter" })
← { available: true, source: "google-fonts",
weights: [100, 200, 300, 400, 500, 600, 700, 800, 900],
styles: ["normal", "italic"] }
get_guide
Recupera workflows guiados para tópicos específicos.
| Campo | Detalhe |
|---|
| Parâmetros | topic (string) — tópico do guia (ex: "figma-import") |
| Retorno | Passos guiados para o tópico solicitado |
| Uso típico | Obter instruções oficiais do Paper para workflows específicos |
| Quando usar | Quando precisar de orientação sobre importação Figma, setup, ou outros workflows |
Exemplo de uso:
→ get_guide({ topic: "figma-import" })
← { steps: ["1. Open your Figma file...", "2. Select the frame...", ...] }
Tópicos conhecidos:
figma-import — passos para importar designs do Figma
2. Tools de Escrita
find_placement
Sugere coordenadas x/y para posicionar um novo artboard sem sobreposição.
| Campo | Detalhe |
|---|
| Parâmetros | Nenhum (ou dimensões opcionais do artboard planejado) |
| Retorno | Coordenadas x, y sugeridas para posicionamento |
| Uso típico | Encontrar espaço livre no canvas antes de criar um artboard |
| Quando usar | Sempre antes de create_artboard — evita sobreposição |
Exemplo de uso:
→ find_placement()
← { x: 1600, y: 0 }
create_artboard
Cria um novo artboard no canvas.
| Campo | Detalhe |
|---|
| Parâmetros | name (string, opcional) — nome do artboard; styles (object, opcional) — width, height e outros estilos CSS |
| Retorno | ID do artboard criado |
| Uso típico | Criar frames para telas de design; base para escrever HTML |
| Quando usar | Início do workflow de design; criação de novos artboards |
Exemplo de uso:
→ create_artboard({ name: "orders / Lista / desktop", styles: { width: 1440, height: 900 } })
← { id: "new_abc123" }
Nomenclatura padrão do projeto:
[feature-slug] / [Nome da Tela] / [breakpoint]
Exemplos:
orders / Lista de Pedidos / desktoporders / Formulário / mobileauth / Login / desktop
write_html
Parseia HTML e adiciona ou substitui nós no Paper.
| Campo | Detalhe |
|---|
| Parâmetros | id (string) — ID do nó alvo; html (string) — HTML para adicionar; mode (string) — "insert-children" ou "replace" |
| Retorno | IDs dos nós criados |
| Uso típico | Inserir layout HTML estruturado num artboard; popular artboard com conteúdo |
| Quando usar | Após create_artboard para popular o artboard; para atualizar conteúdo existente |
Exemplo de uso:
→ write_html({
id: "new_abc123",
mode: "insert-children",
html: '<div style="display: flex; flex-direction: column; gap: 24px; padding: 32px;">
<h1 style="font-size: 24px; font-weight: 600;">Lista de Pedidos</h1>
</div>'
})
← { nodeIds: ["node_001", "node_002"] }
Modos:
"insert-children" — adiciona os nós HTML como filhos do nó alvo (não remove existentes)"replace" — substitui o conteúdo inteiro do nó alvo pelo novo HTML
Boas práticas para o HTML:
- Use flex layouts (não grid complexo) — melhor compatibilidade
- Use estilos inline (
style=) — o Paper interpreta CSS inline
- Use CSS Variables quando possível para tokens do design system
- Use conteúdo real — não Lorem Ipsum
- Estruture semanticamente — cada seção lógica é um partial potencial em Rails
set_text_content
Define o conteúdo de texto de um ou mais Text nodes (batch).
| Campo | Detalhe |
|---|
| Parâmetros | updates (array) — [{ id: string, text: string }] |
| Retorno | Confirmação dos nós atualizados |
| Uso típico | Atualizar textos em massa; sincronizar conteúdo real; traduzir textos |
| Quando usar | Substituir placeholder text; atualizar conteúdo de Notion/API; traduções |
Exemplo de uso:
→ set_text_content({ updates: [
{ id: "text_001", text: "Gerencie seus pedidos" },
{ id: "text_002", text: "Crie, edite e acompanhe todos os pedidos da plataforma." }
] })
← { updated: ["text_001", "text_002"] }
rename_nodes
Renomeia uma ou mais layers (batch).
| Campo | Detalhe |
|---|
| Parâmetros | updates (array) — [{ id: string, name: string }] |
| Retorno | Confirmação dos nós renomeados |
| Uso típico | Organizar layers com nomes semânticos; preparar estrutura para conversão Rails |
| Quando usar | Após write_html para nomear layers semanticamente |
Exemplo de uso:
→ rename_nodes({ updates: [
{ id: "node_001", name: "page-header" },
{ id: "node_002", name: "order-table" },
{ id: "node_003", name: "empty-state" }
] })
← { renamed: ["node_001", "node_002", "node_003"] }
Nomes semânticos padrão Rails:
page-header, page-content, page-footercard-list, card-item, card-detailform-section, form-actionsmodal-overlay, modal-panelempty-state, loading-statesidebar-nav, breadcrumb
duplicate_nodes
Clona nós profundamente (deep clone).
| Campo | Detalhe |
|---|
| Parâmetros | ids (string[]) — IDs dos nós para clonar |
| Retorno | Novos IDs e mapa de IDs descendentes (old → new) |
| Uso típico | Copiar componentes; criar variações de um design existente |
| Quando usar | Quando precisa de versões mobile/tablet de um artboard desktop; duplicar componentes |
Exemplo de uso:
→ duplicate_nodes({ ids: ["abc123"] })
← { newIds: ["dup_abc123"],
descendantMap: { "abc123": "dup_abc123", "ch1": "dup_ch1", "ch2": "dup_ch2" } }
update_styles
Atualiza estilos CSS de um ou mais nós.
| Campo | Detalhe |
|---|
| Parâmetros | updates (array) — [{ id: string, styles: object }] |
| Retorno | Confirmação dos nós atualizados |
| Uso típico | Ajustar cores, tamanhos, espaçamentos; aplicar design tokens |
| Quando usar | Refinamento visual; aplicar nova paleta; ajustar responsive |
Exemplo de uso:
→ update_styles({ updates: [
{ id: "node_001", styles: { "background-color": "#1e293b", "padding": "24px 32px" } },
{ id: "node_002", styles: { "font-size": "18px", "color": "#94a3b8" } }
] })
← { updated: ["node_001", "node_002"] }
delete_nodes
Deleta um ou mais nós e todos os seus descendentes.
| Campo | Detalhe |
|---|
| Parâmetros | ids (string[]) — IDs dos nós para deletar |
| Retorno | Confirmação dos nós deletados |
| Uso típico | Remover artboards obsoletos; limpar nós indesejados |
| Quando usar | Com cuidado — operação destrutiva e irreversível |
Exemplo de uso:
→ delete_nodes({ ids: ["old_artboard_001"] })
← { deleted: ["old_artboard_001"] }
⚠️ CUIDADO: Esta operação é irreversível. Sempre confirme com o usuário antes de deletar.
3. Tools de Indicadores
start_working_on_nodes
Marca artboards como "em progresso", mostrando um indicador visual no Paper.
| Campo | Detalhe |
|---|
| Parâmetros | ids (string[]) — IDs dos artboards |
| Retorno | Confirmação |
| Uso típico | Feedback visual para o usuário de que o agente está trabalhando |
| Quando usar | No início de operações de criação/modificação de artboards |
Exemplo de uso:
→ start_working_on_nodes({ ids: ["abc123"] })
← { working: ["abc123"] }
finish_working_on_nodes
Remove o indicador de "em progresso" dos artboards.
| Campo | Detalhe |
|---|
| Parâmetros | ids (string[]) — IDs dos artboards |
| Retorno | Confirmação |
| Uso típico | Sinalizar que a operação foi concluída |
| Quando usar | Após concluir criação/modificação; sempre chamar para limpar o indicador |
Exemplo de uso:
→ finish_working_on_nodes({ ids: ["abc123"] })
← { finished: ["abc123"] }
Importante: Sempre chame finish_working_on_nodes após start_working_on_nodes,
mesmo em caso de erro — caso contrário o indicador ficará preso.
Workflows Compostos
Workflow 1: Inspecionar um Design Existente
1. get_basic_info() → verificar conexão + listar artboards
2. get_selection() → ver se há seleção ativa
OU identificar artboard por nome da lista
3. get_tree_summary(id, depth: 3) → entender hierarquia
4. get_screenshot(id, scale: 1) → capturar visual
5. get_jsx(id, format: "tailwind") → obter código do design
6. get_computed_styles(ids[]) → CSS exato dos nós principais
7. get_font_family_info(family) → verificar disponibilidade de fontes
Workflow 2: Criar um Artboard Novo
1. get_basic_info() → verificar conexão
2. find_placement() → coordenadas sem sobreposição
3. create_artboard(name, styles) → criar o artboard
4. start_working_on_nodes([id]) → indicador visual
5. write_html(id, html, "insert-children") → popular com conteúdo
6. rename_nodes(updates) → nomes semânticos nas layers
7. get_screenshot(id, scale: 1) → verificar resultado
8. finish_working_on_nodes([id]) → remover indicador
Workflow 3: Modificar um Artboard Existente
1. get_basic_info() → verificar conexão
2. get_selection() OU get_node_info(id) → localizar nó alvo
3. start_working_on_nodes([artboardId]) → indicador visual
4. get_children(id) → entender estrutura atual
5. write_html(id, html, "replace") → substituir conteúdo
OU update_styles(updates) → ajustar estilos
OU set_text_content(updates) → atualizar textos
6. get_screenshot(id, scale: 1) → verificar resultado
7. finish_working_on_nodes([artboardId]) → remover indicador
Workflow 4: Converter Design → Código (usado por paper-to-rails)
1. get_basic_info() → verificar conexão
2. get_selection() → artboard selecionado
3. get_tree_summary(id, depth: 3) → hierarquia para planejamento
4. get_screenshot(id, scale: 2) → referência visual detalhada
5. get_jsx(id, format: "tailwind") → código base para conversão
6. get_computed_styles(ids[]) → valores exatos para tokens
7. get_fill_image(id) → extrair imagens usadas
8. get_font_family_info(family) → verificar fontes
→ Converter JSX → ERB + Tailwind + i18n (ver skill paper-to-rails)
Workflow 5: Duplicar para Breakpoint Responsivo
1. get_basic_info() → listar artboards existentes
2. duplicate_nodes([desktopArtboardId]) → clonar artboard desktop
3. rename_nodes([{ id: newId, name: "feature / Tela / mobile" }])
4. update_styles([{ id: newId, styles: { width: 390, height: 844 } }])
5. start_working_on_nodes([newId])
6. (ajustar layout interno para mobile — update_styles nos filhos)
7. get_screenshot(newId, scale: 1) → verificar resultado
8. finish_working_on_nodes([newId])
Workflow 6: Sincronizar Conteúdo Real
1. get_basic_info() → verificar conexão
2. get_tree_summary(artboardId, depth: 3) → identificar Text nodes
3. get_children(artboardId) → obter IDs dos nós de texto
4. set_text_content([ → atualizar em batch
{ id: "text_01", text: "Conteúdo real da API/DB" },
{ id: "text_02", text: "Outro conteúdo real" }
])
5. get_screenshot(artboardId) → verificar resultado
Boas Práticas
Performance
- Batch sempre que possível:
get_computed_styles, set_text_content, rename_nodes,
update_styles aceitam múltiplos IDs — use uma chamada com array em vez de múltiplas chamadas
- Limite profundidade: Use
depth em get_tree_summary para artboards grandes
- Scale 1x primeiro: Use
scale: 1 em get_screenshot para verificação rápida; 2 apenas quando necessário
Robustez
- Verifique conexão: Sempre comece com
get_basic_info()
- Indicadores: Sempre pareie
start_working_on_nodes com finish_working_on_nodes
- Verificação visual: Capture
get_screenshot após cada operação de escrita
- Confirme antes de deletar:
delete_nodes é irreversível — peça confirmação ao usuário
Estrutura de Design (para conversão Rails)
- Use flex layouts (não grid CSS complexo)
- Use estilos inline no HTML escrito via
write_html
- Use conteúdo real — nunca Lorem Ipsum
- Nomeie layers com
rename_nodes usando nomes semânticos Rails
- Estruture como partials potenciais: cada seção lógica = um partial
Nomenclatura de Artboards
[feature-slug] / [Nome da Tela] / [breakpoint]
Breakpoints padrão:
| Breakpoint | Dimensões | Uso |
|---|
desktop | 1440 × 900 | Principal |
tablet | 768 × 1024 | Opcional |
mobile | 390 × 844 | Responsivo |
Troubleshooting
| Problema | Causa Provável | Solução |
|---|
get_basic_info falha | Paper Desktop não está aberto | Abrir o app com um arquivo |
| Tools retornam erro de conexão | MCP server não iniciou | Reabrir arquivo no Paper Desktop |
| Agente "não vê" as tools | Sessão longa/corrompida | Reiniciar sessão do agente |
| Tool call com parâmetros errados | Hallucination do LLM | Reiniciar sessão; usar esta referência |
| Artboards sobrepostos | Não usou find_placement | Sempre chamar antes de create_artboard |
| Indicador "working" preso | finish_working_on_nodes não chamado | Chamar manualmente com os IDs |
| Windows WSL: conexão recusada | Rede WSL isolada | Habilitar mirrored mode networking |
| Limites não resetados após upgrade | Bug em versões antigas | Atualizar Paper Desktop: About > Check for updates |
Relação com Outras Skills
| Skill | Relação |
|---|
design-in-paper | Usa esta skill — cria artboards a partir de PRDs |
paper-to-rails | Usa esta skill — lê designs e converte para ERB |
tailwind-design-system | Fornece tokens para write_html e mapeamento em get_computed_styles |
frontend-design | Princípios de design aplicados na criação de artboards |
rails-visual-design | Fallback quando Paper MCP não está disponível |
executa-task | Aciona paper-to-rails que usa esta skill indiretamente |
Links de Referência
