Skip to main content
Glama

sprite-canon

MCP server that keeps AI-generated game sprites looking like ONE game.

original vs deterministic repaints — shading survives, silhouettes never change

One character, three outfits — the blue and red rows are sprite_repaint calls, not regenerations. Same shading order, same silhouette, same result every time.

AI generators are great at making a pretty sprite and terrible at making it match the last one. Ask for the same character twice and the palette drifts, the outfit mutates, the new hat floats 3 pixels above the head — each asset is fine alone, and the game looks wrong assembled. Regenerating "until it matches" doesn't converge; it burns money and you can't diff the result.

sprite-canon takes the opposite approach, extracted from a real game project that generated ~4,000 frames and learned every lesson the hard way:

  1. Your consistency rules become data — a sprite-canon.json ("the canon") holding the palette, named colour regions (skin, outfit, outline…), relative scale, and check thresholds. Committed next to your assets.

  2. Verification is numeric, not visual. You cannot eyeball 96 outfit variants × 8 directions × 4 frames. sprite_verify returns hard pass/fail numbers for the defects that actually ship: off-palette pixels, accessories that jitter between frames, a region that's bright from behind and dark from the front, a repaint that touched the face.

  3. Fixes are deterministic pixel operations, not regeneration. Repainting a region onto a new colour ramp preserves shading and silhouettes, never touches protected regions, and produces the same output every time. An outfit variant is one tool call, not a prompt lottery.

Install

Claude Desktop — one file, no config

  1. Download sprite-canon.mcpb from the latest release.

  2. In Claude Desktop, open Settings → Extensions (☰ menu → File → Settings on Windows).

  3. Drag the .mcpb file into the Extensions page, review, and click Install.

(Double-clicking the file also works if your OS has the .mcpb association registered — drag-and-drop always works. Alternative: Extensions → Advanced settings → Install Extension → pick the file.)

That's the whole install: the bundle ships its own dependencies, and Claude Desktop provides the Node runtime. Requires the Claude Desktop app — for Claude Code see below.

Claude Code / other MCP clients

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

Then register in your project's .mcp.json (or any MCP client config):

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

Requires Node 18+. No native dependencies — the PNG/GIF codecs are self-contained.

Build the bundle yourself

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

Related MCP server: Spiritmarch Aseprite MCP

Tools

Tool

What it does

canon_init

Create the canon; learn the palette from sample images (colours used ≥ N times — rarer ones are usually anti-aliasing noise)

canon_learn

Define a region by sampling a few pixels, listing colours, or an HSL rule. Records the region's luminance range. Mark face/outline protected

canon_info

Show the resolved canon + census a file against it (unmatched pixels = gaps in your region definitions)

colors_inspect

List colours actually used, by frequency and luminance — raw material for canon decisions

sprite_measure

Per-frame anatomy (bbox, cap/head width, waist row, first row of each region) + cross-frame jitter

sprite_verify

Numeric checks: palette, jitter, spread, protected, leftover, scale

sprite_repaint

Deterministically recolour a region onto a dark→light ramp; protected regions are untouchable

sprite_sheet

Zoomed contact sheet returned inline as an image — judge consistency on sheets, not in-game

gif_patch

Lossless GIF ops: palette substitution across all colour tables (zero generation loss), retiming

Inputs can be PNGs, animated GIFs, or PNG spritesheets (cellW/cellH).

The workflow

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

Does it generalize?

We blind-tested the full workflow on three freshly generated subjects in foreign styles — a 64px animated fox GIF, a 32px robot spritesheet, a 48px hooded merchant PNG — each driven end-to-end by an independent agent. All passed; the misses are documented too. Read the validation report.

Lessons this tool encodes

These are not hypothetical — each one shipped as a real defect first:

  • Measure, don't assume proportions. A hat brim placed at "52% of head height" landed exactly on the eyes: on a 20px head the eyes are 7–9px from the top, so every fixed ratio hits them. sprite_measure reports where the face actually starts, per frame.

  • Repaint with a fixed luminance range. Normalising per image maps the same source colour to different outputs depending on how much of the region is visible — our hat was bright from behind, dark from the front. The canon records each region's range once; repaint always uses it.

  • Protect regions structurally. "Be careful around the face" fails at scale. protected: true means repaint cannot touch it and verify proves it didn't.

  • Patch GIF palettes, don't re-encode. An indexed GIF's colours live in its colour tables — global and per-frame local ones (patching only the global table is the classic half-fix). Substituting table entries re-dresses every frame in perfect sync with zero loss.

  • Region definitions have gaps; census them. 12 stray pixels of the old colour surviving a repaint is invisible to the eye and obvious to leftover. When it fires, canon_info's census shows which colours your regions don't cover.

