scratch-mcp

Ein Model Context Protocol-Server zum Bearbeiten von Scratch-.sb3-Projekten, aufgebaut auf scratch4js. Er hält ein Projekt im Speicher geöffnet, stellt die Bearbeitungsoberfläche der Bibliothek als MCP-Tools bereit und speichert zurück auf die Festplatte.

Darüber hinaus hostet sie eine Live-Reload-Bridge auf http://localhost:9060. Mit dem installierten TurboWarp-Desktop-Userscript lädt jeder save_project das Projekt live im Editor neu — die Änderungen eines Agents erscheinen also sofort.

Installation

npx scratch-mcp     # serves MCP over stdio

Related MCP server: scratch-mcp

Entwickeln

Der MCP-Server liegt im Repository-Wurzelverzeichnis; die Bibliotheken, auf denen er aufbaut, sind Workspace-Pakete unter packages/.

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

Einen MCP-Client konfigurieren

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

Setzen Sie SCRATCH_MCP_BRIDGE_PORT, um den Bridge-Port zu ändern (Standardwert 9060). Wenn der Port belegt ist, startet der Server trotzdem; nur das Live-Reload wird deaktiviert.

Als MCP-Bundle installieren (.mcpb)

Für die Ein-Klick-Installation in Claude Desktop und anderen MCPB-fähigen Clients packaged sich dieser Server als MCP Bundle — eine einzelne .mcpb-Datei, die den Server plus ein eigenständiges node_modules enthält.

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

Öffnen Sie die .mcpb dann in Ihrem Client (in Claude Desktop ziehen Sie sie auf Einstellungen → Erweiterungen). Das Bundle bietet eine Einstellung — den Live-Reload-Bridge-Port — und benötigt keine weitere Konfiguration. Der Build (scripts/build-mcpb.mjs) bindet die scratch4js- und s-api4js-Workspace-Pakete als Tarballs ein und installiert die Git-Version von scratch-vm und deren Peers in ein flaches node_modules, wie von MCPB verlangt. Die manifest.json ist die maßgebliche Quelle des Bundles (ihre Version wird zur Build-Zeit aus package.json übernommen).

Werkzeuge

Projekt

• open_project { path } — lädt eine .sb3 in den Speicher.

• save_project { path?, compressionLevel? } — schreibt sie zurück (und startet Live-Reload).

• project_info — Targets, Erweiterungen, Monitore, Metadaten.

Scratch-Website (Online-Projekte, über s-api4js)

• scratch_login { username?, password? } — bei scratch.mit.edu anmelden (Standard: $SCRATCH_USER / $SCRATCH_PASS). Die Sitzung lebt nur im Speicher des Serverprozesses.

• open_scratch_project { projectId } — ein Projekt anhand der ID herunterladen und zur Bearbeitung öffnen (geteilte Projekte benötigen keine Anmeldung; eigene, nicht geteilte schon).

• push_to_scratch { projectId?, confirm? } — das geöffnete Projekt zurück auf scratch.mit.edu speichern und online überschreiben (lädt zuerst die Assets hoch, dann project.json).

• share_project { projectId?, confirm? } — ein Projekt veröffentlichen, damit es öffentlich ist.

push_to_scratch und share_project verändern das live Projekt. Sie fragen deshalb immer zuerst nach Ihrer Bestätigung — per MCP-Elicitation-Aufforderung, wenn Ihr Client das unterstützt, andernfalls durch die Anforderung von confirm: true (das der Agent nur setzen sollte, nachdem Sie zugestimmt haben).

Lesen

• list_sprites — alle Figuren mit Position, Größe, Medien.

• get_target { name } — vollständige Details zu einer Figur oder "Stage".

• get_target_json { name, pointer? } — den rohen project.json-Eintrag des Ziels (Blöcke, Kostüme, Klänge, …) oder einen Teilbaum an einem JSON Pointer. Vor der Erstellung eines patch_target lesen.

Block-Referenz (damit der Agent weiß, welche Blöcke es gibt und wie er sie füllt)

• list_blocks { category? } — Katalog der Standard-Opcodes, jeweils mit Kategorie, Form (Einstecker / Block / C-Block / Abdeckung / Reporter / Boolean) und den Namen seiner Eingaben und Felder. Wird beim Start aus dem installierten scratch-vm generiert und bleibt so synchron.

• get_block_schema { opcode, target? } — vollständiges Schema für einem Opcode: jede Eingabe mit ihrer sb3-Schattenkodierung (z. B. ist eine Texteingabe [1, [10, "hi"]]), jedes Feld mit aufgezählten Dropdown-options, und ein direkte anpassbares Beispiel JSON. Dynamische Menüoptionen (Figuren, Klänge, Kostüme, Broadcasts, …) werden aus dem geöffneten Projekt gefüllt; sie target übergeben, um die eigenen Kostüme und Klänge dieser Figur aufzuzählen. Auch eingebaute Extensions-Blöcke sind abgedeckt (pen_*, music_*, microbit_*, …), generiert aus dem getInfo() jeder Erweiterung.

Erweiterungen

• enable_extension { id, url? } — eine Erweiterung registrieren, sodass ihre Blöcke lernen und in der Palette erscheinen (erforderlich, bevor ein <id>_…-Block verwendet wird). Für eine eingebaute Erweiterung nur id übergeben (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor); für eine benutzerdefinierte bzw. Drittanbieter-(TurboWarp-)Erweiterung url hinzufügen. list_blocks { category: "<id>" } und get_block_schema beschreiben eingebaute Erweiterungsblöcke; patch_target warnt, wenn ein Block eine nicht aktivierte Erweiterung verwendet. Benutzerdefinierte Erweiterungen sind stumm — einen bestehenden Block über get_target_json spiegeln.

