ase-mcp

Puente MCP entre un agente de IA y una sesión activa de Aseprite, misma máquina o agente en una máquina virtual.

GitHub
2
Prueba este MCPPatrocinado

Documentación

ase-mcp

Permite que un agente de IA controle una sesión de Aseprite en vivo mediante el Protocolo de Contexto de Modelo (MCP). Dibuja, anima, etiqueta y exporta dentro de un archivo .aseprite real y editable, desde un agente que se ejecuta en una máquina virtual o en la misma máquina.

License: Apache 2.0 Aseprite 1.3+ Windows host

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

Un solo prompt construye una escena completa, casa, jardín y un ciclo de caminata de bebé de 12 fotogramas, en vivo en Aseprite, en una sola transacción Lua. No es un PNG aplanado: es un archivo .aseprite real con capas, etiquetas y animación que puedes seguir editando.

A diferencia de un puente por lotes o sin interfaz, ase-mcp actúa sobre la sesión que ya tienes abierta, por lo que lo que hace el agente aparece en tu lienzo a medida que ocurre.

Instalación (usuario)

Un solo archivo para instalar: ase-mcp-bridge.aseprite-extension (incluye el complemento Y el servidor).

  1. Aseprite: Edit > Preferences > Extensions > Add Extension -> elige ase-mcp-bridge.aseprite-extension -> Aceptar.
  2. La primera vez, Aseprite pide permiso para ejecutar un comando / usar la red -> Permitir (o concede confianza total en Edit > Preferences > Scripts).

Eso es todo. Al cargar, el complemento inicia el servidor incluido y se conecta; cada inicio posterior de Aseprite es automático.

Lado del agente (cualquier cliente MCP; el token de autenticación es obligatorio incluso en la misma máquina):

  • Máquina virtual: ejecuta scripts/ase-mcp-setup.ps1 como administrador en el HOST. Hace todo el cableado (portproxy, firewall con ámbito, generación de token) y escribe un .mcp.json listo para usar en la raíz del repositorio. Detalles en INSTALL.md.

  • Misma máquina: copia .mcp.json.example, establece el host de la URL en 127.0.0.1 y pega el token de %APPDATA%/ase-mcp/token (generado en el primer inicio del servidor).

  • Misma máquina: ejecuta scripts/ase-mcp-setup.ps1 -Local (sin administrador). Omite el portproxy y el firewall, genera el token y escribe .mcp.json en 127.0.0.1.

Arquitectura

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

El servidor se vincula a 127.0.0.1 (8001 HTTP para el MCP, 8767 WebSocket para el complemento). Para una máquina virtual, un portproxy y un firewall con ámbito (scripts/ase-mcp-setup.ps1) exponen el 8001. El Lua de Aseprite es solo un CLIENTE WebSocket, por lo que el complemento marca hacia AFUERA; el servidor no puede vivir dentro de Aseprite, por lo que la extensión lo incluye y lo inicia automáticamente (os.execute).

Diseño

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

Herramientas

33 herramientas. Cada herramienta que modifica el sprite termina su Lua con app.refresh(), para que el lienzo se repinte de inmediato (no es necesario mover el mouse sobre Aseprite).

  • aseprite_status() - ¿puente conectado? información del sprite activo.
  • run_lua(code) - ejecuta Lua arbitrario de Aseprite en la sesión en vivo (herramienta avanzada).
  • new_sprite(w, h, mode), save_png(path), save_aseprite(path).
  • Dibujo: draw_pixel, draw_pixels (lote: pares [x, y], un color, un paso de deshacer, máximo 4096), draw_rect, draw_line, draw_ellipse, bucket_fill, get_pixel(x, y, frame, layer) (lee de vuelta hex/gris/índice).
  • Capas y cels: add_layer, duplicate_layer, get_cels(layer), copy_cel(from_frame, to_frame, layer, to_layer), move_cel(...) (misma firma), delete_cel(frame, layer).
  • Fotogramas: 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) (lote, fotograma 1..N).
  • Etiquetas: create_tag(name, from_frame, to_frame, direction) (hacia adelante, hacia atrás, ping_pong, ping_pong_reverse), update_tag(name, new_name, direction), delete_tag(name).
  • Paleta e información: set_palette(colors), sprite_info() (tamaño, duraciones de fotogramas en ms, capas, etiquetas).
  • Exportación: export_spritesheet(path, data_path, sheet_type, border_padding, shape_padding) (sheet_type: horizontal, vertical, rows, columns, packed; data_path escribe un archivo de datos hash JSON).
  • Depuración: enable_debug_log() / disable_debug_log().

Las rutas de guardado y exportación están restringidas por ASE_OUTPUT_ROOT (ver SECURITY.md B-2): la extensión debe coincidir con la herramienta, y cuando la variable está establecida, la ruta resuelta debe permanecer dentro de esa raíz.

Registro de depuración

Dos interruptores independientes, uno por lado del puente:

  • Lado del host (Aseprite): File > Scripts > ase-mcp: Enable debug log imprime cada comando entrante y su respuesta en la consola de Aseprite. ase-mcp: Disable debug log lo desactiva.
  • Lado del agente (herramientas MCP): enable_debug_log() / disable_debug_log() imprimen cada acción enviada, sus parámetros y la respuesta de Aseprite en la consola del servidor ase-mcp.

Seguridad

run_lua es ejecución de código arbitrario dentro de Aseprite, e instalar la extensión inicia un ejecutable incluido en el host (Aseprite solicita permiso una vez). El puente está construido en torno a eso: se requiere un token compartido en ambos transportes (comparación de tiempo constante), las rutas de guardado y exportación están confinadas por ASE_OUTPUT_ROOT, el servidor se vincula a 127.0.0.1, y una máquina virtual solo lo alcanza a través del portproxy y firewall con ámbito. El modelo de amenazas completo y una auditoría por hallazgo están en SECURITY.md. Léelo antes de exponer el puerto más allá de una sola máquina.

Estado

Funcionando, probado de extremo a extremo en una máquina virtual y en la misma máquina (-Local): un agente controla una sesión de Aseprite en vivo en el host de Windows, generando y animando una escena completa (ver el video anterior). Dirigido a Aseprite 1.3+; algunas llamadas Lua pueden necesitar pequeños ajustes en otras versiones de Aseprite; abre un issue si encuentras alguna.

Licencia

Apache-2.0. Ver LICENSE.