scratch-mcp

Сервер Model Context Protocol для редактирования проектов Scratch .sb3, построенный на scratch4js. Он держит один проект открытым в памяти, предоставляет поверхность редактирования библиотеки в виде инструментов MCP и сохраняет изменения на диск.

Также он включает мост live-reload на http://localhost:9060. Если установлен пользовательский скрипт TurboWarp Desktop, каждый вызов 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

Настройка MCP-клиента

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

Установите значение SCRATCH_MCP_BRIDGE_PORT, чтобы изменить порт моста (по умолчанию 9060). Если порт занят, сервер все равно запускается; отключается только live reload.

Установка в виде MCP Bundle (.mcpb)

Для установки в один клик в Claude Desktop и других клиентах, поддерживающих MCPB, этот сервер упаковывается как MCP Bundle — единый файл .mcpb, содержащий сервер и автономный node_modules.

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

Затем откройте .mcpb в вашем клиенте (в Claude Desktop перетащите его в Settings → Extensions). Бандл предоставляет один параметр — порт моста live-reload — и не требует никакой другой настройки. Сборка (scripts/build-mcpb.mjs) подключает пакеты рабочей области scratch4js и s-api4js как tarball и размещает git scratch-vm и его peer-зависимости в плоском node_modules, как требует MCPB. manifest.json — источник истины для бандла (его версия проставляется из package.json при сборке).

Инструменты

Проект

• open_project { path } — загружает .sb3 в память.

• save_project { path?, compressionLevel? } — сохраняет его обратно (и выполняет live-reload).

• project_info — цели, расширения, мониторы, метаданные.

Сайт Scratch (онлайн-проекты, через s-api4js)

• scratch_login { username?, password? } — вход на scratch.mit.edu (по умолчанию $SCRATCH_USER / $SCRATCH_PASS). Сессия живет в памяти только для процесса сервера.

• open_scratch_project { projectId } — скачивает проект по идентификатору и открывает его для редактирования (открытые проекты не требуют входа; ваши собственные неопубликованные — требуют).

• push_to_scratch { projectId?, confirm? } — сохраняет открытый проект обратно на scratch.mit.edu, перезаписывая его онлайн (сначала загружает медиафайлы, затем project.json).

• share_project { projectId?, confirm? } — публикует проект, делая его общедоступным.

push_to_scratch и share_project изменяют живой проект, поэтому они всегда сначала запрашивают подтверждение — через MCP elicitation-подсказку, если ваш клиент её поддерживает, либо через обязательно требование confirm: true (которое агент должен устанавливать только после вашего согласия).

Чтение

• list_sprites — показывает всех спрайтов с позицией/размером/медиа.

• get_target { name } — полные детали спрайта или "Stage".

• get_target_json { name, pointer? } — исходная запись project.json для цели (блоки, костюмы, звуки и т.д.) или поддерево по JSON Pointer. Прочитайте это перед созданием patch_target.

Справочник по блокам (чтобы агент знал, какие блоки существуют и как их заполнять)

• list_blocks { category? } — каталог стандартных опкодов, каждый со своей категории, формой (hat / stack / c-block / cap / reporter / boolean) и именами своих входов и полей. Генерируется при запуске из установленного scratch-vm, поэтому остаётся синхронизированным.

• get_block_schema { opcode, target? } — полная схема для одного опкода: каждый вход с его sb3 shadow-кодированием (например, текстовый вход — [1, [10, "hi"]), каждое поле с перечисленными options для выпадающих списков, и готовый к адаптации пример JSON-блока. Динамические пункты меню (спрайты, звуки, костюмы, сообщения и т.д.) заполняются из открытого проекта; передайте target, чтобы перечислить костюмы и звуки конкретного спрайта. Охватываются и встроенные блоки расширений (pen_ *, music_ *, microbit_ * и т.д.), сгенерированные из getInfo() каждого расширения.

Расширения

• enable_extension { id, url? } — регистрирует расширение, чтобы его блоки загружались и отображались в палитре (требуется перед использованием любого блока <id>_…). Укажите только id для встроенного (pen, music, videoSensing, text2speech, translate, makeymakey, microbit, ev3, boost, wedo2, gdxfor); добавьте url для пользовательского/стороннего (TurboWarp) расширения. list_blocks { category: "<id>" } и get_block_schema описывают встроенные блоки расширений; patch_target предупреждает, когда блок использует не включённое расширение. Пользовательские расширения не являются прозрачными — повторяйте существующий блок через get_target_json.

Редактирование raw JSON (diff/patch)

• patch_target { name, patch } — применяет RFC 6902 JSON Patch к raw JSON цели. Так вы редактируете скрипты (blocks) спрайта или любые поля, не покрытые более высокоуровневыми инструментами — для только созданного спрайта или существующего. Пути — это JSON Pointer в get_target_json; patch применяется атомарно (все или ничего), и результат содержит предупреждающие warnings для неизвестных опкодов или входов. Правка массивов costumes/sounds не перемещает байты ассетов — для этого используйте add_costume/remove_costume .

Спрайты и сцена

• 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? }

