scratch-mcp

一个用于编辑 Scratch .sb3 项目的 Model Context Protocol 服务器，基于 scratch4js 构建。它在内存中保持一个项目打开，将库的编辑接口暴露为 MCP 工具，并保存回磁盘。

它还在 http://localhost:9060 上托管一个实时重载桥。安装 TurboWarp Desktop 用户脚本 后，每次 save_project 都会在编辑器中实时重新加载项目——因此代理的编辑会立即生效。

安装

npx scratch-mcp     # serves MCP over stdio

Related MCP server: scratch-mcp

开发

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）。如果端口已被占用，服务器仍会启动；只是实时重载会被禁用。

安装为 MCP Bundle（.mcpb）

为了在 Claude Desktop 和其他支持 MCPB 的客户端中一键安装，该服务器打包为一个 MCP Bundle——一个包含服务器和自包含 node_modules 的 .mcpb 文件。

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

然后在你的客户端中打开这个 .mcpb（在 Claude Desktop 中，将其拖入 设置 → 扩展）。该包只暴露一个设置——实时重载桥端口——无需其他配置。构建脚本（scripts/build-mcpb.mjs）会将 scratch4js 和 s-api4js 工作区包以 tarball 形式内置，并按照 MCPB 的要求将 git 依赖 scratch-vm 及其同级依赖安装到扁平的 node_modules 中。manifest.json 是包的唯一事实来源（其版本在构建时从 package.json 中写入）。

工具

项目

• open_project { path } —— 将 .sb3 文件加载到内存中。

• save_project { path?, compressionLevel? } —— 将其写回（并触发实时重载）。

• project_info —— 目标、扩展、监视器、元数据。

Scratch 网站（在线项目，通过 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 和 scratch_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? } —— 标准操作码目录，每个操作码都有其类别、形状（帽子 / 堆叠 / C 形 / 封底 / 报告器 / 布尔）以及其输入和字段的名称。启动时从已安装的 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、pen、video、music、text、translate、makey makey、microbit、evr、boost、me two 2、torcf）；自定义/第三方（TurboWarp）扩展需加 url。list_blocks { category: "<id>" } 和 get_block_schema 会描述内置扩展积木；当某个积木使用的扩展未启用时，patch_target 会发出警告。自定义扩展是不可见的——请通过 get_target_json 镜像。

编辑原始 JSON（diff/patch）

• patch_target { name, patch } —— 对目标的原始 JSON 应用 RFC 6902 JSON Patch。这就是你编辑角色脚本（blocks）或更高层工具未覆盖的其他字段的方式（无论是刚创建的角色还是已有的角色）。路径是 get_target_json_users 和 JSON Pointer；补丁原子应用（要么全改，要么全不改），结果会针对未知操作码或输入给出建议性的 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?, methodCenterX?, rotationCenterY? }

• remove_costume { target, name }

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

运行与测试（进程内的无头 TurboWarp VM）

• vm_load —— 将打开的项目加载到无头 VM 中（会反映内存中的编辑）。

• vm_green_flag —— 按一下绿旗（其主要清除对话气泡、提问、错误）。

• vm_run { seconds?, frames?, untilIdle?, paced? } —— 运行 VM，然后返回返回状态和自上次运行以来的 events 时间线（说 / 思考、广播、提问 / 回答、错误）。

• vm_state —— 快照：每个目标的 position / size / direction / costume / visibility、变量、列表、监视器、说/思考气泡、当前问题、正在运行的线程、错误。

• vm_input { keys?, mouseX?, mouseY?, mouseDown?, answer? } —— 输入键盘/鼠标输入，并回答 ask and wait 的提问。

• vm_stop —— 停止所有脚本。

实时重载与截图（依赖代理 + 用户脚本）

• reload { path? } —— 从内存中加载 .sb3，在编辑器中加载。

• tools / stop_project —— 按下绿旗 / 停止。

• screenshot —— 将实时舞台捕获为无损 PNG 格式，在精确像素重要的情况下使用。不承担参数。参数。

• screenshot_jpeg { quality? } —— 同样的捕获输出为压缩的 JPEG 文件中（更小的体积、更低的读取成本；quality 1–100，默认 80）。

运行和测试项目

vm_* 工具将 TurboWarp 的 scratch-vm（JIT 分支）集成到本进程——不需要浏览器，也不需要 WebGL。工作流程是：编辑 → vm_load → vm_green_flag → vm_run → 读取 vm_state → 断言。它返回结构化状态（变量值、角色位置、说出的气泡），代理可以直接对其断言——远比通过像素判断更好，并且对 CI 来说足够可预测。

无头 VM 没有渲染器或音频：造型的元数据仍然会加载（因此按名称/编号选择造型的逻辑工作），但依赖渲染器的积木（检查颜色/角色/边缘、画笔）和声音播放是无效的。为了查看真实渲染的舞台，请在 TurboWarp Desktop 中运行项目并调用 screenshot。

事件

一些事件——say/think、broadcasts、green flag、stop、question/answer 以及运行时/编译 errors，每一项 { level, type, message, …fields } ——通过两种方式展示：

• 在 vm_run 的结果中（events）：自上一次 vm_run 以来的有序时间线。这是 agent-facing 的通道——模型直接在结果中读取，并可以断言顺序，而不只是最终状态。始终开启。

• 作为 MCP 日志通知（notifications/message、logger: "scratch-vm"）：这是 client/human-facing 的通道，用于宿主的日志视图。直到客户端通过 logging/setLevel 将日志级别提升到——"info" 表示活动，"debug" 还会读取运行边界和气泡消除，"warning" 及更高则只读取错误。（大多数客户端不会把通知反馈给模型，这正是为什么 vm_run 的通道存在。）

重复的相同 say/think 气泡会去重，以避免在循环中的 say 淹没了任何一路通道。

实时重载的工作原理

桥接服务器是一个普通的 WebSocket + HTTP 服务端。用户脚本通过 WebSocket 连接，通过响应 JSON 请求（loadSB3 / start / stop / screenshot）。在 loadSB3 时，它会从 GET /get.sb3?path=… 获取字节并将它们加载到 TurboWarp VM 中；save_project 先写入文件再发送 loadSB3，所以编辑器总能显示最新保存的内容。快照会以 PNG 返回，服务器会原样传递（screenshot）或重新压缩为 screenshot_jpeg（screenshot_jpeg）。