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.

feat(editor): the installed editor ships its MCP server - any AI tool connects

yhh5fd411237bba
diff --git a/desktop/README.md b/desktop/README.md
index 2fd2a31b0..01cc1f9eb 100644
--- a/desktop/README.md
+++ b/desktop/README.md
@@ -68,8 +68,10 @@ public/ wasm runtime, bundled SDK, example projects (served at web root
- **Runtime** — the SDK + `esengine.wasm` boot into a `<canvas>` in `Viewport`; the
editor drives the world through `EditorControlSurface` (also exposed to headless
- automation and AI agents over an MCP server: `pnpm editor:mcp`, see
- `scripts/editor-mcp.mjs`; mutating tools need `ESTELLA_MCP_ALLOW_WRITES=1`).
+ automation and AI agents over an MCP server: `pnpm editor:mcp` for the fixtures
+ host, `pnpm editor:mcp -- --editor` to drive the real app — projects, entity
+ creation, play, export. Mutating tools need `ESTELLA_MCP_ALLOW_WRITES=1`; the
+ installed editor ships the server bundled — see the "AI Agents (MCP)" guide).
- **Scenes & assets** — `ProjectStore` opens a project from disk and the Electron main
process watches it (`fs` + `chokidar`); the `ContentBrowser` browses and creates assets.
- **Inspector** — `Details` is generated from the engine's reflection metadata:
diff --git a/desktop/electron-builder.yml b/desktop/electron-builder.yml
index 33effac94..e0c259c73 100644
--- a/desktop/electron-builder.yml
+++ b/desktop/electron-builder.yml
@@ -26,6 +26,9 @@ files:
asarUnpack:
- "**/node_modules/{esbuild,@esbuild}/**"
- dist-electron/hosts/**
+ # The MCP front: an MCP client runs this with plain node (node cannot read
+ # inside an asar), which spawns/attaches the editor as the MCP host.
+ - dist-electron/mcp/**
- "**/node_modules/esengine/dist/**"
- dist/wasm/**
- dist/wasm-wechat/**
diff --git a/desktop/package.json b/desktop/package.json
index 59c5471dc..6526f4943 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -9,7 +9,7 @@
"main": "dist-electron/main.js",
"scripts": {
"dev": "vite",
- "build": "tsc --noEmit && vite build",
+ "build": "tsc --noEmit && vite build && node scripts/bundle-mcp.mjs",
"dist": "vite build && electron-builder",
"dist:dir": "vite build && electron-builder --dir",
"preview": "vite preview",
diff --git a/desktop/scripts/bundle-mcp.mjs b/desktop/scripts/bundle-mcp.mjs
new file mode 100644
index 000000000..ea2b0cffd
--- /dev/null
+++ b/desktop/scripts/bundle-mcp.mjs
@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file bundle-mcp.mjs — bundle the MCP front into one self-contained file the
+ * INSTALLED editor ships (dist-electron/mcp/editor-mcp.mjs, asar-unpacked
+ * so plain node can run it). This is how any MCP client reaches an
+ * installed Estella: `node <resources>/app.asar.unpacked/dist-electron/
+ * mcp/editor-mcp.mjs --editor`. The editor stays the single distribution
+ * channel — no npm package to keep in sync.
+ */
+import { build } from 'esbuild';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+await build({
+ entryPoints: [path.join(HERE, 'editor-mcp.mjs')],
+ outfile: path.join(HERE, '..', 'dist-electron', 'mcp', 'editor-mcp.mjs'),
+ bundle: true,
+ platform: 'node',
+ format: 'esm',
+ // Only the dev repo resolves electron (lazy createRequire); the installed
+ // flow spawns the editor exe instead, so leave the specifier external.
+ external: ['electron'],
+ // CJS deps inside the ESM bundle may call require() at runtime.
+ banner: {
+ js: "import { createRequire as __bundleRequire } from 'node:module'; const require = __bundleRequire(import.meta.url);",
+ },
+ logLevel: 'warning',
+});
+console.log('[bundle-mcp] dist-electron/mcp/editor-mcp.mjs written');
diff --git a/desktop/scripts/editor-mcp-editor-e2e.mjs b/desktop/scripts/editor-mcp-editor-e2e.mjs
index dadef79e5..26d29dbbf 100644
--- a/desktop/scripts/editor-mcp-editor-e2e.mjs
+++ b/desktop/scripts/editor-mcp-editor-e2e.mjs
@@ -28,7 +28,10 @@ await cp(EXAMPLE, project, {
filter: (src) => !/[/\\](\.esengine|node_modules|dist)([/\\]|$)/.test(src),
});
-const child = spawn(process.execPath, ['scripts/editor-mcp.mjs', '--editor'], {
+// ESTELLA_E2E_FRONT points at an alternate front (e.g. the shipped bundle,
+// dist-electron/mcp/editor-mcp.mjs) to prove distribution artifacts end to end.
+const front = process.env.ESTELLA_E2E_FRONT ?? 'scripts/editor-mcp.mjs';
+const child = spawn(process.execPath, [front, '--editor'], {
cwd: DESKTOP,
stdio: ['pipe', 'pipe', 'pipe'],
env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },
diff --git a/desktop/scripts/editor-mcp.mjs b/desktop/scripts/editor-mcp.mjs
index 82bfcb633..70c9f2ca1 100644
--- a/desktop/scripts/editor-mcp.mjs
+++ b/desktop/scripts/editor-mcp.mjs
@@ -7,9 +7,13 @@
* host and serves the MCP tool registry (editor-mcp-tools.mjs) over stdio,
* forwarding each call to the host's loopback /exec endpoint. Three host modes:
*
- * (default) spawn the headless render host (fixtures; scene tools only)
+ * (default) spawn the headless render host (fixtures; scene tools only;
+ * dev repo only)
* --editor spawn the REAL editor app with --mcp — the full game-making
- * surface: projects, assets, entity templates, play, export
+ * surface: projects, assets, entity templates, play, export.
+ * In the dev repo this is `electron .`; from the installed
+ * editor (this file ships bundled under app.asar.unpacked)
+ * the exe is auto-detected, or pass --editor-exe <path>.
* --attach <file> connect to an already-running editor's endpoint via its
* discovery file (<userData>/mcp-endpoint.json) — drive the
* editor the user is looking at
@@ -24,7 +28,7 @@
*/
import { spawn } from 'node:child_process';
import { randomBytes } from 'node:crypto';
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
import path from 'node:path';
import { createRequire } from 'node:module';
import { fileURLToPath } from 'node:url';
@@ -39,22 +43,63 @@ import {
import { TOOLS, RESOURCES, listTools, runTool } from './editor-mcp-tools.mjs';
const HERE = path.dirname(fileURLToPath(import.meta.url));
-const DESKTOP = path.resolve(HERE, '..');
+// The desktop package root, for dev spawns (`electron .`). This file runs from
+// scripts/ in the repo but from dist-electron/mcp/ as the shipped bundle, so
+// walk up to the nearest package.json instead of assuming one level.
+const DESKTOP = (() => {
+ let dir = HERE;
+ for (let i = 0; i < 4; i++) {
+ dir = path.dirname(dir);
+ if (existsSync(path.join(dir, 'package.json'))) return dir;
+ }
+ return path.resolve(HERE, '..');
+})();
const ALLOW_WRITES = process.env.ESTELLA_MCP_ALLOW_WRITES === '1';
const log = (...a) => process.stderr.write(`[editor-mcp] ${a.join(' ')}\n`);
const argv = process.argv.slice(2);
-const MODE = argv.includes('--editor') ? 'editor' : argv.includes('--attach') ? 'attach' : 'headless';
+const MODE = argv.includes('--editor') || argv.includes('--editor-exe')
+ ? 'editor'
+ : argv.includes('--attach') ? 'attach' : 'headless';
+// When this file ships inside the installed editor it lives under
+// resources/app.asar.unpacked/dist-electron/mcp/ — four levels below the install
+// root (three on macOS, where the exe sits in Contents/MacOS instead).
+const PACKAGED = /app\.asar\.unpacked/.test(HERE);
+
+const argValue = (flag) => {
+ const i = argv.indexOf(flag);
+ const v = i >= 0 ? argv[i + 1] : undefined;
+ return v && !v.startsWith('--') ? v : undefined;
+};
+
+/** The installed editor executable, derived from this bundle's unpacked path. */
+function installedEditorExe() {
+ const resources = path.resolve(HERE, '..', '..', '..'); // …/resources
+ if (process.platform === 'darwin') return path.resolve(resources, '..', 'MacOS', 'Estella Editor');
+ return path.resolve(resources, '..', process.platform === 'win32' ? 'estella-editor.exe' : 'estella-editor');
+}
-/** Spawn an Electron host (headless fixtures or the real editor app with --mcp)
+/** Spawn an Estella host (headless fixtures, dev editor, or installed editor)
* and resolve its /exec endpoint from the MCP_HOST_READY stdout line. */
function spawnHost(mode, token) {
- // Under plain node the electron package's export IS the binary path — works on
- // every platform (the .bin/ shim is a sh script Windows cannot spawn).
- const electron = createRequire(import.meta.url)('electron');
- const args = mode === 'editor' ? ['.', '--mcp'] : [path.join(HERE, 'editor-mcp-host.mjs')];
- const host = spawn(electron, args, {
- cwd: DESKTOP,
+ const editorExe = argValue('--editor-exe') ?? (PACKAGED && mode === 'editor' ? installedEditorExe() : undefined);
+ let command;
+ let args;
+ if (editorExe) {
+ command = editorExe;
+ args = ['--mcp'];
+ } else if (PACKAGED) {
+ log('FATAL: the headless host is dev-repo only — use --editor (or --attach) with the installed editor');
+ process.exit(1);
+ } else {
+ // Under plain node the electron package's export IS the binary path — works on
+ // every platform (the .bin/ shim is a sh script Windows cannot spawn).
+ command = createRequire(import.meta.url)('electron');
+ args = mode === 'editor' ? ['.', '--mcp'] : [path.join(HERE, 'editor-mcp-host.mjs')];
+ }
+ const host = spawn(command, args, {
+ // An installed exe needs no cwd (and the repo layout may not exist there).
+ cwd: editorExe ? undefined : DESKTOP,
stdio: ['ignore', 'pipe', 'pipe'],
env: {
...process.env,
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 02476fcf5..68ae81fb4 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -109,6 +109,7 @@ export default defineConfig({
{ label: 'Building & Exporting', translations: { 'zh-CN': '构建与导出' }, slug: 'guides/build-export' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
{ label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },
+ { label: 'AI Agents (MCP)', translations: { 'zh-CN': 'AI 代理 (MCP)' }, slug: 'guides/mcp' },
],
},
{
diff --git a/docs/astro/src/content/docs/guides/mcp.mdx b/docs/astro/src/content/docs/guides/mcp.mdx
new file mode 100644
index 000000000..d3a6f8142
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/mcp.mdx
@@ -0,0 +1,107 @@
+---
+title: AI Agents (MCP)
+description: The Estella editor is an MCP server — connect Claude Code, Cursor, or any MCP-capable AI tool and let it open projects, build scenes, edit components, run play mode, take screenshots, and export builds.
+---
+
+import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The Estella editor speaks the **Model Context Protocol (MCP)**. Any MCP-capable AI
+tool — Claude Code, Cursor, or your own agent — can drive the real editor: open or
+create projects, open scenes, spawn entities from the same Create-menu catalog you
+use, edit component fields, verify the result in the live engine World, enter play
+mode, take screenshots to *see* what it built, and export the finished game — the
+exact pipelines the UI uses, forty tools in all.
+
+<Aside type="tip">
+Everything an agent does goes through the editor's own command surface — creates
+are undoable, play mode never dirties the edit scene, and saves are the toolbar
+Save. You can watch it work in the editor window, and take over at any time.
+</Aside>
+
+## Connecting an AI tool
+
+The MCP server is a small node script that ships inside the editor. It talks MCP
+over stdio to your AI tool and drives an editor instance for you (spawning one, or
+attaching to one that's already open).
+
+Its path inside an installed editor:
+
+- **Windows** — `%LOCALAPPDATA%\Programs\@estellaeditor\resources\app.asar.unpacked\dist-electron\mcp\editor-mcp.mjs`
+- **macOS** — `/Applications/Estella Editor.app/Contents/Resources/app.asar.unpacked/dist-electron/mcp/editor-mcp.mjs`
+
+<Tabs>
+<TabItem label="Claude Code">
+
+```sh
+claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \
+ node "<path-to>/editor-mcp.mjs" --editor
+```
+
+</TabItem>
+<TabItem label="Any MCP client">
+
+```json
+{
+ "mcpServers": {
+ "estella": {
+ "command": "node",
+ "args": ["<path-to>/editor-mcp.mjs", "--editor"],
+ "env": { "ESTELLA_MCP_ALLOW_WRITES": "1" }
+ }
+ }
+}
+```
+
+</TabItem>
+</Tabs>
+
+`--editor` launches the installed editor with the MCP endpoint enabled. Node.js 20+
+must be on your PATH.
+
+<Aside type="caution">
+Without `ESTELLA_MCP_ALLOW_WRITES=1` the agent can only **observe** — every
+mutating tool (creating entities, editing fields, saving, exporting) is hidden and
+refused. Grant writes deliberately.
+</Aside>
+
+## Driving the editor you're looking at
+
+To let an agent work inside an editor session you already have open, start the
+editor with the endpoint enabled and point the server at its discovery file:
+
+<Steps>
+
+1. Launch the editor with `--mcp` (from a terminal: `estella-editor --mcp`). It
+ writes a discovery file `mcp-endpoint.json` into the editor's user-data folder
+ (Windows: `%APPDATA%\Estella Editor\`; the exact path is printed on startup).
+
+2. Configure your AI tool with `--attach` instead of `--editor`:
+
+ ```json
+ "args": ["<path-to>/editor-mcp.mjs", "--attach", "<path-to>/mcp-endpoint.json"]
+ ```
+
+3. The agent now drives the same window you see — selections, edits, play mode and
+ all — while you watch and intervene.
+
+</Steps>
+
+## What the agent can do
+
+| Area | Tools (excerpt) |
+| --- | --- |
+| Observe | `get_scene_tree`, `get_inspector`, `get_stats`, `capture_viewport` (PNG), `screenshot` (whole window, includes play), `world_component` (live-World probe) |
+| Edit scenes | `create_entity` (the Create-menu catalog via `list_entity_templates`), `set_field`, `set_entity_xy`, `set_parent`, `duplicate_entity`, `undo` / `redo` |
+| Projects & assets | `create_project` / `open_project`, `open_scene`, `save_scene`, `create_scene_file`, `create_asset`, `import_assets` |
+| Run & ship | `toggle_play` + `get_play_state`, `export_game` (web / desktop / wechat / playable) |
+
+A typical agent loop: `open_project` → `open_scene` → `list_entity_templates` →
+`create_entity` → `set_field` → `screenshot` to check its work → `save_scene` →
+`toggle_play` → `screenshot` again → `export_game`.
+
+## From the repository (contributors)
+
+In a source checkout, `pnpm --filter @estella/editor editor:mcp` serves the same
+registry against a headless fixtures host (scene tools only), `editor:mcp -- --editor`
+boots the dev editor, and two e2e suites (`editor:mcp:e2e`,
+`editor:mcp:editor-e2e`) prove the full loop.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx b/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx
new file mode 100644
index 000000000..7cb71e022
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx
@@ -0,0 +1,101 @@
+---
+title: AI 代理 (MCP)
+description: Estella 编辑器本身就是一个 MCP 服务器——接入 Claude Code、Cursor 或任何支持 MCP 的 AI 工具,让它打开项目、搭建场景、编辑组件、运行 Play 模式、截图验证并导出成品。
+---
+
+import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';
+
+Estella 编辑器支持 **Model Context Protocol (MCP)**。任何支持 MCP 的 AI 工具——
+Claude Code、Cursor,或你自己写的代理——都能驱动真实的编辑器:打开或创建项目、
+打开场景、用与你相同的"创建"菜单目录生成实体、编辑组件字段、在活的引擎 World
+里验证结果、进入 Play 模式、截图*亲眼看到*它搭出来的东西,并把成品游戏导出
+——走的都是 UI 自己的管线,共 40 个工具。
+
+<Aside type="tip">
+代理做的每件事都经过编辑器自己的命令面——创建可撤销、Play 模式不会弄脏编辑
+场景、保存就是工具栏的保存。你可以在编辑器窗口里看着它干活,随时接手。
+</Aside>
+
+## 接入 AI 工具
+
+MCP 服务器是随编辑器一起分发的一个小 node 脚本。它对你的 AI 工具讲 stdio MCP,
+并为你驱动一个编辑器实例(拉起新的,或挂到已打开的那个上)。
+
+它在安装版编辑器里的路径:
+
+- **Windows** — `%LOCALAPPDATA%\Programs\@estellaeditor\resources\app.asar.unpacked\dist-electron\mcp\editor-mcp.mjs`
+- **macOS** — `/Applications/Estella Editor.app/Contents/Resources/app.asar.unpacked/dist-electron/mcp/editor-mcp.mjs`
+
+<Tabs>
+<TabItem label="Claude Code">
+
+```sh
+claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \
+ node "<path-to>/editor-mcp.mjs" --editor
+```
+
+</TabItem>
+<TabItem label="任意 MCP 客户端">
+
+```json
+{
+ "mcpServers": {
+ "estella": {
+ "command": "node",
+ "args": ["<path-to>/editor-mcp.mjs", "--editor"],
+ "env": { "ESTELLA_MCP_ALLOW_WRITES": "1" }
+ }
+ }
+}
+```
+
+</TabItem>
+</Tabs>
+
+`--editor` 会以启用 MCP 端点的方式启动安装版编辑器。PATH 里需要 Node.js 20+。
+
+<Aside type="caution">
+不设 `ESTELLA_MCP_ALLOW_WRITES=1` 时代理只能**观察**——所有会产生修改的工具
+(创建实体、改字段、保存、导出)都被隐藏并拒绝。写权限请有意识地授予。
+</Aside>
+
+## 驱动你正看着的编辑器
+
+想让代理在你已经打开的编辑器会话里干活:以启用端点的方式启动编辑器,把服务器
+指向它的发现文件即可:
+
+<Steps>
+
+1. 用 `--mcp` 启动编辑器(终端里:`estella-editor --mcp`)。它会在编辑器的
+ user-data 目录写一个发现文件 `mcp-endpoint.json`(Windows:
+ `%APPDATA%\Estella Editor\`;确切路径启动时会打印出来)。
+
+2. AI 工具的配置里用 `--attach` 代替 `--editor`:
+
+ ```json
+ "args": ["<path-to>/editor-mcp.mjs", "--attach", "<path-to>/mcp-endpoint.json"]
+ ```
+
+3. 代理现在驱动的就是你眼前的这个窗口——选择、编辑、Play 全部同步——你可以
+ 一边看一边随时介入。
+
+</Steps>
+
+## 代理能做什么
+
+| 领域 | 工具(节选) |
+| --- | --- |
+| 观察 | `get_scene_tree`、`get_inspector`、`get_stats`、`capture_viewport`(PNG)、`screenshot`(整窗截图,含 Play 画面)、`world_component`(活 World 探针) |
+| 编辑场景 | `create_entity`(配合 `list_entity_templates` 的创建目录)、`set_field`、`set_entity_xy`、`set_parent`、`duplicate_entity`、`undo` / `redo` |
+| 项目与资产 | `create_project` / `open_project`、`open_scene`、`save_scene`、`create_scene_file`、`create_asset`、`import_assets` |
+| 运行与发布 | `toggle_play` + `get_play_state`、`export_game`(web / desktop / wechat / playable) |
+
+典型的代理循环:`open_project` → `open_scene` → `list_entity_templates` →
+`create_entity` → `set_field` → `screenshot` 检查成果 → `save_scene` →
+`toggle_play` → 再次 `screenshot` → `export_game`。
+
+## 从源码仓库使用(贡献者)
+
+源码仓库里,`pnpm --filter @estella/editor editor:mcp` 用无头夹具宿主提供同一套
+注册表(仅场景工具),`editor:mcp -- --editor` 拉起开发版编辑器;两套 e2e
+(`editor:mcp:e2e`、`editor:mcp:editor-e2e`)验证完整闭环。