Aseprite Agent MCP

Aseprite Agent MCP

MCP stdio を介した、ローカルファーストのピクセルアート制作と検証済みゲームアセットのエクスポートです。

ステータス：0.2.0 alpha。 aseprite-mcp（Brendan Malloy 作、MIT）をベースとしており、8caabf9ce240a040ca2c94d3d7366c9d8dd63653 に固定されています。 追加された本番環境向けレイヤーでは、プレビュー付きのアトミックな編集、厳格なアセット契約、検証済みの Phaser エクスポート、ツールプロファイル、キャストツール、ワークスペースのロック、クラッシュセーフな保存を提供します。 NOTICE、 LICENSE、UPSTREAM_INVENTORY.jsonを参照してください。 継承した Python 名前空間は引き続き aseprite_mcp で、パッケージ名とコマンド名は aseprite-agent-mcp です。

114 個のツールで、ネイティブドキュメント、ピクセル描画、レイヤー、セル、フレーム、パレット、タグ、スライス、変換、タイルマップ、検査、エクスポートを扱えます。本番環境向けの機能では、画像フィードバック付きのアトミックな編集、厳格な型付きアセット契約、全フレームのラベル付きプレビュー、キャラクターキャスト用ツール、再オープンしたネイティブマスターとの照合で検証される Phaser バンドルを追加します。デフォルトでは、サーバーは 42 個のツールを含む core プロファイルを公開します（ツールプロファイルを参照）。正確なスキーマについては、生成されたツールリファレンスを参照してください。

インストールと実行

Python 3.10 以降、uv または pipx、および Lua スクリプトに対応したライセンス取得済みの Aseprite をご用意ください。EULA に基づいて、ご自身で Aseprite をビルドすることもできます。このパッケージは ASEPRITE_PATH を通じてインストール済みの実行ファイルを呼び出すだけで、Aseprite、そのインストーラー、Lua ランタイム、アートアセットは同梱しません。

公開済みパッケージの場合：

uvx aseprite-agent-mcp
# or: pipx install aseprite-agent-mcp
# then: aseprite-agent-mcp

実行前に ASEPRITE_PATH を設定してください。MCP クライアントのコマンド例（パスを置き換えてください）：

# Windows (PowerShell)
claude mcp add aseprite --env ASEPRITE_PATH=C:\\path\\to\\Aseprite.exe -- uvx aseprite-agent-mcp
# macOS
claude mcp add aseprite --env ASEPRITE_PATH=/Applications/Aseprite.app/Contents/MacOS/aseprite -- uvx aseprite-agent-mcp
# Linux
claude mcp add aseprite --env ASEPRITE_PATH=/path/to/aseprite -- uvx aseprite-agent-mcp

JSON を受け取るクライアント（Codex MCP 設定など）では、次の形式を使用してください：

{
  "mcpServers": {
    "aseprite": {
      "command": "uvx",
      "args": ["aseprite-agent-mcp"],
      "env": {
        "ASEPRITE_PATH": "/path/to/aseprite",
        "ASEPRITE_MCP_WORKSPACE": "/path/to/assets"
      }
    }
  }
}

ローカルの stdio MCP サーバーに対応する Grok クライアントでは、同じ実行ファイル、引数、環境フィールドを使用できます。クライアントごとに設定キーが異なる場合があります。

ソースをチェックアウトして開発する場合：

uv sync --locked --group dev
$env:ASEPRITE_PATH = 'C:\path\to\aseprite.exe'
$env:ASEPRITE_MCP_WORKSPACE = 'C:\path\to\assets'
uv run --no-sync aseprite-agent-mcp

このコマンドは stdin/stdout で MCP を通信し、クライアントからの接続を待ちます。診断ログは stderr に出力されます。プレースホルダーパスを置き換えたうえで、クライアントで mcp-config.example.json を使用してください。このプロジェクトがクライアントの設定を変更することはありません。

この小さな GIF は、uv run python scripts/generate_demo.py で生成された手続き型の作例アートです。意図するピクセルアートの出力例を示すもので、Aseprite の実行中セッションを撮影したスクリーンショットではありません。Aseprite MCP の一連の往復処理を通じた完全な証明については、検証を参照してください。

ツールプロファイル

すべてのツールの説明とスキーマはエージェントのコンテキストを消費するため、サーバーは ASEPRITE_MCP_TOOLS で指定されたプロファイルを公開します。値はカンマ区切りの名前のリストです。

