ase-mcp

Ponte MCP entre um agente de IA e uma sessão Aseprite ao vivo, na mesma máquina ou com o agente em uma VM.

GitHub
2
Experimente este MCPPatrocinado

Documentação

ase-mcp

Deixe um agente de IA controlar uma sessão Aseprite ao vivo por meio do Model Context Protocol. Desenhe, anime, marque e exporte dentro de um arquivo .aseprite real e editável, a partir de um agente rodando em uma VM ou na mesma máquina.

License: Apache 2.0 Aseprite 1.3+ Windows host

https://github.com/user-attachments/assets/1ed1c882-1fee-4d09-974f-673eb77eb70a

Um único prompt constrói uma cena completa, casa, jardim e um ciclo de caminhada de bebê com 12 quadros, ao vivo no Aseprite, em uma única transação Lua. Não é um PNG achatado: é um arquivo .aseprite real em camadas, marcado e animado que você pode continuar editando.

Diferente de uma ponte em lote ou headless, o ase-mcp atua na sessão que você já tem aberta, então o que o agente faz aparece no seu canvas conforme acontece.

Instalação (usuário)

Um arquivo para instalar: ase-mcp-bridge.aseprite-extension (ele inclui o plugin E o servidor).

  1. Aseprite: Edit > Preferences > Extensions > Add Extension -> escolha ase-mcp-bridge.aseprite-extension -> OK.
  2. Na primeira vez, o Aseprite pede permissão para executar um comando / usar a rede -> Permitir (ou conceder confiança total em Edit > Preferences > Scripts).

É isso. Ao carregar, o plugin inicia o servidor incluído e conecta; todo início posterior do Aseprite é automático.

Lado do agente (qualquer cliente MCP; o token de autenticação é obrigatório mesmo na mesma máquina):

  • VM: execute scripts/ase-mcp-setup.ps1 como administrador no HOST. Ele faz toda a configuração (portproxy, firewall com escopo, geração de token) e escreve um .mcp.json pronto para uso na raiz do repositório. Detalhes em INSTALL.md.

  • Mesma máquina: copie .mcp.json.example, defina o host da URL como 127.0.0.1 e cole o token de %APPDATA%/ase-mcp/token (gerado no primeiro início do servidor).

  • Mesma máquina: execute scripts/ase-mcp-setup.ps1 -Local (sem administrador). Ele pula o portproxy e o firewall, gera o token e escreve .mcp.json em 127.0.0.1.

Arquitetura

MCP agent (VM)   --HTTP:8001-->  ase-mcp server (HOST)  --WS :8767-->  Aseprite plugin (HOST)
                  (portproxy)      launched by the plugin                dials OUT (WS client)

O servidor vincula 127.0.0.1 (8001 HTTP para o MCP, 8767 WebSocket para o plugin). Para uma VM, um portproxy e firewall com escopo (scripts/ase-mcp-setup.ps1) expõem a porta 8001. O Lua do Aseprite é apenas um CLIENTE WebSocket, então o plugin faz a chamada para fora; o servidor não pode viver dentro do Aseprite, então a extensão o inclui e o inicia automaticamente (os.execute).

Layout

ase-mcp/
  ase-mcp-bridge.aseprite-extension  the deliverable (plugin + bundled exe)
  ase-mcp-server.exe                 standalone server (PyInstaller onefile)
  server.py                          server source (FastMCP HTTP + WebSocket + tools)
  build_exe.bat                      rebuild the exe (needs Python + pyinstaller)
  aseprite-plugin/                   extension source (package.json + ase_bridge.lua + exe)
  scripts/                           ase-mcp-setup / remove / status / test
  build_package.py  requirements.txt  INSTALL.md  SECURITY.md

Ferramentas

33 ferramentas. Toda ferramenta que modifica o sprite termina seu Lua com app.refresh(), para que o canvas seja repintado imediatamente (sem necessidade de mover o mouse sobre o Aseprite).

  • aseprite_status() - ponte conectada? informações do sprite ativo.
  • run_lua(code) - execute Lua arbitrário do Aseprite na sessão ao vivo (ferramenta poderosa).
  • new_sprite(w, h, mode), save_png(path), save_aseprite(path).
  • Desenho: draw_pixel, draw_pixels (em lote: pares [x, y], uma cor, um passo de desfazer, máx. 4096), draw_rect, draw_line, draw_ellipse, bucket_fill, get_pixel(x, y, frame, layer) (lê de volta hex/cinza/índice).
  • Camadas e cels: add_layer, duplicate_layer, get_cels(layer), copy_cel(from_frame, to_frame, layer, to_layer), move_cel(...) (mesma assinatura), delete_cel(frame, layer).
  • Quadros: add_frame, insert_frame(frame), duplicate_frame(frame), delete_frame(frame), set_active_frame(frame), set_frame_duration(frame, duration_ms), set_frame_durations(durations_ms) (em lote, quadro 1..N).
  • Tags: create_tag(name, from_frame, to_frame, direction) (forward, reverse, ping_pong, ping_pong_reverse), update_tag(name, new_name, direction), delete_tag(name).
  • Paleta e informações: set_palette(colors), sprite_info() (tamanho, durações de quadros em ms, camadas, tags).
  • Exportação: export_spritesheet(path, data_path, sheet_type, border_padding, shape_padding) (sheet_type: horizontal, vertical, rows, columns, packed; data_path escreve um arquivo de dados JSON em hash).
  • Depuração: enable_debug_log() / disable_debug_log().

Os caminhos de salvar e exportar são limitados por ASE_OUTPUT_ROOT (veja SECURITY.md B-2): a extensão deve corresponder à ferramenta, e quando a variável está definida, o caminho resolvido deve permanecer dentro dessa raiz.

Log de depuração

Dois interruptores independentes, um para cada lado da ponte:

  • Lado do host (Aseprite): File > Scripts > ase-mcp: Enable debug log imprime cada comando recebido e sua resposta no console do Aseprite. ase-mcp: Disable debug log desliga isso.
  • Lado do agente (ferramentas MCP): enable_debug_log() / disable_debug_log() imprimem cada ação enviada, seus parâmetros e a resposta do Aseprite no console do servidor ase-mcp.

Segurança

run_lua é execução arbitrária de código dentro do Aseprite, e instalar a extensão inicia um executável incluído no host (o Aseprite solicita uma vez). A ponte é construída em torno disso: um token compartilhado é obrigatório em ambos os transportes (comparação em tempo constante), os caminhos de salvar e exportar são confinados por ASE_OUTPUT_ROOT, o servidor vincula 127.0.0.1, e uma VM só o alcança através do portproxy e firewall com escopo. O modelo de ameaça completo e uma auditoria por descoberta estão em SECURITY.md. Leia antes de expor a porta além de uma única máquina.

Status

Funcionando, testado de ponta a ponta em uma VM e na mesma máquina (-Local): um agente controla uma sessão Aseprite ao vivo no host Windows, gerando e animando uma cena completa (veja o vídeo acima). Destinado ao Aseprite 1.3+; algumas chamadas Lua podem precisar de pequenos ajustes em outras versões do Aseprite; abra uma issue se encontrar alguma.

Licença

Apache-2.0. Veja LICENSE.