ue-mcp 1.3.9 → 1.3.10-beta.10

package/README.md

@@ -5,9 +5,12 @@
 [![stars](https://img.shields.io/github/stars/db-lyon/ue-mcp)](https://github.com/db-lyon/ue-mcp/stargazers)
 [![MIT](https://img.shields.io/npm/l/ue-mcp)](LICENSE)
 
-**Unreal Engine Model Context Protocol Server** - gives AI assistants deep read/write access to the Unreal Editor through <!-- count:tools -->26<!-- /count --> category tools covering <!-- count:actions -->1933+<!-- /count --> actions, plus a YAML flow engine for multi-step workflows and an npm plugin system for extending the surface.
+<img width="1354" height="586" alt="{6F52BA62-D736-454E-AD30-A1C98F9EEBAA}" src="https://github.com/user-attachments/assets/9380e080-c608-4609-ba21-90e6b0a3ba7f" />
 
-That total is <!-- count:ownActions -->1103+<!-- /count --> actions of ue-mcp's own plus Epic's entire native AI Toolset Registry: on UE 5.8+ its <!-- count:nativeToolActions -->830<!-- /count --> official Unreal tools are called in-process and surfaced as `epic_*` actions in the matching category, Sequencer in `animation`, PCG in `pcg`, static meshes in `asset`.
+
+**Unreal Engine Model Context Protocol Server** - gives AI assistants deep read/write access to the Unreal Editor through <!-- count:tools -->26<!-- /count --> category tools covering <!-- count:actions -->1972+<!-- /count --> actions, plus a YAML flow engine for multi-step workflows and an npm plugin system for extending the surface.
+
+That total is <!-- count:ownActions -->1142+<!-- /count --> actions of ue-mcp's own plus Epic's entire native AI Toolset Registry: on UE 5.8+ its <!-- count:nativeToolActions -->830<!-- /count --> official Unreal tools are called in-process and surfaced as `epic_*` actions in the matching category, Sequencer in `animation`, PCG in `pcg`, static meshes in `asset`.
 
 ```mermaid
 flowchart LR
@@ -35,7 +38,7 @@ The interactive setup will:
 4. Enable required UE plugins (Niagara, PCG, GAS, etc.)
 5. Detect and configure your MCP client (Claude Code, Claude Desktop, Cursor, Codex)
 
-Restart the editor once after setup to load the bridge plugin. To update later: `npx ue-mcp update`
+Restart the editor once after setup to load the bridge plugin. To update later, run `npx ue-mcp update` from the project directory. It updates the npm package, redeploys the C++ plugin and rebuilds it.
 
 Then talk to your AI in plain English:
 
@@ -65,7 +68,7 @@ If you prefer to configure manually, add to your MCP client config:
   "mcpServers": {
     "ue-mcp": {
       "command": "npx",
-      "args": ["ue-mcp", "C:/path/to/MyGame.uproject"]
+      "args": ["-y", "ue-mcp@latest", "C:/path/to/MyGame.uproject"]
     }
   }
 }
@@ -139,7 +142,7 @@ flows:
 flow(action="run", flowName="build_and_check")
 ```
 
-Every one of the <!-- count:actions -->1933+<!-- /count --> actions is also a flow task. Flows support step references, retries, rollback, custom tasks in your own `.js`/`.ts`, and shell steps. See [Flows](https://ue-mcp.com/docs/flows/).
+Every one of the <!-- count:actions -->1972+<!-- /count --> actions is also a flow task. Flows support step references, retries, rollback, custom tasks in your own `.js`/`.ts`, and shell steps. See [Flows](https://ue-mcp.com/docs/flows/).
 
 ## Plugins
 
@@ -194,8 +197,6 @@ Editor process control (`editor(start_editor)` / `stop_editor` / `restart_editor
 - [Tool Reference](https://ue-mcp.com/docs/tool-reference/) - Every tool, action, and parameter
 - [Architecture](https://ue-mcp.com/docs/architecture/) - How the server, bridge, and editor fit together
 - [Flows](https://ue-mcp.com/docs/flows/) - Multi-step YAML workflows, custom tasks, rollback
-- [Journal](https://ue-mcp.com/docs/journal/) - The per-project record of what a session did, produced, and how it ended
-- [Skill Packs](https://ue-mcp.com/docs/skill-packs/) - Written workflows an agent reads, and checking that the calls they teach still exist
 - [Plugins](https://ue-mcp.com/docs/plugins/) - Extending the surface through npm
 - [Configuration](https://ue-mcp.com/docs/configuration/) - `ue-mcp.yml` and MCP client config
 - [Troubleshooting](https://ue-mcp.com/docs/troubleshooting/) - Connection, build, and asset path issues

package/dist/bridge/bridge-parity.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Does the plugin we reached actually implement what we advertise? (#1021)
+ *
+ * `pluginBuildStale` answers a different question. It compares timestamps: is
+ * the compiled bridge older than its source. That catches the common cause of
+ * a missing handler and is worth reporting, but it is not evidence about the
+ * handlers themselves, and a report against 1.2.4 said so exactly: a session
+ * reported `pluginBuildStale: false` while an advertised method was absent,
+ * and every discovery of that came one failed call at a time.
+ *
+ * The evidence has been on the wire the whole time. The handshake carries the
+ * registered method list read out of the running binary, which the C++ that
+ * builds it describes as the only answer a stale DLL cannot fake. Nothing
+ * compared it to the surface, so it was used to word an error AFTER a call had
+ * already failed and never to say anything beforehand.
+ *
+ * This compares them. What comes out is not a guess about why a method is
+ * missing, and deliberately so: a plugin behind its source, a plugin from
+ * another checkout, a partially deployed one and a handler that failed to
+ * register all look identical from here, and naming one of them would be
+ * inventing a cause. It reports WHICH advertised methods the running plugin
+ * does not have, which is the fact, and leaves the diagnosis to the reader.
+ */
+import type { BridgeCapabilities } from "./bridge.js";
+import type { ToolDef } from "../core/types.js";
+import { type HandlerSpecs } from "../surface/handler-spec.js";
+export interface BridgeParity {
+    /** False when the plugin published no action list, so nothing was compared. */
+    checked: boolean;
+    /** Distinct bridge methods the advertised surface can dispatch to. */
+    advertised: number;
+    /** Methods the running plugin registered. */
+    registered: number;
+    /**
+     * Advertised methods the running plugin does not have, sorted. Every one is
+     * a call that will come back "Unknown method".
+     */
+    missing: string[];
+    /** One line for a caller to surface, or null when there is nothing to say. */
+    message: string | null;
+}
+/**
+ * Compare the advertised surface against what the connected plugin registered.
+ *
+ * `graph` is the tool graph this server actually dispatches, so a category the
+ * user disabled and a plugin's injected actions are counted as they really
+ * are rather than from the pristine declaration.
+ */
+export declare function checkBridgeParity(graph: ToolDef[], capabilities: BridgeCapabilities | null | undefined): BridgeParity;
+/**
+ * What the binary that answered says about itself, or undefined when nothing
+ * answered or it had nothing to add.
+ *
+ * `project(get_status)` already reports `pluginBuildStale` and
+ * `bridgeApiVersion`, and both are read off the SOURCE and the header on disk.
+ * `docs/architecture.md` states that distinction and it is the useful one, so
+ * the running binary's own account lives here as one field rather than as
+ * three more siblings next to them.
+ *
+ * Undefined on a healthy connected session, so a status payload only grows
+ * when there is something to say.
+ */
+export declare function deployedPlugin(capabilities: BridgeCapabilities | null | undefined, parity: BridgeParity, recordedSpecs?: HandlerSpecs): {
+    builtAt?: string;
+    missingActions?: number;
+    warning?: string;
+    handlerSpecDrift?: string[];
+    handlerSpecWarning?: string;
+} | undefined;
+/**
+ * The same comparison the other way: methods the plugin has that nothing
+ * advertises.
+ *
+ * Not a defect and not reported by default. A handler can exist under an
+ * alternate spelling, or ship ahead of the TypeScript that will expose it, and
+ * `scripts/audit-handlers.mjs` is where that question is asked properly with
+ * the alternate-spelling table to hand. Here for a caller that wants the whole
+ * picture rather than only the half that breaks calls.
+ */
+export declare function unadvertisedMethods(graph: ToolDef[], capabilities: BridgeCapabilities | null | undefined): string[];

package/dist/bridge/bridge-parity.js

@@ -0,0 +1,115 @@
+import { compareHandlerSpecs } from "../surface/handler-spec.js";
+import { RECORDED_HANDLER_SPECS } from "../tools/specs/index.js";
+/** How many missing methods to name before summarising the rest. */
+const NAMED = 8;
+/**
+ * Compare the advertised surface against what the connected plugin registered.
+ *
+ * `graph` is the tool graph this server actually dispatches, so a category the
+ * user disabled and a plugin's injected actions are counted as they really
+ * are rather than from the pristine declaration.
+ */
+export function checkBridgeParity(graph, capabilities) {
+    const registered = capabilities?.actions;
+    if (!Array.isArray(registered) || registered.length === 0) {
+        // An older plugin that predates the action list in the handshake. Silent
+        // rather than alarming: nothing was compared, so nothing is known, and
+        // saying "0 missing" would be the same false assurance this module exists
+        // to remove.
+        return { checked: false, advertised: 0, registered: 0, missing: [], message: null };
+    }
+    const have = new Set(registered);
+    const advertised = new Set();
+    for (const tool of graph) {
+        for (const spec of Object.values(tool.actions)) {
+            if (spec.kind === "bridge")
+                advertised.add(spec.bridge);
+        }
+    }
+    const missing = [...advertised].filter((m) => !have.has(m)).sort();
+    return {
+        checked: true,
+        advertised: advertised.size,
+        registered: registered.length,
+        missing,
+        message: missing.length === 0 ? null : describe(missing, advertised.size, registered.length),
+    };
+}
+function describe(missing, advertised, registered) {
+    const named = missing.slice(0, NAMED).join(", ");
+    const rest = missing.length > NAMED ? `, and ${missing.length - NAMED} more` : "";
+    return (`${missing.length} of the ${advertised} bridge methods this server advertises are not `
+        + `registered by the plugin it is connected to (${registered} registered): ${named}${rest}. `
+        + "Calling one returns 'Unknown method'. The usual cause is a deployed plugin behind this "
+        + "package: npm update alone never reaches the editor. Run `ue-mcp update --build` in the "
+        + "project (or `ue-mcp deploy` then `ue-mcp build`), then restart the editor. "
+        + "This is read from the running binary's own handler list, so it holds whatever the build "
+        + "timestamps say.");
+}
+/**
+ * What the binary that answered says about itself, or undefined when nothing
+ * answered or it had nothing to add.
+ *
+ * `project(get_status)` already reports `pluginBuildStale` and
+ * `bridgeApiVersion`, and both are read off the SOURCE and the header on disk.
+ * `docs/architecture.md` states that distinction and it is the useful one, so
+ * the running binary's own account lives here as one field rather than as
+ * three more siblings next to them.
+ *
+ * Undefined on a healthy connected session, so a status payload only grows
+ * when there is something to say.
+ */
+export function deployedPlugin(capabilities, parity, recordedSpecs = RECORDED_HANDLER_SPECS) {
+    if (!capabilities)
+        return undefined;
+    const missing = parity.missing.length > 0 ? parity.missing.length : undefined;
+    // #1057: the spec'd actions' parameters were generated from a recording of
+    // the plugin's own specs. A running plugin whose specs differ is one whose
+    // handlers read something other than what this server advertises.
+    const specs = compareHandlerSpecs(recordedSpecs, capabilities.handlerSpecs);
+    const drift = specs.drifted.length > 0 ? specs.drifted : undefined;
+    // The build time is the half that catches a handler which is PRESENT and
+    // old. #1002 was a DataTable resolution fix that shipped on 2026-08-28 and
+    // was reported as broken three days later by a session whose deployed plugin
+    // predated it, and nothing in reach said so: parity sees an absent method,
+    // not a stale one.
+    const builtAt = capabilities.builtAt;
+    if (!builtAt && missing === undefined && drift === undefined)
+        return undefined;
+    return {
+        builtAt,
+        missingActions: missing,
+        warning: parity.message ?? undefined,
+        handlerSpecDrift: drift,
+        handlerSpecWarning: drift
+            ? `${drift.length} handler parameter spec(s) differ between the running plugin and the recording this server `
+                + `advertises from: ${drift.slice(0, NAMED).join(", ")}${drift.length > NAMED ? `, and ${drift.length - NAMED} more` : ""}. `
+                + "Either the plugin is behind this package (rebuild it), or the specs changed and need "
+                + "npm run specs:record then npm run specs:generate."
+            : undefined,
+    };
+}
+/**
+ * The same comparison the other way: methods the plugin has that nothing
+ * advertises.
+ *
+ * Not a defect and not reported by default. A handler can exist under an
+ * alternate spelling, or ship ahead of the TypeScript that will expose it, and
+ * `scripts/audit-handlers.mjs` is where that question is asked properly with
+ * the alternate-spelling table to hand. Here for a caller that wants the whole
+ * picture rather than only the half that breaks calls.
+ */
+export function unadvertisedMethods(graph, capabilities) {
+    const registered = capabilities?.actions;
+    if (!Array.isArray(registered))
+        return [];
+    const advertised = new Set();
+    for (const tool of graph) {
+        for (const spec of Object.values(tool.actions)) {
+            if (spec.kind === "bridge")
+                advertised.add(spec.bridge);
+        }
+    }
+    return registered.filter((m) => !advertised.has(m)).sort();
+}
+//# sourceMappingURL=bridge-parity.js.map

package/dist/bridge/bridge-parity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-parity.js","sourceRoot":"","sources":["../../src/bridge/bridge-parity.ts"],"names":[],"mappings":"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"}

package/dist/bridge/bridge-timeouts.d.ts

@@ -0,0 +1,37 @@
+/** What a method with no registered timeout gets. Unchanged from before. */
+export declare const DEFAULT_BRIDGE_TIMEOUT_MS = 30000;
+/**
+ * Slack added on top of a server-registered timeout, so the client outlives the
+ * server's own deadline and can report the server's error instead of its own
+ * guess. Without it the two expire together and the race decides which message
+ * the user sees.
+ */
+export declare const SERVER_TIMEOUT_MARGIN_MS = 5000;
+/** Upper bound on any single call, caller-supplied included. */
+export declare const MAX_BRIDGE_TIMEOUT_MS = 3600000;
+/** Environment override for the floor under every call, in milliseconds. */
+export declare const TIMEOUT_ENV_VAR: "UE_MCP_BRIDGE_TIMEOUT_MS";
+/**
+ * Mirror of every FMCPHandlerRegistry::RegisterHandlerWithTimeout call in
+ * plugin/, in seconds, keyed by bridge method name.
+ *
+ * Keep it in the order the parity test reads it: alphabetical by method.
+ * External handlers registered at runtime through
+ * RegisterExternalHandlerWithTimeout are not here and cannot be, since they
+ * come from plugins this repo does not build.
+ */
+export declare const REGISTERED_HANDLER_TIMEOUT_SECONDS: Readonly<Record<string, number>>;
+/** What the editor will wait for this method, in ms, or undefined for the default. */
+export declare function registeredTimeoutMs(method: string): number | undefined;
+/** The floor under every call: the env override when it is a usable number. */
+export declare function environmentTimeoutMs(env?: NodeJS.ProcessEnv): number | undefined;
+/**
+ * How long to wait for `method`.
+ *
+ * An explicit per-call value wins outright, including a shorter one: a caller
+ * that asks for less has said so on purpose. Otherwise the answer is the
+ * longest of the default, the environment floor, and the server's own
+ * registered limit plus its margin, so the client never gives up on a call the
+ * editor is still allowed to be working on.
+ */
+export declare function resolveBridgeTimeout(method: string, explicitMs?: number, env?: NodeJS.ProcessEnv): number;

package/dist/bridge/bridge-timeouts.js

@@ -0,0 +1,150 @@
+/**
+ * How long the client waits for a bridge call to answer (#989).
+ *
+ * The client waited a flat 30 seconds for every method. Two things were wrong
+ * with that, and both produce the same bad outcome: the editor completes the
+ * operation, the client reports a failure, and a naive retry applies the
+ * mutation a second time.
+ *
+ *  1. Some calls are simply long. A 190-item batch on a machine that is also
+ *     compiling shaders does not finish inside 30 seconds. Callers can now pass
+ *     a `timeoutMs` and be believed.
+ *
+ *  2. The two ends disagreed. The C++ side registers a per-handler timeout via
+ *     FMCPHandlerRegistry::RegisterHandlerWithTimeout, and the game-thread
+ *     executor waits that long before giving up. delete_exact_labeled_actors_in_levels
+ *     is allowed 300 seconds there and was cut off by the client at 30, so the
+ *     server's own limit could never be reached and its error could never be
+ *     read. The client now waits at least as long as the server said it would.
+ *
+ * The registered timeouts are NOT advertised. get_bridge_capabilities publishes
+ * the protocol version, the feature list and the registered action names, but
+ * not their timeouts, so there is no way to read this off the wire from a
+ * plugin that is already built. Inventing a field would mean a protocol change
+ * on the C++ side. The table below therefore mirrors the registrations by hand,
+ * and tests/unit/bridge-timeout-parity.test.ts parses the plugin sources and
+ * fails when the two drift apart. A mirror nobody checks is worse than none.
+ */
+import { ENV_VARS, readEnv } from "../core/env.js";
+/** What a method with no registered timeout gets. Unchanged from before. */
+export const DEFAULT_BRIDGE_TIMEOUT_MS = 30_000;
+/**
+ * Slack added on top of a server-registered timeout, so the client outlives the
+ * server's own deadline and can report the server's error instead of its own
+ * guess. Without it the two expire together and the race decides which message
+ * the user sees.
+ */
+export const SERVER_TIMEOUT_MARGIN_MS = 5_000;
+/** Upper bound on any single call, caller-supplied included. */
+export const MAX_BRIDGE_TIMEOUT_MS = 3_600_000;
+/** Environment override for the floor under every call, in milliseconds. */
+export const TIMEOUT_ENV_VAR = ENV_VARS.bridgeTimeoutMs;
+/**
+ * Mirror of every FMCPHandlerRegistry::RegisterHandlerWithTimeout call in
+ * plugin/, in seconds, keyed by bridge method name.
+ *
+ * Keep it in the order the parity test reads it: alphabetical by method.
+ * External handlers registered at runtime through
+ * RegisterExternalHandlerWithTimeout are not here and cannot be, since they
+ * come from plugins this repo does not build.
+ */
+export const REGISTERED_HANDLER_TIMEOUT_SECONDS = {
+    analyze_landscape_terrain: 120,
+    apply_landscape_erosion: 600,
+    apply_mesh_fracture: 600,
+    apply_mesh_hole_fill: 300,
+    apply_mesh_mirror: 300,
+    apply_mesh_remesh: 300,
+    apply_mesh_simplify: 300,
+    audit_asset_hygiene: 300,
+    audit_blueprint_dead_code: 600,
+    batch_retarget_animations: 300,
+    batch_set_actor_properties: 300,
+    batch_set_foliage_settings_where: 300,
+    bulk_read_asset_properties: 300,
+    bulk_restore_data_assets: 120,
+    bulk_set_component_property: 300,
+    bulk_upsert_data_assets: 120,
+    compile_customizable_object: 600,
+    convert_brushes_to_static_mesh: 600,
+    create_cpp_class: 300,
+    delete_exact_labeled_actors_in_levels: 300,
+    export_blueprint_batch: 600,
+    export_landscape_heightmap: 300,
+    fix_asset_hygiene: 300,
+    fixup_redirectors: 300,
+    generate_mesh_collision: 300,
+    get_blueprint_connections: 600,
+    get_landscape_height_region: 120,
+    get_landscape_holes: 120,
+    get_landscape_layer_weight_region: 120,
+    get_landscape_slope_map: 120,
+    import_landscape_heightmap: 600,
+    invoke_object_functions: 300,
+    live_coding_compile: 300,
+    load_actor_descs: 300,
+    merge_landscape_edit_layers: 300,
+    mesh_boolean: 300,
+    paint_landscape_layer: 120,
+    plan_real_world_landscape: 120,
+    query_components: 300,
+    read_blueprint_graph: 180,
+    rebuild_water_zone: 120,
+    recreate_physics_state: 300,
+    refresh_landscape_physical_material_collision: 600,
+    remove_components_by_class: 300,
+    render_sequence_frames: 600,
+    rerun_construction_scripts: 300,
+    run_automation_tests: 300,
+    sculpt_landscape: 120,
+    sculpt_landscape_region: 300,
+    search_blueprint_call_sites: 600,
+    search_blueprint_nodes: 600,
+    set_actor_hlod_layer: 300,
+    set_component_materials: 300,
+    set_landscape_height_region: 300,
+    set_landscape_holes: 300,
+    set_landscape_layer_weight_region: 300,
+    simulate_procedural_foliage: 600,
+    snap_instances_to_surface: 300,
+    spawn_actors_batch: 300,
+    summarize_static_mesh_usage: 300,
+    trigger_hitch: 30,
+};
+/** What the editor will wait for this method, in ms, or undefined for the default. */
+export function registeredTimeoutMs(method) {
+    const seconds = REGISTERED_HANDLER_TIMEOUT_SECONDS[method];
+    return seconds === undefined ? undefined : seconds * 1000;
+}
+/** The floor under every call: the env override when it is a usable number. */
+export function environmentTimeoutMs(env = process.env) {
+    const raw = readEnv("bridgeTimeoutMs", env);
+    if (raw === undefined || raw === "")
+        return undefined;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return undefined;
+    return Math.min(parsed, MAX_BRIDGE_TIMEOUT_MS);
+}
+/**
+ * How long to wait for `method`.
+ *
+ * An explicit per-call value wins outright, including a shorter one: a caller
+ * that asks for less has said so on purpose. Otherwise the answer is the
+ * longest of the default, the environment floor, and the server's own
+ * registered limit plus its margin, so the client never gives up on a call the
+ * editor is still allowed to be working on.
+ */
+export function resolveBridgeTimeout(method, explicitMs, env = process.env) {
+    if (typeof explicitMs === "number" && Number.isFinite(explicitMs) && explicitMs > 0) {
+        return Math.min(explicitMs, MAX_BRIDGE_TIMEOUT_MS);
+    }
+    const registered = registeredTimeoutMs(method);
+    const candidates = [
+        DEFAULT_BRIDGE_TIMEOUT_MS,
+        environmentTimeoutMs(env) ?? 0,
+        registered === undefined ? 0 : registered + SERVER_TIMEOUT_MARGIN_MS,
+    ];
+    return Math.min(Math.max(...candidates), MAX_BRIDGE_TIMEOUT_MS);
+}
+//# sourceMappingURL=bridge-timeouts.js.map

package/dist/bridge/bridge-timeouts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-timeouts.js","sourceRoot":"","sources":["../../src/bridge/bridge-timeouts.ts"],"names":[],"mappings":"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"}