値	公開されるツール
core（デフォルト）	42 個のツール：生成／インポート、作成、描画、アニメーション、プレビュー、検証、エクスポート、キャストツール
all	サポートされているすべてのツール（114 個）
グループ	1 つのツールモジュール（例：tilemap、effects、slices、palette、workflow）
ツール名	追加のツールを 1 つ（例：core,add_outline）

不明な名前が指定されていると、サーバーは起動時に停止します。グループの一覧は ツールリファレンスの先頭にあります。

変数	デフォルト	説明
ASEPRITE_PATH	自動検出	Aseprite 実行ファイル
ASEPRITE_MCP_WORKSPACE	プロジェクト内の workspace/	相対パスの起点
ASEPRITE_MCP_TOOLS	core	上記のツールプロファイル
ASEPRITE_MCP_LOCK_WAIT	15	ビジー状態のワークスペースで、呼び出しが待機する秒数（0 の場合は直ちに失敗）
ASEPRITE_MCP_TIMEOUT	90	Aseprite プロセスごとのタイムアウト秒数
ASEPRITE_MCP_ALLOW_ABSOLUTE	オフ	許可されたルート内での絶対パス構文を許可するかどうか
ASEPRITE_AGENT_ALLOWED_ROOTS	[]	追加のルートを指定する JSON リスト

推奨ワークフロー

生成アートから編集可能なアニメーションへ

画像モデルにキャラクターとキーポーズを描かせてから、import_generated_image で1枚のPNGをピクセルグリッドに変換し、assemble_animationで順序付きのポーズリストを クリーンアップして位置を合わせます。どちらのツールもデフォルトのcoreプロファイルに含まれています。

import_generated_image(filename="base.png", output_directory="base-clean",
                       width=32, height=32, colours=16)
assemble_animation(filenames=["idle-1.png", "idle-2.png", "idle-3.png", "idle-4.png"],
                   output_directory="idle-clean", width=32, height=48, tag="idle",
                   colours=16, alignment="bounding-box",
                   durations_ms=[180, 140, 180, 140], outline="#152b32")