Rohe JSON bearbeiten (diff/patch)

• patch_target { name, patch } — einen RFC 6902-JSON-Patch auf das rohe JSON eines Ziels anwenden. So bearbeiten Sie die Skripte (blocks) einer Figur oder jedes andere Feld, das die höherwertigen Werkzeuge nicht abdecken — bei einer neu erstellten oder einer bestehenden Figur. Die Pfade sind JSON Pointer in get_target_json; der Patch wird atomar (alles oder nichts) angewendet, und das Ergebnis meldet warnings für unbekannte Opcodes oder Eingaben. Das Patchen der costumes-/sounds-Arrays verschiebt keine Asset-Daten — dafür add_costume/remove_costume verwenden.

Sprites & Bühne

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

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

• wie auf Set_stage { tempo?, videoState?, videoTransparency?, volume? }

Variablen, Listen, Broadcasts (target ist eine Figurenname oder "Stage")

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

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

• add_broadcast { name }

Kostüme & 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 (headless TurboWarp-VM, prozessintern)

• vm_load — das geöffnete Projekt in eine headless VM (mit In-Memory-Bearbeitungen) laden.

• vm_green_flag — die grüne Flagge drücken (Sprechblasen, Frage, Fehler löschen).

• vm_run { seconds?, frames?, untilIdle?, paced? } — die VM vorwärtslaufen lassen und Zustand plus events-Zeitweise (sagen/denken, Broadcasts, Frage/Antwort, Fehler) seit dem letzten Lauf zurückgeben.

• vm_state — Zustands-Abbild: Position/Seite/Richtung/Kostüm/Sichtbarkeit jedes Ziels, Variablen, Listen, Monitore, Sprech- und Denkblasen, ausstehende Fragen, laufende Threads, Fehler.

• vm_input { keys?, mouseX?, mouseY?, mouseDown?, answer? } — Tastatur-/Mauseingabe und Antwort auf ask and wait.

• vm_stop — alle Skripte stoppen.

Live-Reload & Screenshots (erfordert Bridge + Userskript)

• reload { path? } — eine .sb3 von der Festplatte im Editor laden.

• run_project / stop_project — grüne Flagge / Stopp.

• screenshot — die Live-Bühne als verlustfreies PNG erfassen, falls exakte Pixel wichtig sind. Ohne Parameter.

• screenshot_jpeg { quality? } — dieselbe Aufnahme als komprimiertes JPEG (kleiner, günstiger zu lesen; quality 1–100, Standardstandard 80).

Ein Projekt ausführen und testen

Die vm_*-Werkzeuge betten TurboWarp's scratch-vm (den JIT-Fork) in denselben Prozess ein — kein Browser, kein WebGL. Der Ablauf ist: Bearbeiten → vm_load → vm_green_flag → vm_run → vm_state lesen → prüfen. Es liefert strukturierten Zustand (Variablenwerte, Figurenpositionen, Sprechblasen), den ein Agent direkt prüfen kann — viel besser als über Pixeln zu raten, und deterministisch genug für CI.

Die headless VM hat keinen Renderer und kein Audio: Kostüm-Metadaten laden weiterhin (damit die Logik „Kostüm nach Name/Nummer” funktioniert), aber renderer-abhängige Blöcke (berühren Farbe/Figur/edge, Stift) und Ton-Wiedergabe sind inaktiv. um die echte gerenderte Bühne zu sehen, das Projekt in TurboWarp Desktop ausführen und screenshot aufrufen.

Ereignisse

Relevante Ereignisse — say/think, broadcast, greenflag, stop, question/answer sowie Laufzeit-/Compiler-errors, jedes { name, type, message, …fields } — werden auf zwei Wegen angezeigt:

• Im Ergebnis von vm_run (events): die chronologische Abfolge seit dem letzten vm_run. Dies ist der agentenfähige Kanal — das Modell liest es direkt im Tool-Ergebnis und kann so die Reihenfolge prüfen, nicht nur den Endzustand. Immer aktiv.

• Als MCP-Log-Benachrichtigungen (notifications/message, logger: "scratch-vm"): der client-/nutzerorientierte Kanal für die Log-Ansicht eines Hosts. Bis der Client sie via logging/setLevel aktiviert, bleibt er stumm — "info" für Aktivität, "debug" auch für Läufe und Block-Grenzen, "warning"+ nur Fehler. (Die meisten Clients geben Benachrichtigungen nicht ans Modell weiter, deshalb gibt es sie auch als vm_run.)

Wiederholte identische say/think-Sprechblasen werden dedupliziert, sodass ein say in einer Loop keinen der beiden Kanäle überflutet.

Wie das Live-Reload funktioniert

Die Bridge ist ein schlichte WebSocket- plus HTTP-Server. Das Userscript verbindet sich über WebSocket und beantwortet JSON-Anfragen (loadSB3 / loadSVG? Nein, loadSB3/start/start/stop/screenshot). Bei loadSB3 ruft es bytes von GET /get.sb3?path=… ab und lädt sie in den TurboWarp-VM; save_project schreibt die Datei und sendet es das loadSB3, damit der Editor stets den letzten Stand zeigt. Ein Screenshot-Schnappschuss kommt als PNG zurück, das der Server unverändert weiterreicht (screenshot) oder als komprimiertes JPEG re-encodiert (screenshot_jpeg).