JinDaGe - AsepriteMCP MCP Details

article

README

🚀 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 详细更改说明

AsepriteMCP