MCPixel Studio

Local-first pixel art and animation editor with a shared GUI and MCP command engine.

ローカルで動くピクセルアート・アニメーション制作ツールです。ブラウザーの制作画面とMCPクライアントが、同じプロジェクト・編集コマンド・Undo履歴を共有します。クラウドアカウントや画像生成APIは不要です。

起動

Node.js 22.12以上とGitが必要です（検証環境: Windows / Node.js 24 / Microsoft Edge）。リポジトリを取得して起動します。Gitを使わない場合はGitHubの Code → Download ZIP から取得し、展開したフォルダーで npm ci 以降を実行してください。

git clone https://github.com/chibivaru1225/mcpixel-studio.git
cd mcpixel-studio
npm ci
npm run build
npm start

http://127.0.0.1:4179 を開きます。初回の依存ライブラリ導入後はオフラインで使用できます。開発時は npm run dev。終了は起動したターミナルで Ctrl+C です。

ファイルの保存・読込先は MCPIXEL_WORKSPACE 内に限られます。既定は起動フォルダーです。別の保存場所・ポートを使う場合:

$env:MCPIXEL_WORKSPACE = 'C:\path\to\mcpixel-studio'
$env:MCPIXEL_PORT = '4179'
npm start

制作

• 左: 鉛筆、消しゴム、線、矩形、楕円、塗りつぶし、同色置換、スポイト、矩形・投げ縄・色選択、移動。

• 中央: nearest-neighborキャンバス、グリッド、Space＋ドラッグのパン、ホイールズーム、対称描画、タイル表示。

• 右: RGBA/HEX、前景・背景色、最近の色、パレット、レイヤー・グループ・合成モード。

• 下: レイヤー×フレームのタイムライン、複製、表示時間、再生、ループ、オニオンスキン、タグ。

• 上のメニュー: 新規、読込、保存、PNG/APNG/連番PNG/スプライトシート出力、キャンバスのサイズ変更、選択の変形、ショートカット一覧。

PNG/APNGと .mcpixel はドラッグ＆ドロップで開けます。プロジェクト形式は全レイヤー・フレーム・パレット・タグ・メタデータ・選択・作業状態を保存します。Undoは最大200操作、バッチは1操作です。保存は一時ファイルを書き切ってから置き換えます。編集は約700msの待機後に data/recovery/ へ自動保存され、サービス再起動時に復元されます。

選択範囲への貼り付けは選択の左上を起点にします。再生中はキャンバスへの描画を止めるため、編集する際は再生を一時停止してください。

MCPクライアント設定

先に npm ci と npm run build を実行してください。Windows向けMCP設定例（JSON）は次のとおりです。C:/path/to/mcpixel-studio を取得したフォルダーの絶対パスへ置き換え、command はNode.jsのインストール先に合わせます。macOS/LinuxではNode.jsとプロジェクトの絶対パスを各環境に合わせて指定してください。

{
  "mcpServers": {
    "mcpixel-studio": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": ["C:/path/to/mcpixel-studio/dist/mcp-server/main.js"],
      "env": {
        "MCPIXEL_WORKSPACE": "C:/path/to/mcpixel-studio",
        "MCPIXEL_PORT": "4179"
      }
    }
  }
}

このサーバーは stdio のMCPです。単体起動は npm run mcp、ビルド済みなら node dist/mcp-server/main.js。既に起動中のローカルサービスに接続し、見つからない場合は同じワークスペースでサービスを自動起動します。GUIを後から開いても同じ状態が見えます。自動起動したサービスはMCPクライアントの切断後も復元データとGUIを維持するため起動し続けます。サービスを自分で管理したい場合は npm start で先に起動し、MCP環境変数に MCPIXEL_NO_AUTOSTART=1 を指定できます。

ポートが別ワークスペースで使用中の場合は接続を拒否します。GUIとMCPで同じ MCPIXEL_PORT と MCPIXEL_WORKSPACE を指定してください。HTTPはGUI用ローカルAPIで、Streamable HTTP MCPではありません。

