sprite-canon

MCP-Server, der KI-generierte Game-Sprites wie EIN Spiel aussehen lässt.

Ein Charakter, drei Outfits – die blauen und roten Zeilen sind sprite_repaint-Aufrufe, keine Neugenerierungen. Gleiche Schattierungsreihenfolge, gleiche Silhouette, jedes Mal dasselbe Ergebnis.

KI-Generatoren sind großartig darin, ein hübsches Sprite zu erzeugen, und schrecklich darin, es an das vorherige anzupassen. Frag zweimal nach demselben Charakter und die Palette driftet, das Outfit mutiert, der neue Hut schwebt 3 Pixel über dem Kopf – jedes Asset ist für sich gut, und das Spiel sieht zusammengebaut falsch aus. „Bis es passt" neu zu generieren konvergiert nicht; es verbrennt Geld und man kann das Ergebnis nicht diffen.

sprite-canon verfolgt den gegenteiligen Ansatz, extrahiert aus einem echten Spielprojekt, das ~4.000 Frames generiert hat und jede Lektion auf die harte Weise gelernt hat:

1. Deine Konsistenzregeln werden zu Daten – eine sprite-canon.json („der Kanon"), die die Palette, benannte Farbregionen (Haut, Outfit, Umriss…), relative Skalierung und Prüfschwellen enthält. Neben deinen Assets eingecheckt.

2. Verifikation ist numerisch, nicht visuell. Du kannst nicht 96 Outfit-Varianten × 8 Richtungen × 4 Frames mit dem Auge prüfen. sprite_verify liefert harte Pass/Fail-Zahlen für die Defekte, die tatsächlich auftreten: Off-Palette-Pixel, Accessoires, die zwischen Frames zittern, eine Region, die von hinten hell und von vorne dunkel ist, eine Neufärbung, die das Gesicht berührt hat.

3. Fixes sind deterministische Pixeloperationen, keine Neugenerierung. Das Neufärben einer Region auf eine neue Farbrampe erhält Schattierung und Silhouetten, berührt niemals geschützte Regionen und erzeugt jedes Mal dasselbe Ergebnis. Eine Outfit-Variante ist ein Tool-Aufruf, keine Prompt-Lotterie.

Installation

Claude Desktop – eine Datei, keine Konfiguration

1. Lade sprite-canon.mcpb vom neuesten Release herunter.

2. Öffne in Claude Desktop Einstellungen → Erweiterungen (☰-Menü → Datei → Einstellungen unter Windows).

3. Ziehe die .mcpb-Datei auf die Erweiterungsseite, überprüfe und klicke auf Installieren.

(Doppelklick auf die Datei funktioniert auch, wenn dein Betriebssystem die .mcpb-Zuordnung registriert hat – Drag-and-Drop funktioniert immer. Alternative: Erweiterungen → Erweiterte Einstellungen → Erweiterung installieren → Datei auswählen.)

Das ist die gesamte Installation: Das Bundle bringt seine eigenen Abhängigkeiten mit, und Claude Desktop stellt die Node-Laufzeit bereit. Erfordert die Claude Desktop-App – für Claude Code siehe unten.

Claude Code / andere MCP-Clients

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

Registriere dann in der .mcp.json deines Projekts (oder in einer beliebigen MCP-Client-Konfiguration):

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

Erfordert Node 18+. Keine nativen Abhängigkeiten – die PNG/GIF-Codecs sind eigenständig.

Bundle selbst bauen

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

Related MCP server: mcp-spritesheet-forge

Werkzeuge

Eingaben können PNGs, animierte GIFs oder PNG-Spritesheets (cellW/cellH) sein.

Der 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

Lektionen, die dieses Tool kodiert

Diese sind nicht hypothetisch – jede wurde zuerst als echter Defekt ausgeliefert:

• Messen, nicht Proportionen annehmen. Eine Hutkrempe bei „52% der Kopfhöhe" landete genau auf den Augen: Bei einem 20-Pixel-Kopf sind die Augen 7–9 Pixel vom oberen Rand entfernt, also trifft jedes feste Verhältnis sie. sprite_measure berichtet, wo das Gesicht tatsächlich beginnt, pro Frame.

• Mit festem Luminanzbereich umfärben. Die Normalisierung pro Bild bildet dieselbe Quellfarbe je nach Sichtbarkeit der Region auf unterschiedliche Ausgaben ab – unser Hut war von hinten hell, von vorne dunkel. Der Kanon zeichnet den Bereich jeder Region einmal auf; Neufärbung verwendet ihn immer.

• Regionen strukturell schützen. „Sei vorsichtig um das Gesicht" scheitert im Maßstab. protected: true bedeutet, dass Neufärbung sie nicht berühren kann und Verifikation beweist, dass sie es nicht getan hat.

• GIF-Paletten patchen, nicht neu encodieren. Die Farben eines indizierten GIFs leben in seinen Farbtabellen – global und pro-Frame lokal (nur die globale Tabelle zu patchen ist der klassische Halbfix). Das Substituieren von Tabelleneinträgen kleidet jeden Frame perfekt synchron und ohne Verlust neu.

• Regionsdefinitionen haben Lücken; zähle sie. 12 verirrte Pixel der alten Farbe, die eine Neufärbung überleben, sind für das Auge unsichtbar und für leftover offensichtlich. Wenn es auslöst, zeigt die Zählung von canon_info, welche Farben deine Regionen nicht abdecken.

Die Skalentabelle

Der scale-Check von sprite_verify liest canon.scale.heights – relative Größen in Einheiten eines Referenz-Assets (der Eintrag gleich 1). Noch schreibt kein Tool diesen Abschnitt; füge ihn von Hand zu sprite-canon.json hinzu:

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

Verifiziere dann mit scaleNames, das Dateibasennamen auf diese Schlüssel abbildet. Das fängt den klassischen „das Haus ist kleiner als der Held" eine Woche vor deinen Spielern ab.

Praktische Hinweise

• Immer canonPath angeben (oder eine Datei, über der der Kanon liegt). Das Arbeitsverzeichnis eines stdio-MCP-Servers gehört dem Client, nicht deinem Projekt, daher weigern sich die Tools, aus dem cwd zu raten.

• Codec-Grenzen: PNG muss 8-Bit, nicht-interlaced, RGB/RGBA/Palette sein (die üblichen Pixel-Art-Fälle; 16-Bit- oder interlaced Dateien werden mit einer klaren Fehlermeldung abgelehnt). Der GIF-Encoder ist exakt bis zu 255 opaken Farben pro Datei – darüber hinaus nächstgelegene Palette.

• sprite_sheet gibt das Bild inline bis zu ~800 KB zurück; größere Blätter geben nur den Dateipfad zurück.

• Spritesheets round-trippen Zelle für Zelle: leere Zellen bleiben leer, nichts wird kompaktiert.

Was das nicht ist

• Kein Generator. Kombiniere es mit dem, was deine Kunst erstellt (PixelLab, Aseprite, Gemini, Handpixel); sprite-canon ist die Schicht, die die Ergebnisse kohärent hält.

• Kein Atlas-Packer / Kollisionswerkzeug – sprite-tools deckt das gut ab.

• Keine Magie: Du investierst ~10 Minuten einmal pro Projekt, um ihm deinen Kanon beizubringen. Diese Investition ist genau das, was jede spätere Prüfung und jeden Fix vertrauenswürdig macht.

Entwicklung

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

Die Testsuite enthält Regressionstests für jeden Bug, den eine adversariale Multi-Agenten-Review in v0.1 fand – Blatt-Zellen-Kompaktierung, GIF-Disposal-Semantik, Fake-Erfolgsantworten, stille Null-Check-Pässe. Wenn einer fehlschlägt, ist ein Bug, der schon einmal existierte, zurück.

MIT