The scale table

sprite_verify's scale check reads canon.scale.heights — relative sizes in units of a reference asset (the entry equal to 1). No tool writes this section yet; add it to sprite-canon.json by hand:

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

Then verify with scaleNames mapping file basenames to those keys. This catches the classic "the house is smaller than the hero" a week before your players do.

Practical notes

  • Always pass canonPath (or a file the canon sits above). A stdio MCP server's working directory belongs to the client, not your project, so the tools refuse to guess from cwd.

  • Codec limits: PNG must be 8-bit, non-interlaced, RGB/RGBA/palette (the common pixel-art cases; 16-bit or interlaced files are rejected with a clear error). The GIF encoder is exact up to 255 opaque colours per file — beyond that, nearest-palette snapping.

  • sprite_sheet returns the image inline up to ~800 KB; larger sheets return the file path only.

  • Spritesheets round-trip cell-for-cell: empty cells stay empty, nothing is compacted.

What this is not

  • Not a generator. Pair it with whatever makes your art (PixelLab, Aseprite, Gemini, hand pixels); sprite-canon is the layer that keeps the results coherent.

  • Not an atlas packer / collision tool — sprite-tools covers that well.

  • Not magic: you spend ~10 minutes once per project teaching it your canon. That investment is exactly what makes every later check and fix trustworthy.

Development

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

The test suite includes regression tests for every bug an adversarial multi-agent review found in v0.1 — sheet cell compaction, GIF disposal semantics, fake-success responses, silent zero-check passes. If one fails, a bug that already existed once is back.

MIT

Available Tools

9 tools
canon_infoA

