🚀 Aseprite MCP Tools v2.0
Aseprite MCP Tools v2.0 是一款强大的 Python MCP（模型上下文协议）服务器，用于与 Aseprite 进行编程式交互。它具备增强的错误处理、配置管理、批处理等功能！
点击查看日语版 | macOS 安装指南
🚀 快速开始
Aseprite MCP Tools v2.0 提供了一系列强大的功能，可帮助你更高效地与 Aseprite 进行交互。你可以创建精灵、添加图层和帧、绘制各种图形、管理调色板、批量处理文件等。
✨ 主要特性
v2.0 新增特性
- 🛡️ 全面的错误处理：自定义异常，提供详细且可操作的错误信息
- 🔧 配置管理：基于 Pydantic 的设置，支持 JSON/YAML 格式
- 📝 高级日志记录：结构化日志记录，包含性能指标
- 🎨 调色板管理：创建、应用和提取调色板
- ⚡ 批处理：并行处理多个文件
- 🏗️ Lua 脚本生成器：生成简洁、类型安全的 Lua 脚本
- 🔒 增强的安全性：输入验证和路径遍历保护
- 🧪 全面的测试覆盖：完整的单元测试
核心绘图工具
- 画布操作：创建精灵、添加图层和帧
- 绘图工具：绘制像素、线条、矩形、圆形和填充操作
- 导出工具：支持多种格式导出，支持缩放和图层
新调色板工具（v2.0）
- 预设调色板：GameBoy、NES、PICO - 8、CGA、单色、棕褐色
- 自定义调色板：创建和应用自定义配色方案
- 调色板提取：从现有图像中提取颜色
- 颜色重映射：替换精灵中的颜色
批处理（v2.0）
- 批量调整大小：按比例调整多个精灵的大小
- 批量导出：将多个文件转换为不同格式
- 批量应用调色板：将调色板应用于多个文件
- 自定义脚本：对文件集运行 Lua 脚本
📦 安装指南
要求
- Python 3.13+
- Aseprite（需单独安装）
Claude 桌面配置
使用 UV（推荐）
{
"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
💻 使用示例
基础用法
# 创建一个新的精灵
await create_canvas(320, 240, "my_sprite.aseprite")
# 绘制像素
await draw_pixels("my_sprite.aseprite", [
{"x": 10, "y": 10, "color": "FF0000"}, # 红色
{"x": 11, "y": 10, "color": "00FF00"}, # 绿色
{"x": 12, "y": 10, "color": "0000FF"} # 蓝色
])
# 绘制图形
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)
# 填充区域
await fill_area("my_sprite.aseprite", 100, 100, "00FFFF", tolerance=10)
高级用法
图层和帧管理
# 添加一个新的图层
await add_layer("my_sprite.aseprite", "Background")
# 添加动画帧
await add_frame("my_sprite.aseprite", after_frame=0)
调色板操作
# 应用预设调色板
await apply_preset_palette("my_sprite.aseprite", "gameboy")
# 可用预设：gameboy, gameboy-pocket, nes, pico-8, cga, monochrome, sepia
# 创建自定义调色板
await create_palette("my_sprite.aseprite", [
"264653", "2A9D8F", "E9C46A", "F4A261", "E76F51"
])
# 从图像中提取调色板
await extract_palette_from_image("reference.png", max_colors=16)
# 获取调色板信息
await get_palette_info("my_sprite.aseprite")
# 重映射颜色
await remap_colors("my_sprite.aseprite", {
"FF0000": "00FF00", # 红色到绿色
"0000FF": "FFFF00" # 蓝色到黄色
})
导出操作
# 导出单个文件
await export_sprite("my_sprite.aseprite", "output.png", scale=2.0)
# 按帧范围导出
await export_sprite("animation.aseprite", "frames.gif", frame_range="1-10")
# 分别导出每个图层
await export_layers("my_sprite.aseprite", "layers/", format="png")
批处理
# 调整多个精灵的大小
await batch_resize(
input_dir="sprites/",
output_dir="sprites_small/",
scale=0.5,
file_pattern="*.aseprite"
)
# 批量导出为 PNG
await batch_export(
input_dir="sprites/",
output_dir="exports/",
format="png",
scale=2.0
)
# 将调色板应用于多个文件
await batch_apply_palette(
input_dir="sprites/",
palette_file="my_palette.aseprite",
create_backup=True
)
# 对多个文件运行自定义 Lua 脚本
await batch_process_custom(
input_dir="sprites/",
lua_script="app.activeSprite:flatten()",
output_dir="flattened/"
)
🔧 技术细节
项目结构
aseprite-mcp/
├── aseprite_mcp/
│ ├── core/
│ │ ├── commands.py # Aseprite 命令执行
│ │ ├── config.py # 配置管理
│ │ ├── exceptions.py # 自定义异常
│ │ ├── logging.py # 日志系统
│ │ ├── lua_builder.py # Lua 脚本生成器
│ │ └── validation.py # 输入验证
│ └── tools/
│ ├── batch.py # 批处理
│ ├── canvas.py # 画布操作
│ ├── drawing.py # 绘图工具
│ ├── export.py # 导出功能
│ └── palette.py # 调色板管理
├── tests/ # 单元测试
├── examples/ # 示例脚本
└── config.example.yaml # 配置示例
错误处理
try:
result = await create_canvas(-100, 200, "test.aseprite")
except ValidationError as e:
print(f"验证失败: {e}")
except AsepriteError as e:
print(f"Aseprite 错误: {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() # 返回简洁的 Lua 代码
🧪 测试
运行所有测试：
pytest tests/ -v
运行特定测试：
pytest tests/test_validation.py -v
运行演示脚本：
python examples/demo_improvements.py
📝 日志记录
日志包括：
- 操作跟踪
- 性能指标
- 错误详情及上下文
- 结构化 JSON 输出（可选）
示例日志：
2024-06-11 10:30:45 - aseprite_mcp - INFO - 操作: create_canvas
2024-06-11 10:30:45 - aseprite_mcp - INFO - 画布创建成功
2024-06-11 10:30:45 - aseprite_mcp - INFO - 性能: create_canvas 耗时 0.234s
🤝 贡献
- 分叉仓库
- 创建功能分支
- 遵循编码标准：
- 使用类型提示
- 添加输入验证
- 包含错误处理
- 编写单元测试
- 更新文档
- 提交拉取请求
📄 许可证
本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。
🙏 致谢
- 原始实现：Divyansh Singh
- v2.0 改进：增强的错误处理、配置管理、批处理等
📚 更多资源
- Aseprite API 文档
- MCP 文档
- IMPROVEMENTS.md - v2.0 详细更改说明