scratch-mcp

Un servidor de Model Context Protocol para editar proyectos Scratch .sb3, construido sobre scratch4js. Mantiene un proyecto abierto en memoria, expone la superficie de edición de la librería como herramientas MCP y guarda de nuevo en el disco.

También aloja un puente de recarga en vivo en http://localhost:9060. Con el userscript de TurboWarp Desktop instalado, cada save_project recarga el proyecto en vivo dentro del editor: así los cambios de un agente aparecen al instante.

Instalación

npx scratch-mcp     # serves MCP over stdio

Related MCP server: scratch-mcp

Desarrollo

El servidor MCP se encuentra en la raíz del repositorio; las librerías sobre las que se construye son paquetes del workspace en packages/.

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

Configurar un cliente MCP

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

Establece SCRATCH_MCP_BRIDGE_PORT para cambiar el puerto del bridge (por defecto 9060). Si el puerto está ocupado, el servidor de todas formas arranca; solo se desactiva la recarga en vivo.

Instalación como MCP Bundle (.mcpb)

Para una instalación de un solo clic en Claude Desktop y otros clientes que soporten MCP Bundle, este servidor se empaqueta como un MCP Bundle: un único archivo .mcpb que contiene el servidor más un node_modules autocontenido.

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

Luego abre el .mcpb en tu cliente (en Claude Desktop, arrástralo a Settings → Extensions). El bundle expone una única configuración: el puerto del bridge de recarga en vivo; no requiere ninguna otra configuración. La compilación (scripts/build-mcpb.mjs) empaqueta los paquetes del workspace duplicar de scratch4js y s-api4js como tarballs, e instala el scratch-vm de git y sus peers en un node_modules plano, como exige MCPB. El manifest.json es la fuente de verdad del bundle (su versión se sella desde package.json en tiempo de compilación).

Herramientas

Proyecto

• open_project { path } — carga un .sb3 en memoria.

• save_project { path?, compressionLevel? } — lo escribe de vuelta a disco (y recarga en vivo).

• project_info — objetivos, extensiones, monitores, metadatos.

Sitio web de Scratch (proyectos en línea, vía s-api4js)

• scratch_login { username?, password? } — inicia sesión en scratch.mit.edu (usa $SCRATCH_USER / $SCRATCH_PASS por defecto). La sesión existe en memoria solo para el proceso del servidor.

• open_scratch_project { projectId } — descarga un proyecto por id y lo abre para edición (los proyectos compartidos no necesitan inicio de sesión; los propios no compartidos sí).

• push_to_scratch { projectId?, confirm? } — guarda el proyecto abierto de nuevo en scratch.mit.edu, sobrescribiendo la versión online (sube los assets y después project.json).

• share_project { projectId?, confirm? } — publica un proyecto para que sea visible.

push_to_scratch y share_project cambian el proyecto en vivo, por lo que siempre te piden confirmación primero — mediante un prompt de elicitation de MCP,si tu cliente lo admite, o, de lo contrario, exigiendo confirm: true (que el agente solo debería establecer después de que hayas aceptado).

Lectura

• list_sprites — lista cada sprite con su posición/tamaño/medios.

• get_target { name } — detalles completos de un objetivo o de "Stage".

• get_target_json { name, pointer? } — la entrada project.json en bruto del objeto (bloques, disfraces, sonidos, …) o un subárbol en un JSON Pointer. Lee esto antes de crear un patch_target.

Referencia de bloques (para que el agente sepa qué bloques hay y cómo rellenarlos)

• list_blocks { category? } — catálogo de operacódigos estándar, cada uno con su categoría, su forma (hat / stack / c-block / cap / reporter / boolean) y los nombres de sus entradas y campos. Se genera al inicio desde el scratch-vm instalado, por lo que se mantiene sincronizado.

• get_block_schema { opcode, target? } — con esquema completo para un opcode: cada entrada con su codificación de sombra sb3 (por ejemplo, una entrada de texto es [1, [10, "hi"]]), cada campo con sus opciones de cuadro enumeradas y un block JSON ejemplo listo para adaptar. Las opciones dinámicas de menú (sprites, sonidos, disfraces, mensajes, …) se extraen del proyecto abierto; pasa target para enumerar los disfraces y sonidos propios de ese sprite. También cubre los bloques de extensiones integradas (pen_*, music_*, microbit_*, …), generados desde el getInfo() de cada extensión.

Extensiones

• enable_extension { id, url? } — registra una extensión para que sus bloques carguen y aparezcan en la paleta (requerido antes de usar cualquier bloque <id>_…). Pasa solo el id para una integrada (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor); añade un url para una personalizada/de tercero (TurboWarp). list_blocks { category: "<id>" } y get_block_schema describen bloques de extensiones built-in; patch_target avisa cuando un bloque utiliza una extensión no habilitada. Las extensiones personalizadas son opacas — réplica un bloque existente a través de get_target_json.

