Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(mcp): the connection survives an editor that fails to start, and tells the agent how to work

yhh1fab955f8dda
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4698265ac..f1062fefb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ published separately; it ships inside the editor.
### Changed
- **An agent call over MCP is one undo step, files included.** Everything one call changes — its scene edits and the project files it writes — goes back with one Undo and forward with one Redo, shown in History as **AI · *tool***. A call that only wrote files does not mark the scene unsaved, and the `undo` / `redo` tools answer once the files are back on disk. Every tool also carries MCP annotations from what it does (read-only, undoable, destructive), so a client asks before only the calls that leave the project or run unlisted code; a long call sends a progress note every five seconds; arguments are checked inside arrays and objects, with the place named; and each call is noted in a local log (`~/.estella/mcp-calls.jsonl`, never the arguments, `ESTELLA_MCP_CALL_LOG=0` to turn off) that `desktop/scripts/mcp-call-stats.mjs` summarises by the tools that fail most. `write_project_file` no longer reports a failure for a script it wrote outside the project's script folders.
+- **The MCP connection survives an editor that fails to start, and tells the agent how to work.** A call made while the editor cannot start says why, in the editor's own output, and the next call tries again; the connection used to drop with it. Every session gets short server instructions at connect (tool groups, the open scene versus the running game, `step` instead of waiting, one call per undo step). Saves, exports, project creation and play-mode tools are no longer undo steps, so Undo does not roll a saved file back. A cancelled call does not start, and a composite one stops at its next step. `enable_tools` takes `plugins`, for clients that do not refresh their tool list.
- **Plugin agent tools reach MCP clients.** A tool a plugin lends with `ctx.agentTools.register` is now listed to every connected MCP client beside the editor's own, and a call runs in the editor. Its `schema` is checked first, and a tool whose `effect` is not `read` is offered only while the editor lets agents change the project. The LDtk plugin's `estella_ldtk_import` is the first.
## [0.97.0] - 2026-10-31
diff --git a/desktop b/desktop
index 98937f155..ad4ea5062 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 98937f1558e24b5654e422eb4a477825b79ff433
+Subproject commit ad4ea50625e052ab2d713d2299e7ea916442a8b8
diff --git a/docs/astro/src/content/docs/agents/mcp.mdx b/docs/astro/src/content/docs/agents/mcp.mdx
index 40a4fe0bb..f80918554 100644
--- a/docs/astro/src/content/docs/agents/mcp.mdx
+++ b/docs/astro/src/content/docs/agents/mcp.mdx
@@ -231,11 +231,18 @@ folder in one call — each asset keeps the settings the patch does not name.
- **One call is one undo step.** Everything a call changes — the scene edits *and* the project files it writes — goes back with
one **Ctrl/⌘ + Z**, and comes forward again with Redo. The step shows in **History** as **AI · *tool***. A call that only wrote
files does not mark the scene unsaved. The agent's own `undo` / `redo` tools answer once the files are back on disk.
+ Saving, exporting, creating a project and anything done to the running game are not steps: Undo does not take back a save.
- **Your client knows what each tool does.** Every tool carries MCP annotations: reading tools are marked read-only, and only the
ones that leave the project or run code nobody listed (an editor command, a probe in the running game) are marked destructive.
A client that asks before such calls asks only before those.
- **Long calls say they are still running.** A client that asks for progress hears every five seconds which tool is running and
- for how long — opening a large scene or exporting reads as working, not hung.
+ for how long — opening a large scene or exporting reads as working, not hung. A call cancelled before it starts does not
+ run, and a composite one stops at its next step; one editor operation already running (an export, a bake) finishes.
+- **If the editor cannot start**, the call says why, in the editor's own words, and the next call tries again — the
+ connection stays up.
+- **The agent is told the house rules at connect**: tool groups, the open scene versus the running game, `step` instead of
+ waiting, one call per undo step. A client that does not refresh its tool list can still reach plugin tools with
+ `enable_tools` and the `plugins` group.
- **Which tools fail, on this machine.** The connection notes each call (tool, client, outcome, time, the start of an error —
never the arguments) in `~/.estella/mcp-calls.jsonl`. `node desktop/scripts/mcp-call-stats.mjs` lists the tools that fail
most and how. Nothing is sent anywhere; `ESTELLA_MCP_CALL_LOG=0` turns it off.
diff --git a/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx b/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx
index 759b249de..5bad980e0 100644
--- a/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx
+++ b/docs/astro/src/content/docs/zh-cn/agents/mcp.mdx
@@ -206,9 +206,14 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \
- **一次调用就是一步撤销。** 一次调用改的所有东西——场景改动*和*它写的项目文件——按一次 **Ctrl/⌘ + Z** 一起退回,重做再一起回来。
这一步在**历史**里显示为 **AI · *工具名***。只写了文件的调用不会把场景标成未保存。代理自己的 `undo` / `redo` 工具会等文件回到磁盘上才回复。
+ 保存、导出、新建项目以及对运行中游戏做的事不算步骤:撤销不会把一次保存退回去。
- **客户端知道每个工具会做什么。** 每个工具都带 MCP 注解:读取类标为只读,只有离开当前项目、或执行没人列得清后果的代码(编辑器命令、在运行中的游戏里跑探针)的才标为破坏性。
会在这类调用前询问的客户端,只会在这些调用前问。
- **长调用会说自己还在跑。** 请求了进度的客户端每五秒会收到一次:哪个工具在跑、跑了多久——打开大场景或导出不再像卡住了。
+ 开始前就被取消的调用不会执行,组合调用会在下一步停下;已经在跑的单个编辑器操作(导出、烘焙)会跑完。
+- **编辑器起不来时**,这次调用会用编辑器自己的话说明原因,下一次调用会重试——连接不会断。
+- **代理一连上就知道规矩**:工具分组、打开的场景和运行中的游戏的区别、用 `step` 而不是干等、一次调用一步撤销。
+ 跟不上工具列表变化的客户端,也能用 `enable_tools` 的 `plugins` 组拿到插件工具。
- **在这台机器上,哪些工具最常失败。** 连接会把每次调用(工具、客户端、成败、耗时、报错开头——从不记参数)记在 `~/.estella/mcp-calls.jsonl`。
`node desktop/scripts/mcp-call-stats.mjs` 列出最常失败的工具和原因。不会发到任何地方;`ESTELLA_MCP_CALL_LOG=0` 可以关掉。