Show the resolved canon (palette size, regions with their rules and protection flags, scale table, thresholds) and optionally census a file against it — how many pixels each region matches, and how many match nothing (unmatched pixels mean your region definitions have gaps). Pass canonPath or censusFile — without either there is nowhere to search from (the server's working directory is the client's, not your project's).

Inputs: cellH, cellW, canonPath, censusFile, +1 more.

canon_initA

Create sprite-canon.json for a project: the single source of truth for palette, regions, scale and check thresholds. Learns the palette from sample images (colours used at least minCount times; rarer colours are usually anti-aliasing noise). Run once per project, then commit the file.

Inputs: dir (required), name, cellH, cellW, +3 more.

canon_learnA

Define or update a named region in the canon (e.g. skin, hair, outfit, outline). Give a few [x,y] points on sample images; the sampled colours (optionally expanded by absorb) become the region. The region's luminance range is recorded — repaint uses that FIXED range so the same source colour always maps to the same output colour in every frame and direction. Mark regions like face/eyes/outline as protected: repaint will never touch them and verify will fail if anything else does. Instead of points you may pass explicit colors, or an HSL rule (hue/sat/light ranges) for anti-aliased art — an HSL-only region additionally needs lumRange if you ever want to repaint it. Updates MERGE additively into an existing region; pass replace=true to redefine it from scratch (the only way to remove a mis-sampled colour).

Inputs: region (required), hue, sat, cellH, +9 more.

colors_inspectA

List the colours actually used in files, sorted by frequency, with luminance — the raw material for canon_init/canon_learn decisions. Use it to spot near-duplicate colours, anti-aliasing noise, and which hexes belong to which visual part before defining regions.

Inputs: files (required), top, cellH, cellW.

gif_patchA

Operations on animated GIFs. 'palette' swaps colours in every colour table (global AND per-frame local — patching only the global table is a classic half-fix) without touching frame data: zero generation loss, every frame changes in perfect sync — the correct way to re-dress an indexed sprite. The response reports how many table entries each source colour actually matched; 0 means that hex isn't in the file (use colors_inspect to find the exact hexes). 'retime' re-times all frames to msPerFrame. GIF delays are quantised to 10ms steps with a 20ms minimum; pixels survive a decode/re-encode that is exact up to 255 opaque colours (beyond that, nearest-palette snapping). Real bug this fixes: an animation authored at 1.8s being cut off by game code that frees the sprite after 0.62s — retime the GIF instead of dropping frames.

Inputs: file (required), action (required), outFile (required), colorMap, +1 more.

sprite_measureA

Measure a sprite's anatomy per frame and its cross-frame jitter: bounding box, top row, widest row, cap (head) width, waist (neck) row, and — with canon regions — the first row of each region (e.g. where the face starts). Use before placing anything relative to a sprite: measured rows beat guessed proportions. Real bug this catches: a hat brim placed at '52% of head height' landed exactly on the eyes, because eye rows vary per frame — measure, don't assume.

Inputs: file (required), cellH, cellW, canonPath.

sprite_repaintA

Deterministically recolour a canon region onto a colour ramp (dark→light hex list) — the alternative to regenerating with AI and losing consistency. Shading survives (luminance maps onto the ramp using the region's FIXED recorded range), silhouettes never change, protected regions are never touched, and the same input always gives the same output. Use maskFromFile when repainting an already-recoloured variant: regions are matched on the original (identical pixel layout), paint is applied to the variant. Writes to outFile (never overwrites the input unless outFile equals it).

Inputs: file (required), ramp (required), region (required), outFile (required), +5 more.

sprite_sheetA

Compose a zoomed contact sheet (PNG on a checkerboard) from sprites — one row per file, one column per frame — and return it as an image so you can LOOK at what you just made. Judge consistency on sheets, not in-game: every visual defect we ever caught was caught on a sheet. Use crop to zoom into the area under suspicion (e.g. just the head).

Inputs: files (required), outFile (required), crop, zoom, +4 more.

sprite_verifyA

Run numeric consistency checks and get hard pass/fail numbers — the replacement for eyeballing hundreds of frames. Checks: 'palette' (every pixel on the canon palette), 'jitter' (landmarks stay put across frames), 'spread' (a region's mean luminance agrees across a file group — catches 'bright from behind, dark from the front'), 'protected' (vs baseFile: face/outline pixels untouched), 'leftover' (vs baseFile: no source-region pixel survived inside a repainted area), 'scale' (relative sizes match the canon table). Files may be directories (all PNG/GIF inside).

Inputs: files (required), cellH, cellW, checks, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool has a clearly different job: inspecting colors, defining canon, measuring sprites, verifying, repainting, compositing sheets, and patching GIFs. The only mild overlap is between sprite_repaint and gif_patch palette swapping, but their contexts (canon region remapping vs. indexed GIF color tables) are distinct enough to avoid real confusion.

    Naming Consistency4/5

    Names follow a clear snake_case pattern of a domain prefix (colors, canon, sprite, gif) plus an action or noun. Minor grammatical inconsistency exists (colors_inspect, canon_info, sprite_sheet are noun-heavy while canon_learn and sprite_repaint are verb-focused), but the overall convention is predictable and readable.

    Tool Count5/5

    Nine tools is a well-scoped set for a sprite canon workflow: each tool covers a distinct step from inspection and canon creation to measurement, verification, repainting, contact sheets, and GIF operations. Nothing feels redundant or missing at the count level.

    Completeness4/5

    The suite covers the full workflow: inspect, initialize canon, define regions, measure, verify, repaint, and generate contact sheets. Minor gaps exist, such as no explicit tool for deleting or renaming a region, and global canon settings like scale/thresholds can only be managed through init or by editing the file directly.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to create, draw, and refine Aseprite documents through deterministic canvas, layer, frame, tag, and palette tools, with pixel analyzers, style validation, and preview/diff visual feedback. It also supports spritesheet and animated GIF export, producing multi-layer game-ready assets.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables agents to author, validate, inspect, patch, and render editable JSON pixel-art and animation recipes through local tools, producing PNG contact sheets, APNGs, sprite atlases, and related export bundles.
      2
      8
      1,639 npm
      95
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create layered pixel-art sprites and animations, inspect pixels, and export images, spritesheets, GIFs, APNGs, and TrueType pixel fonts. Documents and edits stay local, accessible over stdio MCP or callable directly from a shell.
      40
      MIT