Skip to main content
Glama

Aseprite MCP Server

Servidor Model Context Protocol (MCP) de código aberto em TypeScript que conecta clientes de IA (como Google Gemini, Claude Desktop e outros clientes compatíveis com MCP) ao editor de pixel art Aseprite.

NOTE

Projeto Comunitário Não Oficial: Este projeto é desenvolvido de forma independente pela comunidade e não é afiliado, patrocinado ou endossado pelos criadores do Aseprite (David Capello / Igara Studio S.A.).

O servidor permite inspecionar sprites, ler pixels, editar imagens, controlar camadas, frames e animações, validando cada alteração por meio de previews PNG gerados pelo motor do Aseprite. A comunicação com o Aseprite ocorre via WebSocket loopback local por meio de um script bridge em Lua, sem emulação de cliques de mouse e com políticas estritas de proteção de arquivos.

Fluxo principal:

Observar -> analisar -> editar -> inspecionar novamente -> corrigir

Recursos principais

  • Inspeção visual rica: previews em PNG com escala nearest-neighbor, réguas de coordenadas e grades customizáveis.

  • Leitura precisa de pixels: formatos hexadecimal (#RRGGBBAA), RGBA, indexado e compacto otimizado para economia de tokens.

  • Edição em lote e Undo atômico: operações em lote agrupadas em uma única entrada de histórico de Undo.

  • 138 ferramentas MCP tipadas: pixels, formas, referências locais, arquivos, camadas/grupos, frames/tags, cels, slices, seleções, tilesets/tilemaps, preview animado, revisão visual, análise de pixel art, tween, smear, aprovação humana, pintura ao vivo, ações direcionais e exportação para engines.

  • Estrutura nativa do Aseprite: cels vinculados, grupos aninhados, pivôs/nine-patch, blend modes, merge/flatten e exportação avançada por tag, intervalo e camada.

  • Ciclo visual incremental: preview opcional após mutações, filmstrip, onion skin, comparação exata entre frames, checkpoints e histórico de alterações por revisão.

  • Qualidade de pixel art: lint heurístico, CIEDE2000, análise de paleta, rampas com hue shift e dithering Bayer determinístico.

  • Segurança de arquivos: contenção estrita de caminhos (ASEPRITE_ALLOWED_PATHS), política no-clobber por padrão (overwrite: true explícito) e validação de arquivo esperado no salvamento.

  • Bridge autenticável e versionado: handshake obrigatório, sessão identificada, compatibilidade de protocolo verificada e token opcional (ASEPRITE_BRIDGE_TOKEN).

  • Superfície configurável: modo somente leitura e seleção de toolsets para reduzir risco e custo de descoberta.

  • Mock Bridge em memória: possibilita testes de integração rápidos e headless sem necessidade de abrir a interface do Aseprite.

  • Transporte padrão stdio: mensagens de protocolo MCP isoladas em stdout e registros de diagnóstico em stderr.

  • Conexão persistente compartilhada: um daemon local invisível mantém o único socket do Aseprite, enquanto todas as instâncias stdio entram como pares autenticados e podem abrir ou encerrar sem derrubar a conexão do editor.


Related MCP server: Aseprite MCP Tools

Arquitetura

Cliente MCP (Gemini / Claude / outros)
    |
    | MCP sobre stdio
    v
Aseprite MCP Server (Node.js/TypeScript)
    |
    | par autenticado do daemon local
    v
Daemon persistente (Node.js; loopback por padrão)
    ^
    | iniciado pela extensão empacotada
Bridge Lua no Aseprite (aseprite-bridge.lua)
    |
    v
Documento ativo no Aseprite

O servidor registra as ferramentas MCP, valida parâmetros de entrada e encaminha comandos em envelopes correlacionados por ID ao bridge Lua. Antes de aceitar comandos, servidor e bridge concluem um handshake hello/hello_ack com versão, sessão, capacidades e revisão. Uma sessão reconectada pode pedir ressincronização e consultar alterações estruturadas desde uma revisão conhecida.


Requisitos

  • Node.js: versão 18.0.0 ou superior.

  • npm: gerenciador de pacotes incluso no Node.js.

  • Aseprite: versão v1.2.30+ ou v1.3+ com suporte à API WebSocket em Lua.

  • PowerShell: para execução dos scripts de conveniência no Windows.


Instalação rápida

Usuário final: extensão recomendada

No Aseprite, abra Edit > Preferences > Extensions > Add Extension e selecione o arquivo aseprite-mcp-bridge.aseprite-extension distribuído com o projeto. Ao abrir o editor, a extensão inicia o bridge e o daemon local empacotado; a janela do editor passa por Starting bundled MCP server, Connecting e Connected.

Isso elimina copiar o Lua e abrir um terminal para iniciar o bridge. O Node.js continua necessário como runtime local, e o cliente de IA ainda precisa apontar para dist/index.js uma vez, conforme a seção de configuração do cliente MCP.

Antes de editar, execute aseprite_status e confirme connected: true.

Desenvolver ou empacotar a extensão

Clone o repositório e navegue até a pasta:

git clone https://github.com/Zythenth/MCP-Aseprite.git
cd MCP-Aseprite

Windows (instalação de desenvolvimento ou script legado)

No PowerShell:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1

O script install.ps1:

  1. Verifica Node.js >= 18 e npm;

  2. Instala as dependências via npm ci --ignore-scripts --no-audit --no-fund;

  3. Compila o projeto TypeScript gerando dist/;

  4. Executa a suíte de testes (a menos que -SkipTests seja informado);

  5. Verifica que servidor e bridge declaram a mesma versão de protocolo;

  6. Copia lua/aseprite-bridge.lua para %APPDATA%\Aseprite\scripts caso o Aseprite seja detectado (ou se -InstallLuaToAseprite for fornecido) e confere o SHA-256 da cópia.

Instalação manual (Todas as plataformas)

npm ci --ignore-scripts --no-audit --no-fund
npm run build
npm test

O ponto de entrada compilado será gerado em dist/index.js.


Instalação do Bridge no Aseprite

Extensão em um clique (recomendado)

Para gerar o pacote a partir do código-fonte, execute npm run build e npm run package:extension. O resultado é dist/aseprite-mcp-bridge.aseprite-extension. No Aseprite, use Edit > Preferences > Extensions > Add Extension e selecione esse arquivo. A extensão inclui o daemon compilado e a dependência WebSocket, inicia-o localmente quando o editor abre e mantém uma pequena janela com Starting bundled MCP server, Connecting, Connected ou reconexão. Não é necessário copiar Lua nem abrir um terminal para iniciar o bridge.

A extensão não baixa executáveis: o runtime Node.js já instalado continua sendo um requisito. Use ASEPRITE_NODE_PATH somente se node não estiver no PATH. O daemon inicia no host/porta já configurados e permanece em loopback por padrão; ela não abre portas públicas.

Script avulso (legado)

Caso o script não tenha sido copiado automaticamente pelo instalador:

  1. Abra o Aseprite;

  2. Acesse o menu File > Scripts > Open Scripts Folder;

  3. Copie o arquivo lua/aseprite-bridge.lua para dentro da pasta aberta;

  4. No Aseprite, clique em File > Scripts > Rescan Scripts Folder;

  5. Execute File > Scripts > aseprite-bridge.

O diálogo do bridge exibirá o estado da conexão (Connecting..., Connected ou Disconnected (Reconnecting...)). Ele tenta se conectar ao servidor em 127.0.0.1:PORT e reconecta automaticamente. Se a retomada nativa do WebSocket não abrir uma sessão em até seis segundos, o bridge substitui a conexão automaticamente; não é necessário clicar em Reconnect.

Inspeções de canvas e previews retornados pelas ferramentas de pintura são transportados em memória e não precisam gravar PNG temporário. Na primeira exportação ou preview temporal que precise gravar GIF/PNG, o Aseprite ainda pode pedir autorização de arquivo. Depois de conferir que o caminho exibido é exatamente o aseprite-bridge.lua instalado na pasta de scripts, marque Give full trust to this script e confirme Give Script Full Access para não repetir a confirmação a cada saída. Não conceda essa confiança a outro script ou a uma cópia cuja origem você não verificou.

IMPORTANT

Não edite o arquivo lua/aseprite-bridge.lua para alterar a porta. A porta e o token de autenticação são lidos dinamicamente das variáveis de ambiente (ASEPRITE_PORT e ASEPRITE_BRIDGE_TOKEN). Como o Aseprite é um processo independente, configure essas variáveis no ambiente do sistema ou do usuário e reinicie o Aseprite.


Configuração de Segurança e Ambiente

1. Política de Acesso a Arquivos (ASEPRITE_ALLOWED_PATHS)

Para impedir que comandos abram ou salvem arquivos fora das pastas do seu projeto, o servidor restringe operações de arquivo às raízes configuradas em ASEPRITE_ALLOWED_PATHS:

  • Formato: lista de caminhos absolutos existentes separados por ; no Windows ou : em ambientes POSIX.

  • Padrão: caso a variável esteja ausente ou vazia, o servidor restringe o acesso ao diretório atual (process.cwd()), resolvido canonicamente via realpath.

  • Contenção e Symlinks: links simbólicos que apontam para arquivos dentro das raízes permitidas são resolvidos e aceitos; links simbólicos que apontam para fora das raízes são bloqueados. Alvos de salvamento não podem ser symlinks existentes.

  • Extensões: .ase, .aseprite e .png para leitura (open_sprite) e gravação (save_sprite_as); exclusivamente .png para export_png.

  • Proteção No-Clobber: save_sprite_as e export_png nunca sobrescrevem arquivos existentes por padrão. Para sobrescrever intencionalmente, é necessário passar o parâmetro overwrite: true.

  • Salvamento Seguro (save_sprite): a ferramenta save_sprite não recebe caminho do usuário nem parâmetro de rota (é invocada sem argumentos). Ela opera diretamente sobre o arquivo já associado ao sprite ativo no Aseprite (app.sprite.filename). A validação de integridade expectedFilePath é realizada internamente pelo servidor MCP consultando aseprite_status antes de despachar o comando ao bridge Lua, que verifica a coincidência exata do caminho antes de executar o salvamento.

1.1. Raiz do projeto (ASEPRITE_PROJECT_ROOT)

ASEPRITE_PROJECT_ROOT define a base para caminhos relativos de referências, projetos e exports. Ela deve ser um diretório absoluto existente contido em uma das raízes de ASEPRITE_ALLOWED_PATHS; quando omitida, usa a primeira raiz autorizada.

  • references/heroi.png é resolvido sob a raiz do projeto, nunca sob uma pasta arbitrária do computador.

  • find_reference_images faz busca limitada por profundidade, quantidade de resultados e total de entradas; não percorre links simbólicos.

  • load_reference_image aceita PNG, JPEG e WebP, valida tamanho e dimensões antes da decodificação e não altera o documento ativo.

  • save_project grava somente .aseprite, preserva exatamente um nome fornecido e mantém no-clobber por padrão.

2. Autenticação por Token no WebSocket (ASEPRITE_BRIDGE_TOKEN)

Por padrão, o bridge conecta-se localmente em 127.0.0.1. Para adicionar uma barreira extra contra acessos locais não autorizados de outros softwares rodando na máquina:

  • Formato: token de 16 a 128 caracteres contendo apenas caracteres URL-safe ASCII ([A-Za-z0-9._~-]).

  • Geração: gere um token seguro de 32 bytes aleatórios executando:

    node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
  • Configuração no Aseprite (Windows): Como o Aseprite é executado separadamente, defina as variáveis no nível do usuário:

    [Environment]::SetEnvironmentVariable("ASEPRITE_PORT", "32123", "User")
    [Environment]::SetEnvironmentVariable("ASEPRITE_BRIDGE_TOKEN", "seu-token-gerado", "User")

    Após definir, reinicie o Aseprite e o cliente MCP para carregar as novas variáveis.

  • Validação e Privacidade: a validação é feita em tempo constante (crypto.timingSafeEqual). O token nunca é impresso em logs, console, diálogos ou mensagens de erro. A interface do Aseprite exibe apenas [Auth: enabled] ou [Auth: disabled].

  • Aviso: conexões no loopback e tokens de autenticação mitigam conexões acidentais ou não autorizadas no host local, mas não eliminam todos os riscos em sistemas compartilhados. Se nenhum token for configurado, o servidor emitirá um aviso único na inicialização indicando que a autenticação no loopback está desabilitada.

O token não é colocado na URL. Ele é enviado somente no primeiro envelope de handshake. O servidor fixa o primeiro bridge autenticado e pronto como cliente ativo; conexões candidatas não substituem uma sessão ativa.

3. Modo somente leitura e toolsets

  • ASEPRITE_READ_ONLY=1 não registra ferramentas que alteram o sprite ou gravam arquivos. Inspeção, análise e abertura de documento permanecem disponíveis.

  • ASEPRITE_TOOLSETS recebe uma lista separada por vírgulas. Valores aceitos: core, visual, editing, files, shapes, layers, frames, palette, cels, slices, selection, tiles, animation, pixel-art e review.

  • core (aseprite_status) é sempre incluído. O valor ausente, vazio ou all ativa todos os conjuntos.

Exemplo enxuto para um agente revisor:

.\start.ps1 -ReadOnly -Toolsets visual,palette,animation,pixel-art,review

4. Agente em VM, WSL ou LAN privada

O padrão é sempre loopback. Para um agente em VM/WSL/LAN, habilite explicitamente ASEPRITE_REMOTE_MODE=true, use um ASEPRITE_HOST IPv4 privado (somente 10/8, 172.16/12 ou 192.168/16), um token de pelo menos 32 caracteres e uma allowlist de IPs privados em ASEPRITE_REMOTE_PEERS. O bridge rejeita bind público, wildcard e DNS, e o daemon rejeita qualquer cliente que não esteja na allowlist mesmo com token válido.

$env:ASEPRITE_REMOTE_MODE = "true"
$env:ASEPRITE_HOST = "192.168.1.10"
$env:ASEPRITE_REMOTE_PEERS = "192.168.1.42"
$env:ASEPRITE_BRIDGE_TOKEN = "gere-um-token-url-safe-com-pelo-menos-32-caracteres"

Não configure encaminhamento de porta no roteador. Para redes fora da LAN, use uma VPN privada que forneça endereços privados e inclua o IP do agente na allowlist.

4. Limites operacionais

O servidor limita payloads do bridge, comandos pendentes, dimensões de canvas, pixels por lote, frames de filmstrip/spritesheet, tamanho do checkpoint e cardinalidade da análise de paleta. Esses limites são proteções contra consumo acidental de memória/CPU; não constituem uma sandbox para processos locais já comprometidos.


Configuração do Cliente MCP

Exemplo Mínimo (Padrão)

No arquivo de configuração do seu cliente MCP (por exemplo, gemini-mcp-config.json ou configuração do Claude Desktop):

{
  "mcpServers": {
    "aseprite": {
      "command": "node",
      "args": [
        "C:/caminho/para/MCP-Aseprite/dist/index.js"
      ],
      "env": {
        "ASEPRITE_PORT": "32123",
        "ASEPRITE_ALLOWED_PATHS": "C:/Projetos/PixelArt",
        "ASEPRITE_PROJECT_ROOT": "C:/Projetos/PixelArt"
      }
    }
  }
}

Exemplo Endurecido (Com Token e Múltiplas Raízes)

NOTE

O valor"SubstituaPeloSeuTokenAleatorio12345" abaixo é um marcador de posição demonstrativo com charset URL-safe válido ([A-Za-z0-9._~-], entre 16 e 128 caracteres). Substitua-o pelo token seguro gerado no seu ambiente.

{
  "mcpServers": {
    "aseprite": {
      "command": "node",
      "args": [
        "C:/caminho/para/MCP-Aseprite/dist/index.js"
      ],
      "env": {
        "ASEPRITE_PORT": "32123",
        "ASEPRITE_ALLOWED_PATHS": "C:/Projetos/PixelArt;D:/Assets/Sprites",
        "ASEPRITE_PROJECT_ROOT": "C:/Projetos/PixelArt",
        "ASEPRITE_BRIDGE_TOKEN": "SubstituaPeloSeuTokenAleatorio12345"
      }
    }
  }
}

Skill de projeto para Gemini/Antigravity

O repositório inclui a skill aseprite em .agents/skills/aseprite/SKILL.md. O Antigravity descobre automaticamente skills de workspace versionadas quando o projeto é aberto pela raiz, permitindo que todas as pessoas que clonarem o repositório usem o mesmo fluxo seguro de criação, revisão e salvamento.

Depois de conectar o servidor MCP aseprite, atualize as customizações ou reinicie o Antigravity e inicie o pedido com:

/aseprite

Crie uma animação no Aseprite usando exclusivamente as ferramentas aseprite/.

A skill proíbe o uso de Python, terminal e scripts auxiliares para gerar pixels, exige edição por coordenadas explícitas, preview, análise temporal, revisão e verificação dos arquivos finais. Ela complementa as instruções enviadas automaticamente pelo próprio servidor MCP.

IMPORTANT

Várias conversas compartilham o mesmo bridge persistente. A extensão inicia o daemon local ao abrir o Aseprite; cada cliente stdio mantém sua própria sessão MCP e entra como par desse daemon. O daemon permanece ativo depois que as conversas terminam, portanto o socket do Aseprite não é derrubado quando uma tarefa fecha. Novas conversas apenas reutilizam a conexão existente. Uma porta ocupada por outro programa ou um token divergente continua sendo rejeitada e reavaliada automaticamente.


Execução Manual e Scripts

Para diagnóstico standalone (não junto com um cliente MCP configurado), execute:

npm start

No Windows via PowerShell:

# Execução standalone explícita
.\start.ps1 -ManualBridgeServer

# Especificando porta, diretórios autorizados e a raiz para caminhos relativos
.\start.ps1 -ManualBridgeServer -Port 32123 -AllowedPaths @("C:\Projetos\PixelArt") -ProjectRoot "C:\Projetos\PixelArt"

# Execução com Mock Bridge (headless, sem Aseprite)
.\start.ps1 -ManualBridgeServer -Mock

# Revisão sem mutações, expondo apenas conjuntos necessários
.\start.ps1 -ManualBridgeServer -ReadOnly -Toolsets visual,palette,animation,pixel-art,review
TIP

Segurança de Segredos no Terminal: Evite passar -BridgeToken como argumento de linha de comando para não gravar segredos no histórico do shell (Get-History, .bash_history) ou na listagem de processos do sistema. Prefira sempre definir a variável de ambiente $env:ASEPRITE_BRIDGE_TOKEN na sessão do terminal ou nas variáveis de ambiente de usuário antes de executar o script.


Resumo das Ferramentas MCP

O conjunto completo contém 138 ferramentas únicas. Para reduzir o contexto enviado ao modelo, exponha somente os toolsets necessários.

Inspeção Visual e Leitura

  • aseprite_status: Estado da conexão, arquivo ativo, tamanho do canvas, camada e frame selecionados e revisão atual.

  • get_sprite_info: Estrutura hierárquica de camadas, frames, opacidades e blend modes.

  • inspect_sprite: Preview PNG combinado com matriz de dados de pixels.

  • get_canvas: Renderiza o canvas completo ou uma camada isolada como PNG.

  • get_pixel_grid: Extração matricial de pixels (formatos hex, rgba ou compact).

  • get_pixel_grid_preview: Visualização ampliada com réguas de coordenadas e grade de pixels.

Edição de Pixels e Formas

  • set_pixels: Aplicação de pixels em lote com Undo atômico.

  • set_pixel: Aplicação de pixel único.

  • erase_pixels: Limpeza de pixels para transparência (#00000000).

  • draw_line, draw_rectangle, draw_ellipse: Rasterização de formas geométricas.

  • flood_fill, replace_color: Preenchimento por tolerância e substituição de cores.

  • undo, redo: Controle do histórico de edição.

Camadas, grupos e composição

  • Básico: list_layers, create_layer, rename_layer, delete_layer, select_layer, set_layer_visibility, set_layer_opacity, move_layer, create_group.

  • Hierarquia: list_layer_tree, move_layer_to_group, ungroup_layer.

  • Composição: set_layer_blend_mode, merge_down_layer, flatten_layers.

Frames, tags e inspeção de animação

  • Frames/tags: list_frames, select_frame, create_frame, duplicate_frame, move_frame, delete_frame, set_frame_duration, set_frame_durations, create_tag, list_tags, update_tag, delete_tag.

  • Revisão: get_onion_skin, get_filmstrip, compare_frames, inspect_animation, render_animation_preview.

  • inspect_animation combina frames, durações, tags, repetição, ordem efetiva de playback, camadas e cobertura de cels em uma resposta estruturada.

  • render_animation_preview retorna primeiro um GIF reproduzível e depois um contact sheet PNG na mesma ordem temporal, com previewId, timing, FPS médio e revisão observada.

  • Tags aceitam forward, reverse, pingpong e pingpong_reverse; repeats: 0 representa loop contínuo.

Cels, slices e seleções

  • Cels: get_cel, create_cel, copy_cel, move_cel, delete_cel, set_cel_position, set_cel_opacity, link_cel, unlink_cel. Por segurança, move_cel move o cel entre frames da mesma camada; para copiar entre camadas, use copy_cel.

  • Slices: list_slices, get_slice, create_slice, update_slice, delete_slice, incluindo centro nine-patch e pivô.

  • Seleção persistente: get_selection, set_selection, clear_selection, invert_selection. set_selection oferece substituição, união, subtração e interseção retangulares.

Tilesets e tilemaps

  • list_tilesets, create_tileset, delete_tileset, get_tile, set_tile_pixels.

  • create_tilemap_layer, get_tilemap, set_tiles, incluindo índices e flags de espelhamento X/Y/diagonal.

Pixel art, checkpoints e waivers

  • lint_pixel_art: encontra indícios de pixels órfãos, outline interrompido, banding, pillow shading, drift de simetria e seams. Resultados são heurísticos e nunca corrigidos automaticamente.

  • analyze_palette, find_perceptual_palette_color, generate_palette_ramp, apply_ordered_dither.

  • create_review_checkpoint, list_review_checkpoints, compare_review_checkpoint, delete_review_checkpoint.

  • add_lint_waiver, list_lint_waivers, delete_lint_waiver. Checkpoints e waivers são vinculados à sessão atual e mantidos apenas em memória.

Workflow de animação e edição atômica

  • batch_animation_edits valida antecipadamente uma lista fechada de operações de pixels, posição/opacidade de cel e duração; uma execução efetiva forma uma única transação de Undo e respeita limites de payload, operações, frames e pixels.

  • O workflow estruturado registra a referência carregada e sua análise, plano e key poses, preview da revisão atual, revisão das poses, autoavaliação nas 22 categorias e QA independente (reviewerId diferente de authorId).

  • analyze_animation_temporal produz achados temporais determinísticos e limitados, com hash da seleção/revisão analisada.

  • Qualquer mutação invalida previews e revisões anteriores. Achados críticos abertos, achados altos não tratados, QA ausente/reprovada ou evidência obsoleta impedem a conclusão.

  • create_pixel_art_tween gera intermediários entre duas poses-chave movendo clusters 4-conectados da mesma cor; não mistura alfa, redimensiona ou suaviza pixels. Os frames produzidos exigem inspeção com get_canvas, preview temporal e QA.

  • create_smear_frame insere um único frame de smear nítido entre keyframes normais, calculando a direção a partir dos limites ocupados e preservando as poses original e final.

  • request_human_approval abre um diálogo nativo no Aseprite com preview, Aprovar, Pedir alterações e Rejeitar. O recibo aprovado pode ser exigido antes de um export final.

Ações direcionais

  • plan_directional_animation compõe o plano para caminhada, corrida, idle, ataque corpo a corpo/à distância, hit, morte, dash, cast e interação em 4 ou 8 direções. Ele produz nomes de tags, timing, poses, eventos de engine e critérios de QA com base em frames, FPS, passada e estilo; hit aceita opcionalmente força máxima de recoil e tipo de dano.

  • create_directional_animation_timeline duplica uma pose-base para criar os slots editáveis de cada direção e suas tags. Os slots não são declarados como arte final: o agente deve desenhar as poses indicadas antes da revisão.

  • generate_directional_animation_from_key_poses cria automaticamente todos os frames finais para cada direção a partir de duas ou mais poses-chave já desenhadas para aquela direção. Ele preserva pixels nítidos com interpolação de clusters 4-conectados da mesma cor, registra quais intermediários foram produzidos e pede inspeção visual antes do export.

  • analyze_directional_animation verifica tags, timing, frames repetidos, bounds, jitter, paleta, loop, pontos exatos de contato para detectar foot sliding, contatos contra uma linha de chão, amplitude vertical e trilhas explícitas das duas mãos para confirmar balanço alternado. Na corrida, walkReference verifica que FPS e passada superam os da caminhada, e walkContactFrameCount comprova contato com o chão mais curto.

  • assess_directional_mirroring exige uma decisão explícita para espada em uma mão, texto, cicatrizes, iluminação ou equipamento assimétrico. mirror_directional_animation só espelha depois dessa aprovação e cria um novo tag sem sobrescrever o original.

  • Os eventos retornados pelo plano (impact/shot, final_pose, dash_*, cast_* e interaction_contact) incluem os frames por direção e podem ser encaminhados diretamente ao parâmetro events de export_engine_assets.

  • Interações exigem targetHeightPx, targetOffsetX e targetOffsetY, evitando templates cegos para objetos em alturas ou posições diferentes.

Fluxo curto: plan_directional_animation → key poses/timeline → preview + análise → decisão explícita antes do espelhamento.

Modo pintura ao vivo

  • start_live_painting inicia um processo observável e devolve o PNG inicial. Ele aceita as etapas sketch, blocks, silhouette, line, base_colors, shadows, details e polish, além de velocidade e modo comentário.

  • Para cada etapa, o agente deve chamar begin_live_painting_stage, fazer exatamente uma mutação atômica no Aseprite e chamar complete_live_painting_stage. A conclusão retorna o PNG atualizado, de modo que a construção fica visível no canvas e registrada no log.

  • pause_live_painting, continue_live_painting, cancel_live_painting, set_live_painting_speed e undo_live_painting_stage fornecem os controles do processo. Enquanto ativo, o MCP bloqueia edições fora da etapa aberta; cada etapa contém uma única transação do Aseprite para que o Undo da etapa seja seguro. Cancelar não apaga silenciosamente a arte já feita.

  • get_live_painting_status, list_live_painting_snapshots, get_live_painting_snapshot e render_live_painting_replay permitem acompanhar e revisar o log visual. Os snapshots ficam apenas em memória, até 16 imagens e 64 MiB por processo, e são descartados se a conexão ou o documento mudar.

  • A velocidade é uma recomendação de espaçamento entre snapshots visíveis: slow 900 ms, normal 350 ms e fast 100 ms. Com commentaryMode: true, cada etapa exige uma explicação curta do agente.

Arquivos e exportação

  • find_reference_images: localiza PNG, JPEG e WebP por nome somente em diretórios autorizados, com busca recursiva limitada.

  • load_reference_image: retorna a imagem de referência, dimensões, formato, transparência, hash e análise de paleta sem trocar o sprite ativo.

  • new_sprite, open_sprite, save_sprite, save_sprite_as, save_project, export_png, resize_canvas.

  • export_sprite_sheet: exporta por tag ou intervalo explícito, filtra camadas e organiza frames horizontalmente, verticalmente ou em grade, respeitando direção da tag, escala, espaçamento e no-clobber.

  • export_animation: exporta a ordem efetiva de uma tag ou intervalo como GIF, spritesheet, sequência PNG ou PNG único. A sequência PNG usa nomes determinísticos e remove arquivos novos já escritos se uma execução no-clobber falhar parcialmente. Com final: true, o gate é aplicado quando o workflow ativo exige conclusão estrita ou quando strictWorkflowValidation: true; o resultado aceito inclui evidência compacta vinculada à revisão, preview, revisão das poses, autoavaliação e QA atuais.

  • export_engine_assets: gera um spritesheet PNG, SpriteFrames do Godot (.tres) e metadata de importação Unity (.engine.json), preservando tags, durações, pivô de slice e eventos declarados.

  • batch_export_sprites: processa até 256 arquivos .ase/.aseprite sob um diretório autorizado, exporta PNG ou spritesheet em escalas inteiras (por exemplo, 1x/2x/4x), aplica no-clobber e restaura o documento original salvo.

  • APNG é rejeitado antes de qualquer comando ao bridge; nenhum PNG estático é apresentado falsamente como APNG. A decisão é intencional: a documentação oficial de exportação, a CLI oficial e o registro atual de formatos do Aseprite não expõem um encoder APNG. Adicionar um encoder Node de terceiros ampliaria a superfície de dependências e manutenção sem suporte nativo verificável; a interface mantém apng apenas para retornar uma incompatibilidade explícita e estável.

Ferramentas destrutivas exigem confirm: true; gravações em caminho existente exigem overwrite: true. Mutações com returnPreview: true retornam a imagem como conteúdo MCP sem repetir o base64 no bloco textual.


Testes e integração contínua

  • Testes unitários, de contrato, integração e E2E executados pelo Vitest; a configuração falha se uma seleção de testes não encontrar casos.

  • O mock cobre o protocolo, recuperação incremental e as estruturas expostas pelas ferramentas.

  • test/real/aseprite-api-smoke.lua valida contratos críticos dentro de um processo Aseprite real, incluindo as APIs usadas por cópia/movimentação de cels, reordenação e duração de frames, atualização/exclusão de tags e Undo/Redo atômico.

  • O workflow de CI executa Node.js 18/20/22 e os sistemas Linux, Windows e macOS; um job separado compila a versão do Aseprite fixada no workflow e roda o smoke test real.

  • O smoke local real depende de um executável Aseprite disponível; os testes headless do Node não substituem essa validação da API Lua.


Solução de problemas

O bridge permanece desconectado no Aseprite

  1. Confirme que a extensão está instalada e que o diálogo exibiu Connected. Ela inicia o daemon local automaticamente ao abrir o Aseprite.

  2. Verifique se a porta coincide (ASEPRITE_PORT, padrão 32123).

  3. Se você configurou ASEPRITE_BRIDGE_TOKEN no servidor MCP, confirme que a mesma variável foi definida no ambiente do Aseprite e que o Aseprite foi reiniciado.

  4. Tentativas com token divergente são rejeitadas com o código 1008 (Invalid bridge authentication).

Erro de acesso negado em operações de arquivo

  • Se receber Access denied: path is outside allowed roots, adicione o diretório do arquivo à variável ASEPRITE_ALLOWED_PATHS.

  • Certifique-se de que os caminhos em ASEPRITE_ALLOWED_PATHS sejam absolutos e usem ; como separador no Windows.

  • Para usar caminhos relativos, defina ASEPRITE_PROJECT_ROOT dentro de uma das raízes autorizadas.

Arquivo já existe e não é salvo

  • Por padrão, o servidor adota a política no-clobber. Ao salvar em um arquivo existente via save_sprite_as ou exportar via export_png, inclua "overwrite": true nos argumentos da ferramenta.


Licença

Distribuído sob a licença MIT. Consulte o arquivo LICENSE para obter mais informações.

Available Tools

43 tools
aseprite_statusB

Returns connection status with Aseprite, open document details, dimensions, color mode, layers, frames, active layer/frame, and revision.

Inputs: no named parameters.

create_frameA

Creates a new blank animation frame after the specified frame or at the end.

Inputs: duration, afterFrame.

create_groupC

Creates a folder layer group for organizing layers.

Inputs: name (required).

create_layerB

Creates a new image layer in the active sprite.

Inputs: name (required), parentGroup.

create_tagC

Creates an animation tag for a range of frames (e.g. 'walk', 'idle').

Inputs: name (required), toFrame (required), fromFrame (required), color.

delete_frameB

Deletes an animation frame. Requires confirm: true.

Inputs: confirm (required), frameNumber (required).

delete_layerB

Deletes a layer from the active sprite. Requires confirm: true for safety.

Inputs: name (required), confirm (required).

draw_ellipseB

Draws an ellipse (outline or filled) within a bounding box in a single undo transaction.

Inputs: x (required), y (required), color (required), width (required), +6 more.

draw_lineB

Draws a pixel art line from (x1, y1) to (x2, y2) using Bresenham's algorithm in a single undo transaction.

Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +6 more.

draw_rectangleA

Draws a rectangle (outline or filled) on the canvas in a single undo transaction.

Inputs: x (required), y (required), color (required), width (required), +6 more.

duplicate_frameC

Duplicates an existing frame and its cels.

Inputs: frameNumber (required).

erase_pixelsB

Erases a list of pixel coordinates by turning them transparent (#00000000) within a single undo transaction.

Inputs: points (required), layerName, layerIndex, frameNumber, +1 more.

export_pngC

Exports the active sprite or frame to a PNG image file on disk.

Inputs: outputPath (required), scale, frameNumber.

find_palette_colorB

Finds exact or nearest color match in the active palette using Euclidean distance.

Inputs: color (required), findNearest.

flood_fillB

Fills a contiguous area of matching pixels starting from (x, y) with color in a single undo transaction.

Inputs: x (required), y (required), color (required), layerName, +4 more.

get_canvasB

Renders the active sprite canvas/frame as a crisp PNG image using nearest-neighbor scaling. Returns official MCP image content.

Inputs: scale, layerName, frameIndex, checkerboard.

get_changes_sinceA

Differential inspection: returns modified regions and pixel deltas since a specified revision number, avoiding re-reading the entire canvas.

Inputs: sinceRevision (required).

get_paletteA

Retrieves all colors in the active sprite's color palette with index, RGBA, and HEX values.

Inputs: no named parameters.

get_pixel_gridA

Returns exact pixel values from the canvas or cel in absolute canvas coordinates (0,0 is top-left). Supports hex, rgba, indexed, or token-saving compact format.

Inputs: format, region, layerName, frameIndex, +1 more.

get_pixel_grid_previewB

Generates an enlarged visual inspection PNG with nearest-neighbor scaling, 1px pixel grid separators, X/Y coordinate rulers, and optional highlights.

Inputs: scale, showGrid, frameIndex, checkerboard, +3 more.

get_sprite_infoA

Returns complete structural information about the active sprite, including dimensions, color mode, layers hierarchy, animation frames, active layer/frame, and revision.

Inputs: no named parameters.

inspect_spriteA

PRIMARY VISION TOOL: Inspects the active sprite. In a single call returns: crisp PNG image content, sprite dimensions, active layer and frame, revision, and compact pixel matrix.

Inputs: scale, format, frameIndex, includePixels.

list_framesA

Lists all animation frames with their frame numbers and durations in milliseconds.

Inputs: no named parameters.

list_layersA

Lists all layers in the active sprite with visibility, opacity, blend mode, and hierarchy position.

Inputs: no named parameters.

list_tagsB

Lists all animation tags defined in the sprite.

Inputs: no named parameters.

move_layerC

Reorders a layer position in the layer stack.

Inputs: name (required), targetIndex (required).

new_spriteC

Creates a new blank sprite document in Aseprite with specified dimensions and color mode.

Inputs: width, height, colorMode.

open_spriteB

Opens an existing sprite file (.ase, .aseprite, .png) from disk.

Inputs: filePath (required).

redoA

Redoes the most recently undone editing operation on the active sprite.

Inputs: no named parameters.

rename_layerC

Renames an existing layer.

Inputs: newName (required), oldName (required).

replace_colorC

Replaces all occurrences of fromColor with toColor across the cel or sprite in a single undo transaction.

Inputs: toColor (required), fromColor (required), layerName, tolerance, +2 more.

resize_canvasC

Resizes the active sprite canvas dimensions without interpolation or blurring.

Inputs: width (required), height (required), anchor.

save_spriteA

Explicitly saves the active sprite to disk. (Saves only when explicitly requested).

Inputs: no named parameters.

save_sprite_asC

Saves the active sprite to a specific target file path on disk.

Inputs: filePath (required).

select_frameC

Changes active frame number in the editor.

Inputs: frameNumber (required).

select_layerC

Sets the active working layer in Aseprite.

Inputs: name (required).

set_frame_durationC

Sets duration for a frame in milliseconds.

Inputs: durationMs (required), frameNumber (required).

set_layer_opacityC

Adjusts opacity for a layer (0 to 255).

Inputs: name (required), opacity (required).

set_layer_visibilityC

Shows or hides a layer.

Inputs: name (required), visible (required).

set_palette_colorC

Updates the color at a specific palette index.

Inputs: color (required), index (required).

set_pixelA

Paints a single pixel at (x, y) with the specified color within an atomic undo transaction.

Inputs: x (required), y (required), color (required), layerName, +3 more.

set_pixelsA

PRIMARY DRAWING TOOL: Paints tens to thousands of pixels in a single batch operation and single atomic undo step. Returns modified count, affected bounding box, and optional updated preview.

Inputs: pixels (required), layerName, layerIndex, frameNumber, +2 more.

undoA

Undoes the most recent editing tool call or transaction on the active sprite.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 43 tools

    Disambiguation3/5

    Several inspection tools overlap significantly: aseprite_status and get_sprite_info return nearly identical structural details, and get_canvas, inspect_sprite, and get_pixel_grid_preview all provide visual/pixel inspection with different granularity. Descriptions clarify 'primary' tools, but an agent still faces multiple plausible choices for common tasks like checking sprite state or viewing the canvas.

    Naming Consistency4/5

    Names are consistently snake_case and mostly follow a verb_noun pattern (create_frame, list_layers, set_pixel). Minor deviations exist: new_sprite uses 'new' instead of the dominant 'create', aseprite_status is noun-first, and undo/redo are bare verbs.

    Tool Count2/5

    43 tools is well above the typical 3-15 range and exceeds the 25+ threshold for 'too many' in this rubric. Although Aseprite is feature-rich, several tools are redundant (e.g., get_canvas vs inspect_sprite vs get_pixel_grid; aseprite_status vs get_sprite_info), making the set heavy for an agent to navigate.

    Completeness3/5

    Core painting, layer, frame, and file workflows are covered, but several resources lack full lifecycle operations. Tags only support create/list (no delete/rename/update range), palette lacks add/remove/resize operations, and frames have no reorder/move tool, creating notable dead ends for common animation tasks.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to drive Aseprite for pixel-art creation, including sprite setup, grid-based drawing, layer/frame/tag management, reference image import, and export, with rendered previews after every mutation.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to create and edit pixel art and animated sprites in Aseprite through 104 tools covering drawing, layers, animation, palettes, tilemaps, exports, visual analysis, and raw Lua scripting.
      116
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to draw live in Aseprite, creating and editing sprites, using drawing tools, managing layers and frames, and viewing results as images.
      23
      157 npm
      11
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables an AI agent to create and edit pixel art directly in Aseprite — building sprites, layers, frames, animation tags and palettes, painting pixels and primitives, inspecting the rendered result, and exporting GIFs or sprite sheets. All work lands on real .aseprite files that can be opened and edited by hand.
      43
      157 npm
      1
      MIT