scratch-mcp

Model Context Protocol に基づいた、Scratch .sb3 プロジェクトを編集するためのサーバー。scratch4js 上に構築されており、1件のプロジェクトをメモリ内に保持し、ライブラリの編集インターフェイスを MCP ツールとして公開して、ディスクに保存し直します。

また、http://localhost:9060 でライブリロードブリッジもホストしています。TurboWarp Desktop userscript をインストールすると、save_project が実行されるたびにプロジェクトがエディタ内でライブリロードされます — つまり、エージェントによる編集が即座に反映されます。

Install

npx scratch-mcp     # serves MCP over stdio

Related MCP server: scratch-mcp

Develop

MCP サーバーはリポジトリ直下に置かれ、その基盤となるライブラリは packages/ 配下のワークスペースパッケージです。

pnpm install
pnpm run build   # builds scratch4js, s-api4js and the userscript
pnpm start       # serves MCP over stdio

Configure an MCP client

{
  "mcpServers": {
    "scratch": {
      "command": "node",
      "args": ["/abs/path/to/ScratchMCP/src/index.js"]
    }
  }
}

SCRATCH_MCP_BRIDGE_PORT を設定するとブリッジポートを変更できます（デフォルトは 9060）。ポートが既に使用されていてもサーバーは起動します。ライブリロードだけが無効になります。

Install as an MCP Bundle (.mcpb)

Claude Desktop など MCPB 対応クライアントへの1クリックインストール用に、このサーバーは MCP Bundle としてパッケージされます。サーバーと自己完結型の node_modules を含む単一の .mcpb ファイルです。

pnpm run mcpb   # → dist/scratch-mcp-<version>.mcpb

その後、.mcpb をクライアントで開きます（Claude Desktop では、Settings → Extensions にドラッグします）。このバンドルが公開する設定はライブリロードブリッジポートの1つだけで、他に設定は不要です。ビルド（scripts/build-mcpb.mjs）は scratch4js と s-api4js のワークスペースパッケージを tarball として取り込み、git リポジトリの scratch-vm とその対応パッケージを、MCPB が要求するフラットな node_modules にインストールします。manifest.json がバンドルの情報源です（バージョンはビルド時に package.json から刻印されます）。

Tools

Project

• open_project { path } — .sb3 をメモリにロードします。

• save_project { path?, compressionLevel? } — ディスクに書き戻します（さらにライブリロードします）。

• project_info — targets、extensions、monitors、meta。

Scratch website（オンラインプロジェクト、s-api4js 経由）

• scratch_login { username?, password? } — scratch.mit.edu にログインします（デフォルトは $SCRATCH_USER / $SCRATCH_PASS）。セッションはサーバープロセスのメモリ内だけに保持されます。

• open_scratch_project { projectId } — 指定した ID のプロジェクトをダウンロードして編集用に開きます（共有済みプロジェクトはログイン不要。未共有の自分用プロジェクトはログインが必要です）。

• push_to_scratch { projectId?, confirm? } — 開いているプロジェクトを scratch.mit.edu に保存し、オンライン上のプロジェクトを上書きします（アセットをアップロードしてから project.json を送信します）。

• share_project { projectId?, confirm? } — プロジェクトを公開してパブリックにします。

push_to_scratch と share_project はライブのプロジェクトを変更するため、必ず最初に確認を求められます。クライアントが対応している場合（: サポートされている場合）は MCP の elicitation プロンプトを使い、そうでない場合は confirm: true を要求します（エージェントは、あなたが同意した後でのみこの値を設定できます）。

Reading

• list_sprites — すべてのスプライトを、位置・サイズ・メディア情報とともに一覧します。

• get_target { name } — スプライトまたは "Stage" の完全な詳細を取得します。

• get_target_json { name, pointer? } — ターゲットの生の project.json エントリ（ブロック、コスチューム/サウンド、…）、または JSON Pointer で指定した部分木を取得します。patch_target を作成する前に、この出力を読んでおいてください。

Blocks（エージェントがどのブロックが存在し、それらをどう扱うかを把握できるように）

• list_blocks { category? } — 各標準条項（オペコード）のカタログ。各項目には、そのカテゴリ、形状（hat / stack / c-block / cap / reporter / boolean）、入力とフィールドの名前が含まれます。起動時にインストール済みの scratch-vm から生成されるため、常に実際と同期しています。

• get_block_schema { opcode, target? } — 1つのオペコードの完全スキーマ: 各入力の sb3 シャドウエンコーディング（例: テキスト入力は [1, [10, "hi"]]）、各フィールドの列挙済みドロップダウン options、そして編集のベースにできるサンプルのブロックJSON。動的なメニューオプション（スプライト、サウンド、コスチューム、ブロードキャスト、…）は、そのとき開いているプロジェクトから入力されます。target を渡すと、そのスプライト自身のコスチュームとサウンドが列挙されます。組み込みの削除ブロック（pen_*、music_*、microbit_*、…）もカバーしており、各拡張の getInfo() から生成されます。

Extensions

• enable_extension { id, url? } — 拡張機能を登録して、そのブロックをロードしパレットに表示します（<id>_… ブロックを使用する前に必要）。組み込み拡張（pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor）には id だけを渡します。カスタム/サードパーティ（TurboWarp）拡張には url を追加します。list_blocks { category: "<id>" } と get_block_schema は組み込み拡張のブロックを説明します。patch_target は、有効になっていない拡張を使用するブロックがあると警告します。カスタム拡張は透過なので、get_target_json で既存のブロックを参照して読み替えてください。

