sprite-canon

AIが生成したゲームスプライトを、まるで1つのゲームのように見せるMCPサーバー。

同じキャラクター、3つの衣装 — 青と赤の行は sprite_repaint の呼び出しであり、再生成ではありません。同じシェーディング順、同じシルエット、毎回同じ結果が得られます。

AIジェネレーターは、きれいなスプライトを作るのは得意ですが、前回のものと一致させるのは苦手です。同じキャラクターを2回依頼すると、パレットがずれ、衣装が変異し、新しい帽子が頭の上に3ピクセル浮いてしまいます。各アセットは単体では問題なく、組み立てるとゲームが壊れて見えます。「一致するまで」再生成しても収束しません。お金を費やすだけで、結果を diff することもできません。

sprite-canon は正反対のアプローチを取ります。実際に約4,000フレームを生成したゲームプロジェクトから抽出し、すべての教訓を苦労して学んでいます：

1. 一貫性のルールがデータになります — sprite-canon.json（「カノン」）は、パレット、名前付き色領域（肌、衣装、輪郭…）、相対スケール、チェックしきい値を保持します。アセットの隣にコミットします。

2. 検証は視覚ではなく数値です。 96の衣装バリエーション × 8方向 × 4フレームを目視で確認することはできません。sprite_verify は、実際に問題になる欠陥に対して明確な合否を数値で返します：パレット外のピクセル、フレーム間でジッターするアクセサリー、後ろから見ると明るく前から見ると暗い領域、顔に触れてしまった再描画。

3. 修正は再生成ではなく、決定論的なピクセル操作です。 領域を新しいカラーランプに再描画すると、シェーディングとシルエットが保持され、保護された領域には決して触れず、毎回同じ結果を出力します。衣装バリエーションは、プロンプトの抽選ではなく、1回のツール呼び出しです。

インストール

Claude Desktop — 1ファイル、設定不要

1. 最新リリース から sprite-canon.mcpb をダウンロードします。

2. Claude Desktop で 設定 → 拡張機能 を開きます（Windows では ☰ メニュー → ファイル → 設定）。

3. .mcpb ファイルを拡張機能ページにドラッグし、確認して「インストール」をクリックします。

（ダブルクリックも動作します もしOSが .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%」に置いた帽子のつばが、ちょうど目に重なりました。20px の頭では、目は上から7〜9px の位置にあります。したがって どの 固定比率も当たります。sprite_measure は、フレームごとに顔の実際の開始位置を報告します。

• 固定された輝度範囲で再描画する。 画像ごとに正規化すると、同じソース色が領域の表示量に応じて異なる出力にマップされます。私たちの帽子は後ろから見ると明るく、前から見ると暗かった。カノンは各領域の輝度範囲を一度記録し、再描画は常にそれを使います。

• 領域を構造的に保護する。 「顔の周りに気をつけて」というスケールでは機能しません。protected: true は、再描画が 触れることはできず、検証が 触れていないことを証明 します。

• GIFパレットを修正し、エンコードし直さない。 インデックス付きGIFの色はそのカラーテーブルにあります — グローバル と フレームごとのローカルテーブルです（グローバルのみを修正するのは一般的な中途半端な修正です）。テーブルのエントリを置き換えることで、すべてのフレームが完全にピザインされ、ゼロロスで再描写できます。

• 領域の定義には隙間があります。それを数え上げます。 新しい描画の後に残った古い色の数がしないで、目には見えていませんが、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 を渡します（またはカノンがその上位にあるファイル）。stdio MCP サーバーの作業ディレクトリは自分のプロジェクトではなく クライアント に属するため、ツールは cwd から推定しないことを選択します。

• コーデックの制限：PNG は8bit、非インターレース、RGB/RGBA/パレットである必要があります（一般的なピクセルアートのケース。16bit やインターレースのファイルは明確なエラーで拒否されます）。GIFエンコーダは、ファイルごとに最大255の不透明色まで正確です。それを超える場合は、最も近いパレットにスナップされます。

• sprite_sheet は、約800KB までインライン画像を返します。それ以上の大きなシートはファイルパスのみを返します。

• スプライトシートはセル単位で往復変換されます。空のセルは空のままで、詰められたりしません。

これではないもの

• ジェネレー タではありません。あなたのアートを作るもの（PixelLab、Aseprite、Gemini、手ピクセル）と組み合わせてください。sprit-canon は結果を一貫させるレイヤーです。

• アトラスパッカーやコリジョンツールではありません — sprite-tools がそれをよくカバーしています。

• 魔法ではありません。プロジェクトごとに一度、約10分間だけ、あなたのカノンを教えてください。その投資が、その後のすべてのチェックと修正を信頼できるものにするのです。

開発

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

テストスイートには、v0.1 で敵対的なマルチエージェントレビューが見つけたすべてのバグに対する回帰テストが含まれています — シートセルの圧縮、GIFの破棄セマティクスぜフィックな成功応答、静かなゼロチェック合格です。もし1つでも失敗したら、既存のバグが再発したことです。

MIT