README_v2.md•6.22 kB
# Aseprite MCP Tools v2.0
A powerful Python MCP (Model Context Protocol) server for programmatic interaction with Aseprite, now with enhanced error handling, configuration management, batch processing, and more!
## 🚀 New in v2.0
- **🛡️ Comprehensive Error Handling**: Custom exceptions with detailed, actionable error messages
- **🔧 Configuration Management**: Pydantic-based settings with JSON/YAML support
- **📝 Advanced Logging**: Structured logging with performance metrics
- **🎨 Palette Management**: Create, apply, and extract color palettes
- **⚡ Batch Processing**: Process multiple files in parallel
- **🏗️ Lua Script Builder**: Clean, type-safe Lua script generation
- **🔒 Enhanced Security**: Input validation and path traversal protection
- **🧪 Full Test Coverage**: Comprehensive unit tests
## 📋 Features
### Core Tools
- **Canvas Operations**
- Create new sprites with custom dimensions
- Add layers and frames
- Full validation and error handling
- **Drawing Tools**
- Draw pixels, lines, rectangles, and circles
- Fill areas with paint bucket
- Batch pixel operations for performance
- **Export Tools**
- Export to various formats (PNG, GIF, JPG, etc.)
- Export individual layers
- Scale and frame range support
### New Tools in v2.0
- **Palette Management**
- Apply preset palettes (GameBoy, NES, PICO-8, CGA, etc.)
- Extract palettes from images
- Create custom palettes
- Remap colors across sprites
- **Batch Processing**
- Resize multiple sprites
- Export batches to different formats
- Apply palettes to multiple files
- Run custom Lua scripts on file sets
## 🔧 Installation
### Using UV (Recommended)
```json
{
"mcpServers": {
"aseprite": {
"command": "/opt/homebrew/bin/uv",
"args": [
"--directory",
"/path/to/aseprite-mcp",
"run",
"-m",
"aseprite_mcp"
],
"env": {
"ASEPRITE_PATH": "/path/to/aseprite"
}
}
}
}
```
### Using Python directly
```json
{
"mcpServers": {
"aseprite": {
"command": "python",
"args": [
"-m",
"aseprite_mcp"
],
"cwd": "/path/to/aseprite-mcp",
"env": {
"ASEPRITE_PATH": "/path/to/aseprite"
}
}
}
}
```
## ⚙️ Configuration
Create a `config.json` or `config.yaml` file:
```yaml
# Aseprite executable path
aseprite_path: /path/to/aseprite
# Canvas settings
canvas:
max_width: 10000
max_height: 10000
default_color_mode: RGBA
# Batch processing
batch:
max_parallel_jobs: 4
continue_on_error: true
# Logging
log_level: INFO
log_file: aseprite_mcp.log
# Security
security:
allowed_directories:
- /home/user/sprites
- /home/user/projects
max_file_size: 104857600 # 100MB
```
Or use environment variables:
```bash
export ASEPRITE_MCP_LOG_LEVEL=DEBUG
export ASEPRITE_MCP_ASEPRITE_PATH=/usr/bin/aseprite
```
## 📖 Usage Examples
### Basic Drawing
```python
# Create a new canvas
create_canvas(width=320, height=240, filename="my_sprite.aseprite")
# Draw some pixels
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
draw_rectangle("my_sprite.aseprite", x=50, y=50, width=100, height=50, color="FFFF00", fill=True)
draw_circle("my_sprite.aseprite", center_x=200, center_y=150, radius=30, color="FF00FF")
```
### Palette Management
```python
# Apply a retro palette
apply_preset_palette("my_sprite.aseprite", "gameboy")
# Create custom palette
create_palette("my_sprite.aseprite", [
"1A1C2C", "5D275D", "B13E53", "EF7D57",
"FFCD75", "A7F070", "38B764", "257179"
])
# Extract palette from reference image
extract_palette_from_image("reference.png", max_colors=16)
```
### Batch Processing
```python
# Resize all sprites in a directory
batch_resize(
input_dir="sprites/",
output_dir="sprites_small/",
scale=0.5
)
# Export all as PNG
batch_export(
input_dir="sprites/",
output_dir="exports/",
format="png",
scale=2.0
)
# Apply palette to multiple files
batch_apply_palette(
input_dir="sprites/",
palette_file="my_palette.aseprite"
)
```
### Error Handling
All operations now return detailed error messages:
```
Failed to create canvas: Validation failed for 'width': Width must be positive
Failed to draw pixels: File not found: 'missing.aseprite'
Failed to export sprite: Security violation: Path traversal detected
```
## 🏗️ Architecture Improvements
### Custom Exception Hierarchy
```python
AsepriteError
├── AsepriteNotFoundError
├── CommandExecutionError
├── LuaScriptError
├── FileNotFoundError
├── ValidationError
└── SecurityError
```
### Lua Script Builder
```python
builder = LuaBuilder()
builder.create_sprite(100, 100)
builder.begin_transaction()
builder.for_loop("i", 0, 9)
builder.draw_pixel(10, "i * 10", "FF0000")
builder.end_loop()
builder.end_transaction()
builder.save_sprite("output.aseprite")
script = builder.build() # Clean, indented Lua code
```
### Structured Logging
```json
{
"timestamp": "2024-11-06T10:30:45.123Z",
"level": "INFO",
"operation": "create_canvas",
"file_path": "sprite.aseprite",
"duration": 0.234,
"details": {
"width": 320,
"height": 240
}
}
```
## 🧪 Testing
Run the comprehensive test suite:
```bash
pytest tests/ -v
```
Run the demo script:
```bash
python examples/demo_improvements.py
```
## 📚 Documentation
- [IMPROVEMENTS.md](IMPROVEMENTS.md) - Detailed list of v2.0 improvements
- [config.example.json](config.example.json) - Example JSON configuration
- [config.example.yaml](config.example.yaml) - Example YAML configuration
## 🤝 Contributing
1. Use the validation module for all inputs
2. Implement proper error handling with custom exceptions
3. Use LuaBuilder for Lua script generation
4. Add comprehensive unit tests
5. Update documentation
## 📄 License
MIT License - see LICENSE file for details
## 🙏 Acknowledgments
- Original implementation by Divyansh Singh
- v2.0 improvements focus on production readiness and developer experience