sprite-canon

一个 MCP 服务器，让 AI 生成的游戏精灵看起来像同一个游戏。

一个角色，三套服装——蓝色和红色行是 sprite_repaint 调用，而不是重新生成。相同的着色顺序，相同的轮廓，每次结果一致。

AI 生成器擅长制作漂亮的精灵，却不擅长让它与上一个匹配。要求同一个角色两次，调色板就会漂移，服装会变异，新帽子会漂浮在头顶上方 3 像素处——每个资源单独看都很好，但组装起来游戏看起来就不对劲。反复“直到匹配”的重新生成不会收敛；它烧钱，而且你无法对结果进行差异比较。

sprite-canon 采取了相反的方法，该方法源自一个真实游戏项目，该项目生成了约 4,000 帧，并艰难地吸取了所有教训：

1. 你的一致性规则变成数据——一个 sprite-canon.json（“canon”）保存调色板、命名颜色区域（皮肤、服装、轮廓等）、相对比例和检查阈值。与你的资源一起提交。

2. 验证是数字化的，而非视觉化的。 你无法用肉眼检查 96 种服装变体 × 8 个方向 × 4 帧。sprite_verify 返回针对实际发布缺陷的硬性通过/失败数字：偏离调色板的像素、帧间抖动的配饰、从背面亮而从正面暗的区域、触及脸部的重绘。

3. 修复是确定性的像素操作，而非重新生成。 将区域重绘到新的颜色渐变上会保留着色和轮廓，绝不触及受保护区域，并且每次产生相同输出。服装变体是一次工具调用，而不是提示词彩票。

安装

Claude Desktop — 一个文件，无需配置

1. 从最新版本下载 sprite-canon.mcpb。

2. 在 Claude Desktop 中，打开 设置 → 扩展（Windows 上为 ☰ 菜单 → 文件 → 设置）。

3. 将 .mcpb 文件拖入扩展页面，查看并点击安装。

（如果您的操作系统已注册 .mcpb 关联，双击文件也可以——拖放始终有效。替代方法：扩展 → 高级设置 → 安装扩展 → 选择文件。）

这就是全部安装过程：该捆绑包自带依赖项，Claude Desktop 提供 Node 运行时。需要 Claude Desktop 应用——Claude Code 请参见下文。

Claude Code / 其他 MCP 客户端

git clone https://github.com/useka12-eng/sprite-canon
cd sprite-canon && npm install

然后在项目的 .mcp.json（或任何 MCP 客户端配置）中注册：

{
  "mcpServers": {
    "sprite-canon": {
      "command": "node",
      "args": ["/path/to/sprite-canon/src/mcp/server.mjs"]
    }
  }
}

需要 Node 18+。无原生依赖——PNG/GIF 编解码器是自包含的。

自行构建捆绑包

npx @anthropic-ai/mcpb pack . dist/sprite-canon.mcpb

Related MCP server: mcp-spritesheet-forge

工具

输入可以是 PNG、动画 GIF 或 PNG 精灵表（cellW/cellH）。

工作流程

canon_init      → learn the palette from your existing good assets
canon_learn     → sample skin / outfit / outline once; mark face + outline protected
sprite_measure  → read the numbers before placing anything ("where do the eyes start?")
sprite_repaint  → make variants deterministically (outfits, teams, seasons)
sprite_verify   → prove it: face untouched, nothing left over, no jitter, on palette
sprite_sheet    → look at the result as a sheet, zoomed, before it enters the game

此工具编码的教训

这些不是假设——每一个都首先作为真实缺陷出现：

• 测量，不要假设比例。 将帽檐放置在“头部高度的 52%”恰好落在眼睛上：在 20 像素高的头上，眼睛距顶部 7–9 像素，因此每个固定比例都会碰到它们。sprite_measure 报告每帧面部实际开始的位置。

• 使用固定亮度范围进行重绘。 按图像归一化会将相同的源颜色映射到不同的输出，具体取决于区域可见多少——我们的帽子从背面亮，从正面暗。canon 记录每个区域的范围一次；重绘始终使用它。

• 结构性保护区域。 “在面部周围小心”在规模上会失败。protected: true 意味着重绘不能触及它，验证证明它没有触及。

• 修补 GIF 调色板，不要重新编码。 索引 GIF 的颜色存在于其颜色表中——全局和每帧局部（仅修补全局表是经典的半修复）。替换表条目会完美同步地重新装扮每一帧，零损失。

• 区域定义有缺口；统计它们。 重绘后残留的 12 个旧颜色像素对眼睛不可见，但对 leftover 显而易见。当它触发时，canon_info 的统计显示你的区域未覆盖哪些颜色。

比例表

sprite_verify 的 scale 检查读取 canon.scale.heights——相对于参考资源（等于 1 的条目）的相对大小。目前没有工具写入此部分；手动添加到 sprite-canon.json：

"scale": { "heights": { "hero": 1, "house": 3.4, "chicken": 0.45 } }

然后使用 scaleNames 将文件基名映射到这些键进行验证。这会在玩家发现之前一周捕捉到经典的“房子比英雄小”问题。

实用说明

• 始终传递 canonPath（或 canon 所在目录之上的文件）。stdio MCP 服务器的工作目录属于客户端，而不是你的项目，因此工具拒绝从 cwd 猜测。

• 编解码器限制：PNG 必须是 8 位、非隔行、RGB/RGBA/调色板（常见的像素艺术情况；16 位或隔行文件会被拒绝并显示明确错误）。GIF 编码器在每文件最多 255 种不透明颜色时精确——超出后，最近调色板吸附。

• sprite_sheet 内联返回图像，最大约 800 KB；更大的表仅返回文件路径。

• 精灵表逐格往返：空单元格保持为空，不会压缩。

这不是什么

• 不是生成器。将其与任何制作艺术品的工具配对（PixelLab、Aseprite、Gemini、手绘像素）；sprite-canon 是保持结果连贯的层。

• 不是图集打包器/碰撞工具——sprite-tools 很好地覆盖了这一点。

• 不是魔法：你每个项目花约 10 分钟教它你的 canon。正是这种投入使每个后续检查和修复都值得信赖。

开发

npm test          # unit + end-to-end MCP tests (22)

测试套件包括针对 v0.1 中对抗性多代理审查发现的每个错误的回归测试——表单元格压缩、GIF 处置语义、假成功响应、静默零检查通过。如果其中一个失败，说明曾经存在的错误又回来了。

MIT