Aseprite MCP Tools

# Aseprite MCP Improvements This document outlines the improvements made to the Aseprite MCP implementation. ## Completed Improvements ✅ ### 1. Comprehensive Error Handling 🛡️ - **Custom Exception Classes**: Created a hierarchy of custom exceptions in `core/exceptions.py`: - `AsepriteError`: Base exception for all Aseprite MCP errors - `AsepriteNotFoundError`: When Aseprite executable cannot be found - `CommandExecutionError`: When command execution fails - `LuaScriptError`: When Lua script execution fails - `FileNotFoundError`: When required files are missing - `ValidationError`: When input validation fails - `SecurityError`: When security violations are detected - **Improved Error Messages**: All errors now provide detailed, actionable error messages with context ### 2. Lua Script Builder 🏗️ - **Reusable Builder Pattern**: Created `LuaBuilder` class in `core/lua_builder.py` - **Features**: - Automatic indentation management - Transaction handling - Control flow structures (if/else, loops) - Drawing operations with optimized batch processing - Type-safe color handling - Export and frame management ### 3. Input Validation & Security 🔒 - **Validation Module**: Created `core/validation.py` with validators for: - File paths (with path traversal protection) - Colors (hex format validation) - Dimensions (positive values, max size limits) - Coordinates (bounds checking) - Export formats - Layer names - Lua string sanitization - **Security Measures**: - Path traversal detection and prevention - Input sanitization for Lua scripts - File existence validation - Proper escaping of user inputs ### 4. Unit Tests 🧪 - **Test Coverage**: Added comprehensive unit tests for: - Validation functions - Lua builder - Custom exceptions - All edge cases and error conditions ### 5. Enhanced Tools 🛠️ - **Improved All Existing Tools**: - Better error handling with try/catch blocks - Input validation on all parameters - Cleaner code using Lua builder - More detailed success/failure messages ### 6. Palette Management Tools 🎨 - **New Tools Added**: - `create_palette`: Create custom palettes with any colors - `apply_preset_palette`: Apply predefined palettes (GameBoy, NES, PICO-8, etc.) - `extract_palette_from_image`: Extract colors from existing images - `get_palette_info`: Display current palette information - `remap_colors`: Remap specific colors throughout the sprite - **Preset Palettes Available**: - GameBoy (4 colors) - GameBoy Pocket (4 colors) - NES (54 colors) - PICO-8 (16 colors) - CGA (16 colors) - Monochrome (16 shades) - Sepia (16 tones) ### 7. Enhanced Export Capabilities 📤 - **New Features**: - `export_layers`: Export each layer as a separate file - Scale factor support for exports - Frame range selection - Automatic format detection from file extension ## Architecture Improvements 🏛️ ### Before: ``` - Static methods everywhere - Minimal error handling - Hardcoded Lua scripts - No input validation - No tests ``` ### After: ``` - Proper class instances with state management - Comprehensive error handling - Reusable Lua builder pattern - Full input validation and security - Complete test coverage - Backward compatibility maintained ``` ## Code Quality Improvements 📊 1. **Type Safety**: Full type hints throughout the codebase 2. **Documentation**: Comprehensive docstrings for all functions 3. **Consistency**: Uniform error handling and response patterns 4. **Maintainability**: Modular design with clear separation of concerns 5. **Performance**: Optimized batch operations for pixel drawing ## Usage Examples ### Creating a sprite with error handling: ```python # Old way (minimal error handling) success, output = AsepriteCommand.execute_lua_script(script) if success: return "Success" else: return f"Failed: {output}" # New way (comprehensive error handling) try: file_path = validate_file_path(filename, must_exist=True) builder = LuaBuilder() builder.create_sprite(width, height) builder.save_sprite(str(file_path)) cmd = get_command() success, output = cmd.execute_lua_script(builder.build()) return f"Canvas created successfully: {file_path}" except (ValidationError, AsepriteError) as e: return f"Failed to create canvas: {e}" ``` ### Using the new palette tools: ```python # Apply a retro GameBoy palette await apply_preset_palette("my_sprite.aseprite", "gameboy") # Extract palette from an image await extract_palette_from_image("reference.png", max_colors=16) # Remap colors await remap_colors("sprite.aseprite", { "FF0000": "00FF00", # Red to Green "0000FF": "FFFF00" # Blue to Yellow }) ``` ## Additional Completed Improvements ✅ ### 7. Configuration Management 🔧 - **Pydantic-based Settings**: Type-safe configuration with validation - **Multiple Sources**: Support for environment variables, JSON, and YAML files - **Security Settings**: Configurable security restrictions - **Performance Tuning**: Cache settings, timeouts, and parallel processing limits - **Flexible Loading**: Load from file or environment, with sensible defaults ### 8. Batch Processing 🚀 - **Parallel Processing**: Process multiple files concurrently - **Batch Operations**: - `batch_resize`: Resize multiple sprites with aspect ratio control - `batch_export`: Export multiple files to different formats - `batch_apply_palette`: Apply palettes to multiple files - `batch_process_custom`: Run custom Lua scripts on multiple files - **Error Handling**: Continue on error option with detailed reporting - **Progress Tracking**: Optional progress callbacks ### 9. Logging System 📝 - **Structured Logging**: JSON or traditional format output - **Context-Rich Logs**: Operation tracking, performance metrics, error details - **Flexible Output**: Console and/or rotating file logs - **Performance Timing**: Built-in Timer context manager - **Log Levels**: Configurable from DEBUG to CRITICAL ## Future Improvements (Roadmap) ### High Priority: 1. **Animation Tools**: Advanced frame and timeline management 2. **Advanced Filters**: Blur, sharpen, color adjustments 3. **Sprite Sheet Tools**: Packing and unpacking sprites ### Medium Priority: 1. **Performance Optimization**: Connection pooling, caching 2. **Plugin System**: Extensible architecture for custom tools 3. **Advanced Filters**: Blur, sharpen, color adjustments 4. **Sprite Sheet Tools**: Packing and unpacking sprites ### Low Priority: 1. **GUI Integration**: Visual feedback for operations 2. **Cloud Storage**: Integration with cloud services 3. **Version Control**: Built-in sprite versioning 4. **AI Integration**: Smart color suggestions, auto-palette generation ## Breaking Changes None! All improvements maintain backward compatibility. Existing code will continue to work as before, with enhanced error messages when things go wrong. ## Testing Run the test suite: ```bash pytest tests/ -v ``` ## Contributing When adding new features: 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