コピー用の mcp-client.example.json も同梱しています。Windows環境で、Node.jsとビルド済みサーバーの絶対パスを使い、別の作業フォルダーからの起動・サービス自動起動・保存・出力を確認済みです。起動検証結果 の個人用パスは公開用の表記に置き換えています。

MCPだけの制作デモ

npm run demo

実際のstdio MCPクライアントが、32×32・14色・4レイヤー・4フレームのカエルの配達員「Fern」を制作します。GUI操作は使いません。Undo/Redo、領域ピクセル読取、画像プレビュー、全形式への出力、プロジェクトとPNG/APNGの再読込を行い、各フレームのRGBAが一致することを検証します。

成果物: examples/mcp-demo/。fern.mcpixel をアプリで開けます。fern.png、fern-preview.png、fern.apng、fern-sheet.png と fern-sheet.json、連番PNG、GPLパレット、acceptance.json が含まれます。

検証コマンド

npm run typecheck
npm run lint
npm test
npm run build
npm run test:e2e
npm run demo
npm run benchmark

ブラウザーテストはWindowsにインストール済みのMicrosoft Edgeを既定で使用します。他環境は npx playwright install chromium の後、PLAYWRIGHT_CHANNEL=chromium を指定します。テストは独立したローカルサービスとテスト用保存先を使います。MCPテストは公式SDKのクライアントでサーバー子プロセスを起動し、全共通コマンドの公開とスキーマ一致、Resourceと通知、revision競合、バッチのロールバックを検証します。

検証項目と結果は 検証レポート、性能測定の再現条件・結果は docs/benchmark.json、実画面は 制作画面 と コンパクト画面 に記録しています。

設計・仕様

• アーキテクチャ

• MCP仕様・操作例・GUI対応表

• 機械可読capability manifest

• src/core: 整数座標アルゴリズム、合成、選択、共有コマンド、copy-on-write履歴。

• src/server: loopbackサービス、JSON Schema検証、パス制限、圧縮プロジェクト形式、PNG/APNG。

• src/studio: ReactとCanvasの編集クライアント。

• src/mcp-server: 公式MCP SDKによるstdioアダプター。ツールを別実装せず共通レジストリから公開。

制作ワークフローは Asepriteのアニメーション操作 と Pixeloramaの描画ツール を参照しています。独自実装で、これらのソフトウェアのコード・画像は含みません。

不具合や改善提案は GitHub Issues へ、再現手順・OS・Node.jsのバージョンを添えて報告してください。

制限

• デスクトップ向けローカルWebアプリです。ネイティブインストーラー、タッチ端末向けUI、Aseprite/PSD形式の読込は提供しません。

• アニメーションはAPNGと連番PNG。GIFは未対応です。APNGにはRGBAとフレーム時間を保持できます。

• GPL形式はRGBのみです。アルファを維持するパレット保存にはJSONを使います。

• ブラシは正方形、回転は90度単位、拡大縮小はnearest-neighborです。音声、ベクター、テキスト、カスタムブラシはありません。

• 履歴はメモリ内です。プロジェクトと復元ファイルには編集結果を保存し、アプリ再起動後のUndo履歴は復元しません。クラッシュ復元時は元の保存先を引き継がないため、保存先を指定して保存してください。

• ピクセル選択はアクティブcelを対象とします。グループは独立合成、通常・乗算・スクリーン・加算の4モードです。

• レイヤー結合は両方が通常モードの場合に対応します。下のレイヤーに依存する合成モードは、見た目を変えてしまう結合を防ぐため明示的なエラーになります。

• APNGの時間表現に収まらない極端に長いフレーム時間は出力時に拒否します。その場合は連番PNGを使用してください。外部スプライトシートの回転・トリミング済みフレームは読込対象外です。

• MCPはローカル利用を前提とし、認証付きリモート共同編集やStreamable HTTPは未実装です。

• 上限と大規模プロジェクトの実測上の制約は docs/architecture.md と性能測定に記録します。