Aseprite MCP

Un servidor para la interacción programática con Aseprite, que permite el procesamiento por lotes y la automatización para la creación y gestión de sprites.

GitHub
24
Prueba este MCPPatrocinado

Documentación

Herramientas Aseprite MCP v2.0

Versión en japonés | Guía de configuración para macOS

Un potente servidor MCP (Model Context Protocol) en Python para la interacción programática con Aseprite, con manejo mejorado de errores, gestión de configuración, procesamiento por lotes y más.

🚀 Novedades en v2.0

  • 🛡️ Manejo integral de errores: Excepciones personalizadas con mensajes de error detallados y accionables
  • 🔧 Gestión de configuración: Configuración basada en Pydantic con soporte para JSON/YAML
  • 📝 Registro avanzado: Registro estructurado con métricas de rendimiento
  • 🎨 Gestión de paletas: Crear, aplicar y extraer paletas de colores
  • ⚡ Procesamiento por lotes: Procesar múltiples archivos en paralelo
  • 🏗️ Constructor de scripts Lua: Generación de scripts Lua limpia y segura en cuanto a tipos
  • 🔒 Seguridad mejorada: Validación de entrada y protección contra recorridos de rutas
  • 🧪 Cobertura completa de pruebas: Pruebas unitarias integrales

📋 Características

Herramientas de dibujo principales

  • Operaciones de lienzo: Crear sprites, agregar capas y fotogramas
  • Herramientas de dibujo: Píxeles, líneas, rectángulos, círculos y operaciones de relleno
  • Herramientas de exportación: Exportar a varios formatos con soporte de escala y capas

Nuevas herramientas de paleta (v2.0)

  • Paletas predefinidas: GameBoy, NES, PICO-8, CGA, Monocromo, Sepia
  • Paletas personalizadas: Crear y aplicar esquemas de colores personalizados
  • Extracción de paletas: Extraer colores de imágenes existentes
  • Reasignación de colores: Reemplazar colores en sprites completos

Procesamiento por lotes (v2.0)

  • Redimensionamiento por lotes: Redimensionar múltiples sprites manteniendo la relación de aspecto
  • Exportación por lotes: Convertir múltiples archivos a diferentes formatos
  • Aplicación de paleta por lotes: Aplicar paletas a múltiples archivos
  • Scripts personalizados: Ejecutar scripts Lua en conjuntos de archivos

🔧 Instalación

Requisitos

  • Python 3.13+
  • Aseprite (debe instalarse por separado)

Configuración de Claude Desktop

Usando UV (Recomendado)

{
  "mcpServers": {
    "aseprite": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "/path/to/aseprite-mcp",
        "run",
        "-m",
        "aseprite_mcp"
      ],
      "env": {
        "ASEPRITE_PATH": "/path/to/aseprite"
      }
    }
  }
}

Usando Python

{
  "mcpServers": {
    "aseprite": {
      "command": "python",
      "args": ["-m", "aseprite_mcp"],
      "cwd": "/path/to/aseprite-mcp",
      "env": {
        "ASEPRITE_PATH": "/path/to/aseprite"
      }
    }
  }
}

Instalar dependencias

pip install -r requirements.txt

⚙️ Configuración

Variables de entorno

export ASEPRITE_PATH="/Applications/Aseprite.app/Contents/MacOS/aseprite"
export ASEPRITE_MCP_LOG_LEVEL="INFO"

Archivo de configuración (config.json)

{
  "aseprite_path": "/path/to/aseprite",
  "canvas": {
    "max_width": 10000,
    "max_height": 10000
  },
  "batch": {
    "max_parallel_jobs": 4,
    "continue_on_error": true
  },
  "log_level": "INFO",
  "security": {
    "allowed_directories": ["/home/user/sprites"],
    "max_file_size": 104857600
  }
}

Archivo de configuración (config.yaml)

aseprite_path: /path/to/aseprite

canvas:
  max_width: 10000
  max_height: 10000
  default_color_mode: RGBA

batch:
  max_parallel_jobs: 4
  continue_on_error: true

log_level: INFO

security:
  allowed_directories:
    - /home/user/sprites
  max_file_size: 104857600

📖 Ejemplos de uso

Operaciones básicas de dibujo

# Create a new sprite
await create_canvas(320, 240, "my_sprite.aseprite")

# Draw pixels
await draw_pixels("my_sprite.aseprite", [
    {"x": 10, "y": 10, "color": "FF0000"},  # Red
    {"x": 11, "y": 10, "color": "00FF00"},  # Green
    {"x": 12, "y": 10, "color": "0000FF"}   # Blue
])

# Draw shapes
await draw_rectangle("my_sprite.aseprite", 50, 50, 100, 80, "FFFF00", fill=True)
await draw_circle("my_sprite.aseprite", 160, 120, 30, "FF00FF", fill=False)
await draw_line("my_sprite.aseprite", 0, 0, 320, 240, "FFFFFF", thickness=2)

