Aseprite MCP工具v2.0
一个强大的Python MCP（模型上下文协议）服务器，用于与Aseprite进行编程交互，具有增强的错误处理、配置管理、批处理等功能！
🚀 v2.0中的新增功能
- 🛡️ 全面的错误处理：带有详细、可操作错误消息的自定义异常
- 🔧 配置管理：基于Pydantic的设置，支持JSON/YAML
- 📝 高级日志记录：具有性能指标的结构化日志记录
- 🎨 调色板管理：创建、应用和提取调色板
- ⚡ 批处理：并行处理多个文件
- 🏗️ Lua脚本生成器：干净、类型安全的Lua脚本生成
- 🔒 增强的安全性：输入验证和路径遍历保护
- 🧪 全面测试覆盖：综合单元测试
📋 特性
核心绘图工具
- 画布操作：创建精灵，添加图层和框架
- 绘图工具：像素、线条、矩形、圆形和填充操作
- 导出工具：导出为各种格式，支持缩放和图层
新调色板工具（v2.0）
- 预设选项板：GameBoy、NES、PICO-8、CGA、单色、深褐色
- 自定义调色板：创建和应用自定义配色方案
- 调色板提取：从现有图像中提取颜色
- 颜色重映射：替换整个精灵的颜色
批处理（v2.0）
- 批量调整大小：调整多个精灵的大小，保持纵横比
- 批量导出：将多个文件转换为不同格式
- 批处理调色板应用：将调色板应用于多个文件
- 自定义脚本：在文件集上运行Lua脚本
🔧 安装
需求
- Python 3.13+
- Aseprite（必须单独安装）
Claude桌面配置
使用紫外线（推荐）
{
"mcpServers": {
"aseprite": {
"command": "/opt/homebrew/bin/uv",
"args": [
"--directory",
"/path/to/aseprite-mcp",
"run",
"-m",
"aseprite_mcp"
],
"env": {
"ASEPRITE_PATH": "/path/to/aseprite"
}
}
}
}使用Python
{
"mcpServers": {
"aseprite": {
"command": "python",
"args": ["-m", "aseprite_mcp"],
"cwd": "/path/to/aseprite-mcp",
"env": {
"ASEPRITE_PATH": "/path/to/aseprite"
}
}
}
}再进行
pip install -r requirements.txt⚙️ 配置
环境变量
export ASEPRITE_PATH="/Applications/Aseprite.app/Contents/MacOS/aseprite"
export ASEPRITE_MCP_LOG_LEVEL="INFO"配置文件（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
}
}配置文件（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📖 使用示例
基本绘图操作
# 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)层和帧管理
# Add a new layer
await add_layer("my_sprite.aseprite", "Background")
# Add animation frames
await add_frame("my_sprite.aseprite", after_frame=0)调色板操作
# 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
})出口业务
# 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")批处理
# 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/"
)🏗️ 建筑
项目结构
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错误处理
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}")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🧪 测试
运行所有测试：
pytest tests/ -v运行特定测试：
pytest tests/test_validation.py -v运行演示脚本：
python examples/demo_improvements.py📝 日志记录
日志包括：
- 运营跟踪
- 性能指标
- 带有上下文的错误详细信息
- 结构化JSON输出（可选）
日志示例：
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🤝 贡献
- 分叉存储库
- 创建要素分支
- 遵循编码标准：
- 使用类型提示 - 添加输入验证 - 包括错误处理 - 编写单元测试 - 更新文档
- 提交拉取请求
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件
🙏 鸣谢
- 原执行人：Divyansh Singh
- v2.0改进：增强的错误处理、配置、批处理等
📚 额外资源
- Aseprite API文件
- MCP文件
- 改进.md -详细的v2.0更改