• method="nearest"はグリッドをサンプリングします。"majority"は、各ソースセルで最も頻度の高いRGBA値を選びます。同数の場合の結果は決定的です。majorityは縮小時のみ使用できます。
• widthとheightには、各辺が最大256pxのグリッドを指定できます。詳細なスプライトには、height=128、colours=32から48、method="majority"、palette_first=Trueを使用してください。パレット優先モードでは、投票の前に共有のソースパレットに色をスナップするため、生成された色合いのうち近似したものは同じ色として扱われます。このモードはオプトインです。既存の呼び出しでは従来の動作が維持されます。
• palette=["#RRGGBB", ...]を指定すると、明示した色にスナップします。指定しない場合は、coloursによってアニメーション全体で共有される自動パレットが作成されます。アルファはalpha_threshold（デフォルトは128）を基準に二値化されます。透明色は色数に含まれません。オプションの1pxの輪郭線によって色が1色増えることがあり、セル境界でクリップされます。
• background="#RRGGBB"は、境界につながっている一致色のピクセルのみを除去します。background_toleranceを指定することもできます。囲まれた部分のディテールは保持されます。これはカラーキーであり、セマンティックセグメンテーションではありません。既存の透明部分には背景キーは不要です。
• バウンディングボックスによる位置合わせでは、すべてのポーズに同じスケールを使い、シルエットの下端中央を揃えます。alignment="anchor"では、同じサイズの入力それぞれにソースの[x,y]を1つ指定し、それを(width//2,height-2)に配置します。クリッピングが発生する場合は拒否されます。"none"では各キャンバスをそのまま保持します。ポーズのスケールと余白を一定に保ち、返されたプレビューを確認してください。

新しい出力ディレクトリには、master.aseprite、クリーンアップ済みのフレームPNG、sheet.png、sheet.json、qa.jsonが含まれます。ネイティブマスターはAsepriteのLua APIを通じて再度開かれます。公開前に、すべてのレンダリング済みフレーム、タグ範囲、表示時間、シートのピクセルが検証されます。ディレクトリの公開はアトミックに行われ、既存のディレクトリを上書きしません。ソースPNGは保持されます。入力は、1ファイルあたり400万ピクセル、合計1600万ピクセル、128フレーム、出力100万ピクセルに制限されています。

生成された配達員のデモには、元のモデル出力、クリーンアップ済みのベース、4フレームの待機アニメーション、編集可能なマスター、再現可能なローカルスクリプトが含まれています。ピクセル検証ではファイルの完全性を確認します。アートの品質を評価するものではなく、一貫性のないキーポーズからまとまりのあるアニメーションを作り出すものでもありません。

歩行デモでは、8ポーズの生成パス、高さ128pxのセル、共有の48色パレット、明示的な足元アンカーを使用しています。同じソースとパレットを使用したループGIFと64px／128pxの比較も含まれています。

1. health_checkで、ローカルCLIとLuaのパスが作成とエクスポートを実行できることを確認します。
2. create_spriteで編集可能な.asepriteマスターを作成します。
3. ase_apply_and_previewで、型付きのバッチを1つのトランザクション内で適用し、レンダリング済みPNGを返します。操作に失敗した場合、ファイルは変更されません。その後のプレビューに失敗した場合は、編集が保存済みであることを明示して報告します。
4. ase_preview_animationで、すべてのフレームを補間せずに表示します。
5. ase_validate_asset_contractで、ジオメトリ、フレーム数、タグ範囲の完全一致、タグの再生方法、パレットへの所属、二値アルファ、空のフレーム、およびオプションの行ごとの足元／中心のずれを検証します。不明なフィールドはエラーになります。
6. ase_export_phaserで、シートPNG、ハッシュ付きアトラスJSON、アニメーションのタイミング、ローダーJS、コントラクト、QAを含むバンドルディレクトリを作成します。公開前にマスターとエクスポート済みPNGを再度開き、すべてのフレームのRGBAピクセルを比較します。既存のディレクトリは、以前のバンドルを名前変更で置き換えるreplace=trueを指定しない限り拒否されます。ネイティブマスターはそのまま残ります。

キャラクターを作成する

1. draw_pixel_rows は、テキストの行とカラーキーからフレーム全体を描画します。例： rows=["..oo..", ".oxxo."]、key={"o": "#203040", "x": "#f0c060"}。未知の 文字はエラーになり、. と空白はスキップされます。
2. copy_cel と offset_cel のバッチ操作でアニメーションを作成します（再描画せずに動きを付けられます）。各アニメーションにはタグを付けてください。
3. derive_mirrored_tag は walk_right から walk_left を作成します。
4. save_sprite_as でテンプレートとして保存し、recolor_sprite で各キャラクター用に色を変更するか、copy_frames_from を使って共有のベースからキャラクターを作成します。
5. ase_preview_animation は、チェッカーボード上にタグごとにラベル付きの行を表示します。
6. ase_export_cast_atlas は、各マスターをそれぞれのコントラクトに照らして検証し、1 つの Phaser アトラスを書き出します。フレームは <character>/<tag>_<nn>、アニメーションは <character>:<tag> です。

編集内容は、一時ファイルを同じディレクトリに作成してから名前を変更することで保存されるため、Aseprite プロセスが強制終了しても、マスターが不完全な状態で残ることはありません。フレーム番号は存在している必要があります。範囲外のフレーム番号はエラーとなり、最も近いフレーム番号に切り詰められることはありません。 すべてのフレーム番号は 1 から始まります。コントラクトの行には、正確に連続したアニメーションタグを指定します。パレットの項目にはインラインの 16 進数カラーを指定し、任意のファイルパスは指定できません。最終検証／書き出しの前に参照レイヤーを非表示にしてください。ロックされたレイヤーもピクセルとして表示されます。

{
  "name": "robot",
  "cell": {"width": 16, "height": 16},
  "rows": [
    {"tag": "walk_down", "frames": 4},
    {"tag": "idle", "frames": 2, "playback": "pingpong"},
    {"tag": "sleep", "frames": 2, "repeat": 0, "check_anchor": false}
  ],
  "alpha": "binary",
  "palette": ["#315c88", "#8bd5ed", "#223344"],
  "anchor": {"max_foot_drift": 0.0, "max_center_drift": 0.0}
}

検証

uv run pytest
uv run pytest --run-aseprite
uv run python scripts/proof_stdio.py --output ./workspace/proof-final

検証実行ごとに新しい出力ディレクトリを使用してください。検証では、実際の MCP stdio クライアントを介してサーバーに接続し、互いに異なる合成フレームを 16 個作成して、保存後に再度開いたマスターを比較し、スプライトシートと GIF を書き出し、ロールバックと上書き／パス拒否をテストします。また、意図的に破損させたアセットが書き出し時の QA に合格しないことも確認します。proof.json と視覚的なアーティファクトが出力されます。検証を参照してください。

Phaser 3.90.0 で出力を再生するには、次のようにします。

npm ci --prefix examples/phaser --ignore-scripts
uv run python -m http.server 8795 --bind 127.0.0.1

http://127.0.0.1:8795/examples/phaser/ を開きます。4 つすべてのアニメーションの各 4 フレームが再生された後にのみ、ページは成功を報告します。ローカルの npm 開発用依存関係を使用しており、MCP 自体はインストール後にネットワーク依存関係を持ちません。 workspace/my-proof で新たに実行した場合、その実行結果を再生するには http://127.0.0.1:8795/examples/phaser/?proof=my-proof を使用してください。

境界と現在の制限

• stdio のみです。MCP サーバーにはライブエディターとのブリッジやネットワークリスナーはありません。
• パスはワークスペースと、明示的に設定された許可ルート内に制限されます。 ASEPRITE_MCP_ALLOW_ABSOLUTE=1 を設定すると絶対パス形式を使用できますが、アクセスが無制限になるわけではありません。 追加のルート：ASEPRITE_AGENT_ALLOWED_ROOTS='["/absolute/asset/root"]'。
• トラバーサル、シンボリックリンクによる範囲外アクセス、安全でない Windows のデバイス／ストリームパス、ファイル名テンプレートの展開は拒否されます。継承された一部のツールは意図的に非表示になっています。
• これは信頼されたローカルユーザー向けのツールであり、OS のサンドボックスではありません。信頼できないローカルプロセスがシンボリックリンクを差し替えたり、同じマスターを同時に編集したりしないようにしてください。同じワークスペースを共有する MCP 呼び出しは OS のアドバイザリロックを使用します。同時呼び出しは ASEPRITE_MCP_LOCK_WAIT 秒まで待機し、その後「Workspace busy」で失敗します。共有アセットに書き込むサーバーは、追加のルートを使用する場合も含め、すべて同じワークスペースを使用する必要があります。Python の直接呼び出し、エディターの GUI、その他のプログラムはこのロックを取得しません。
• QA では合成後の RGBA ピクセルを比較します。芸術的な品質、正しい解剖や動き、パレットインデックスの同一性、アンカーの意味、許可されたパレット内でスムージングが行われていないことは証明しません。アンカーチェックは、同じ対象を接地させたアニメーションに適しています。
• テスト用フィクスチャは手続き的に生成された証拠であり、製品品質の歩行サイクルアートではありません。
• Phaser バンドルはステージング環境で検証され、サポート対象のローカル Windows、Linux、macOS ファイルシステム上で、上書きしないアトミックなディレクトリ名変更によって公開されます。サポートされていない名前変更の動作では、フェイルクローズします。プロセスが終了した場合、最終パスは存在しないか、完全な状態になります。非表示のステージングフォルダーが残ることがあります。停電時の耐久性やネットワークファイルシステムの動作は保証されません。
• ライブエディターのターン単位の元に戻す操作、非公開のプロジェクト契約、より広範なリサンプリング／フリンジのチェック、正式なビジュアルゴールデンベースラインは、引き続き作業中です。

リリース

タグのワークフローでは、信頼された公開を通じて PyPI へのビルド、チェック、公開を行い、その後 MCP Registry エントリーを検証して公開します。まず、このリポジトリ、release.yml、pypi 環境に対して PyPI の信頼されたパブリッシャーを設定してください。 パッケージのバージョンは src/aseprite_mcp/__init__.py から取得されます。

GitHub Actions を利用できない場合、uv run python scripts/release --tag v0.2.0 を実行すると、クリーンなツリー、lint、テスト、配布物をチェックした後、何も送信せずに公開コマンドを表示します。--publish を指定するには、環境内に明示的な UV_PUBLISH_TOKEN と、ローカルの mcp-publisher 実行ファイルが必要です。このオプションを指定すると、uv publish、レジストリの検証、対話型の GitHub ログイン、レジストリへの公開を実行します。リリース内容を確認し、トークンを設定した後にのみ実行してください。

セキュリティ · ロードマップ · 変更履歴