# Aseprite Live MCP

Codexから、開いているAsepriteの作品を見ながらドット絵を描き、レイヤー・アニメーションを編集してゲーム用に書き出すMCPです。Mac上で動作し、このMCP用のクラウド契約や追加の画像生成APIキーは必要ありません。Codex自体の利用条件・料金は別です。

```text
あなたの指示 → Codex → MCP → Mac内の接続用プログラム → 開いているAseprite
                    ← 作品情報・画像プレビュー ←
```

絵を考えるのは接続したCodexのモデルです。このMCPはピクセル単位の描画・確認・修正の道具を提供します。別の画像生成モデルは内蔵していません。

## 必要な環境

macOS、Node.js 22以降、Aseprite、ローカルMCPに対応したCodexが必要です。Aseprite **1.3.18.3-arm64**で動作確認しています。これより古いバージョン、Windows・Linuxは未検証です。

## セットアップ

1. このフォルダーで依存ライブラリと接続ファイルを準備します。

   ```sh
   npm ci
   npm run setup
   ```

2. Asepriteの **Edit → Preferences → Extensions → Add Extension** から、生成された `artifacts/codex-live-bridge.aseprite-extension` を追加します。通常の **File → Open** は作品用なので使いません。

3. Codexの **Settings → MCP servers → Add server** で、生成された `artifacts/codex-config.toml` にある `command` と `args` を設定します。CLIを使える場合は、このフォルダーで次のコマンドでも登録できます。

   ```sh
   codex mcp add aseprite -- "$(command -v node)" "$(pwd)/src/server.mjs"
   ```

4. CodexのMCP設定で **Restart** を実行します。Asepriteの **File → Connect to Codex** を選び、Codexで「Asepriteの接続状態を確認して」と指示します。接続用プログラムは最初のツール呼び出しで自動起動します。

5. 「新しく32×32のスライムを描いて。体と顔をレイヤーに分けて、待機アニメーションを4コマ作って」のように依頼します。現在の作品を編集したい場合は「いま開いている作品を確認して」と明示すると対象を合わせやすくなります。

接続が成功するとAsepriteのステータスバーに `Connected to Codex` と表示されます。接続操作後は次回起動時にも自動で接続を試みます。**File → Disconnect from Codex** で切断すると、自動接続も停止します。

Asepriteが初めての接続やコピー保存を確認する場合は、対象を確認して `Allow to Open Connections` または `Allow Write Access` を選びます。`Give full trust to this script` は必要ありません。45秒以内に許可できなかった場合は、処理が終わっているか確認してから再開します。

## できること

| 機能 | Codexへの依頼例 |
| --- | --- |
| 作品確認・プレビュー | 「現在の絵とレイヤーを確認して」 |
| 描画・レイヤー編集 | 「武器を別レイヤーに描いて」「輪郭を濃くして」 |
| RGB・Indexed編集 | 「Indexedで作って」「パレットの2番を赤にして」 |
| 選択・回転・拡大縮小 | 「選択部分を時計回りに90度回して、2倍にして」 |
| レイヤー・コマ削除 | 「下書きレイヤーを削除して」「最後の2コマを削除して」 |
| タイルマップ | 「8×8の草タイルを作って床に並べて」 |
| GIF出力 | 「待機アニメーションをループGIFにして」 |
| アニメーション編集 | 「歩行を4コマ追加して、walkという名前にして」 |
| PNG・スプライトシート出力 | 「全コマを横4列で書き出して」 |
| 編集可能なコピー保存 | 「レイヤーを残したAseprite形式のコピーも保存して」 |

レイヤーは絵の部品、フレームは動きの各コマ、タグは「待機・歩行・攻撃」などのコマ範囲です。詳細は[機能資料](docs/features/README.md)にあります。

## 保存と取り消し

AIの編集は開いている作品に即時反映され、**1回の編集ツール呼び出しがAsepriteの1回のUndo**になります。長い依頼を複数回のツールに分けた場合は、取り消しも複数回です。自動で元ファイルを上書き保存することはありません。通常の保存はAsepriteから行ってください。

書き出し先は初期設定でこのプロジェクトの `exports/` です。PNGとJSONは `exports/指定名/spritesheet.png` と `spritesheet.json` に、編集可能なコピーは別の新しいフォルダーに保存します。同名フォルダーがあればエラーになり、既存の内容を上書きしません。