Raw JSON の編集（差分/パッチ）

• patch_target { name, patch } — RFC 6902 の JSON Patch をターゲットの生 JSON に適用します。これは、スプライトのスクリプト（blocks）や高レベルツールが扱わないフィールドを編集する方法です。rに対象は、新しく作成したスプライトでも既存のスプライトでもかまいません。パスは get_target_json への JSON Pointer です。パッチは原子的（オールオアナッシング）に適用され、結果は未知のオペコードや入力への参考 warnings を報告します。costumes/sounds 配列のパッチでは、アセットのバイトは変化しません。それには add_costume/remove_costume を使ってください。

Sprites & stage

• set_sprite { name, x?, y?, size?, direction?, visible?, draggable?, rotationStyle?, layerOrder?, volume? }

• add_sprite { name, ...props } / remove_sprite { name } / rename_target { name, newName }

• set_stage { tempo?, videoState?, videoTransparency?, volume? }

Variables, lists, broadcasts (target はスプライト名、または "Stage")

• set_variable { target, name, value } / delete_variable { target, name }

• set_list { target, name, items } / delete_list { target, name }

• add_broadcast { name }

Costumes & sounds

• add_costume { target, name, path, dataFormat?, rotationCenterX?, rotationCenterY? }

• remove_costume { target, name }

• add_sound { target, name, path, dataFormat? } / remove_sound { target, name }

Run & test (ideally TurboWarp VM、in-process)

• vm_load — 開いているプロジェクトをヘッドレス VM（エディット内容も含む）にロードします。

• vm_green_flag — 緑旗を押します（バブル、返答、エラーをクリアします）。

• vm_run { seconds?, frames?, untilIdle?, paced? } — VM を進め、その後、状態と（前回の実行からの）events タイムライン（say/think、broadcast、question/answer、errors）を返します。

• vm_state — スナップショット: すべてのターゲットの位置・サイズ・メタデータ・コスチューム・表示状態、変数、リスト、モニター、say/think バブル、保留中の質問、実行中スレッド、エラー。

• vm_input { keys?, mouseX?, mouseY?, mouseDown?, answer? } — キーボード/マウスを送信し、ask and wait に答えます。

• vm_stop — すべてのスクリプトを停止します。

Live reload & screenshots（ブリッジ + userscript が必要）

• reload { path? } — ディスクから .sb3 をエディタにロードします。

• run_project / stop_project — プログフラグ / 停止

• screenshot — ライブステージを PNG としてキャプチャします（ピクセル単位での正確性が重要な場合に）。パラメータはありません。

• screenshot_jpeg { quality? } — 同じキャプチャを JPEG に再エンコードしたもの（より小さく、読み込みが高速。quality は 1–100、デフォルト 80）。

Running and testing a project

vm_* ツールは TurboWarp の scratch-vm（JIT フォーク）をこのプロセス内に組み込みます — ブラウザ不要、WebGL 不要。基本的なフローは: 編集 → vm_load → vm_green_flag → vm_run → vm_state の確認 → アサーション です。構造化された状態（変数値、スプライト位置、say バブルなど）が返されるため、エージェントは直接アサーションできます。ピリングから推論するよりもはるか確実で、CI でも十分に決定的です。

ヘッドレス VM にはレンダラーやオーディオはありませんが、コスチュームのメタデータはロードされるため（名前/番号によるコスチューム指定は機能します）、renderer に依存するブロック（色/スプライト/エッジへの接触、ペン）やサウンド再生は無効です。実際のレンダリングされたステージを見るには、TurboWarp Desktop でプロジェクトを実行し、screenshot を呼び出してください。

イベント（Events）

注目すべきイベント — say/think、broadcast、greenflag、stop、question/answer、実行時/コンパイル時 errors。それぞれ { level, type, message, …fields } — は2つの方法で送信されます。

• vm_run の結果内（events）: 前回の vm_run からの順序付きタイムライン。これはエージェント向けのチャネルで、モデルはツールの結果から直接読み取れ、最終状態だけでなくシーケンスをアリティできます。常にオンです。

• MCP ログ通知（notifications/message、logger: "scratch-vm"）: ホストのログビュー用のクライアント/ユーザー向けのチャネル。クライアントが logging/setLevel でログレベルを上げるまではオフです。アクティビティには "info" を、実行境界やバブルがクリアされる情報も含めるには "debug" を、エラーのみにするには "warning" 以上を指定します。（ほとんどのクライアントは通知をモデルに返さないため、vm_run のチャネルが必要になります）。

同じ内容の say/think バブルは重複削除され、ループ内の say がどちらかのチャネルにあふれることがありません。

How live reload works

ライブリロードは、シンプルな WebSocket + HTTP サーバーとして動作します。userscript は WebSocket で接続し、JSON リクエスト（loadSB3 / start / stop / screenshot）に応答します。loadSB3 では、GET /get.sb3?path=… からバイトを取得し、TurboWarp VM にロードします。save_project はファイルを書き込んだ後で loadSB3 を送るため、エディタは常に最新の保存を表示します。スナップショットは PNG として返され、サーバーはそれをそのまま返す（screenshot）か、JPEG に再エンコード（screenshot_jpeg）します。