# MCPixel Studio

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

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

![MCPだけで制作したFernを編集中](docs/screenshots/studio-demo.png)

## 起動

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

```powershell
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](http://127.0.0.1:4179) を開きます。初回の依存ライブラリ導入後はオフラインで使用できます。開発時は `npm run dev`。終了は起動したターミナルで Ctrl+C です。

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

```powershell
$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とプロジェクトの絶対パスを各環境に合わせて指定してください。

```json
{
  "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](mcp-client.example.json) も同梱しています。Windows環境で、Node.jsとビルド済みサーバーの絶対パスを使い、別の作業フォルダーからの起動・サービス自動起動・保存・出力を確認済みです。[起動検証結果](docs/installed-verification.json) の個人用パスは公開用の表記に置き換えています。

## MCPだけの制作デモ

```powershell
npm run demo
```

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

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

## 検証コマンド

```powershell
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/verification.md)、性能測定の再現条件・結果は [docs/benchmark.json](docs/benchmark.json)、実画面は [制作画面](docs/screenshots/studio-demo.png) と [コンパクト画面](docs/screenshots/studio-demo-compact.png) に記録しています。

## 設計・仕様

- [アーキテクチャ](docs/architecture.md)
- [MCP仕様・操作例・GUI対応表](docs/mcp.md)
- [機械可読capability manifest](docs/capabilities.json)
- `src/core`: 整数座標アルゴリズム、合成、選択、共有コマンド、copy-on-write履歴。
- `src/server`: loopbackサービス、JSON Schema検証、パス制限、圧縮プロジェクト形式、PNG/APNG。
- `src/studio`: ReactとCanvasの編集クライアント。
- `src/mcp-server`: 公式MCP SDKによるstdioアダプター。ツールを別実装せず共通レジストリから公開。

制作ワークフローは [Asepriteのアニメーション操作](https://www.aseprite.org/docs/animation) と [Pixeloramaの描画ツール](https://pixelorama.org/user_manual/drawing/) を参照しています。独自実装で、これらのソフトウェアのコード・画像は含みません。

不具合や改善提案は [GitHub Issues](https://github.com/chibivaru1225/mcpixel-studio/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](docs/architecture.md) と性能測定に記録します。