Edición de JSON en bruto (diff/patch)

• patch_target { name, patch } — aplica un RFC 6902 JSON Patch al JSON en bruto de un objetivo. Así se editan los guiones (blocks) de un sprite o cualquier campo que las herramientas de nivel más alto no cubran, ya sea en un sprite que acabas de crear o en uno ya existente. Los caminos son JSON Pointers dentro de get_target_json; el patch se aplica atómicamente (todo o nada) y el resultado reporta avisos warnings para opcodes o entradas desconocidos. Hacer patch en los arregos costumes/sounds no mueve los bytes de los assets — usa add_costume/remove_costume para eso.

Sprites y escenario

• 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, listas y broadcasts (target es el nombre de un sprite o "Stage")

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

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

• Confirmación del list add_broadcast { name }

Disfraces y sonidos

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

• remove_costume { target, name }

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

Ejecutar y probar (máquina virtual de TurboWarp VM en el proceso, sin navegador)

• vm_load — carga el proyecto abierto en una VM headless (realiza los cambios en memoria).

• vm_green_flag — pulsa la bandera verde (límpia burbujas, preguntas y errores).

• vm_run { seconds?, frames?, untilIdle?, paced? } — avanza la VM y luego devuelve el estado y una línea de tiempo events (dice/piensa, broadcast, pregunta/respuesta, errores) desde la última ejecución.

• vm_state — instantánea: posición/tamaño/dirección/disfraz/visibilidad de cada objeto, variables, listas, monitores, burbujas say/think, pregunta en curso, hilos en ejecución, errores.

• vm_input { keys?, mouseX?, mouseY?, mouseDown?, answer? } — envía entrada de teclado y ratón, y responde a la pregunta de ask and wait.

• vm_stop — detiene todos los scripts.

Recarga en vivo y capturas de pantalla (requiere el bridge + userscript)

• reload { path? } — carga una imagen del .sb3 desde el disco en el editor.

• run_project / stop_project — bandera verde / stop.

• screenshot — capturo la escena en vivo como PNG sin pérdidas, por si los píxeles cuidados importan. No recibe parametros.

• screenshot_jpeg { quality? } — la misma captura re-indexada como JPEG comprimido (más pequeño y más barato de leer; quality 1–100, 80).

Ejecutar y probar un proyecto

Las herramientas vm_* incrustan el scratch-vm de TurboWarp (el fork JIT) dentro del proceso — sin navegador, sin WebGL. El ciclo es: editar → vm_load → vm_green_flag → vm_run → leer vm_state → hacer verificación. Proporciona estado estructurado (valores de variables, posiciones de sprites, burbujas) que el agente puede verificar directamente — mucho mejor que razonar sobre píxeles y lo suficientemente determinista para CI.

La VM headless no tiene renderizador ni audio: los metadatos de disfraz siguen cargándose (la lógica por nombre/número de disfraz funciona), pero los bloques basados en renderer (tocar color/sprite/borde, pen) y la reproducción de sonido son inertes. Para ver el escenario renderizado real, ejecuta el proyecto en TurboWarp Desktop y llama a screenshot.

Eventos

Eventos notables — say/think, broadcast, greenflag, stop, question/answer y errores de runtime/compilación (error), cada uno { level, type, message, …,fields } — se presentan de dos maneras:

• En el resultado de vm_run (events): la línea de tiempo en orden desde la ejecución anterior de vm_ previous. Este es el canal dirigido al agente — el modelo lo lee directamente en el centro de resultados y puede evaluar la secuencia, no solo el estado final. Siempre activado.

• Como notificaciones de log MCP (notifications/message, logger: "scratch-vm"): el canal cliente/humano, para la vista de logs del client. Apagado hasta que el cliente sube su nivel de registro a logging/setLevel — "info" para actividad, "debug" para incluir también los límites de ejecución y limpieza de burbujas, "warning" y superiores solo errores. (La mayoría de clientes no retroalimentan las notificaciones al modelo, por eso existe el canal vm_run).

Las burbujas say/think idénticas se deduplican para que un say dentro de un bucle no saturan los canales.

Como funciona la recarga en vivo

El bridge es un servidor WebSocket + HTTP simple. El usuarioscript se conecta a través de WebSocket y responde a peticiones JSON (loadSB3 / start / stop / screenshot). En loadSB3, obtiene los bytes de GET /get.sb3?path=… y los carga en la VM de TurboWarp; save_project escribe el archivo y luego envía loadSB3, por lo que el editor siempre muestra la última copia guardada. Una captura viene como PNG que el servidor transmite directamente (screenshot) o lo recodifica como JPEG comprimido (screenshot_jpeg).