## 対応範囲

編集は**RGB・Indexedの両形式**に対応し、新規作成は**Indexedが既定**です。最大512×512、128レイヤー、256フレームが対象です。Indexedは色番号を維持し、未登録の色はパレットへ追加します。256色で満杯の場合はエラーとし、近似色に置き換えません。

選択範囲とセル単位の回転・拡大縮小・反転、レイヤー・コマ削除、標準タイルマップの作成・タイル絵・配置編集に対応します。ロックされたレイヤーや親グループ、背景・参照レイヤーへの描画は未対応です。タイルマップには専用操作を使います。Grayscaleは確認・プレビューのみです。

スプライトシートは透過RGBA PNGとAseprite形式に近いJSONです。フレームはトリミングせず等間隔に配置し、コマ時間とタグを含めます。1回の出力は最大256コマ・約400万ピクセルです。GIF出力は透過とコマ時間、ループ回数に対応します。GIFの半透明は透明／不透明に分け、コマ時間は10ミリ秒単位に丸めます。ゲームエンジンへの自動登録、ボーンアニメーション、画像ファイルの取り込み、キャンバス全体の寸法変更は未実装です。

## 接続できないとき

| 状態 | 対応 |
| --- | --- |
| Codexにツールが表示されない | MCP設定の登録・再読み込みと、`command` のNode.jsパスを確認する |
| `Aseprite is not connected` | Asepriteで `Connect to Codex` を選ぶ。メニューがなければExtensionsから追加を確認する |
| `Document changed` | 人の編集や別の依頼が先に反映されたため、作品を再確認してから続ける |
| `timed out` / `disconnected` | Asepriteのダイアログを閉じて接続を確認する。直前の処理が反映済みの可能性があるため、再実行前に作品を確認する |
| 出力名が既に存在する | 別の出力名を指定する |

接続は `127.0.0.1:47118` のみで待ち受け、認証用トークンを使います。外部サイト由来の接続は拒否します。`.local/` と生成された個人用拡張パッケージには接続情報が含まれるため、配布対象に含めないでください。ソースを別のMacへ移し、そのMacで `npm run setup` を行うと別の接続情報を作れます。

複数のCodexタスクは1つの接続用プログラムを共有します。同時編集は受け付けず、別の処理が進行中ならエラーを返します。1つの接続用プログラムに接続できるAsepriteのプロセスは1つです。AsepriteもMCPも利用していない状態が10分続くと、接続用プログラムは停止します。

## 開発・検証

```sh
npm run check
npm test
npm run test:aseprite
```

`test:aseprite` は別のバッチプロセスでテスト作品を作り、既存のGUI作品を操作しません。Asepriteの場所が異なる場合は `ASEPRITE_PATH` を指定します。

GUIで接続後に次を実行すると、実際のMCP経由で新しいテスト作品を作り、画像プレビュー・アニメーション・PNG/JSON・GIF出力・Aseprite形式のコピー、選択・変形・削除・タイルマップとRGB・Indexed編集を確認します。既存の作品は閉じません。

```sh
npm run test:live
```

生成結果は `artifacts/live/` と `exports/live-demo-*` に記録します。テスト結果・確認範囲は[検証記録](docs/verification.md)を参照してください。

拡張の更新時は `npm run setup -- --install-aseprite` を実行し、Asepriteの **Preferences → Extensions → Codex Live Bridge → Disable → Enable** で再読み込みできます。開いている作品を閉じる必要はありません。Codex側もMCP設定を再読み込みして新しいツール定義を取得します。

接続設定は `.local/bridge.json` にあります。変更後は拡張を再生成・更新し、接続用プログラムとCodex MCPを再起動してください。`ASEPRITE_MCP_CONFIG` で別の設定ファイルを使う構成も可能ですが、拡張の接続先・トークンと一致させる必要があります。

## 参照

[Aseprite公式API](https://www.aseprite.org/api/)、[WebSocket](https://www.aseprite.org/api/websocket)、[拡張機能](https://www.aseprite.org/api/plugin)、[Codex公式MCP設定](https://developers.openai.com/codex/mcp)。