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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat: add MCP server for AI-assisted editor integration
esengine4f5eed61a127
diff --git a/.mcp.json b/.mcp.jsonnew file mode 100644index 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.rsnew file mode 100644index 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.rsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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"]+}