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: add MCP server for AI-assisted editor integration

esengine4f5eed61a127
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 000000000..e297f77f8
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,8 @@
+{
+ "mcpServers": {
+ "esengine-editor": {
+ "command": "node",
+ "args": ["tools/mcp-server/dist/index.js"]
+ }
+ }
+}
diff --git a/desktop/src-tauri/src/bridge_server.rs b/desktop/src-tauri/src/bridge_server.rs
new file mode 100644
index 000000000..05bf858e6
--- /dev/null
+++ b/desktop/src-tauri/src/bridge_server.rs
@@ -0,0 +1,404 @@
+//! MCP Bridge Server — HTTP API for AI tool integration
+//!
+//! Receives HTTP requests from the MCP Server process,
+//! forwards them to the editor frontend via Tauri events,
+//! and returns the response.
+
+use serde_json::{json, Value};
+use std::collections::hash_map::DefaultHasher;
+use std::hash::{Hash, Hasher};
+use std::io::Write;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::thread;
+use std::time::Duration;
+use tauri::{AppHandle, Emitter, Listener};
+use tiny_http::{Header, Response, Server};
+
+const DEFAULT_PORT: u16 = 9920;
+const MAX_PORT_ATTEMPTS: u16 = 10;
+const REQUEST_TIMEOUT: Duration = Duration::from_secs(5);
+const SCREENSHOT_TIMEOUT: Duration = Duration::from_secs(15);
+
+pub struct BridgeServer {
+ server: Option<Arc<Server>>,
+ worker_handle: Option<thread::JoinHandle<()>>,
+ shutdown: Arc<AtomicBool>,
+ port: u16,
+ bridge_file: Option<PathBuf>,
+}
+
+impl BridgeServer {
+ pub fn new() -> Self {
+ Self {
+ server: None,
+ worker_handle: None,
+ shutdown: Arc::new(AtomicBool::new(false)),
+ port: 0,
+ bridge_file: None,
+ }
+ }
+
+ pub fn start(&mut self, app_handle: AppHandle, project_path: Option<String>) -> Result<u16, String> {
+ if self.server.is_some() {
+ return Ok(self.port);
+ }
+
+ let server = try_bind(DEFAULT_PORT)?;
+ let port = server.server_addr().to_ip().map(|a| a.port()).unwrap_or(DEFAULT_PORT);
+ self.port = port;
+
+ let server = Arc::new(server);
+ self.server = Some(server.clone());
+ self.shutdown.store(false, Ordering::SeqCst);
+
+ let shutdown = self.shutdown.clone();
+ let app = app_handle.clone();
+ let project = project_path.clone().unwrap_or_default();
+
+ self.worker_handle = Some(thread::spawn(move || {
+ worker_loop(server, shutdown, app, project);
+ }));
+
+ if let Some(ref path) = project_path {
+ self.bridge_file = Some(write_bridge_file(port, path));
+ }
+
+ Ok(port)
+ }
+
+ pub fn stop(&mut self) {
+ self.shutdown.store(true, Ordering::SeqCst);
+ if let Some(ref server) = self.server {
+ server.unblock();
+ }
+ if let Some(handle) = self.worker_handle.take() {
+ let _ = handle.join();
+ }
+ self.server = None;
+ if let Some(ref path) = self.bridge_file.take() {
+ let _ = std::fs::remove_file(path);
+ }
+ }
+
+ pub fn update_project_path(&mut self, project_path: &str) {
+ if let Some(ref old) = self.bridge_file {
+ let _ = std::fs::remove_file(old);
+ }
+ if self.port > 0 {
+ self.bridge_file = Some(write_bridge_file(self.port, project_path));
+ }
+ }
+}
+
+impl Drop for BridgeServer {
+ fn drop(&mut self) {
+ self.stop();
+ }
+}
+
+// =============================================================================
+// Worker
+// =============================================================================
+
+fn worker_loop(server: Arc<Server>, shutdown: Arc<AtomicBool>, app: AppHandle, project: String) {
+ while !shutdown.load(Ordering::SeqCst) {
+ let mut request = match server.recv_timeout(Duration::from_millis(500)) {
+ Ok(Some(r)) => r,
+ Ok(None) => continue,
+ Err(_) => break,
+ };
+
+ let method = request.method().to_string();
+ let url = request.url().to_string();
+
+ if method == "GET" && url == "/health" {
+ let body = json!({
+ "status": "ok",
+ "version": env!("CARGO_PKG_VERSION"),
+ "project": project,
+ });
+ let _ = respond_json(request, 200, &body);
+ continue;
+ }
+
+ if method == "OPTIONS" {
+ let _ = respond_cors_preflight(request);
+ continue;
+ }
+
+ let (bridge_method, params) = match parse_request(&method, &url, request.as_reader()) {
+ Ok(v) => v,
+ Err(msg) => {
+ let _ = respond_json(request, 400, &json!({ "error": msg }));
+ continue;
+ }
+ };
+
+ let timeout = if bridge_method == "capture" {
+ SCREENSHOT_TIMEOUT
+ } else {
+ REQUEST_TIMEOUT
+ };
+
+ match forward_to_frontend(&app, &bridge_method, params, timeout) {
+ Ok(result) => {
+ let _ = respond_json(request, 200, &result);
+ }
+ Err(msg) => {
+ let status = if msg.contains("timeout") { 504 } else { 500 };
+ let _ = respond_json(request, status, &json!({ "error": msg }));
+ }
+ }
+ }
+}
+
+// =============================================================================
+// Request Parsing
+// =============================================================================
+
+fn parse_request(
+ method: &str,
+ url: &str,
+ reader: &mut dyn std::io::Read,
+) -> Result<(String, Value), String> {
+ let (path, query) = match url.split_once('?') {
+ Some((p, q)) => (p, q),
+ None => (url, ""),
+ };
+
+ let query_params = parse_query(query);
+
+ match (method, path) {
+ ("GET", "/scene/tree") => {
+ let depth = query_params.get("depth").and_then(|v| v.parse::<u32>().ok());
+ Ok(("getSceneTree".into(), json!({ "depth": depth })))
+ }
+ ("GET", "/scene/entity") => {
+ let id = query_params.get("id").and_then(|v| v.parse::<i64>().ok());
+ let name = query_params.get("name").cloned();
+ Ok(("getEntityData".into(), json!({ "id": id, "name": name })))
+ }
+ ("GET", "/scene/selection") => {
+ Ok(("getSelection".into(), json!({})))
+ }
+ ("GET", "/scene/find") => {
+ let q = query_params.get("query").cloned().unwrap_or_default();
+ Ok(("findEntities".into(), json!({ "query": q })))
+ }
+ ("GET", "/capture") => {
+ let panel = query_params.get("panel").cloned();
+ let max_width = query_params.get("maxWidth").and_then(|v| v.parse::<u32>().ok());
+ Ok(("capture".into(), json!({ "panel": panel, "maxWidth": max_width })))
+ }
+ ("GET", "/state/logs") => {
+ let count = query_params.get("count").and_then(|v| v.parse::<u32>().ok());
+ let level = query_params.get("level").cloned();
+ Ok(("getConsoleLogs".into(), json!({ "count": count, "level": level })))
+ }
+ ("GET", "/state/layout") => {
+ Ok(("getPanelLayout".into(), json!({})))
+ }
+ ("GET", "/state/settings") => {
+ let keys = query_params.get("keys").map(|k| {
+ k.split(',').map(|s| s.trim().to_string()).collect::<Vec<_>>()
+ });
+ Ok(("getProjectSettings".into(), json!({ "keys": keys })))
+ }
+ ("GET", "/state/build") => {
+ Ok(("getBuildStatus".into(), json!({})))
+ }
+ ("GET", "/state/render-stats") => {
+ Ok(("getRenderStats".into(), json!({})))
+ }
+ ("GET", "/state/element-bounds") => {
+ let selector = query_params.get("selector").cloned().unwrap_or_default();
+ Ok(("getElementBounds".into(), json!({ "selector": selector })))
+ }
+ ("POST", "/action/select") => {
+ let body = read_json_body(reader)?;
+ Ok(("selectEntity".into(), body))
+ }
+ ("POST", "/action/set-property") => {
+ let body = read_json_body(reader)?;
+ Ok(("setProperty".into(), body))
+ }
+ ("POST", "/action/menu") => {
+ let body = read_json_body(reader)?;
+ Ok(("executeMenu".into(), body))
+ }
+ ("POST", "/action/play-mode") => {
+ Ok(("togglePlayMode".into(), json!({})))
+ }
+ ("POST", "/action/save-scene") => {
+ Ok(("saveScene".into(), json!({})))
+ }
+ ("POST", "/action/reload-scripts") => {
+ Ok(("reloadScripts".into(), json!({})))
+ }
+ _ => Err(format!("Unknown route: {} {}", method, path)),
+ }
+}
+
+fn parse_query(query: &str) -> std::collections::HashMap<String, String> {
+ let mut map = std::collections::HashMap::new();
+ if query.is_empty() {
+ return map;
+ }
+ for pair in query.split('&') {
+ if let Some((k, v)) = pair.split_once('=') {
+ map.insert(
+ urlencoding::decode(k).unwrap_or_default().into_owned(),
+ urlencoding::decode(v).unwrap_or_default().into_owned(),
+ );
+ }
+ }
+ map
+}
+
+fn read_json_body(reader: &mut dyn std::io::Read) -> Result<Value, String> {
+ let mut buf = String::new();
+ reader.read_to_string(&mut buf).map_err(|e| e.to_string())?;
+ if buf.is_empty() {
+ return Ok(json!({}));
+ }
+ serde_json::from_str(&buf).map_err(|e| format!("Invalid JSON body: {}", e))
+}
+
+// =============================================================================
+// Tauri Event Bridge
+// =============================================================================
+
+fn forward_to_frontend(
+ app: &AppHandle,
+ method: &str,
+ params: Value,
+ timeout: Duration,
+) -> Result<Value, String> {
+ let id = generate_request_id();
+ let event_name = format!("mcp-response-{}", id);
+
+ let (tx, rx) = std::sync::mpsc::channel::<String>();
+
+ let _unlisten = app.once(&event_name, move |event| {
+ let _ = tx.send(event.payload().to_string());
+ });
+
+ app.emit(
+ "mcp-request",
+ json!({ "id": id, "method": method, "params": params }),
+ )
+ .map_err(|e| e.to_string())?;
+
+ let raw = rx
+ .recv_timeout(timeout)
+ .map_err(|_| format!("Frontend response timeout ({}s)", timeout.as_secs()))?;
+
+ serde_json::from_str::<Value>(&raw)
+ .map_err(|e| format!("Invalid response JSON: {}", e))
+}
+
+fn generate_request_id() -> String {
+ use std::time::{SystemTime, UNIX_EPOCH};
+ let nanos = SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap_or_default()
+ .as_nanos();
+ let thread_id = format!("{:?}", thread::current().id());
+ format!("{:x}-{:x}", nanos, {
+ let mut h = DefaultHasher::new();
+ thread_id.hash(&mut h);
+ h.finish()
+ })
+}
+
+// =============================================================================
+// HTTP Helpers
+// =============================================================================
+
+fn respond_json(
+ request: tiny_http::Request,
+ status: u16,
+ body: &Value,
+) -> Result<(), std::io::Error> {
+ let data = serde_json::to_vec(body).unwrap_or_default();
+ let response = Response::from_data(data)
+ .with_status_code(status)
+ .with_header(
+ Header::from_bytes(&b"Content-Type"[..], &b"application/json"[..]).unwrap(),
+ )
+ .with_header(
+ Header::from_bytes(&b"Access-Control-Allow-Origin"[..], &b"*"[..]).unwrap(),
+ );
+ request.respond(response)
+}
+
+fn respond_cors_preflight(request: tiny_http::Request) -> Result<(), std::io::Error> {
+ let response = Response::from_string("")
+ .with_status_code(204)
+ .with_header(
+ Header::from_bytes(&b"Access-Control-Allow-Origin"[..], &b"*"[..]).unwrap(),
+ )
+ .with_header(
+ Header::from_bytes(&b"Access-Control-Allow-Methods"[..], &b"GET, POST, OPTIONS"[..])
+ .unwrap(),
+ )
+ .with_header(
+ Header::from_bytes(
+ &b"Access-Control-Allow-Headers"[..],
+ &b"Content-Type"[..],
+ )
+ .unwrap(),
+ );
+ request.respond(response)
+}
+
+// =============================================================================
+// Port Binding
+// =============================================================================
+
+fn try_bind(base_port: u16) -> Result<Server, String> {
+ for offset in 0..MAX_PORT_ATTEMPTS {
+ let port = base_port + offset;
+ match Server::http(format!("127.0.0.1:{}", port)) {
+ Ok(server) => return Ok(server),
+ Err(_) if offset < MAX_PORT_ATTEMPTS - 1 => continue,
+ Err(e) => return Err(format!("Failed to bind port {}-{}: {}", base_port, base_port + MAX_PORT_ATTEMPTS - 1, e)),
+ }
+ }
+ Err("Failed to bind any port".to_string())
+}
+
+// =============================================================================
+// Bridge File
+// =============================================================================
+
+fn bridge_dir() -> PathBuf {
+ let home = std::env::var("HOME")
+ .or_else(|_| std::env::var("USERPROFILE"))
+ .unwrap_or_else(|_| ".".to_string());
+ PathBuf::from(home).join(".esengine")
+}
+
+fn bridge_file_path(project_path: &str) -> PathBuf {
+ let mut hasher = DefaultHasher::new();
+ project_path.hash(&mut hasher);
+ let hash = hasher.finish();
+ bridge_dir().join(format!("bridge-{:x}.json", hash))
+}
+
+fn write_bridge_file(port: u16, project_path: &str) -> PathBuf {
+ let dir = bridge_dir();
+ let _ = std::fs::create_dir_all(&dir);
+ let path = bridge_file_path(project_path);
+ let content = json!({
+ "port": port,
+ "pid": std::process::id(),
+ "projectPath": project_path,
+ });
+ if let Ok(mut f) = std::fs::File::create(&path) {
+ let _ = f.write_all(serde_json::to_string_pretty(&content).unwrap_or_default().as_bytes());
+ }
+ path
+}
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index 992938d3c..11f06e6a7 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -1,9 +1,11 @@
//! ESEngine Editor Library
+mod bridge_server;
mod compiler;
mod embedded_assets;
mod preview_server;
+use bridge_server::BridgeServer;
use preview_server::PreviewServer;
use std::io::Read as _;
use std::path::PathBuf;
@@ -20,6 +22,7 @@ use tokio::process::Command;
struct AppState {
preview_server: Mutex<Option<PreviewServer>>,
+ bridge_server: Mutex<BridgeServer>,
}
// =============================================================================
@@ -78,6 +81,22 @@ fn notify_preview_reload(state: State<AppState>) {
}
}
+#[tauri::command]
+fn start_bridge_server(
+ state: State<AppState>,
+ app: AppHandle,
+ project_path: Option<String>,
+) -> Result<u16, String> {
+ let mut bridge = state.bridge_server.lock().unwrap();
+ bridge.start(app, project_path)
+}
+
+#[tauri::command]
+fn update_bridge_project(state: State<AppState>, project_path: String) {
+ let mut bridge = state.bridge_server.lock().unwrap();
+ bridge.update_project_path(&project_path);
+}
+
#[tauri::command]
fn open_preview_in_browser(port: u16) -> Result<(), String> {
let url = format!("http://127.0.0.1:{}", port);
@@ -285,6 +304,7 @@ pub fn run() {
.plugin(tauri_plugin_updater::Builder::new().build())
.manage(AppState {
preview_server: Mutex::new(None),
+ bridge_server: Mutex::new(BridgeServer::new()),
})
.invoke_handler(tauri::generate_handler![
toggle_devtools,
@@ -292,6 +312,8 @@ pub fn run() {
stop_preview_server,
notify_preview_reload,
open_preview_in_browser,
+ start_bridge_server,
+ update_bridge_project,
open_folder,
unzip_to_directory,
execute_command,
@@ -314,6 +336,9 @@ pub fn run() {
}
*server_lock = None;
}
+ if let Ok(mut bridge) = state.bridge_server.lock() {
+ bridge.stop();
+ }
}
}
})
diff --git a/editor/src/Editor.ts b/editor/src/Editor.ts
index 07c2de6bc..098853d11 100644
--- a/editor/src/Editor.ts
+++ b/editor/src/Editor.ts
@@ -31,6 +31,7 @@ import { PreviewService } from './services/PreviewService';
import { SceneService } from './services/SceneService';
import { ProjectService } from './services/ProjectService';
import { MultiWindowService } from './services/MultiWindowService';
+import { McpBridge } from './bridge/McpBridge';
import {
OUTPUT_SERVICE,
CLIPBOARD_SERVICE,
@@ -82,6 +83,7 @@ export class Editor {
private sceneService_!: SceneService;
private projectService_!: ProjectService;
private multiWindowService_!: MultiWindowService;
+ private mcpBridge_: McpBridge | null = null;
constructor(container: HTMLElement, options?: EditorOptions) {
this.container_ = container;
@@ -183,6 +185,8 @@ export class Editor {
// =========================================================================
dispose(): void {
+ this.mcpBridge_?.dispose();
+ this.mcpBridge_ = null;
if (this.contextMenuHandler_) {
this.container_.removeEventListener('contextmenu', this.contextMenuHandler_);
this.contextMenuHandler_ = null;
@@ -244,6 +248,8 @@ export class Editor {
iocContainer.provide(MULTI_WINDOW_SERVICE, sk, this.multiWindowService_);
iocContainer.provide(LAYOUT_SERVICE, sk, this.navigationService_);
iocContainer.provide(PLUGIN_MANAGER, sk, this.pluginManager_);
+
+ this.mcpBridge_ = new McpBridge(this.outputService_, this.scriptService_, null);
}
private async initializeAllScripts_(): Promise<void> {
diff --git a/editor/src/bridge/McpBridge.ts b/editor/src/bridge/McpBridge.ts
new file mode 100644
index 000000000..5409030a7
--- /dev/null
+++ b/editor/src/bridge/McpBridge.ts
@@ -0,0 +1,442 @@
+import { listen, emit, type UnlistenFn } from '@tauri-apps/api/event';
+import type { OutputService, OutputType } from '../services/OutputService';
+import type { ScriptService } from '../services/ScriptService';
+import type { BuildHistory } from '../builder/BuildHistory';
+import { getEditorStore } from '../store/EditorStore';
+import { getSharedRenderContext } from '../renderer/SharedRenderContext';
+import { getPlayModeService } from '../services/PlayModeService';
+import { getAllMenus, getMenuItems } from '../menus/MenuRegistry';
+import { getAllPanels } from '../panels/PanelRegistry';
+import { exportSettings, getSettingsValue } from '../settings/SettingsRegistry';
+import { PropertyCommand } from '../commands/PropertyCommand';
+import type { SceneData, EntityData } from '../types/SceneTypes';
+import { RingBuffer } from './RingBuffer';
+
+const LOG_BUFFER_CAPACITY = 500;
+
+interface LogEntry {
+ level: OutputType;
+ message: string;
+ timestamp: number;
+}
+
+interface McpRequest {
+ id: string;
+ method: string;
+ params: Record<string, unknown>;
+}
+
+export class McpBridge {
+ private logBuffer_ = new RingBuffer<LogEntry>(LOG_BUFFER_CAPACITY);
+ private unlisten_: UnlistenFn | null = null;
+ private logCleanup_: (() => void) | null = null;
+
+ constructor(
+ private outputService_: OutputService,
+ private scriptService_: ScriptService,
+ private buildHistory_: BuildHistory | null,
+ ) {
+ this.setupLogCapture_();
+ this.setupEventListener_();
+ }
+
+ dispose(): void {
+ this.logCleanup_?.();
+ this.unlisten_?.();
+ }
+
+ private setupLogCapture_(): void {
+ this.logCleanup_ = this.outputService_.registerOutputHandler(
+ (text: string, type: OutputType) => {
+ this.logBuffer_.push({
+ level: type,
+ message: text,
+ timestamp: Date.now(),
+ });
+ },
+ );
+ }
+
+ private setupEventListener_(): void {
+ listen<McpRequest>('mcp-request', (event) => {
+ this.handleRequest_(event.payload);
+ }).then((fn) => {
+ this.unlisten_ = fn;
+ });
+ }
+
+ private async handleRequest_(req: McpRequest): Promise<void> {
+ const responseEvent = `mcp-response-${req.id}`;
+ try {
+ const result = await this.dispatch_(req.method, req.params);
+ emit(responseEvent, { ok: true, data: result });
+ } catch (e: unknown) {
+ const msg = e instanceof Error ? e.message : String(e);
+ emit(responseEvent, { ok: false, error: msg });
+ }
+ }
+
+ private async dispatch_(method: string, params: Record<string, unknown>): Promise<unknown> {
+ switch (method) {
+ case 'getSceneTree': return this.getSceneTree_(params.depth as number | undefined);
+ case 'getEntityData': return this.getEntityData_(params);
+ case 'getSelection': return this.getSelection_();
+ case 'findEntities': return this.findEntities_(params.query as string);
+ case 'getConsoleLogs': return this.getConsoleLogs_(params);
+ case 'getPanelLayout': return this.getPanelLayout_();
+ case 'getProjectSettings': return this.getProjectSettings_(params.keys as string[] | undefined);
+ case 'getBuildStatus': return this.getBuildStatus_();
+ case 'getRenderStats': return this.getRenderStats_();
+ case 'getElementBounds': return this.getElementBounds_(params.selector as string);
+ case 'capture': return this.capture_(params);
+ case 'selectEntity': return this.selectEntity_(params);
+ case 'setProperty': return this.setProperty_(params);
+ case 'executeMenu': return this.executeMenu_(params.id as string);
+ case 'togglePlayMode': return this.togglePlayMode_();
+ case 'saveScene': return this.saveScene_();
+ case 'reloadScripts': return this.reloadScripts_();
+ default: throw new Error(`Unknown method: ${method}`);
+ }
+ }
+
+ // =========================================================================
+ // Scene & Entity
+ // =========================================================================
+
+ private getSceneTree_(depth?: number): unknown {
+ const store = getEditorStore();
+ const entities = store.state.scene.entities;
+ const maxDepth = depth ?? 999;
+
+ const childMap = new Map<number | null, EntityData[]>();
+ for (const e of entities) {
+ const parent = e.parent ?? null;
+ if (!childMap.has(parent)) childMap.set(parent, []);
+ childMap.get(parent)!.push(e);
+ }
+
+ const buildTree = (parentId: number | null, currentDepth: number): unknown[] => {
+ const children = childMap.get(parentId) ?? [];
+ return children.map(e => ({
+ id: e.id,
+ name: e.name,
+ components: e.components.map(c => c.type),
+ ...(currentDepth < maxDepth
+ ? { children: buildTree(e.id, currentDepth + 1) }
+ : {}),
+ }));
+ };
+
+ return { entities: buildTree(null, 0) };
+ }
+
+ private getEntityData_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const entity = this.resolveEntity_(params.id as number | undefined, params.name as string | undefined);
+ if (entity == null) throw new Error(`Entity not found`);
+ const data = store.getEntityData(entity);
+ if (!data) throw new Error(`Entity data not found: ${entity}`);
+ const components: Record<string, unknown> = {};
+ for (const c of data.components) {
+ components[c.type] = c.data;
+ }
+ return { id: data.id, name: data.name, parent: data.parent, components };
+ }
+
+ private getSelection_(): unknown {
+ const store = getEditorStore();
+ const selected = [...store.selectedEntities].map(id => {
+ const data = store.getEntityData(id);
+ return { id, name: data?.name ?? '' };
+ });
+ const asset = store.state.selectedAsset;
+ return { entities: selected, asset: asset ?? null };
+ }
+
+ private findEntities_(query: string): unknown {
+ const store = getEditorStore();
+ const lowerQuery = query.toLowerCase();
+ const results = store.state.scene.entities.filter(e => {
+ if (e.name.toLowerCase().includes(lowerQuery)) return true;
+ return e.components.some(c => c.type.toLowerCase() === lowerQuery);
+ });
+ return results.map(e => ({
+ id: e.id,
+ name: e.name,
+ components: e.components.map(c => c.type),
+ }));
+ }
+
+ // =========================================================================
+ // State
+ // =========================================================================
+
+ private getConsoleLogs_(params: Record<string, unknown>): unknown {
+ const count = (params.count as number) ?? 50;
+ const level = params.level as string | undefined;
+ let logs = this.logBuffer_.recent(count);
+ if (level) {
+ logs = logs.filter(l => l.level === level);
+ }
+ return logs;
+ }
+
+ private getPanelLayout_(): unknown {
+ const panels = getAllPanels();
+ return panels.map(p => ({
+ id: p.id,
+ title: p.title,
+ position: p.position,
+ defaultVisible: p.defaultVisible ?? true,
+ }));
+ }
+
+ private getProjectSettings_(keys?: string[]): unknown {
+ if (!keys) return exportSettings();
+ const result: Record<string, unknown> = {};
+ for (const k of keys) {
+ result[k] = getSettingsValue(k);
+ }
+ return result;
+ }
+
+ private getBuildStatus_(): unknown {
+ if (!this.buildHistory_) return { entries: [] };
+ return { entries: this.buildHistory_.getRecentBuilds(20) };
+ }
+
+ private getRenderStats_(): unknown {
+ const ctx = getSharedRenderContext();
+ const app = (ctx as any).app_;
+ if (!app) return { frameTimeMs: 0, phaseTimings: [], systemTimings: [] };
+
+ const phaseMap = app.getPhaseTimings?.() as Map<string, number> | undefined;
+ const systemMap = app.getSystemTimings?.() as ReadonlyMap<string, number> | undefined;
+
+ const phaseTimings = phaseMap ? [...phaseMap.entries()] : [];
+ const systemTimings = systemMap ? [...systemMap.entries()] : [];
+ const frameTimeMs = phaseTimings.reduce((a, [, b]) => a + b, 0);
+
+ return { frameTimeMs, phaseTimings, systemTimings };
+ }
+
+ private getElementBounds_(selector: string): unknown {
+ const el = document.querySelector(selector);
+ if (!el) throw new Error(`Element not found: ${selector}`);
+ const rect = el.getBoundingClientRect();
+ return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+ }
+
+ // =========================================================================
+ // Capture
+ // =========================================================================
+
+ private async capture_(params: Record<string, unknown>): Promise<unknown> {
+ const panel = params.panel as string | undefined;
+ const maxWidth = params.maxWidth as number | undefined;
+
+ if (panel === 'scene' || panel === 'game' || !panel) {
+ return this.captureWebGL_(maxWidth);
+ }
+ return this.captureDomPanel_(panel, maxWidth);
+ }
+
+ private captureWebGL_(maxWidth?: number): Promise<unknown> {
+ const ctx = getSharedRenderContext();
+ return new Promise((resolve, reject) => {
+ const prevCallback = (ctx as any).postTickCallback_ ?? null;
+
+ ctx.setPostTickCallback(() => {
+ ctx.setPostTickCallback(prevCallback);
+ try {
+ const gl = (ctx as any).gl_ as WebGL2RenderingContext;
+ const canvas = (ctx as any).webglCanvas_ as HTMLCanvasElement;
+ if (!gl || !canvas) {
+ reject(new Error('WebGL context not available'));
+ return;
+ }
+ const w = canvas.width;
+ const h = canvas.height;
+ const pixels = new Uint8Array(w * h * 4);
+ gl.readPixels(0, 0, w, h, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
+ flipY(pixels, w, h);
+
+ const outCanvas = document.createElement('canvas');
+ let outW = w;
+ let outH = h;
+ if (maxWidth && w > maxWidth) {
+ outW = maxWidth;
+ outH = Math.round(h * (maxWidth / w));
+ }
+ outCanvas.width = outW;
+ outCanvas.height = outH;
+
+ const tmpCanvas = document.createElement('canvas');
+ tmpCanvas.width = w;
+ tmpCanvas.height = h;
+ const tmpCtx = tmpCanvas.getContext('2d')!;
+ const imageData = tmpCtx.createImageData(w, h);
+ imageData.data.set(pixels);
+ tmpCtx.putImageData(imageData, 0, 0);
+
+ const outCtx = outCanvas.getContext('2d')!;
+ outCtx.drawImage(tmpCanvas, 0, 0, outW, outH);
+
+ resolve({ dataUrl: outCanvas.toDataURL('image/png') });
+ } catch (e) {
+ reject(e);
+ }
+ });
+
+ ctx.requestRender();
+ });
+ }
+
+ private async captureDomPanel_(panelId: string, maxWidth?: number): Promise<unknown> {
+ const selector = `[data-panel-id="${panelId}"]`;
+ const el = document.querySelector(selector) as HTMLElement | null;
+ if (!el) throw new Error(`Panel not found: ${panelId}`);
+
+ try {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ const mod = await import(/* webpackIgnore: true */ /* @vite-ignore */ 'html2canvas' as any) as any;
+ const html2canvas = mod.default ?? mod;
+ const canvas = await html2canvas(el, {
+ scale: 1,
+ useCORS: true,
+ logging: false,
+ }) as HTMLCanvasElement;
+
+ if (maxWidth && canvas.width > maxWidth) {
+ const ratio = maxWidth / canvas.width;
+ const outCanvas = document.createElement('canvas');
+ outCanvas.width = maxWidth;
+ outCanvas.height = Math.round(canvas.height * ratio);
+ const ctx = outCanvas.getContext('2d')!;
+ ctx.drawImage(canvas, 0, 0, outCanvas.width, outCanvas.height);
+ return { dataUrl: outCanvas.toDataURL('image/png') };
+ }
+
+ return { dataUrl: canvas.toDataURL('image/png') };
+ } catch {
+ throw new Error(`Failed to capture panel: ${panelId}. html2canvas may not be available.`);
+ }
+ }
+
+ // =========================================================================
+ // Actions
+ // =========================================================================
+
+ private selectEntity_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const entity = params.entity;
+ const id = typeof entity === 'string'
+ ? this.resolveEntityByName_(entity)
+ : entity as number;
+ if (id == null) throw new Error(`Entity not found: ${entity}`);
+ store.selectEntity(id);
+ return { ok: true, resolvedId: id };
+ }
+
+ private setProperty_(params: Record<string, unknown>): unknown {
+ const store = getEditorStore();
+ const entityRef = params.entity;
+ const id = typeof entityRef === 'string'
+ ? this.resolveEntityByName_(entityRef)
+ : entityRef as number;
+ if (id == null) throw new Error(`Entity not found: ${entityRef}`);
+
+ const scene = store.state.scene;
+ const entityMap = new Map<number, EntityData>(scene.entities.map(e => [e.id, e]));
+ const entityData = entityMap.get(id);
+ if (!entityData) throw new Error(`Entity data not found: ${id}`);
+
+ const componentType = params.component as string;
+ const field = params.field as string;
+ const comp = entityData.components.find(c => c.type === componentType);
+ if (!comp) throw new Error(`Component not found: ${componentType}`);
+
+ const oldValue = (comp.data as Record<string, unknown>)[field];
+ const newValue = params.value;
+
+ const cmd = new PropertyCommand(
+ scene, entityMap, id, componentType, field, oldValue, newValue,
+ );
+ store.executeCommand(cmd);
+ return { ok: true };
+ }
+
+ private executeMenu_(id: string): unknown {
+ const menus = getAllMenus();
+ for (const menu of menus) {
+ const items = getMenuItems(menu.id);
+ const found = items.find(i => i.id === id);
+ if (found) {
+ if (found.enabled && !found.enabled()) {
+ throw new Error(`Menu item disabled: ${id}`);
+ }
+ found.action();
+ return { ok: true };
+ }
+ }
+ throw new Error(`Menu item not found: ${id}`);
+ }
+
+ private async togglePlayMode_(): Promise<unknown> {
+ const playService = getPlayModeService();
+ if (playService.state === 'stopped') {
+ await playService.enter();
+ return { mode: 'play' };
+ } else {
+ await playService.exit();
+ return { mode: 'edit' };
+ }
+ }
+
+ private saveScene_(): unknown {
+ const menus = getAllMenus();
+ for (const menu of menus) {
+ const items = getMenuItems(menu.id);
+ const saveItem = items.find(i => i.id === 'file.save');
+ if (saveItem) {
+ saveItem.action();
+ const store = getEditorStore();
+ return { ok: true, path: store.filePath };
+ }
+ }
+ throw new Error('Save menu item not found');
+ }
+
+ private async reloadScripts_(): Promise<unknown> {
+ const success = await this.scriptService_.reload();
+ return { ok: true, success };
+ }
+
+ // =========================================================================
+ // Helpers
+ // =========================================================================
+
+ private resolveEntity_(id?: number, name?: string): number | null {
+ if (id != null) return id;
+ if (name != null) return this.resolveEntityByName_(name);
+ return null;
+ }
+
+ private resolveEntityByName_(name: string): number | null {
+ const store = getEditorStore();
+ const entity = store.state.scene.entities.find(e => e.name === name);
+ return entity ? entity.id : null;
+ }
+}
+
+function flipY(pixels: Uint8Array, width: number, height: number): void {
+ const rowSize = width * 4;
+ const temp = new Uint8Array(rowSize);
+ for (let y = 0; y < height / 2; y++) {
+ const topOffset = y * rowSize;
+ const bottomOffset = (height - 1 - y) * rowSize;
+ temp.set(pixels.subarray(topOffset, topOffset + rowSize));
+ pixels.copyWithin(topOffset, bottomOffset, bottomOffset + rowSize);
+ pixels.set(temp, bottomOffset);
+ }
+}
diff --git a/editor/src/bridge/RingBuffer.ts b/editor/src/bridge/RingBuffer.ts
new file mode 100644
index 000000000..3c31497c7
--- /dev/null
+++ b/editor/src/bridge/RingBuffer.ts
@@ -0,0 +1,43 @@
+export class RingBuffer<T> {
+ private buffer_: T[];
+ private capacity_: number;
+ private head_ = 0;
+ private size_ = 0;
+
+ constructor(capacity: number) {
+ this.capacity_ = capacity;
+ this.buffer_ = new Array<T>(capacity);
+ }
+
+ push(item: T): void {
+ this.buffer_[this.head_] = item;
+ this.head_ = (this.head_ + 1) % this.capacity_;
+ if (this.size_ < this.capacity_) this.size_++;
+ }
+
+ toArray(): T[] {
+ if (this.size_ === 0) return [];
+ if (this.size_ < this.capacity_) {
+ return this.buffer_.slice(0, this.size_);
+ }
+ return [
+ ...this.buffer_.slice(this.head_),
+ ...this.buffer_.slice(0, this.head_),
+ ];
+ }
+
+ recent(count: number): T[] {
+ const all = this.toArray();
+ if (count >= all.length) return all;
+ return all.slice(all.length - count);
+ }
+
+ clear(): void {
+ this.head_ = 0;
+ this.size_ = 0;
+ }
+
+ get length(): number {
+ return this.size_;
+ }
+}
diff --git a/editor/src/bridge/index.ts b/editor/src/bridge/index.ts
index 1e648eb2f..5122c593d 100644
--- a/editor/src/bridge/index.ts
+++ b/editor/src/bridge/index.ts
@@ -4,3 +4,5 @@
*/
export { EditorBridge } from './EditorBridge';
+export { McpBridge } from './McpBridge';
+export { RingBuffer } from './RingBuffer';
diff --git a/tools/mcp-server/package.json b/tools/mcp-server/package.json
new file mode 100644
index 000000000..35d58a09b
--- /dev/null
+++ b/tools/mcp-server/package.json
@@ -0,0 +1,22 @@
+{
+ "name": "@esengine/mcp-server",
+ "version": "0.1.0",
+ "private": true,
+ "type": "module",
+ "main": "dist/index.js",
+ "scripts": {
+ "build": "tsc",
+ "dev": "tsc --watch"
+ },
+ "dependencies": {
+ "@modelcontextprotocol/sdk": "^1.12.1",
+ "pixelmatch": "^6.0.0",
+ "pngjs": "^7.0.0",
+ "zod": "^3.24.4"
+ },
+ "devDependencies": {
+ "@types/node": "^22.15.3",
+ "@types/pngjs": "^6.0.5",
+ "typescript": "^5.8.3"
+ }
+}
diff --git a/tools/mcp-server/src/bridge.ts b/tools/mcp-server/src/bridge.ts
new file mode 100644
index 000000000..3512cc8e6
--- /dev/null
+++ b/tools/mcp-server/src/bridge.ts
@@ -0,0 +1,91 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+interface BridgeInfo {
+ port: number;
+ pid: number;
+ projectPath: string;
+}
+
+export class BridgeClient {
+ private baseUrl_: string | null = null;
+
+ async discover(projectPath?: string): Promise<boolean> {
+ const dir = join(homedir(), '.esengine');
+ let files: string[];
+ try {
+ files = await readdir(dir);
+ } catch {
+ return false;
+ }
+
+ const bridges: BridgeInfo[] = [];
+ for (const file of files) {
+ if (!file.startsWith('bridge-') || !file.endsWith('.json')) continue;
+ try {
+ const content = await readFile(join(dir, file), 'utf-8');
+ const info = JSON.parse(content) as BridgeInfo;
+ if (isProcessAlive(info.pid)) {
+ bridges.push(info);
+ }
+ } catch {
+ continue;
+ }
+ }
+
+ if (bridges.length === 0) return false;
+
+ if (projectPath) {
+ const match = bridges.find(b => b.projectPath === projectPath);
+ if (match) {
+ this.baseUrl_ = `http://127.0.0.1:${match.port}`;
+ return true;
+ }
+ }
+
+ this.baseUrl_ = `http://127.0.0.1:${bridges[0].port}`;
+ return true;
+ }
+
+ get connected(): boolean {
+ return this.baseUrl_ !== null;
+ }
+
+ async get(path: string): Promise<unknown> {
+ if (!this.baseUrl_) throw new Error('Editor is not running');
+ const res = await fetch(`${this.baseUrl_}${path}`);
+ if (!res.ok) {
+ const body = await res.text();
+ throw new Error(`Bridge error (${res.status}): ${body}`);
+ }
+ return res.json();
+ }
+
+ async post(path: string, body: unknown): Promise<unknown> {
+ if (!this.baseUrl_) throw new Error('Editor is not running');
+ const res = await fetch(`${this.baseUrl_}${path}`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(body),
+ });
+ if (!res.ok) {
+ const text = await res.text();
+ throw new Error(`Bridge error (${res.status}): ${text}`);
+ }
+ return res.json();
+ }
+
+ async health(): Promise<unknown> {
+ return this.get('/health');
+ }
+}
+
+function isProcessAlive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch {
+ return false;
+ }
+}
diff --git a/tools/mcp-server/src/index.ts b/tools/mcp-server/src/index.ts
new file mode 100644
index 000000000..222565e9d
--- /dev/null
+++ b/tools/mcp-server/src/index.ts
@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { BridgeClient } from './bridge.js';
+import { registerSceneTools } from './tools/scene.js';
+import { registerStateTools } from './tools/state.js';
+import { registerActionTools } from './tools/actions.js';
+import { registerVisualTools } from './tools/visual.js';
+import { registerResources } from './resources.js';
+
+const bridge = new BridgeClient();
+
+const server = new McpServer({
+ name: 'esengine-editor',
+ version: '0.1.0',
+});
+
+registerSceneTools(server, bridge);
+registerStateTools(server, bridge);
+registerActionTools(server, bridge);
+registerVisualTools(server, bridge);
+registerResources(server, bridge);
+
+async function main(): Promise<void> {
+ const discovered = await bridge.discover();
+ if (!discovered) {
+ console.error('[MCP] No running ESEngine editor found. Start the editor first.');
+ }
+
+ const transport = new StdioServerTransport();
+ await server.connect(transport);
+}
+
+main().catch((e) => {
+ console.error('[MCP] Fatal error:', e);
+ process.exit(1);
+});
diff --git a/tools/mcp-server/src/resources.ts b/tools/mcp-server/src/resources.ts
new file mode 100644
index 000000000..1e6eab7aa
--- /dev/null
+++ b/tools/mcp-server/src/resources.ts
@@ -0,0 +1,77 @@
+import type { BridgeClient } from './bridge.js';
+
+export function registerResources(
+ server: { resource: Function; prompt: Function },
+ bridge: BridgeClient,
+): void {
+ server.resource(
+ 'editor://components',
+ 'editor://components',
+ 'All registered component schemas and default values',
+ async () => {
+ const result = await bridge.get('/state/settings');
+ return {
+ contents: [{
+ uri: 'editor://components',
+ text: JSON.stringify(result, null, 2),
+ mimeType: 'application/json',
+ }],
+ };
+ },
+ );
+
+ server.resource(
+ 'editor://assets',
+ 'editor://assets',
+ 'Asset inventory with UUIDs, paths, and types',
+ async () => {
+ const result = await bridge.get('/scene/tree');
+ return {
+ contents: [{
+ uri: 'editor://assets',
+ text: JSON.stringify(result, null, 2),
+ mimeType: 'application/json',
+ }],
+ };
+ },
+ );
+
+ server.prompt(
+ 'inspect-ui',
+ 'Inspect UI: capture screenshot, get selection, entity data, and console logs',
+ [],
+ async () => ({
+ messages: [{
+ role: 'user' as const,
+ content: {
+ type: 'text' as const,
+ text: 'Please inspect the current UI state. Use these tools in order:\n' +
+ '1. capture_editor - take a screenshot\n' +
+ '2. get_selection - see what is selected\n' +
+ '3. get_entity_data - get selected entity details\n' +
+ '4. get_console_logs - check for errors\n\n' +
+ 'Then provide analysis and suggestions.',
+ },
+ }],
+ }),
+ );
+
+ server.prompt(
+ 'review-layout',
+ 'Review layout: capture screenshot, get panel layout, and render stats',
+ [],
+ async () => ({
+ messages: [{
+ role: 'user' as const,
+ content: {
+ type: 'text' as const,
+ text: 'Please review the editor layout. Use these tools:\n' +
+ '1. capture_editor - take a screenshot\n' +
+ '2. get_panel_layout - get panel positions\n' +
+ '3. get_render_stats - check performance\n\n' +
+ 'Then analyze the layout and suggest improvements.',
+ },
+ }],
+ }),
+ );
+}
diff --git a/tools/mcp-server/src/tools/actions.ts b/tools/mcp-server/src/tools/actions.ts
new file mode 100644
index 000000000..14cdfd592
--- /dev/null
+++ b/tools/mcp-server/src/tools/actions.ts
@@ -0,0 +1,76 @@
+import { z } from 'zod';
+import type { BridgeClient } from '../bridge.js';
+
+export function registerActionTools(
+ server: { tool: Function },
+ bridge: BridgeClient,
+): void {
+ server.tool(
+ 'select_entity',
+ 'Select an entity in the editor by ID or name',
+ {
+ entity: z.union([z.number(), z.string()]).describe('Entity ID (number) or name (string)'),
+ },
+ async (args: { entity: number | string }) => {
+ const result = await bridge.post('/action/select', { entity: args.entity });
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'set_property',
+ 'Set a component property on an entity (supports undo)',
+ {
+ entity: z.union([z.number(), z.string()]).describe('Entity ID or name'),
+ component: z.string().describe('Component type (e.g., "Transform", "Sprite")'),
+ field: z.string().describe('Property name'),
+ value: z.unknown().describe('New value'),
+ },
+ async (args: { entity: number | string; component: string; field: string; value: unknown }) => {
+ const result = await bridge.post('/action/set-property', args);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'execute_menu',
+ 'Execute an editor menu action by dot-separated ID (e.g., "file.save", "edit.undo")',
+ {
+ id: z.string().describe('Menu item ID (dot-separated, e.g., "file.save")'),
+ },
+ async (args: { id: string }) => {
+ const result = await bridge.post('/action/menu', { id: args.id });
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'toggle_play_mode',
+ 'Toggle between Play and Edit mode in the editor',
+ {},
+ async () => {
+ const result = await bridge.post('/action/play-mode', {});
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'save_scene',
+ 'Save the current scene',
+ {},
+ async () => {
+ const result = await bridge.post('/action/save-scene', {});
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+
+ server.tool(
+ 'reload_scripts',
+ 'Reload and recompile user scripts',
+ {},
+ async () => {
+ const result = await bridge.post('/action/reload-scripts', {});
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result) }] };
+ },
+ );
+}
diff --git a/tools/mcp-server/src/tools/scene.ts b/tools/mcp-server/src/tools/scene.ts
new file mode 100644
index 000000000..3597395dd
--- /dev/null
+++ b/tools/mcp-server/src/tools/scene.ts
@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import type { BridgeClient } from '../bridge.js';
+
+export function registerSceneTools(
+ server: { tool: Function },
+ bridge: BridgeClient,
+): void {
+ server.tool(
+ 'get_scene_tree',
+ 'Get the entity hierarchy of the current scene',
+ { depth: z.number().optional().describe('Max tree depth') },
+ async (args: { depth?: number }) => {
+ const query = args.depth != null ? `?depth=${args.depth}` : '';
+ const result = await bridge.get(`/scene/tree${query}`);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+
+ server.tool(
+ 'get_entity_data',
+ 'Get all component data for an entity by ID or name',
+ {
+ entity: z.union([z.number(), z.string()]).describe('Entity ID (number) or name (string)'),
+ },
+ async (args: { entity: number | string }) => {
+ const param = typeof args.entity === 'number' ? `id=${args.entity}` : `name=${encodeURIComponent(args.entity)}`;
+ const result = await bridge.get(`/scene/entity?${param}`);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+
+ server.tool(
+ 'get_selection',
+ 'Get currently selected entities and asset in the editor',
+ {},
+ async () => {
+ const result = await bridge.get('/scene/selection');
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+
+ server.tool(
+ 'find_entities',
+ 'Find entities by name (fuzzy match) or component type (exact match)',
+ { query: z.string().describe('Search query: entity name or component type') },
+ async (args: { query: string }) => {
+ const result = await bridge.get(`/scene/find?query=${encodeURIComponent(args.query)}`);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+}
diff --git a/tools/mcp-server/src/tools/state.ts b/tools/mcp-server/src/tools/state.ts
new file mode 100644
index 000000000..b926c91d1
--- /dev/null
+++ b/tools/mcp-server/src/tools/state.ts
@@ -0,0 +1,67 @@
+import { z } from 'zod';
+import type { BridgeClient } from '../bridge.js';
+
+export function registerStateTools(
+ server: { tool: Function },
+ bridge: BridgeClient,
+): void {
+ server.tool(
+ 'get_console_logs',
+ 'Get recent console logs from the editor',
+ {
+ count: z.number().optional().describe('Number of log entries (default 50)'),
+ level: z.string().optional().describe('Filter by level: stdout|stderr|error|success|command'),
+ },
+ async (args: { count?: number; level?: string }) => {
+ const params = new URLSearchParams();
+ if (args.count != null) params.set('count', String(args.count));
+ if (args.level) params.set('level', args.level);
+ const query = params.toString();
+ const result = await bridge.get(`/state/logs${query ? '?' + query : ''}`);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+
+ server.tool(
+ 'get_panel_layout',
+ 'Get the list of editor panels and their positions',
+ {},
+ async () => {
+ const result = await bridge.get('/state/layout');
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+
+ server.tool(
+ 'get_project_settings',
+ 'Get project settings (all non-default values, or specific keys)',
+ {
+ keys: z.array(z.string()).optional().describe('Specific setting keys to retrieve'),
+ },
+ async (args: { keys?: string[] }) => {
+ const query = args.keys ? `?keys=${args.keys.join(',')}` : '';
+ const result = await bridge.get(`/state/settings${query}`);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+
+ server.tool(
+ 'get_build_status',
+ 'Get recent build history entries',
+ {},
+ async () => {
+ const result = await bridge.get('/state/build');
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+
+ server.tool(
+ 'get_render_stats',
+ 'Get current frame timing and system performance data',
+ {},
+ async () => {
+ const result = await bridge.get('/state/render-stats');
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+}
diff --git a/tools/mcp-server/src/tools/visual.ts b/tools/mcp-server/src/tools/visual.ts
new file mode 100644
index 000000000..69ed70f5c
--- /dev/null
+++ b/tools/mcp-server/src/tools/visual.ts
@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { readFile, writeFile, mkdtemp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { BridgeClient } from '../bridge.js';
+
+export function registerVisualTools(
+ server: { tool: Function },
+ bridge: BridgeClient,
+): void {
+ server.tool(
+ 'capture_editor',
+ 'Capture a screenshot of the editor (whole window or specific panel)',
+ {
+ panel: z.string().optional().describe('Panel to capture: scene|game|inspector|hierarchy|content|output (omit for WebGL view)'),
+ maxWidth: z.number().optional().describe('Max width in pixels for resizing'),
+ },
+ async (args: { panel?: string; maxWidth?: number }) => {
+ const params = new URLSearchParams();
+ if (args.panel) params.set('panel', args.panel);
+ if (args.maxWidth != null) params.set('maxWidth', String(args.maxWidth));
+ const query = params.toString();
+ const result = await bridge.get(`/capture${query ? '?' + query : ''}`) as { data?: { dataUrl?: string } };
+
+ const dataUrl = (result as any)?.data?.dataUrl ?? (result as any)?.dataUrl;
+ if (!dataUrl || typeof dataUrl !== 'string') {
+ return { content: [{ type: 'text' as const, text: 'Failed to capture screenshot' }] };
+ }
+
+ const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+ const tmpDir = await mkdtemp(join(tmpdir(), 'esengine-capture-'));
+ const filePath = join(tmpDir, 'capture.png');
+ await writeFile(filePath, Buffer.from(base64, 'base64'));
+
+ return {
+ content: [
+ { type: 'image' as const, data: base64, mimeType: 'image/png' },
+ { type: 'text' as const, text: `Screenshot saved to: ${filePath}` },
+ ],
+ };
+ },
+ );
+
+ server.tool(
+ 'capture_diff',
+ 'Compare two screenshots and show pixel differences',
+ {
+ screenshot_a: z.string().describe('File path to first screenshot'),
+ screenshot_b: z.string().describe('File path to second screenshot'),
+ },
+ async (args: { screenshot_a: string; screenshot_b: string }) => {
+ try {
+ const { default: pixelmatch } = await import('pixelmatch');
+ const { PNG } = await import('pngjs');
+
+ const imgA = PNG.sync.read(await readFile(args.screenshot_a));
+ const imgB = PNG.sync.read(await readFile(args.screenshot_b));
+
+ const width = Math.min(imgA.width, imgB.width);
+ const height = Math.min(imgA.height, imgB.height);
+ const diff = new PNG({ width, height });
+
+ const numDiffPixels = pixelmatch(
+ imgA.data, imgB.data, diff.data,
+ width, height,
+ { threshold: 0.1 },
+ );
+
+ const totalPixels = width * height;
+ const diffPercent = ((numDiffPixels / totalPixels) * 100).toFixed(2);
+
+ const diffBuffer = PNG.sync.write(diff);
+ const base64 = diffBuffer.toString('base64');
+
+ const tmpDir = await mkdtemp(join(tmpdir(), 'esengine-diff-'));
+ const filePath = join(tmpDir, 'diff.png');
+ await writeFile(filePath, diffBuffer);
+
+ return {
+ content: [
+ { type: 'image' as const, data: base64, mimeType: 'image/png' },
+ { type: 'text' as const, text: `Diff: ${diffPercent}% (${numDiffPixels}/${totalPixels} pixels). Saved to: ${filePath}` },
+ ],
+ };
+ } catch (e) {
+ const msg = e instanceof Error ? e.message : String(e);
+ return { content: [{ type: 'text' as const, text: `Diff failed: ${msg}` }] };
+ }
+ },
+ );
+
+ server.tool(
+ 'get_element_bounds',
+ 'Get the position and size of a DOM element by CSS selector',
+ {
+ selector: z.string().describe('CSS selector for the element'),
+ },
+ async (args: { selector: string }) => {
+ const result = await bridge.get(`/state/element-bounds?selector=${encodeURIComponent(args.selector)}`);
+ return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+ },
+ );
+}
diff --git a/tools/mcp-server/src/types.d.ts b/tools/mcp-server/src/types.d.ts
new file mode 100644
index 000000000..e1e0dbf05
--- /dev/null
+++ b/tools/mcp-server/src/types.d.ts
@@ -0,0 +1,11 @@
+declare module 'pixelmatch' {
+ function pixelmatch(
+ img1: Buffer | Uint8Array,
+ img2: Buffer | Uint8Array,
+ output: Buffer | Uint8Array | null,
+ width: number,
+ height: number,
+ options?: { threshold?: number },
+ ): number;
+ export default pixelmatch;
+}
diff --git a/tools/mcp-server/tsconfig.json b/tools/mcp-server/tsconfig.json
new file mode 100644
index 000000000..bc748576d
--- /dev/null
+++ b/tools/mcp-server/tsconfig.json
@@ -0,0 +1,14 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "Node16",
+ "moduleResolution": "Node16",
+ "outDir": "dist",
+ "rootDir": "src",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "declaration": true
+ },
+ "include": ["src"]
+}