Aseprite Agent MCP

Aseprite Agent MCP

通过 MCP stdio 实现本地优先的像素艺术创作和经过验证的游戏资源导出。

状态：0.2.0 alpha。 基于 aseprite-mcp 构建，原作者为 Brendan Malloy（MIT），固定到 8caabf9ce240a040ca2c94d3d7366c9d8dd63653。 新增的生产层提供带预览的原子编辑、严格的资源契约、 经过验证的 Phaser 导出、工具配置、角色阵容工具、工作区锁定和崩溃安全保存。 详见 NOTICE、 LICENSE 和 UPSTREAM_INVENTORY.json。 沿用的 Python 命名空间仍为 aseprite_mcp；软件包和命令为 aseprite-agent-mcp。

114 个工具涵盖原生文档、像素绘制、图层、cel、帧、调色板、 标签、切片、变换、tilemap、检查和导出。生产流程 新增带图像反馈的原子编辑、严格的类型化资源契约、带标签的 全帧预览、角色阵容工具，以及经过重新打开的原生主文件验证的 Phaser 资源包。默认情况下，服务会提供包含 42 个工具的 core 配置 （参见工具配置）。精确的架构请参见生成的 工具参考。

安装和运行

安装 Python 3.10+、uv 或 pipx，以及你拥有许可证的、支持 Lua 脚本的 Aseprite。你也可以根据其 EULA 自行构建 Aseprite。此软件包只会通过 ASEPRITE_PATH 调用你已安装的可执行文件；不会捆绑 Aseprite、 其安装程序、Lua 运行时或美术资源。

安装已发布的软件包：

uvx aseprite-agent-mcp
# or: pipx install aseprite-agent-mcp
# then: aseprite-agent-mcp

运行前设置 ASEPRITE_PATH。MCP 客户端命令示例（请替换路径）：

# Windows (PowerShell)
claude mcp add aseprite --env ASEPRITE_PATH=C:\\path\\to\\Aseprite.exe -- uvx aseprite-agent-mcp
# macOS
claude mcp add aseprite --env ASEPRITE_PATH=/Applications/Aseprite.app/Contents/MacOS/aseprite -- uvx aseprite-agent-mcp
# Linux
claude mcp add aseprite --env ASEPRITE_PATH=/path/to/aseprite -- uvx aseprite-agent-mcp

对于使用 JSON 的客户端（包括 Codex MCP 配置），请使用以下格式：

{
  "mcpServers": {
    "aseprite": {
      "command": "uvx",
      "args": ["aseprite-agent-mcp"],
      "env": {
        "ASEPRITE_PATH": "/path/to/aseprite",
        "ASEPRITE_MCP_WORKSPACE": "/path/to/assets"
      }
    }
  }
}

支持本地 stdio MCP 服务的 Grok 客户端可以使用相同的可执行文件、 参数和环境字段。不同客户端的配置键可能有所不同。

从源码检出版本并进行开发：

uv sync --locked --group dev
$env:ASEPRITE_PATH = 'C:\path\to\aseprite.exe'
$env:ASEPRITE_MCP_WORKSPACE = 'C:\path\to\assets'
uv run --no-sync aseprite-agent-mcp

该命令通过 stdin/stdout 使用 MCP 通信，并等待客户端连接。诊断日志会输出到 stderr。替换占位路径后，可在客户端中使用 mcp-config.example.json。 本项目不会修改客户端设置。

这个小型 GIF 是由程序生成的示例美术图，使用 uv run python scripts/generate_demo.py 生成。它展示了预期的像素艺术 效果；并非 Aseprite 实际运行画面的截图。完整的 Aseprite MCP 往返验证说明见验证部分。

工具配置

每个工具的说明和架构都会占用 Agent 的上下文，因此服务会通过 ASEPRITE_MCP_TOOLS 指定要启用的配置。该变量是一个以逗号分隔的名称列表：

值	启用内容
core（默认）	42 个工具：生成/导入、创建、绘制、制作动画、预览、验证、导出和角色相关工具
all	所有受支持的工具（114 个）
一个分组	一个工具模块，例如 tilemap、effects、slices、palette、workflow
一个工具名称	一个额外工具，例如 core,add_outline

遇到未知名称时，服务会在启动时停止。分组列于工具参考顶部。

变量	默认值	含义
ASEPRITE_PATH	自动检测	Aseprite 可执行文件
ASEPRITE_MCP_WORKSPACE	项目中的 workspace/	相对路径的根目录
ASEPRITE_MCP_TOOLS	core	工具配置，如上所述
ASEPRITE_MCP_LOCK_WAIT	15	调用等待工作区空闲的秒数（0 表示立即失败）
ASEPRITE_MCP_TIMEOUT	90	每个 Aseprite 进程的超时秒数
ASEPRITE_MCP_ALLOW_ABSOLUTE	关闭	允许在许可的根目录内使用绝对路径语法
ASEPRITE_AGENT_ALLOWED_ROOTS	[]	额外根目录的 JSON 列表

