Aseprite Asset MCP

MCP server público para crear pixel art, personajes y escenarios de Aseprite con TypeScript 6.0.3, Node.js 24 y arquitectura hexagonal.

El servidor usa stdio. El adaptador MCP llama a casos de uso de aplicación y el adaptador de infraestructura ejecuta Aseprite de forma controlada. Los workflows generan primero un plan JSON reproducible y un manifiesto compatible con Godot.

Arquitectura

src/
  domain/          contratos y resultados del dominio
  application/     casos de uso
  infrastructure/  adaptador CLI de Aseprite
  interfaces/      adaptador MCP y entrada stdio
  workflows/       planes TypeScript y cliente MCP
tests-ts/          TDD unitario y handshake MCP

Estado de la migración

La rama develop usa únicamente el runtime TypeScript. El núcleo disponible incluye canvas, grupos, capas, frames, tags, paletas, dibujo pixelado, tilemaps, validación, exportación, planes deterministas para personajes y escenarios, y handshake MCP real por stdio.

Este proyecto mantiene su propio desarrollo, roadmap y contrato de herramientas para convertirlo en una fábrica de assets pixel-art eficiente para agentes.

Showcase visual

Los ejemplos se generan de forma reproducible con npm run showcase. El mismo pipeline crea estilo, tileset, mapa, oleaje, transición temporal y manifests.

Ver también:

• Guía de uso
• Recetas y reglas de calidad
• Ejemplos visuales

Requisitos

• Node.js 24 o posterior.
• npm 11 o posterior.
• Aseprite instalado y accesible.
• ASEPRITE_PATH configurado si el ejecutable no está en el PATH.

En Windows:

$env:ASEPRITE_PATH = 'C:\Program Files (x86)\Steam\steamapps\common\Aseprite\Aseprite.exe'
npm install
npm test

Conectar el MCP

.mcp.json usa el servidor TypeScript:

{
  "mcpServers": {
    "aseprite": {
      "type": "stdio",
      "command": "npm",
      "args": ["run", "mcp", "--silent"]
    }
  }
}

Ejecuta manualmente con npm run mcp. stdout pertenece al protocolo MCP; los logs operativos van a stderr.

Workflows para juegos

Modo plan:

npm run asset:character -- --asset=moon-knight
npm run asset:scene -- --asset=forest-ruins

Esto crea en artifacts/aseprite/ el plan de llamadas y el manifiesto *.godot.json.

Modo ejecución, después de revisar el plan:

$env:ASEPRITE_PATH = 'C:\Program Files (x86)\Steam\steamapps\common\Aseprite\Aseprite.exe'
npm run asset:character -- --asset=moon-knight --execute
npm run asset:scene -- --asset=forest-ruins --execute
npm run asset:odiseum-style
npm run asset:odiseum-world
npm run asset:library
npm run showcase

Secuencia: canvas; grupos y capas semánticas; paleta; frames y tags; validación; spritesheet, datos y manifiesto para Godot.

asset:odiseum-style genera los personajes, el entrenador y la transición de viaje de Odiseum. asset:odiseum-world genera el sheet de seis props, el glifo animado de los portales y el cristal animado exclusivo de Starfall Grove con la misma paleta cozy. asset:library genera odiseum-cozy-kit, una biblioteca reutilizable de ocho assets de entorno de 48 px con sombras de contacto, navegación, naturaleza y arquitectura.

La biblioteca se exporta en art/library/odiseum-cozy-kit.png junto con asset-library.json. El manifiesto documenta el índice de cada frame, categoría, paleta, escala y regla de renderizado nearest para reutilizar el kit en otros juegos originales.

Herramientas compactas para agentes

El agente puede descubrir capacidades por carpetas antes de cargar detalles:

• get_tools_list: devuelve carpetas y conteos sin repetir los más de cien nombres.
• get_tools_by_folder: carga solo una familia, por ejemplo asset/animation o asset/quality.
• run_asset_recipe: ejecuta o previsualiza recetas pixel_art, animation_pixel_art, gif y atlas.
• batch_asset_job: agrupa varias recetas en una sola llamada y devuelve un resultado compacto.
• convert_image_to_pixel_art: convierte PNG, JPG, WebP y otros formatos soportados por Sharp con resize box/nearest, paleta limitada, transparencia y dithering Bayer opcional.
• convert_animation_to_pixel_art: procesa todos los frames con una paleta global y conserva sus delays en GIF.
• export_animation_gif: exporta una imagen animada o un .aseprite a GIF.
• inspect_asset y validate_asset_quality: reportan dimensiones, frames, colores, transparencia, delays y pixeles aislados antes de exportar.
• build_texture_atlas: empaqueta imágenes del mismo tamaño en un atlas PNG con columnas y padding.
• export_asset_pack: entrega el atlas y un manifiesto JSON con la posición de cada asset.
• create_style_bible: fija paleta, luz, escala, detalle y semilla para mantener consistencia.
• inspect_reference y run_asset_quality_gate: analizan color, contraste, bordes, transparencia, banding y píxeles aislados.
• build_terrain_tileset: genera 16 máscaras cardinales por terreno para transiciones reutilizables.
• generate_world_map: crea mapas multi-bioma deterministas con landmarks y preview.
• generate_beach_scene: crea costa, arena, tierra, preview y oleaje animado.
• generate_time_of_day_pack: crea transición día, atardecer, noche y amanecer.
• generate_environment_pack: empaqueta playa, bosque, aldea o cueva en una sola llamada.

Las operaciones de imagen no necesitan abrir Aseprite; eso reduce latencia y tokens para conversiones masivas. Las operaciones sobre .aseprite siguen pasando por el adaptador CLI hexagonal y mantienen la compatibilidad con Godot.

TDD y calidad

npm run typecheck
npm run test:ts
npm test

Las pruebas de dominio y planes no necesitan abrir Aseprite. La prueba MCP inicia el servidor TypeScript real, hace el handshake stdio y verifica las herramientas expuestas.

Docker

La imagen usa Node.js 24. El binario de Aseprite debe estar disponible dentro del contenedor y configurarse con ASEPRITE_PATH; no se incluyen credenciales ni binarios propietarios.

docker compose run --rm aseprite-mcp-dev

Licencia y proyecto

Proyecto independiente: jdsalasca/aseprite-asset-mcp. Conserva la licencia MIT.