Aseprite MCP

Um servidor para interação programática com o Aseprite, permitindo processamento em lote e automação para criação e gerenciamento de sprites.

GitHub

Experimente este MCPPatrocinado

Documentação

Aseprite MCP Tools v2.0

日本語版はこちら | Guia de Configuração para macOS

Um poderoso servidor Python MCP (Model Context Protocol) para interação programática com Aseprite, com tratamento de erros aprimorado, gerenciamento de configuração, processamento em lote e muito mais!

🚀 Novidades na v2.0

🛡️ Tratamento Abrangente de Erros: Exceções personalizadas com mensagens de erro detalhadas e acionáveis
🔧 Gerenciamento de Configuração: Configurações baseadas em Pydantic com suporte a JSON/YAML
📝 Registro Avançado: Registro estruturado com métricas de desempenho
🎨 Gerenciamento de Paletas: Crie, aplique e extraia paletas de cores
⚡ Processamento em Lote: Processe vários arquivos em paralelo
🏗️ Construtor de Scripts Lua: Geração limpa e type-safe de scripts Lua
🔒 Segurança Aprimorada: Validação de entrada e proteção contra path traversal
🧪 Cobertura Completa de Testes: Testes unitários abrangentes

📋 Recursos

Ferramentas Básicas de Desenho

Operações de Canvas: Crie sprites, adicione camadas e quadros
Ferramentas de Desenho: Pixels, linhas, retângulos, círculos e operações de preenchimento
Ferramentas de Exportação: Exporte para vários formatos com suporte a escala e camadas

Novas Ferramentas de Paleta (v2.0)

Paletas Predefinidas: GameBoy, NES, PICO-8, CGA, Monocromática, Sépia
Paletas Personalizadas: Crie e aplique esquemas de cores personalizados
Extração de Paletas: Extraia cores de imagens existentes
Remapeamento de Cores: Substitua cores em sprites

Processamento em Lote (v2.0)

Redimensionamento em Lote: Redimensione vários sprites mantendo a proporção
Exportação em Lote: Converta vários arquivos para diferentes formatos
Aplicação de Paleta em Lote: Aplique paletas a vários arquivos
Scripts Personalizados: Execute scripts Lua em conjuntos de arquivos

🔧 Instalação

Requisitos

Python 3.13+
Aseprite (deve ser instalado separadamente)

Configuração do 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 Dependências

pip install -r requirements.txt

⚙️ Configuração

Variáveis de Ambiente

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

Arquivo de Configuração (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
  }
}

Arquivo de Configuração (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

📖 Exemplos de Uso

Operações Básicas de Desenho

# 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)

Gerenciamento de Camadas e Quadros

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

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

Operações de Paleta

# 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
})

Operações de Exportação

# 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")

Processamento em Lote

# 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/"
)

🏗️ Arquitetura

Estrutura do Projeto

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

Tratamento de Erros

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}")

Construtor 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

🧪 Testes

Execute todos os testes:

pytest tests/ -v

Execute um teste específico:

pytest tests/test_validation.py -v

Execute o script de demonstração:

python examples/demo_improvements.py

📝 Registro (Logging)

Os registros incluem:

Rastreamento de operações
Métricas de desempenho
Detalhes de erro com contexto
Saída JSON estruturada (opcional)

Exemplo 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

🤝 Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Siga os padrões de codificação:
- Use type hints
- Adicione validação de entrada
- Inclua tratamento de erros
- Escreva testes unitários
- Atualize a documentação
Envie um pull request

📄 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes

🙏 Créditos

Implementação original: Divyansh Singh
Melhorias da v2.0: Tratamento de erros aprimorado, configuração, processamento em lote e muito mais

📚 Recursos Adicionais

Documentação da API do Aseprite
Documentação do MCP
IMPROVEMENTS.md - Mudanças detalhadas da v2.0