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): MCP grows the game-making axis - the live editor is a host

yhh2d76bbb6c2fc
diff --git a/desktop/electron/main.ts b/desktop/electron/main.ts
index f19e75997..945c8c2cf 100644
--- a/desktop/electron/main.ts
+++ b/desktop/electron/main.ts
@@ -33,6 +33,7 @@ import { httpContentType } from './mimeTypes';
import { buildPlayRealm } from './buildPlayRealm';
import { syncSdkTypes } from './syncSdkTypes';
import { installCrashCapture, logsDir } from './resilience';
+import { mcpMode, startMcpEndpoint } from './mcpEndpoint';
import { checkForUpdate } from './updateCheck';
import { resolveLayout, resolveScripts } from '../src/project/format';
import type { WorkspaceState } from '../src/project/format';
@@ -353,8 +354,10 @@ function createWindow() {
// Screenshot/visual-regression mode (ESTELLA_SHOT=out.png): open ?automation=1 so
// the renderer hook is live, then drive the launcher→editor flow and capturePage.
+ // MCP mode (--mcp) rides the same renderer hook — the exec endpoint drives
+ // window.__estellaEditor instead of the screenshot flow.
const shotOut = process.env.ESTELLA_SHOT;
- const automation = shotOut ? '?automation=1' : '';
+ const automation = shotOut || mcpMode() ? '?automation=1' : '';
if (VITE_DEV_SERVER_URL) {
win.loadURL(VITE_DEV_SERVER_URL + automation);
@@ -367,6 +370,7 @@ function createWindow() {
}
if (shotOut) void runScreenshot(win, shotOut);
+ if (mcpMode()) void startMcpEndpoint(() => win);
// Unsaved-changes quit guard: prompt before closing a window with a dirty scene.
// `sceneDirty` is pushed from the renderer (app:dirty); `quitting` lets the chosen
diff --git a/desktop/electron/mcpEndpoint.ts b/desktop/electron/mcpEndpoint.ts
new file mode 100644
index 000000000..77af6a6f9
--- /dev/null
+++ b/desktop/electron/mcpEndpoint.ts
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file mcpEndpoint.ts — the live editor's MCP exec endpoint (`--mcp` mode).
+ *
+ * Starts the shared loopback /exec seam against the REAL editor window, so the
+ * MCP front (scripts/editor-mcp.mjs --editor / --attach) can drive the full app:
+ * scene calls resolve on `window.__estellaEditor.surface` (the same
+ * EditorControlSurface the UI uses), editor-level calls (project open, scenes,
+ * play, entity templates) on `window.__estellaEditor`, renderer-code snippets run
+ * verbatim, and `op: screenshot` captures the composited window main-side — the
+ * only way to see into the play realm's OOPIF.
+ *
+ * The token comes from the spawning front (ESTELLA_MCP_TOKEN) or is generated for
+ * a user-launched editor; either way the endpoint is advertised in a discovery
+ * file under userData (mcp-endpoint.json) that `--attach` reads, and a
+ * `MCP_HOST_READY {"port":N}` line on stdout for the spawn flow.
+ */
+import { app, BrowserWindow } from 'electron';
+import { randomBytes } from 'node:crypto';
+import { writeFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+// Plain .mjs, shared with the headless host (scripts/editor-mcp-host.mjs) —
+// esbuild bundles it into the main bundle.
+// @ts-expect-error untyped shared module
+import { createExecEndpoint } from '../scripts/mcp-exec-endpoint.mjs';
+
+const log = (...a: unknown[]) => process.stderr.write(`[editor-mcp-endpoint] ${a.join(' ')}\n`);
+
+/** True when this editor process should expose the MCP exec endpoint. */
+export function mcpMode(): boolean {
+ return process.argv.includes('--mcp') || process.env.ESTELLA_MCP === '1';
+}
+
+/**
+ * Start the endpoint against the editor window. `getWin` re-resolves per call so
+ * a recreated window keeps working. Idempotent-ish: call once after the first
+ * window exists.
+ */
+export async function startMcpEndpoint(getWin: () => BrowserWindow | null): Promise<void> {
+ const token = process.env.ESTELLA_MCP_TOKEN || randomBytes(24).toString('hex');
+
+ const exec = async (code: string) => {
+ const win = getWin();
+ if (!win) throw new Error('no editor window');
+ // A call can arrive before the renderer finished booting (the endpoint comes
+ // up with the window) — wait out the initial load instead of failing it.
+ if (win.webContents.isLoading()) {
+ await new Promise<void>((resolve) => win.webContents.once('did-finish-load', () => resolve()));
+ }
+ return win.webContents.executeJavaScript(code, true);
+ };
+
+ const server = await createExecEndpoint({
+ token,
+ run: async ({ method, args, root, js, op }: {
+ method?: string; args?: unknown[]; root?: string; js?: string; op?: string;
+ }) => {
+ if (op === 'screenshot') {
+ const win = getWin();
+ if (!win) throw new Error('no editor window');
+ const image = await win.webContents.capturePage();
+ return image.toPNG().toString('base64');
+ }
+ if (js) return exec(js);
+ const target = root === 'editor' ? 'window.__estellaEditor' : 'window.__estellaEditor.surface';
+ return exec(`${target}.${method}(${(args ?? [])
+ .map((a) => (a === undefined ? 'undefined' : JSON.stringify(a)))
+ .join(',')})`);
+ },
+ });
+
+ const port = (server.address() as { port: number }).port;
+
+ // Advertise for --attach; the token in the file is what authorizes a local
+ // client, so the file lives in userData (per-user, not world-readable temp).
+ const discovery = path.join(app.getPath('userData'), 'mcp-endpoint.json');
+ try {
+ writeFileSync(discovery, JSON.stringify({ port, token, pid: process.pid }) + '\n');
+ app.on('will-quit', () => { try { rmSync(discovery); } catch { /* already gone */ } });
+ } catch (e) {
+ log('could not write discovery file:', String(e));
+ }
+
+ // The spawn flow (editor-mcp.mjs --editor) reads this exact line.
+ process.stdout.write(`MCP_HOST_READY ${JSON.stringify({ port })}\n`);
+ log(`exec endpoint on 127.0.0.1:${port} (discovery: ${discovery})`);
+}
diff --git a/desktop/package.json b/desktop/package.json
index 35dcc57a3..59c5471dc 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -20,6 +20,7 @@
"editor:mcp": "node scripts/editor-mcp.mjs",
"editor:mcp:build": "vite build && node scripts/editor-mcp.mjs",
"editor:mcp:e2e": "vite build && node scripts/editor-mcp-e2e.mjs",
+ "editor:mcp:editor-e2e": "vite build && node scripts/editor-mcp-editor-e2e.mjs",
"editor:shot": "vite build && electron .",
"verify:render:spine": "vite build && ESTELLA_VERIFY_SCENE=/scenes/spine-test.esscene ESTELLA_VERIFY_MANIFEST=/scenes/spine-test.textures.json electron scripts/headless-verify.mjs",
"verify:render:particles": "vite build && ESTELLA_VERIFY_PLAY=1 ESTELLA_VERIFY_SCENE=/scenes/particle-demo.esscene ESTELLA_VERIFY_MANIFEST=/scenes/particle-demo.textures.json ESTELLA_VERIFY_STEPS=90 electron scripts/headless-verify.mjs",
diff --git a/desktop/scripts/editor-mcp-editor-e2e.mjs b/desktop/scripts/editor-mcp-editor-e2e.mjs
new file mode 100644
index 000000000..dadef79e5
--- /dev/null
+++ b/desktop/scripts/editor-mcp-editor-e2e.mjs
@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file editor-mcp-editor-e2e.mjs — end-to-end smoke for the EDITOR-host MCP mode.
+ *
+ * Spawns editor-mcp.mjs --editor (the real editor app with --mcp) against a TEMP
+ * COPY of the platformer example and drives the full game-making loop over MCP:
+ * open project → open scene → entity-template catalog → create entity → edit a
+ * field → verify it reached the live World → screenshot → save → play → stop.
+ * Run from desktop/ after a dist build: node scripts/editor-mcp-editor-e2e.mjs
+ * (ESTELLA_E2E_EXPORT=1 additionally runs a web export to the temp dir.)
+ */
+import { spawn } from 'node:child_process';
+import { cp, mkdtemp, rm, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DESKTOP = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'platformer');
+
+// Stage the example as a disposable project (transients filtered like the
+// packaged templates are).
+const tmpRoot = await mkdtemp(path.join(os.tmpdir(), 'estella-mcp-e2e-'));
+const project = path.join(tmpRoot, 'platformer');
+await cp(EXAMPLE, project, {
+ recursive: true,
+ filter: (src) => !/[/\\](\.esengine|node_modules|dist)([/\\]|$)/.test(src),
+});
+
+const child = spawn(process.execPath, ['scripts/editor-mcp.mjs', '--editor'], {
+ cwd: DESKTOP,
+ stdio: ['pipe', 'pipe', 'pipe'],
+ env: { ...process.env, ESTELLA_MCP_ALLOW_WRITES: '1' },
+});
+
+let buf = '';
+const waiters = new Map();
+child.stdout.on('data', (d) => {
+ buf += d.toString();
+ let nl;
+ while ((nl = buf.indexOf('\n')) >= 0) {
+ const line = buf.slice(0, nl).trim();
+ buf = buf.slice(nl + 1);
+ if (!line) continue;
+ let msg;
+ try { msg = JSON.parse(line); } catch { continue; } // skip stray non-JSON stdout
+ if (msg.id != null && waiters.has(msg.id)) { waiters.get(msg.id)(msg); waiters.delete(msg.id); }
+ }
+});
+child.stderr.on('data', (d) => process.stderr.write(d));
+
+const send = (msg) => child.stdin.write(JSON.stringify(msg) + '\n');
+let nextId = 0;
+const rpc = (method, params, timeoutMs = 60_000) => new Promise((resolve, reject) => {
+ const id = ++nextId;
+ const t = setTimeout(() => reject(new Error(`timeout waiting for ${method}`)), timeoutMs);
+ waiters.set(id, (m) => { clearTimeout(t); resolve(m); });
+ send({ jsonrpc: '2.0', id, method, params });
+});
+const call = async (name, args, timeoutMs) => {
+ const res = await rpc('tools/call', { name, arguments: args ?? {} }, timeoutMs);
+ if (res.result?.isError) throw new Error(`${name}: ${res.result?.content?.[0]?.text}`);
+ return res.result?.content?.[0];
+};
+const cleanup = async () => {
+ child.kill();
+ await new Promise((r) => setTimeout(r, 500));
+ await rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+};
+const fail = async (m) => { console.log('EDITOR-E2E FAIL:', m); await cleanup(); process.exit(1); };
+
+try {
+ const init = await rpc('initialize', {
+ protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'editor-e2e', version: '0' },
+ }, 180_000);
+ if (!init.result?.serverInfo) await fail('no serverInfo in initialize');
+ send({ jsonrpc: '2.0', method: 'notifications/initialized' });
+ console.log('initialize OK');
+
+ const list = await rpc('tools/list', {});
+ const names = (list.result?.tools ?? []).map((t) => t.name);
+ for (const need of ['open_project', 'open_scene', 'list_entity_templates', 'create_entity', 'save_scene', 'screenshot', 'export_game'])
+ if (!names.includes(need)) await fail(`tools/list missing ${need}`);
+ console.log(`tools/list OK — ${names.length} tools`);
+
+ await call('open_project', { root: project }, 120_000);
+ console.log('open_project OK');
+
+ await call('open_scene', { path: 'assets/scenes/main.esscene' }, 60_000);
+ // The openScene promise resolves ahead of the model spawn — poll the tree the
+ // way the shot-automation flow does.
+ let tree = [];
+ for (let i = 0; i < 30 && tree.length === 0; i++) {
+ tree = JSON.parse((await call('get_scene_tree')).text) ?? [];
+ if (tree.length === 0) await new Promise((r) => setTimeout(r, 1000));
+ }
+ if (!Array.isArray(tree) || tree.length === 0) await fail('scene tree empty after open_scene');
+ console.log(`open_scene OK — ${tree.length} roots`);
+
+ const templates = JSON.parse((await call('list_entity_templates')).text);
+ if (!templates.some((t) => t.id === 'anchor:Sprite')) await fail('anchor:Sprite missing from entity templates');
+ console.log(`list_entity_templates OK — ${templates.length} templates`);
+
+ const before = JSON.parse((await call('get_stats')).text).entities;
+ const created = Number((await call('create_entity', { template: 'anchor:Sprite', x: 64, y: 96 })).text);
+ const after = JSON.parse((await call('get_stats')).text).entities;
+ if (!Number.isFinite(created) || after <= before) await fail(`create_entity did not spawn (${before} -> ${after})`);
+ console.log(`create_entity OK — id ${created} (${before} -> ${after} entities)`);
+
+ await call('set_field', { entity: created, component: 'Transform', key: 'position', type: 'vec3', value: [64, 96, 0] });
+ const live = JSON.parse((await call('world_component', { id: created, component: 'Transform' })).text);
+ if (!live) await fail('world_component returned null — edit did not reach the World');
+ console.log('set_field + world_component OK — edit reached the live World');
+
+ const shot = await call('screenshot');
+ if (shot.type !== 'image' || (shot.data?.length ?? 0) < 100) await fail('screenshot not a PNG image block');
+ console.log(`screenshot OK — ${shot.data.length} base64 chars`);
+
+ const scenePath = path.join(project, 'assets', 'scenes', 'main.esscene');
+ const mtimeBefore = (await stat(scenePath)).mtimeMs;
+ await call('save_scene', {}, 60_000);
+ const mtimeAfter = (await stat(scenePath)).mtimeMs;
+ if (mtimeAfter <= mtimeBefore) await fail('save_scene did not rewrite the scene file');
+ console.log('save_scene OK — scene file rewritten');
+
+ await call('toggle_play', {}, 60_000);
+ let play = null;
+ for (let i = 0; i < 60; i++) {
+ play = JSON.parse((await call('get_play_state')).text);
+ if (play.ready || play.error) break;
+ await new Promise((r) => setTimeout(r, 1000));
+ }
+ if (!play?.ready) await fail(`play realm never became ready (${JSON.stringify(play)})`);
+ const playShot = await call('screenshot');
+ if (playShot.type !== 'image') await fail('screenshot during play failed');
+ await call('toggle_play', {}, 60_000);
+ console.log('play OK — realm ready, screenshot captured, stopped');
+
+ if (process.env.ESTELLA_E2E_EXPORT === '1') {
+ const outDir = path.join(tmpRoot, 'export-web');
+ const result = JSON.parse((await call('export_game', { platform: 'web', outDir }, 300_000)).text);
+ const index = await stat(path.join(outDir, 'index.html')).catch(() => null);
+ if (!index) await fail(`export_game produced no index.html (${JSON.stringify(result).slice(0, 200)})`);
+ console.log('export_game OK — web export written');
+ }
+
+ console.log('\nEDITOR-E2E PASS — MCP drives the real editor end-to-end (project → scene → entity → save → play)');
+ await cleanup();
+ process.exit(0);
+} catch (e) {
+ await fail(String(e?.message ?? e));
+}
diff --git a/desktop/scripts/editor-mcp-host.mjs b/desktop/scripts/editor-mcp-host.mjs
index d9bb91a3f..09f448442 100644
--- a/desktop/scripts/editor-mcp-host.mjs
+++ b/desktop/scripts/editor-mcp-host.mjs
@@ -22,6 +22,7 @@ import http from 'node:http';
import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { createExecEndpoint } from './mcp-exec-endpoint.mjs';
const DIST = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'dist');
const TOKEN = process.env.ESTELLA_MCP_TOKEN;
@@ -59,13 +60,6 @@ function serveDist() {
return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server)));
}
-const readBody = (req) => new Promise((resolve, reject) => {
- const chunks = [];
- req.on('data', (c) => chunks.push(c));
- req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
- req.on('error', reject);
-});
-
// Keep the process alive on the hidden window (this is a long-running host).
app.on('window-all-closed', () => {});
@@ -84,26 +78,25 @@ app.whenReady().then(async () => {
// The exec endpoint: marshal a surface call ({method, args}) or a renderer-code
// snippet ({js}) into the headless renderer. `undefined` args become the JS
- // `undefined` literal so the surface's default parameters apply.
- const exec = http.createServer(async (req, res) => {
- const reply = (code, body) => {
- res.writeHead(code, { 'content-type': 'application/json' });
- res.end(JSON.stringify(body));
- };
- if (req.method !== 'POST' || req.url !== '/exec') return reply(404, { ok: false, error: 'not found' });
- if (req.headers['x-estella-mcp-token'] !== TOKEN) return reply(403, { ok: false, error: 'bad token' });
- try {
- const { method, args, js } = JSON.parse(await readBody(req));
+ // `undefined` literal so the surface's default parameters apply. Editor-only
+ // tools (root: 'editor' — project/asset/play operations) have no meaning in a
+ // fixtures host; fail them with the pointer to the right host.
+ const exec = await createExecEndpoint({
+ token: TOKEN,
+ run: async ({ method, args, root, js, op }) => {
+ if (op === 'screenshot') {
+ const image = await win.webContents.capturePage();
+ return image.toPNG().toString('base64');
+ }
+ if (root === 'editor') {
+ throw new Error(`${method} needs the live editor host — connect through editor-mcp.mjs --editor (or --attach)`);
+ }
const code = js ?? `window.__estellaHeadless.api.${method}(${(args ?? [])
.map((a) => (a === undefined ? 'undefined' : JSON.stringify(a)))
.join(',')})`;
- const result = await win.webContents.executeJavaScript(code, true);
- reply(200, { ok: true, hasResult: result !== undefined, result: result === undefined ? null : result });
- } catch (e) {
- reply(200, { ok: false, error: String((e && e.message) || e) });
- }
+ return win.webContents.executeJavaScript(code, true);
+ },
});
- await new Promise((resolve) => exec.listen(0, '127.0.0.1', resolve));
// The front reads this line to learn the port; everything else goes to stderr.
process.stdout.write(`MCP_HOST_READY ${JSON.stringify({ port: exec.address().port })}\n`);
diff --git a/desktop/scripts/editor-mcp-tools.mjs b/desktop/scripts/editor-mcp-tools.mjs
index f4592c359..ee166f324 100644
--- a/desktop/scripts/editor-mcp-tools.mjs
+++ b/desktop/scripts/editor-mcp-tools.mjs
@@ -11,22 +11,28 @@
* entry (editor-mcp.mjs) supplies the executeJavaScript driver and the
* MCP SDK wiring. See docs/REARCH_EDITOR_ARCH.md §11.
*
- * Two tool shapes:
- * - method tools: `{ method, args(input) }` → driver(method, args) — a surface call.
+ * Tool shapes:
+ * - method tools: `{ method, args(input) }` → driver(method, args, root) — a
+ * surface call; `root: 'editor'` targets `window.__estellaEditor` (project /
+ * asset / play doors of the LIVE editor host) instead of the scene surface.
* - renderer-code tools: `{ js(input) }` → driver.js(code) — for routines that
- * need the renderer's DOM (canvas PNG encode); still surface-only underneath.
+ * need the renderer's DOM (canvas PNG encode, window.estella bridge calls).
+ * - main-process ops: `{ op }` → driver.op(op) — host-side routines like the
+ * composited-window screenshot (the only way to see the play realm's OOPIF).
*
- * Mutating tools carry `write: true` and are hidden + refused unless the host
- * enables writes (ESTELLA_MCP_ALLOW_WRITES=1) — an agent can observe by default
- * but cannot silently rewrite a scene.
+ * Editor-host tools fail with a pointer when called on the headless fixtures
+ * host. Mutating tools carry `write: true` and are hidden + refused unless the
+ * host enables writes (ESTELLA_MCP_ALLOW_WRITES=1) — an agent can observe by
+ * default but cannot silently rewrite a scene or a project.
*/
const obj = (properties, required = []) => ({ type: 'object', properties, required });
// Render the viewport to a base64 PNG. Runs in the renderer (needs document):
// captureViewport returns bottom-up GL rows, so flip Y into a 2D canvas first.
+// Resolves the surface on either host (headless fixtures / live editor).
const CAPTURE_PNG_JS = `(() => {
- const c = window.__estellaHeadless.api.captureViewport();
+ const c = (window.__estellaHeadless?.api ?? window.__estellaEditor.surface).captureViewport();
const { rgba, width, height } = c;
const cv = document.createElement('canvas'); cv.width = width; cv.height = height;
const ctx = cv.getContext('2d');
@@ -123,6 +129,84 @@ export const TOOLS = [
schema: obj({}), method: 'getSubsystems', args: () => [] },
{ name: 'undo', write: true, description: 'Undo the last edit.', schema: obj({}), method: 'undo', args: () => [] },
{ name: 'redo', write: true, description: 'Redo the last undone edit.', schema: obj({}), method: 'redo', args: () => [] },
+
+ // — Editor-host tools (root: 'editor'): the project/asset/play doors of the LIVE
+ // editor app. On the headless fixtures host these fail with a pointer to
+ // `editor-mcp.mjs --editor`. —
+ { name: 'list_project_templates',
+ description: 'New-project templates the editor ships (blank starter + sample projects). Use a returned dir with create_project.',
+ schema: obj({}), js: () => `window.estella.templates.list()` },
+ { name: 'create_project', write: true,
+ description: 'Create a new project from a template directory (see list_project_templates) at <location>/<name>; returns the new project root. Follow with open_project.',
+ schema: obj({ templateDir: { type: 'string' }, location: { type: 'string' }, name: { type: 'string' } },
+ ['templateDir', 'location', 'name']),
+ js: (i) => `window.estella.project.createFromTemplate(${JSON.stringify(i.templateDir)}, ${JSON.stringify(i.location)}, ${JSON.stringify(i.name)})` },
+ { name: 'open_project',
+ description: 'Open a project by absolute root path and enter the editor. Call before any scene/asset work on the editor host.',
+ schema: obj({ root: { type: 'string' } }, ['root']),
+ js: (i) => `window.__estellaEditor.open(${JSON.stringify(i.root)}).then((ok) => { window.__estellaEditor.enterEditor(); return ok; })` },
+ { name: 'open_scene',
+ description: 'Open a scene by project-relative path (e.g. assets/scenes/main.esscene) in the editor.',
+ schema: obj({ path: { type: 'string' } }, ['path']),
+ method: 'openScene', args: (i) => [i.path], root: 'editor' },
+ { name: 'save_scene', write: true,
+ description: 'Save the open scene to disk (the toolbar Save).',
+ schema: obj({}), method: 'save', args: () => [], root: 'editor' },
+ { name: 'create_scene_file', write: true,
+ description: 'Create a blank scene FILE under a project-relative directory (does not switch to it); returns its path.',
+ schema: obj({ destDir: { type: 'string' } }, ['destDir']),
+ method: 'createSceneFile', args: (i) => [i.destDir], root: 'editor' },
+ { name: 'create_asset', write: true,
+ description: 'Create a text asset file under a project-relative directory with the given content (types the editor knows: scene, inputmap, locale, fsm, bt, timeline, animclip, tileset, material, shader, prefab...). Returns its project-relative path.',
+ schema: obj({
+ destDir: { type: 'string' }, baseName: { type: 'string' },
+ content: { type: 'string' }, type: { type: 'string' },
+ }, ['destDir', 'baseName', 'content', 'type']),
+ js: (i) => `window.estella.project.createAsset(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.baseName)}, ${JSON.stringify(i.content)}, ${JSON.stringify(i.type)})` },
+ { name: 'import_assets', write: true,
+ description: 'Import external files (absolute paths: textures, audio, fonts, spine, tilemaps...) into a project-relative directory. Returns { imported, skipped }.',
+ schema: obj({ destDir: { type: 'string' }, sources: { type: 'object', description: 'array of absolute file paths' } },
+ ['destDir', 'sources']),
+ js: (i) => `window.estella.project.importFiles(${JSON.stringify(i.destDir)}, ${JSON.stringify(i.sources)})` },
+ { name: 'list_entity_templates',
+ description: "The Create-popover catalog: every ready-made entity the editor can spawn (id, label, category). Use an id with create_entity.",
+ schema: obj({}), method: 'listEntityTemplates', args: () => [], root: 'editor' },
+ { name: 'create_entity', write: true,
+ description: 'Spawn a ready-made entity from a template id (see list_entity_templates) through the same pipeline as the Create menu; returns the new entity id. Optional world position and parent.',
+ schema: obj({
+ template: { type: 'string' }, parent: { type: ['number', 'null'] },
+ x: { type: 'number' }, y: { type: 'number' },
+ }, ['template']),
+ method: 'createEntity',
+ args: (i) => [i.template, { parent: i.parent ?? null, x: i.x, y: i.y }], root: 'editor' },
+ { name: 'toggle_play',
+ description: 'Toggle play mode in the editor (check get_play_state first; play runs the game in an isolated realm and never dirties the edit scene).',
+ schema: obj({}), method: 'play', args: () => [], root: 'editor' },
+ { name: 'get_play_state',
+ description: 'The play realm state: { playing, ready, error }.',
+ schema: obj({}), method: 'playState', args: () => [], root: 'editor' },
+ { name: 'screenshot',
+ description: 'Capture the composited editor window as a PNG (includes the play realm iframe — use this to SEE gameplay; capture_viewport only sees the edit viewport).',
+ schema: obj({}), op: 'screenshot', image: true },
+ { name: 'world_component',
+ description: "A LIVE World component's data for a source entity, resolved by component name — verifies an edit actually reached the engine.",
+ schema: obj({ id: { type: 'number' }, component: { type: 'string' } }, ['id', 'component']),
+ method: 'worldComp', args: (i) => [i.id, i.component], root: 'editor' },
+ { name: 'run_editor_command', write: true,
+ description: 'Dispatch any registered editor command by id (the UI\'s own channel) — the escape hatch for operations without a dedicated tool.',
+ schema: obj({ id: { type: 'string' } }, ['id']),
+ method: 'runCommand', args: (i) => [i.id], root: 'editor' },
+ { name: 'export_game', write: true,
+ description: 'Build + export the open project. platform: web | desktop | wechat | playable. Returns the export result (outDir, files...).',
+ schema: obj({
+ platform: { type: 'string' }, outDir: { type: 'string' },
+ minify: { type: 'boolean' }, compressTextures: { type: 'boolean' },
+ compressAudio: { type: 'boolean' }, atlasTextures: { type: 'boolean' },
+ }, ['platform']),
+ js: (i) => `window.estella.project.exportGame(${JSON.stringify({
+ platform: i.platform, outDir: i.outDir, minify: i.minify,
+ compressTextures: i.compressTextures, compressAudio: i.compressAudio, atlasTextures: i.atlasTextures,
+ })})` },
];
/** MCP resources — read-only surface views an MCP client can subscribe to. */
@@ -164,9 +248,10 @@ function validate(schema, raw) {
/**
* Validate `rawInput`, invoke the surface via the driver, and wrap the result as
- * an MCP CallToolResult. Method tools call `driver(method, args)`; renderer-code
- * tools call `driver.js(code)`. A gated write without permission, a validation
- * failure, or a driver throw becomes an `isError` result rather than a crash.
+ * an MCP CallToolResult. Method tools call `driver(method, args, root)`;
+ * renderer-code tools call `driver.js(code)`; main-process ops call
+ * `driver.op(op)`. A gated write without permission, a validation failure, or a
+ * driver throw becomes an `isError` result rather than a crash.
*/
export async function runTool(tool, driver, rawInput, allowWrites = true) {
try {
@@ -174,13 +259,18 @@ export async function runTool(tool, driver, rawInput, allowWrites = true) {
throw new Error(`tool ${tool.name} mutates the scene — start the server with ESTELLA_MCP_ALLOW_WRITES=1`);
}
const input = validate(tool.schema, rawInput);
- if (tool.js) {
- const data = await driver.js(tool.js(input));
+ if (tool.op) {
+ const data = await driver.op(tool.op, input);
return tool.image
? { content: [{ type: 'image', data, mimeType: 'image/png' }] }
: { content: [{ type: 'text', text: String(data) }] };
}
- const result = await driver(tool.method, tool.args(input));
+ if (tool.js) {
+ const data = await driver.js(tool.js(input));
+ if (tool.image) return { content: [{ type: 'image', data, mimeType: 'image/png' }] };
+ return { content: [{ type: 'text', text: data === undefined ? 'ok' : JSON.stringify(data) }] };
+ }
+ const result = await driver(tool.method, tool.args(input), tool.root);
return { content: [{ type: 'text', text: result === undefined ? 'ok' : JSON.stringify(result) }] };
} catch (err) {
return { content: [{ type: 'text', text: `error: ${err?.message ?? String(err)}` }], isError: true };
diff --git a/desktop/scripts/editor-mcp.mjs b/desktop/scripts/editor-mcp.mjs
index be88fe570..82bfcb633 100644
--- a/desktop/scripts/editor-mcp.mjs
+++ b/desktop/scripts/editor-mcp.mjs
@@ -3,10 +3,16 @@
/**
* @file editor-mcp.mjs — the editor MCP server (stdio front, plain node).
*
- * An MCP client (an AI agent) spawns this with node; it spawns the Electron half
- * (editor-mcp-host.mjs — the proven headless render host publishing
- * EditorControlSurface) and serves the MCP tool registry (editor-mcp-tools.mjs)
- * over stdio, forwarding each call to the host's loopback /exec endpoint.
+ * An MCP client (an AI agent) spawns this with node; it stands up an Estella
+ * 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)
+ * --editor spawn the REAL editor app with --mcp — the full game-making
+ * surface: projects, assets, entity templates, play, export
+ * --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
*
* Split on purpose: an Electron main process never receives piped stdin on
* Windows, so the MCP protocol must live in a plain-node process. The surface
@@ -18,6 +24,7 @@
*/
import { spawn } from 'node:child_process';
import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
import path from 'node:path';
import { createRequire } from 'node:module';
import { fileURLToPath } from 'node:url';
@@ -32,49 +39,76 @@ import {
import { TOOLS, RESOURCES, listTools, runTool } from './editor-mcp-tools.mjs';
const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DESKTOP = path.resolve(HERE, '..');
const ALLOW_WRITES = process.env.ESTELLA_MCP_ALLOW_WRITES === '1';
const log = (...a) => process.stderr.write(`[editor-mcp] ${a.join(' ')}\n`);
-// 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 token = randomBytes(24).toString('hex');
+const argv = process.argv.slice(2);
+const MODE = argv.includes('--editor') ? 'editor' : argv.includes('--attach') ? 'attach' : 'headless';
-const host = spawn(electron, [path.join(HERE, 'editor-mcp-host.mjs')], {
- stdio: ['ignore', 'pipe', 'pipe'],
- env: {
- ...process.env,
- ESTELLA_MCP_TOKEN: token,
- ESTELLA_MCP_PARENT_PID: String(process.pid),
- },
-});
-host.stderr.on('data', (d) => process.stderr.write(d));
-host.on('exit', (code) => {
- log(`host exited (${code}) — shutting down`);
- process.exit(code === 0 ? 0 : 1);
-});
-const killHost = () => { try { host.kill(); } catch { /* already gone */ } };
-process.on('exit', killHost);
-process.stdin.on('close', () => { killHost(); process.exit(0); });
+/** Spawn an Electron host (headless fixtures or the real editor app with --mcp)
+ * 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,
+ stdio: ['ignore', 'pipe', 'pipe'],
+ env: {
+ ...process.env,
+ ESTELLA_MCP_TOKEN: token,
+ ESTELLA_MCP_PARENT_PID: String(process.pid),
+ },
+ });
+ host.stderr.on('data', (d) => process.stderr.write(d));
+ host.on('exit', (code) => {
+ log(`host exited (${code}) — shutting down`);
+ process.exit(code === 0 ? 0 : 1);
+ });
+ const killHost = () => { try { host.kill(); } catch { /* already gone */ } };
+ process.on('exit', killHost);
-// Wait for the host's readiness line to learn the /exec port.
-const port = await new Promise((resolve, reject) => {
- let buf = '';
- const timer = setTimeout(() => reject(new Error('host did not become ready in 120s')), 120_000);
- host.stdout.on('data', (d) => {
- buf += d.toString();
- const m = /^MCP_HOST_READY (\{.*\})$/m.exec(buf);
- if (m) {
- clearTimeout(timer);
- resolve(JSON.parse(m[1]).port);
- }
+ return new Promise((resolve, reject) => {
+ let buf = '';
+ const timer = setTimeout(() => reject(new Error('host did not become ready in 120s')), 120_000);
+ host.stdout.on('data', (d) => {
+ buf += d.toString();
+ const m = /^MCP_HOST_READY (\{.*\})$/m.exec(buf);
+ if (m) {
+ clearTimeout(timer);
+ resolve(JSON.parse(m[1]).port);
+ }
+ });
});
-}).catch((e) => {
- log('FATAL', e.message);
- killHost();
- process.exit(1);
-});
-log(`host ready on 127.0.0.1:${port} (writes ${ALLOW_WRITES ? 'ENABLED' : 'disabled'})`);
+}
+
+let port;
+let token;
+if (MODE === 'attach') {
+ // Connect to a running editor via its discovery file (written in --mcp mode).
+ const fileArg = argv[argv.indexOf('--attach') + 1];
+ const discovery = fileArg && !fileArg.startsWith('--') ? fileArg : process.env.ESTELLA_MCP_DISCOVERY;
+ if (!discovery) {
+ log('FATAL: --attach needs the discovery file path (<userData>/mcp-endpoint.json) or ESTELLA_MCP_DISCOVERY');
+ process.exit(1);
+ }
+ try {
+ ({ port, token } = JSON.parse(readFileSync(discovery, 'utf8')));
+ } catch (e) {
+ log(`FATAL: cannot read discovery file ${discovery}: ${e.message}`);
+ process.exit(1);
+ }
+} else {
+ token = randomBytes(24).toString('hex');
+ port = await spawnHost(MODE, token).catch((e) => {
+ log('FATAL', e.message);
+ process.exit(1);
+ });
+}
+process.stdin.on('close', () => process.exit(0));
+log(`${MODE} host ready on 127.0.0.1:${port} (writes ${ALLOW_WRITES ? 'ENABLED' : 'disabled'})`);
async function post(body) {
const res = await fetch(`http://127.0.0.1:${port}/exec`, {
@@ -87,9 +121,11 @@ async function post(body) {
return out.hasResult ? out.result : undefined;
}
-// The registry's driver: surface method calls + renderer-code snippets.
-const driver = (method, args) => post({ method, args });
+// The registry's driver: surface/editor method calls, renderer-code snippets,
+// and main-process ops.
+const driver = (method, args, root) => post({ method, args, root });
driver.js = (js) => post({ js });
+driver.op = (op, input) => post({ op, ...input });
const mcp = new Server(
{ name: 'estella-editor', version: '0.2.0' },
diff --git a/desktop/scripts/mcp-exec-endpoint.mjs b/desktop/scripts/mcp-exec-endpoint.mjs
new file mode 100644
index 000000000..617afd305
--- /dev/null
+++ b/desktop/scripts/mcp-exec-endpoint.mjs
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file mcp-exec-endpoint.mjs — the loopback /exec seam every MCP host shares.
+ *
+ * One tiny HTTP server on 127.0.0.1: POST /exec with the host token executes one
+ * marshalled call and returns `{ ok, hasResult, result }` (or `{ ok:false, error }`).
+ * The MCP protocol layer lives in the plain-node front (editor-mcp.mjs); hosts —
+ * the headless render host and the live editor app — differ only in how they
+ * resolve a payload to a result, which they supply as `run(payload)`.
+ *
+ * Plain .mjs so both host flavors can use it: the headless host imports it
+ * directly, the editor main process bundles it through esbuild.
+ */
+import http from 'node:http';
+
+const readBody = (req) => new Promise((resolve, reject) => {
+ const chunks = [];
+ req.on('data', (c) => chunks.push(c));
+ req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+ req.on('error', reject);
+});
+
+/**
+ * Start the endpoint. `run(payload)` executes one call (payload is the parsed
+ * request body — `{method, args, root?}`, `{js}`, or `{op, ...}`) and may return
+ * any JSON-able value (undefined = void). Returns the http.Server, already
+ * listening; read `.address().port`.
+ */
+export function createExecEndpoint({ token, run }) {
+ const server = http.createServer(async (req, res) => {
+ const reply = (code, body) => {
+ res.writeHead(code, { 'content-type': 'application/json' });
+ res.end(JSON.stringify(body));
+ };
+ if (req.method !== 'POST' || req.url !== '/exec') return reply(404, { ok: false, error: 'not found' });
+ if (req.headers['x-estella-mcp-token'] !== token) return reply(403, { ok: false, error: 'bad token' });
+ try {
+ const result = await run(JSON.parse(await readBody(req)));
+ reply(200, { ok: true, hasResult: result !== undefined, result: result === undefined ? null : result });
+ } catch (e) {
+ reply(200, { ok: false, error: String((e && e.message) || e) });
+ }
+ });
+ return new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve(server)));
+}
diff --git a/desktop/src/main.tsx b/desktop/src/main.tsx
index 9ade71201..3a18b2ded 100644
--- a/desktop/src/main.tsx
+++ b/desktop/src/main.tsx
@@ -46,6 +46,7 @@ import { EngineHost } from './engine/EngineHost';
import { Particle, getComponent } from 'esengine';
import { applyFxPreview, initFxPreviewEditRestart } from './engine/fxPreview';
import { commands } from './commands/registry';
+import { ENTITY_SOURCES, sourceById, createFromSource } from './engine/entitySources';
import { ViewportController } from './engine/ViewportController';
import { PerfMonitor } from './engine/PerfMonitor';
import { LogStore } from './store/LogStore';
@@ -100,6 +101,21 @@ if (new URLSearchParams(location.search).has('automation')) {
},
/** Dispatch any registered editor command by id (the UI's own channel). */
runCommand: (id: string) => commands.run(id),
+ /** Save the open scene to disk (the toolbar Save, awaitable). */
+ save: () => ProjectStore.save(),
+ /** Create a blank scene FILE under `destDir` (Content Browser "New Scene"). */
+ createSceneFile: (destDir: string) => ProjectStore.createSceneFile(destDir),
+ /** The Create-popover catalog: every ready-made entity the editor can spawn. */
+ listEntityTemplates: () => ENTITY_SOURCES.map(({ id, label, category }) => ({ id, label, category })),
+ /** Spawn a ready-made entity through the one create pipeline (menu/DnD parity). */
+ createEntity: async (sourceId: string, opts?: { parent?: number | null; x?: number; y?: number }) => {
+ const source = sourceById(sourceId);
+ if (!source) throw new Error(`unknown entity template: ${sourceId} (see listEntityTemplates)`);
+ return createFromSource(source, {
+ parent: opts?.parent ?? null,
+ position: opts?.x != null && opts?.y != null ? { x: opts.x, y: opts.y } : undefined,
+ });
+ },
/** Double-click-open an asset by project path (FSM/BT/tileset/clip editors…). */
openAsset: (path: string) => {
const name = path.split('/').pop() ?? path;
diff --git a/desktop/tests/editor-mcp-tools.test.ts b/desktop/tests/editor-mcp-tools.test.ts
index 32d259360..bd323c85d 100644
--- a/desktop/tests/editor-mcp-tools.test.ts
+++ b/desktop/tests/editor-mcp-tools.test.ts
@@ -8,10 +8,11 @@ import { TOOLS, RESOURCES, runTool, listTools } from '../scripts/editor-mcp-tool
// surface method. These cover the pure dispatch layer (no Electron) — the Electron entry
// only supplies the executeJavaScript driver.
describe('editor MCP tool registry', () => {
- it('every tool has a unique name and either a surface method or renderer code', () => {
+ it('every tool has a unique name and a surface method, renderer code, or host op', () => {
const names = new Set<string>();
- for (const t of TOOLS as Array<{ name: string; method?: string; args?: unknown; js?: unknown }>) {
+ for (const t of TOOLS as Array<{ name: string; method?: string; args?: unknown; js?: unknown; op?: unknown }>) {
if (t.js) expect(typeof t.js).toBe('function');
+ else if (t.op) expect(typeof t.op).toBe('string');
else {
expect(typeof t.method).toBe('string');
expect(typeof t.args).toBe('function');
@@ -22,13 +23,34 @@ describe('editor MCP tool registry', () => {
expect(TOOLS.length).toBeGreaterThan(10);
});
+ it('editor-root tools pass their root through to the driver', async () => {
+ const driver = vi.fn(async () => 3);
+ const createEntity = TOOLS.find((t: { name: string }) => t.name === 'create_entity');
+ const res = await runTool(createEntity, driver, { template: 'anchor:Sprite', x: 10, y: 20 });
+ expect(driver).toHaveBeenCalledWith(
+ 'createEntity',
+ ['anchor:Sprite', { parent: null, x: 10, y: 20 }],
+ 'editor',
+ );
+ expect(res.content[0].text).toBe('3');
+ });
+
+ it('an op tool routes through driver.op and wraps as an image', async () => {
+ const driver = vi.fn() as unknown as { op: ReturnType<typeof vi.fn> } & ((...a: unknown[]) => unknown);
+ driver.op = vi.fn(async () => 'cGpn');
+ const shot = TOOLS.find((t: { name: string }) => t.name === 'screenshot');
+ const res = await runTool(shot, driver, {});
+ expect(driver.op).toHaveBeenCalledWith('screenshot', {});
+ expect(res.content[0]).toEqual({ type: 'image', data: 'cGpn', mimeType: 'image/png' });
+ });
+
it('runTool validates input and calls the driver with (method, args)', async () => {
const driver = vi.fn(async () => 42);
const setField = TOOLS.find((t: { name: string }) => t.name === 'set_field');
const res = await runTool(setField, driver, {
entity: 1, component: 'Transform', key: 'position.x', type: 'float', value: 5,
});
- expect(driver).toHaveBeenCalledWith('setField', [1, 'Transform', 'position.x', 'float', 5]);
+ expect(driver).toHaveBeenCalledWith('setField', [1, 'Transform', 'position.x', 'float', 5], undefined);
expect(res.content[0].text).toBe('42');
expect(res.isError).toBeFalsy();
});