推荐工作流

将生成的图像转换为可编辑动画

让图像模型绘制角色和关键姿势，然后使用 import_generated_image 将一张 PNG 转换为像素网格，再使用 assemble_animation 清理并对齐 有序姿势列表。这两个工具都位于默认的 core 配置中。

import_generated_image(filename="base.png", output_directory="base-clean",
                       width=32, height=32, colours=16)
assemble_animation(filenames=["idle-1.png", "idle-2.png", "idle-3.png", "idle-4.png"],
                   output_directory="idle-clean", width=32, height=48, tag="idle",
                   colours=16, alignment="bounding-box",
                   durations_ms=[180, 140, 180, 140], outline="#152b32")

• method="nearest" 会对网格进行采样；"majority" 会为每个源单元格选择出现频率最高的 RGBA 值，平票时采用确定性规则。majority 仅用于缩小尺寸。
• width 和 height 支持每边最多 256px 的网格。对于细节丰富的精灵图， 请使用 height=128、colours=32 到 48、method="majority" 和 palette_first=True。优先使用调色板的模式会先将一个共享源调色板进行映射，再进行 投票，因此相近的生成色调会被计为同一种颜色。此模式需选择启用； 现有调用会保持原有行为。
• palette=["#RRGGBB", ...] 会映射到指定颜色。否则，colours 会为整个动画生成 一个共享的自动调色板。经过 alpha_threshold（默认值为 128）处理后，Alpha 值为二元值。 透明部分不计入颜色数量；可选的 1px 描边可能会增加一种颜色，并会在单元格边界处裁切。
• background="#RRGGBB" 只会移除与边界连通且颜色匹配的像素，还可选用 background_tolerance。它会保留封闭区域中的细节，是颜色键控，不是语义分割。已有的透明区域无需背景键。
• 边界框对齐会让所有姿势使用相同缩放比例，并将每个轮廓的底部居中。alignment="anchor" 接受每个同尺寸输入各自的一个源 [x,y]， 并将其放置在 (width//2,height-2)；如果会发生裁切则拒绝处理。"none" 会保留每个画布。 请保持姿势缩放比例和留白一致，并检查返回的预览。

每个新输出目录都包含 master.aseprite、清理后的帧 PNG、 sheet.png、sheet.json 和 qa.json。原生主文件会通过 Aseprite 的 Lua API 重新打开；发布前会检查每个渲染帧、 标签范围、时长和图集像素，然后以原子操作发布，且不会覆盖已有目录。源 PNG 会被保留。输入限制为每张最多 400 万像素、总计 1600 万像素、128 帧和 100 万输出像素。

生成的信使演示包含 原始模型输出、清理后的基础图、4 帧待机动画、可编辑主文件，以及可复现的本地脚本。像素验证可证明文件完整性，但 不会评估美术质量，也不会将不一致的关键姿势变成连贯的动画。

行走演示采用 8 姿势生成流程、 128px 高的单元格、共享的 48 色调色板和明确的脚部锚点。它包含 循环 GIF，以及基于相同源图和调色板的 64px/128px 对比图。

1. health_check 可验证本地 CLI 和 Lua 路径能够创建并导出内容。
2. create_sprite 会创建可编辑的 .aseprite 主文件。
3. ase_apply_and_preview 会在一个事务中应用一批带类型的操作，并返回 渲染后的 PNG。操作失败时文件保持不变。如果之后预览失败，会明确说明编辑已保存。
4. ase_preview_animation 会显示每一帧，且不会进行平滑处理。
5. ase_validate_asset_contract 会检查几何信息、帧数、精确的标签范围、 标签播放、调色板成员关系、二元 Alpha、空帧，以及可选的 每行脚部/中心偏移。未知字段会报错。
6. ase_export_phaser 会创建一个包含图集 PNG、哈希图集 JSON、 动画时序、加载器 JS、契约和 QA 的打包目录。发布前会重新打开主文件和导出的 PNG，并比较每一帧的 RGBA 像素。除非设置 replace=true，否则会拒绝 已存在的目录；设置后会通过重命名替换之前的打包内容。原生主文件会保留。

构建角色阵容

1. draw_pixel_rows 使用文本行和颜色键绘制整帧，例如： rows=["..oo..", ".oxxo."]、key={"o": "#203040", "x": "#f0c060"}。未知 字符会报错；. 和空格会跳过。
2. 使用批量操作 copy_cel 和 offset_cel 制作动画（无需重绘即可移动和踏步），并为每个动画添加标签。
3. derive_mirrored_tag 会从 walk_right 创建 walk_left。
4. 使用 save_sprite_as 保存模板，再用 recolor_sprite 为每个角色重新着色；也可以用 copy_frames_from 从共享基础图像创建角色。
5. ase_preview_animation 会在棋盘格背景上为每个标签显示一行带标签的动画。
6. ase_export_cast_atlas 会根据每个主文件各自的契约进行验证，并写入一个 Phaser 图集：帧名为 <character>/<tag>_<nn>，动画名为 <character>:<tag>。

编辑会先写入同级临时文件，再通过重命名保存，因此即使 Aseprite 进程被强制终止，也不会留下只写入一部分的主文件。帧号必须存在：超出范围 的帧会报错，不会钳制到最近的帧。 所有帧号均从 1 开始。契约行必须指定一个精确且连续的动画标签。 调色板条目必须是内联十六进制颜色，不能使用任意文件路径。最终验证或导出前请隐藏参考图层：锁定的图层仍然会显示像素。

{
  "name": "robot",
  "cell": {"width": 16, "height": 16},
  "rows": [
    {"tag": "walk_down", "frames": 4},
    {"tag": "idle", "frames": 2, "playback": "pingpong"},
    {"tag": "sleep", "frames": 2, "repeat": 0, "check_anchor": false}
  ],
  "alpha": "binary",
  "palette": ["#315c88", "#8bd5ed", "#223344"],
  "anchor": {"max_foot_drift": 0.0, "max_center_drift": 0.0}
}

验证

uv run pytest
uv run pytest --run-aseprite
uv run python scripts/proof_stdio.py --output ./workspace/proof-final

每次验证运行都使用一个新的输出目录。验证流程通过真实的 MCP 标准输入/输出客户端与服务通信，创建 16 个不同的合成帧，对比保存并重新打开的主文件，导出精灵表和 GIF，测试回滚以及覆盖/路径拒绝，并确认故意损坏的资源无法通过导出 QA。 它会写入 proof.json 和可视化产物。请参阅验证。

要在 Phaser 3.90.0 中播放该输出：

npm ci --prefix examples/phaser --ignore-scripts
uv run python -m http.server 8795 --bind 127.0.0.1

打开 http://127.0.0.1:8795/examples/phaser/。只有当四个动画中的所有四帧都播放完毕后，页面才会报告成功。 它使用本地 npm 开发依赖；安装后，MCP 本身不依赖网络。 若要在 workspace/my-proof 下进行全新运行，请使用 http://127.0.0.1:8795/examples/phaser/?proof=my-proof 播放该次运行的输出。

边界与当前限制

• 仅支持 Stdio；MCP 服务中没有实时编辑器桥接或网络监听器。
• 路径仅限于工作区和明确配置的允许根目录。 ASEPRITE_MCP_ALLOW_ABSOLUTE=1 允许使用绝对路径语法，但绝不代表可以不受限制地访问。 其他根目录：ASEPRITE_AGENT_ALLOWED_ROOTS='["/absolute/asset/root"]'。
• 会拒绝目录遍历、符号链接逃逸、不安全的 Windows 设备／流路径和文件名模板展开。部分继承的工具会被刻意隐藏。
• 这是供本地受信任用户使用的工具，不是操作系统沙箱。不要让不受信任的本地进程替换符号链接，也不要并发编辑同一个主文件。在同一工作区中共享的 MCP 调用会使用操作系统咨询锁；并发调用最多等待 ASEPRITE_MCP_LOCK_WAIT 秒，之后会失败并提示“Workspace busy”。所有写入共享资源的服务都必须使用同一工作区，包括使用其他根目录时。 直接调用 Python、编辑器 GUI 和其他程序不会获取此锁。
• QA 会比较合成后的 RGBA 像素。它无法证明艺术质量、解剖结构／动作是否正确、调色板索引身份、锚点语义，或允许的调色板内是否存在平滑处理。锚点检查适用于主体不变且脚踏实地的动画。
• 测试夹具是程序生成的证据，不是可用于生产的行走循环美术素材。
• Phaser 捆绑包会在暂存区中验证，并通过一次原子、不会覆盖现有内容的目录重命名来发布；此操作适用于受支持的本地 Windows、Linux 和 macOS 文件系统。不支持的重命名语义会安全失败。进程终止后，最终路径要么不存在，要么内容完整；但可能遗留隐藏的暂存文件夹。 这无法保证断电后的持久性或网络文件系统行为。
• 实时编辑器回合撤销、私有项目约定、更全面的重采样／边缘检查和正式的视觉黄金基线仍在计划中。

发布

标签工作流会构建、检查并通过可信发布发布到 PyPI，然后验证并发布 MCP Registry 条目。首先为此仓库、release.yml 和 pypi 环境配置 PyPI 的可信发布者。 软件包版本来自 src/aseprite_mcp/__init__.py。

GitHub Actions 不可用时，uv run python scripts/release --tag v0.2.0 会检查干净的代码树、lint、测试和分发包，然后打印发布命令，但不会执行发布。--publish 还要求在环境中明确设置 UV_PUBLISH_TOKEN，并且本地安装了 mcp-publisher 可执行文件。 此选项会运行 uv publish、Registry 验证、交互式 GitHub 登录和 Registry 发布。仅在审查发布内容并设置好令牌后运行。

安全 · 路线图 · 变更记录