# Fill area
await fill_area("my_sprite.aseprite", 100, 100, "00FFFF", tolerance=10)

Gestión de capas y fotogramas

# Add a new layer
await add_layer("my_sprite.aseprite", "Background")

# Add animation frames
await add_frame("my_sprite.aseprite", after_frame=0)

Operaciones con paletas

# Apply preset palette
await apply_preset_palette("my_sprite.aseprite", "gameboy")
# Available presets: gameboy, gameboy-pocket, nes, pico-8, cga, monochrome, sepia

# Create custom palette
await create_palette("my_sprite.aseprite", [
    "264653", "2A9D8F", "E9C46A", "F4A261", "E76F51"
])

# Extract palette from image
await extract_palette_from_image("reference.png", max_colors=16)

# Get palette information
await get_palette_info("my_sprite.aseprite")

# Remap colors
await remap_colors("my_sprite.aseprite", {
    "FF0000": "00FF00",  # Red to Green
    "0000FF": "FFFF00"   # Blue to Yellow
})

Operaciones de exportación

# Export single file
await export_sprite("my_sprite.aseprite", "output.png", scale=2.0)

# Export with frame range
await export_sprite("animation.aseprite", "frames.gif", frame_range="1-10")

# Export each layer separately
await export_layers("my_sprite.aseprite", "layers/", format="png")

Procesamiento por lotes

# Resize multiple sprites
await batch_resize(
    input_dir="sprites/",
    output_dir="sprites_small/",
    scale=0.5,
    file_pattern="*.aseprite"
)

# Export batch to PNG
await batch_export(
    input_dir="sprites/",
    output_dir="exports/",
    format="png",
    scale=2.0
)

# Apply palette to multiple files
await batch_apply_palette(
    input_dir="sprites/",
    palette_file="my_palette.aseprite",
    create_backup=True
)

# Run custom Lua script on multiple files
await batch_process_custom(
    input_dir="sprites/",
    lua_script="app.activeSprite:flatten()",
    output_dir="flattened/"
)

🏗️ Arquitectura

Estructura del proyecto

aseprite-mcp/
├── aseprite_mcp/
│   ├── core/
│   │   ├── commands.py      # Aseprite command execution
│   │   ├── config.py        # Configuration management
│   │   ├── exceptions.py    # Custom exceptions
│   │   ├── logging.py       # Logging system
│   │   ├── lua_builder.py   # Lua script builder
│   │   └── validation.py    # Input validation
│   └── tools/
│       ├── batch.py         # Batch processing
│       ├── canvas.py        # Canvas operations
│       ├── drawing.py       # Drawing tools
│       ├── export.py        # Export functions
│       └── palette.py       # Palette management
├── tests/                   # Unit tests
├── examples/                # Example scripts
└── config.example.yaml      # Configuration example

Manejo de errores

try:
    result = await create_canvas(-100, 200, "test.aseprite")
except ValidationError as e:
    print(f"Validation failed: {e}")
except AsepriteError as e:
    print(f"Aseprite error: {e}")

Constructor de scripts Lua

from aseprite_mcp.core.lua_builder import LuaBuilder

builder = LuaBuilder()
builder.create_sprite(200, 200)
builder.begin_transaction()
builder.set_color("FF0000")
builder.for_loop("i", 0, 10)
    builder.draw_pixel("i * 10", "i * 10")
builder.end_loop()
builder.end_transaction()
builder.save_sprite("output.aseprite")

script = builder.build()  # Returns clean Lua code

🧪 Pruebas

Ejecutar todas las pruebas:

pytest tests/ -v

Ejecutar una prueba específica:

pytest tests/test_validation.py -v

Ejecutar el script de demostración:

python examples/demo_improvements.py

📝 Registro

Los registros incluyen:

  • Seguimiento de operaciones
  • Métricas de rendimiento
  • Detalles de errores con contexto
  • Salida JSON estructurada (opcional)

Ejemplo de registro:

2024-06-11 10:30:45 - aseprite_mcp - INFO - Operation: create_canvas
2024-06-11 10:30:45 - aseprite_mcp - INFO - Canvas created successfully
2024-06-11 10:30:45 - aseprite_mcp - INFO - Performance: create_canvas took 0.234s

🤝 Contribuciones

  1. Hacer un fork del repositorio
  2. Crear una rama de características
  3. Seguir los estándares de codificación:
    • Usar sugerencias de tipos
    • Agregar validación de entrada
    • Incluir manejo de errores
    • Escribir pruebas unitarias
    • Actualizar la documentación
  4. Enviar una solicitud de extracción

📄 Licencia

Licencia MIT: consulte el archivo LICENSE para más detalles

🙏 Créditos

  • Implementación original: Divyansh Singh
  • Mejoras v2.0: Manejo de errores mejorado, configuración, procesamiento por lotes y más

📚 Recursos adicionales