@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/app/src/renderer/standard-automation-tools.js

@@ -0,0 +1,720 @@
+// ============================================================================
+// createStandardAutomationTools — the standard MCP automation tool set.
+//
+// Games previously hand-rolled ~10 identical tools in their mcp/setup.ts
+// (to-the-ocean, overburden, sandjongg): capture_screenshot, inject_input,
+// clear_injected_input, dispatch_key, dispatch_click, wait_for_condition,
+// set_test_state, get_player_state, get_world_state, get_ui_state, plus the
+// DOM-inspection trio (get_element_bounds, inspect_dom, get_element_style).
+//
+// This factory centralizes them. Everything game-specific is injected via
+// the context object — state providers, input injector, render hooks.
+//
+// Usage:
+//
+//   createMcpHarness({
+//     serverName: "downdraft-mygame-automation",
+//     tools: createStandardAutomationTools({
+//       canvas: () => renderer.getCanvas(),
+//       renderOnce: () => renderer.renderOnce(),
+//       input: () => renderer.getInputHandler(),   // { injectInput, clearInjectedInput }
+//       getPlayerState: (i) => readPlayer(i),
+//       getWorldState: () => readWorld(),
+//       getUiState: () => useGameStore.getState(),
+//       extraTools: [...gameSpecificTools],
+//     }),
+//   });
+// ============================================================================
+import { getHostCapabilities, KEY } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { downdraft } from "./index.js";
+import { blobToBase64, createMcpHarness, errorResult, jsonResult } from "./mcp-harness.js";
+const log = createLogger("info");
+// dispatch_click: real pointer input produces a pointer* event before its
+// compat mouse* event (pointerdown→mousedown, pointermove→mousemove,
+// pointerup→mouseup).
+const POINTER_COMPANION = {
+    mousedown: "pointerdown",
+    mouseup: "pointerup",
+    mousemove: "pointermove",
+};
+// DOM `buttons` bitmask per `button` index (0=left→1, 1=middle→4, 2=right→2).
+const MOUSE_BUTTON_MASK = [1, 4, 2];
+// dispatch_key: KeyboardEventInit carries no keyCode, but engine UI code
+// (e.g. UITextInput) reads it — derive the legacy DOM value from `key`.
+const DOM_KEY_CODES = {
+    Backspace: 8, Tab: 9, Enter: 13, Shift: 16, Control: 17, Alt: 18,
+    Pause: 19, CapsLock: 20, Escape: 27, " ": 32, PageUp: 33, PageDown: 34,
+    End: 35, Home: 36, ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39,
+    ArrowDown: 40, Insert: 45, Delete: 46, Meta: 91,
+};
+function domKeyCodeFor(key) {
+    if (key.length === 1) {
+        const c = key.toUpperCase().charCodeAt(0);
+        if (c >= 32 && c <= 126)
+            return c;
+    }
+    return DOM_KEY_CODES[key] ?? 0;
+}
+// ── Helpers ──
+const DEFAULT_KEY_MAP = { ...KEY };
+function resolveKeys(keys, keyMap) {
+    const out = new Set();
+    keys.forEach((k) => {
+        if (typeof k === "number")
+            out.add(k);
+        else {
+            const code = keyMap[k.toUpperCase()];
+            if (code !== undefined)
+                out.add(code);
+        }
+    });
+    return out;
+}
+function resolveSurface(surface) {
+    return typeof surface === "function" ? surface() : surface;
+}
+// ── Factory ──
+/**
+ * Build the standard MCP automation tool set. Returns McpToolRegistration[]
+ * suitable for `createMcpHarness({ tools })`.
+ */
+export function createStandardAutomationTools(ctx) {
+    const keyMap = { ...DEFAULT_KEY_MAP, ...ctx.keyMap };
+    const tools = [];
+    const want = (name) => {
+        if (ctx.include && !ctx.include.includes(name))
+            return false;
+        if (ctx.exclude?.includes(name))
+            return false;
+        return true;
+    };
+    // ── capture_screenshot ──
+    if (want("capture_screenshot")) {
+        tools.push({
+            def: {
+                name: "capture_screenshot",
+                description: "Capture the current frame as a PNG image. By default composites the game canvas with the UI overlay (HUD, menus, etc.). Set fullPage=false to capture only the game canvas. Returns the image inline as base64.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        fullPage: {
+                            type: "boolean",
+                            default: true,
+                            description: "If true, composite the game canvas + extra layers + DOM overlay. If false, capture only the game canvas.",
+                        },
+                    },
+                },
+            },
+            handler: async (params) => {
+                const surface = resolveSurface(ctx.surface);
+                if (!surface)
+                    return errorResult("Surface not available");
+                const fullPage = params.fullPage ?? ctx.fullPageDefault ?? true;
+                const width = surface.width;
+                const height = surface.height;
+                // If the render loop is paused (test/headless mode), render one frame
+                // first so the screenshot reflects current simulation state.
+                if (ctx.isRunning && !ctx.isRunning())
+                    ctx.renderOnce?.();
+                if (fullPage) {
+                    // Host capture: captureFrame() returns the fully composited
+                    // swapchain (game + all overlay layers) — no DOM composite
+                    // needed.
+                    if (typeof downdraft?.captureFrame === "function") {
+                        try {
+                            const framePng = await downdraft.captureFrame();
+                            if (framePng && framePng.byteLength > 0) {
+                                const u8 = new Uint8Array(framePng);
+                                let bin = "";
+                                for (let i = 0; i < u8.length; i += 0x8000) {
+                                    bin += String.fromCharCode(...u8.subarray(i, i + 0x8000));
+                                }
+                                const base64 = btoa(bin);
+                                return {
+                                    content: [
+                                        { type: "text", text: JSON.stringify({ width, height, fullPage: true }, null, 2) },
+                                        { type: "image", data: base64, mimeType: "image/png" },
+                                    ],
+                                };
+                            }
+                        }
+                        catch (e) {
+                            log.warn("mcp", `Host frame capture failed, falling back to canvas-only: ${e.message}`);
+                        }
+                    }
+                }
+                // Surface-only capture. toBlob is a canvas-compat API — it exists on
+                // HTMLCanvasElement and the native surface's canvas-compat layer,
+                // but is not part of the RenderSurface contract.
+                const toBlob = surface.toBlob;
+                if (typeof toBlob !== "function") {
+                    return errorResult("Screenshot capture requires canvas.toBlob or a host captureFrame()");
+                }
+                const blob = await new Promise((resolve) => {
+                    toBlob.call(surface, (b) => resolve(b), "image/png");
+                });
+                if (!blob)
+                    return errorResult("Screenshot capture failed");
+                const base64 = await blobToBase64(blob);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ width, height, fullPage: false }, null, 2) },
+                        { type: "image", data: base64, mimeType: "image/png" },
+                    ],
+                };
+            },
+        });
+    }
+    // ── inject_input ──
+    if (want("inject_input") && ctx.input) {
+        tools.push({
+            def: {
+                name: "inject_input",
+                description: "Inject keyboard/mouse input for a number of frames. Useful for automation tests when no real user is interacting with the game.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        playerIndex: { type: "number", description: "Player slot index", default: 0 },
+                        keys: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "Key names to hold (e.g. ['W','A','SPACE']) or keyCodes if numbers",
+                            default: [],
+                        },
+                        leftMouse: { type: "boolean", default: false },
+                        rightMouse: { type: "boolean", default: false },
+                        mouseDx: { type: "number", default: 0 },
+                        mouseDy: { type: "number", default: 0 },
+                        wheel: { type: "number", default: 0 },
+                        frames: { type: "number", description: "Number of frames to hold the input", default: 1 },
+                    },
+                },
+            },
+            handler: (params) => {
+                const input = ctx.input();
+                if (!input)
+                    return errorResult("Input handler not initialized");
+                const frames = Math.max(1, Math.floor(params.frames ?? 1));
+                input.injectInput({
+                    keys: resolveKeys(params.keys ?? [], keyMap),
+                    leftMouse: !!params.leftMouse,
+                    rightMouse: !!params.rightMouse,
+                    mouseDx: params.mouseDx ?? 0,
+                    mouseDy: params.mouseDy ?? 0,
+                    wheel: params.wheel ?? 0,
+                    framesRemaining: frames,
+                });
+                return jsonResult({ injected: true, frames, playerIndex: params.playerIndex ?? 0 });
+            },
+        });
+    }
+    // ── clear_injected_input ──
+    if (want("clear_injected_input") && ctx.input) {
+        tools.push({
+            def: {
+                name: "clear_injected_input",
+                description: "Clear any pending injected input frames.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            handler: () => {
+                const input = ctx.input();
+                if (!input)
+                    return errorResult("Input handler not initialized");
+                input.clearInjectedInput();
+                return jsonResult({ cleared: true });
+            },
+        });
+    }
+    // ── dispatch_key ──
+    if (want("dispatch_key")) {
+        tools.push({
+            def: {
+                name: "dispatch_key",
+                description: "Dispatch a real DOM keyboard event on the main thread (keydown or keyup). This tests the full input pipeline: DOM event → game handler.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        key: { type: "string", description: "Key value (e.g. 'i', 'Tab', 'Escape')" },
+                        code: { type: "string", description: "Key code (e.g. 'KeyI', 'Tab', 'Escape')" },
+                        type: { type: "string", enum: ["keydown", "keyup"], default: "keydown" },
+                        repeat: { type: "boolean", default: false },
+                    },
+                    required: ["key"],
+                },
+            },
+            handler: (params) => {
+                const key = params.key;
+                const code = params.code ?? key;
+                const type = params.type ?? "keydown";
+                const ev = new KeyboardEvent(type, {
+                    key, code, keyCode: domKeyCodeFor(key),
+                    bubbles: true, cancelable: true, repeat: !!params.repeat,
+                });
+                // Real KeyboardEvent ignores keyCode in the init dict — force it.
+                try {
+                    Object.defineProperty(ev, "keyCode", { value: domKeyCodeFor(key) });
+                }
+                catch { /* polyfill already set it */ }
+                window.dispatchEvent(ev);
+                return jsonResult({ dispatched: true, key, code, type });
+            },
+        });
+    }
+    // ── dispatch_click ──
+    if (want("dispatch_click")) {
+        tools.push({
+            def: {
+                name: "dispatch_click",
+                description: "Dispatch a real DOM click event at canvas-relative coordinates. The event hits the topmost element at that point (mimics a real user click through UI overlays).",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        x: { type: "number", description: "X coordinate (default: center of canvas)" },
+                        y: { type: "number", description: "Y coordinate (default: center of canvas)" },
+                        type: { type: "string", enum: ["click", "mousedown", "mouseup", "mousemove", "wheel"], default: "click", description: "Event type — 'click' fires the full press/release sequence (pointerdown→mousedown→pointerup→mouseup→click); mousedown/mouseup/mousemove fire just that event plus its pointer* companion. 'wheel' fires a WheelEvent with deltaX/deltaY." },
+                        button: { type: "number", description: "Mouse button (0=left, 1=middle, 2=right). Default 0." },
+                        deltaX: { type: "number", description: "Wheel deltaX in pixels (type=wheel only). Default 0." },
+                        deltaY: { type: "number", description: "Wheel deltaY in pixels (type=wheel only). Default 120 (one detent down)." },
+                    },
+                },
+            },
+            handler: (params) => {
+                const surface = resolveSurface(ctx.surface);
+                if (!surface)
+                    return errorResult("Surface not available");
+                const x = params.x ?? surface.clientWidth / 2;
+                const y = params.y ?? surface.clientHeight / 2;
+                const type = params.type ?? "click";
+                const button = params.button ?? 0;
+                const rect = surface.getBoundingClientRect();
+                const clientX = rect.left + x;
+                const clientY = rect.top + y;
+                const hasDom = getHostCapabilities().hasDom;
+                // DOM hosts hit-test the topmost element (mimics a real user click
+                // through UI overlays). On native there is no DOM tree — the surface
+                // itself is the input target.
+                const target = hasDom
+                    ? (document.elementFromPoint(clientX, clientY) ?? surface)
+                    : surface;
+                // MiniEventTarget (native event polyfill) has no capture/bubble —
+                // mirror real propagation by also dispatching on window. In a real
+                // DOM this would double-fire, so only do it under the polyfill.
+                const isNativeDom = !hasDom;
+                const fire = (ev) => {
+                    target.dispatchEvent(ev);
+                    if (isNativeDom)
+                        window.dispatchEvent?.(ev);
+                };
+                if (type === "wheel") {
+                    const deltaX = params.deltaX ?? 0;
+                    const deltaY = params.deltaY ?? 120;
+                    fire(new WheelEvent("wheel", {
+                        bubbles: true, cancelable: true, clientX, clientY, deltaX, deltaY, deltaMode: 0,
+                    }));
+                    return jsonResult({ dispatched: true, x, y, type, deltaX, deltaY });
+                }
+                // Real pointer input produces the pointer* event before its compat
+                // mouse* event. RendererInputBus listens on pointer*; older UI code
+                // listens on mouse* — emit both so either sees a real click.
+                const PtrEvent = globalThis.PointerEvent;
+                const downMask = MOUSE_BUTTON_MASK[button] ?? 1;
+                const fireOne = (name, isPointer, buttons) => {
+                    if (isPointer && PtrEvent) {
+                        fire(new PtrEvent(name, {
+                            bubbles: true, cancelable: true, clientX, clientY, button, buttons,
+                            pointerId: 1, pointerType: "mouse", isPrimary: true,
+                        }));
+                    }
+                    else if (!isPointer) {
+                        fire(new MouseEvent(name, { bubbles: true, cancelable: true, clientX, clientY, button, buttons }));
+                    }
+                };
+                if (type === "click") {
+                    // A real click is a full press/release cycle — UI hit-testing needs
+                    // the pointerdown→pointerup pair to register press and click.
+                    fireOne("pointerdown", true, downMask);
+                    fireOne("mousedown", false, downMask);
+                    fireOne("pointerup", true, 0);
+                    fireOne("mouseup", false, 0);
+                    fireOne("click", false, 0);
+                }
+                else {
+                    const buttons = type === "mouseup" || type === "mousemove" ? 0 : downMask;
+                    const pointerType = POINTER_COMPANION[type];
+                    if (pointerType)
+                        fireOne(pointerType, true, buttons);
+                    fireOne(type, false, buttons);
+                }
+                const targetEl = target;
+                return jsonResult({
+                    dispatched: true, x, y, type,
+                    targetTag: targetEl.tagName ?? targetEl.id ?? "surface",
+                    targetClass: targetEl.className?.toString().slice(0, 80),
+                });
+            },
+        });
+    }
+    // ── wait_for_condition ──
+    if (want("wait_for_condition")) {
+        tools.push({
+            def: {
+                name: "wait_for_condition",
+                description: "Poll until a condition on game state is met or a timeout occurs. Conditions are JS predicate expressions evaluated against named state variables (e.g. 'player.position[1] < -2').",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        condition: {
+                            type: "string",
+                            description: "JavaScript predicate expression. Variables: player, world, tick (when providers configured) plus any conditionVars.",
+                        },
+                        timeoutMs: { type: "number", default: 5000, description: "Maximum time to wait in milliseconds" },
+                        intervalMs: { type: "number", default: 50, description: "Polling interval" },
+                    },
+                    required: ["condition"],
+                },
+            },
+            handler: async (params) => {
+                const condition = params.condition;
+                const timeoutMs = params.timeoutMs ?? 5000;
+                const intervalMs = params.intervalMs ?? 50;
+                const start = performance.now();
+                const extraNames = Object.keys(ctx.conditionVars ?? {});
+                const names = ["player", "world", "tick", ...extraNames];
+                return new Promise((resolve) => {
+                    const check = async () => {
+                        const player = ctx.getPlayerState?.(0) ?? null;
+                        const world = (await ctx.getWorldState?.()) ?? null;
+                        const tick = world?.tick ?? 0;
+                        const extraValues = extraNames.map((n) => ctx.conditionVars[n]());
+                        try {
+                            // eslint-disable-next-line no-new-func
+                            const fn = new Function(...names, `"use strict"; return (${condition});`);
+                            if (fn(player, world, tick, ...extraValues)) {
+                                resolve(jsonResult({ satisfied: true, elapsedMs: performance.now() - start, player, world }));
+                                return;
+                            }
+                        }
+                        catch (e) {
+                            resolve(errorResult(`Condition evaluation error: ${e.message}`));
+                            return;
+                        }
+                        if (performance.now() - start > timeoutMs) {
+                            resolve(errorResult(`Timeout waiting for condition: ${condition}`));
+                            return;
+                        }
+                        setTimeout(check, intervalMs);
+                    };
+                    check();
+                });
+            },
+        });
+    }
+    // ── set_test_state ──
+    if (want("set_test_state") && (ctx.setTestState || ctx.pauseRendering || ctx.resumeRendering || ctx.setTargetFPS)) {
+        tools.push({
+            def: {
+                name: "set_test_state",
+                description: "Set deterministic game state for tests. Built-in keys: pauseRendering, resumeRendering, targetFPS. Additional keys are forwarded to the game's setTestState handler.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        pauseRendering: { type: "boolean", description: "Pause the continuous render loop to save CPU. Screenshot capture still works (renders on demand)." },
+                        resumeRendering: { type: "boolean", description: "Resume the continuous render loop." },
+                        targetFPS: { type: "number", description: "Set a target FPS limit for the render loop (0 = unlimited)." },
+                    },
+                },
+            },
+            handler: async (params) => {
+                if (params.pauseRendering)
+                    ctx.pauseRendering?.();
+                if (params.resumeRendering)
+                    ctx.resumeRendering?.();
+                if (params.targetFPS !== undefined)
+                    ctx.setTargetFPS?.(params.targetFPS);
+                if (ctx.setTestState) {
+                    const { pauseRendering: _p, resumeRendering: _r, targetFPS: _t, ...rest } = params;
+                    await ctx.setTestState(rest);
+                }
+                return jsonResult({ applied: true, params });
+            },
+        });
+    }
+    // ── get_player_state ──
+    if (want("get_player_state") && ctx.getPlayerState) {
+        tools.push({
+            def: {
+                name: "get_player_state",
+                description: "Read the current state of a player from the simulation SharedArrayBuffer.",
+                inputSchema: {
+                    type: "object",
+                    properties: { playerIndex: { type: "number", default: 0 } },
+                },
+            },
+            handler: (params) => {
+                const playerIndex = params.playerIndex;
+                const state = ctx.getPlayerState(playerIndex);
+                if (state === null || state === undefined)
+                    return errorResult(`Player ${playerIndex} not available`);
+                return jsonResult(state);
+            },
+        });
+    }
+    // ── get_world_state ──
+    if (want("get_world_state") && ctx.getWorldState) {
+        tools.push({
+            def: {
+                name: "get_world_state",
+                description: "Read global simulation state (tick, entity count, weather, etc.).",
+                inputSchema: { type: "object", properties: {} },
+            },
+            handler: async () => {
+                const state = await ctx.getWorldState();
+                if (state === null || state === undefined)
+                    return errorResult("World state not available");
+                return jsonResult(state);
+            },
+        });
+    }
+    // ── get_ui_state ──
+    if (want("get_ui_state") && ctx.getUiState) {
+        tools.push({
+            def: {
+                name: "get_ui_state",
+                description: "Read the current UI store state (menu visibility, pointer lock, readiness flags, etc.).",
+                inputSchema: { type: "object", properties: {} },
+            },
+            handler: () => jsonResult(ctx.getUiState()),
+        });
+    }
+    // ── get_element_bounds ──
+    if (want("get_element_bounds")) {
+        tools.push({
+            def: {
+                name: "get_element_bounds",
+                description: "Get the bounding box of a DOM element matching a CSS selector. Returns {x, y, width, height, top, left, bottom, right} or found:false.",
+                inputSchema: {
+                    type: "object",
+                    properties: { selector: { type: "string", description: "CSS selector" } },
+                    required: ["selector"],
+                },
+            },
+            handler: (params) => {
+                const selector = params.selector;
+                try {
+                    const el = document.querySelector(selector);
+                    if (!el)
+                        return jsonResult({ found: false, selector });
+                    const rect = el.getBoundingClientRect();
+                    return jsonResult({
+                        found: true, selector,
+                        x: rect.x, y: rect.y, width: rect.width, height: rect.height,
+                        top: rect.top, left: rect.left, bottom: rect.bottom, right: rect.right,
+                    });
+                }
+                catch (e) {
+                    return errorResult(`Failed to query selector "${selector}": ${e.message}`);
+                }
+            },
+        });
+    }
+    // ── inspect_dom ──
+    if (want("inspect_dom")) {
+        tools.push({
+            def: {
+                name: "inspect_dom",
+                description: "Inspect the main thread's DOM for debugging CSS/layout issues. 'stylesheets' lists all <style>/<link> tags; 'element' gets details for a selector.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        action: { type: "string", enum: ["stylesheets", "element"] },
+                        selector: { type: "string", description: "CSS selector (for action='element')" },
+                    },
+                    required: ["action"],
+                },
+            },
+            handler: (params) => {
+                if (!getHostCapabilities().hasDom) {
+                    return errorResult("inspect_dom requires a real DOM — the native host's document is a canvas-compat facade, not a DOM tree");
+                }
+                const action = params.action;
+                if (action === "stylesheets") {
+                    const styles = Array.from(document.querySelectorAll("style, link[rel='stylesheet']")).map((el) => {
+                        const tag = el.tagName.toLowerCase();
+                        if (tag === "style") {
+                            const text = el.textContent ?? "";
+                            return { tag, length: text.length, preview: text.slice(0, 200) };
+                        }
+                        return { tag, href: el.href };
+                    });
+                    return jsonResult({ stylesheets: styles, count: styles.length });
+                }
+                if (action === "element" && params.selector) {
+                    const el = document.querySelector(params.selector);
+                    if (!el)
+                        return jsonResult({ found: false, selector: params.selector });
+                    const cs = getComputedStyle(el);
+                    return jsonResult({
+                        found: true,
+                        selector: params.selector,
+                        tagName: el.tagName,
+                        className: el.className,
+                        id: el.id,
+                        style: {
+                            width: cs.width, height: cs.height,
+                            maxWidth: cs.maxWidth, maxHeight: cs.maxHeight,
+                            display: cs.display, position: cs.position,
+                            top: cs.top, left: cs.left, overflow: cs.overflow,
+                        },
+                        bounds: el.getBoundingClientRect().toJSON(),
+                        childCount: el.children.length,
+                    });
+                }
+                return errorResult("Invalid action or missing selector");
+            },
+        });
+    }
+    // ── get_element_style ──
+    if (want("get_element_style")) {
+        tools.push({
+            def: {
+                name: "get_element_style",
+                description: "Get computed style of a DOM element matching a CSS selector. Pass properties[] to read specific CSS properties.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        selector: { type: "string", description: "CSS selector" },
+                        properties: { type: "array", items: { type: "string" }, description: "CSS properties to read" },
+                    },
+                    required: ["selector"],
+                },
+            },
+            handler: (params) => {
+                if (!getHostCapabilities().hasDom) {
+                    return errorResult("get_element_style requires a real DOM — no computed styles on the native host");
+                }
+                const selector = params.selector;
+                const props = params.properties ?? [];
+                try {
+                    const el = document.querySelector(selector);
+                    if (!el)
+                        return jsonResult({ found: false, selector });
+                    const cs = getComputedStyle(el);
+                    const result = { found: true, selector };
+                    props.forEach((p) => { result[p] = cs.getPropertyValue(p); ; });
+                    result._className = el.className;
+                    return jsonResult(result);
+                }
+                catch (e) {
+                    return errorResult(`Failed to query style for "${selector}": ${e.message}`);
+                }
+            },
+        });
+    }
+    // ── inspectable_list / inspectable_get / inspectable_set ──
+    const inspectables = ctx.inspectables;
+    if (want("inspectable_list") && inspectables) {
+        tools.push({
+            def: {
+                name: "inspectable_list",
+                description: "List the game's inspectable state nodes — schema'd read/write points over game state " +
+                    "(player customization, settings, etc.). Returns each node's path, type, valid " +
+                    "range/options, readOnly flag, and current value. Mutate them with inspectable_set " +
+                    "instead of synthesizing input — writes run through the game's normal apply pipeline.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        prefix: { type: "string", description: "Limit to nodes under this path prefix (e.g. 'player.customization')" },
+                        tree: { type: "boolean", default: false, description: "Also return a nested tree keyed by path segments" },
+                    },
+                },
+            },
+            handler: (params) => {
+                const prefix = params.prefix;
+                const nodes = inspectables.list(prefix).map((info) => {
+                    let value, error;
+                    try {
+                        value = inspectables.get(info.path).value;
+                    }
+                    catch (e) {
+                        error = e.message;
+                    }
+                    return { ...info, value, error };
+                });
+                return jsonResult({
+                    nodes,
+                    ...(params.tree ? { tree: inspectables.tree(prefix) } : {}),
+                });
+            },
+        });
+    }
+    if (want("inspectable_get") && inspectables) {
+        tools.push({
+            def: {
+                name: "inspectable_get",
+                description: "Read the current value and schema of a single inspectable node. Discover paths with inspectable_list.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Node path (e.g. 'player.customization.girth')" },
+                    },
+                    required: ["path"],
+                },
+            },
+            handler: (params) => {
+                const path = params.path;
+                try {
+                    return jsonResult({ ...inspectables.describe(path), ...inspectables.get(path) });
+                }
+                catch (e) {
+                    return errorResult(e.message);
+                }
+            },
+        });
+    }
+    if (want("inspectable_set") && inspectables) {
+        tools.push({
+            def: {
+                name: "inspectable_set",
+                description: "Write a value to an inspectable node (see inspectable_list for paths, types, and valid " +
+                    "options/ranges). The write is validated then routed through the game's apply function — " +
+                    "engine side-effects (mesh re-resolution, sim dispatch, saves) happen as if the game's " +
+                    "own UI had made the change. Returns the post-write value.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        path: { type: "string", description: "Node path (e.g. 'player.customization.girth')" },
+                        value: { description: "JSON value matching the node's declared type" },
+                    },
+                    required: ["path", "value"],
+                },
+            },
+            handler: async (params) => {
+                try {
+                    const res = await inspectables.set(params.path, params.value);
+                    return jsonResult({ applied: true, ...res });
+                }
+                catch (e) {
+                    return errorResult(e.message);
+                }
+            },
+        });
+    }
+    return [...tools, ...(ctx.extraTools ?? [])];
+}
+export function createGameMcp(opts) {
+    const { appId, tools, serverVersion, ...ctx } = opts;
+    try {
+        createMcpHarness({
+            serverName: `${appId}-automation`,
+            serverVersion,
+            tools: createStandardAutomationTools({
+                ...ctx,
+                extraTools: [...(ctx.extraTools ?? []), ...(tools ?? [])],
+            }),
+        });
+    }
+    catch (e) {
+        log.warn("mcp", `${appId} automation harness setup failed (non-fatal): ${e}`);
+    }
+}