Переменные, списки, сообщения (target — имя спрайта или "Stage")

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

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

• add_broadcast { name }

Костюмы и звуки

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

• remove_costume { target, name }

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

Запуск и тестирование (безголоввная TurboWarp VM, в процессе сервера)

• vm_load — загружает открытый проект в безголовую VM (учитывает изменения в памяти).

• vm_green_flag — нажимает зелёный флаг (очищает пузыри, вопрос, ошибки).

• vm_run { seconds?, times?, untilIdle?, paced? } — продвигает VM, затем возвращает состояние и временную линию events (сказать/думать, сообщения, вопрос/ответ, ошибки) с последнего запуска.

• vm_state — мгновенный снимок: позиция/размер/направление/костюм/видимость каждого спрайта, переменные, списки, мониторы, пузыри «сказать/подумать», ожидающий вопрос, выполняемые потоки, ошибки.

• vm_input { keys?, mouse }, mouse? — подает клавиатурный/мышиный ввод и отвечает на ask and wait.

• vm_stop — останавливает все скрипты.

Live reload и скриншоты (требуют мост + пользовательский скрипт)

• reload { path? } — загружает .sb3 из диска в редакторе.

• run_project / stop_project — зелёный флаг / стоп.

• screenshot — снимает живое игровое поле как PNG без потерь, для случаев, когда важны точно попадающиеся пиксели. Не принимает параметров.

• screenshot_jpeg { quality? } — то же изображение, перекодированное в сжатый JPEG (меньше, дешевле при чтении; quality 1–100, по умолчанию 80).

Запуск и тестирование проекта

Инструменты vm_* встраивают TurboWarp's scratch-vm (JIT-сторс) в этот процесс — без браузера и без WebGL. Цикл: редактируйте → vm_load → vm_green_flag → vm_run → читайте vm_state → проверяйте. Возвращает структурированное состояние (значения переменных, позиции спрайтов, пузыри «сказать»), против которого агент может напрямую выполнять проверки — это намного лучше, чем анализировать пиксели, и достаточно детерминированно для CI.

Безголовая VM не имеет ни рендерера, ни аудио: метаданные костюмо (можно выполнять логику по имени/номеру костюма), но блоки с целиком на рендер (задевание цвета/спрайта/края, перо) и звук не работают. Чтобы увидеть настоящую отрендеренную сцену, запустите проект в TurboWarp Desktop и выполните screenshot.

События

Заметные события — say/think, broadcast, greenflag, stop, question/answer и error времени запуска/компиляции, каждое с { level, type, message , …fields } — отображаются двумя способами:

• В результате vm_run (events): упорядоченный временной ряд с предыдущего vm_run. Это канал для агента — модель читает его прямо в результате инструмента и может проверять последовательность, а не только конечное состояние. Всегда включён.

• Как MCP-лог-уведомления (notifications/message, logger: "scratch-vm"): клиентский/пользовательский канал для представления логов хоста. Выключен, пока клиент не повысит уровень логгирования через logging/setLevel — "info" для %активности, "debug" для добавления граница запуска и отмены пузырей, "warning" ить только ошибки. (Бильшие/меньшинство клиентов не передают уведомления обратно модели, поэтому существует канал vm_run.)

Повторяющиеся одинаковые пузыри say/think дедуплицируются, чтобы say в цикле не завалил ни один канал.

Как работает live reload

Мост — это обычный WebSocket + HTTP-сервер. Пользовательский скрипт подключается по WebSocket и обрабатывает JSON-запросы (loadSB3 / start / stop / screenshot). При loadSB3 он получает байты по GET /get.sb3?path=… и загружает их в VM в TurboWarp; save_project сначала записывает файл, а затем отправляет loadSB3, поэтому редактор всегда показывает последнее сохранение. Снимок возвращается как PNG, который сервер передаёт без изменений (screenshot) или перекодирует в сжатый JPEG (screenshot_jpeg).