ue-mcp 1.1.44 → 1.2.0-beta.2

package/README.md

@@ -5,7 +5,7 @@
 [![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 -->24<!-- /count --> category tools covering <!-- count:actions -->760+<!-- /count --> actions, plus a YAML flow engine for multi-step workflows and an npm plugin system for extending the surface.
+**Unreal Engine Model Context Protocol Server** - gives AI assistants deep read/write access to the Unreal Editor through <!-- count:tools -->24<!-- /count --> category tools covering <!-- count:actions -->783+<!-- /count --> actions, plus a YAML flow engine for multi-step workflows and an npm plugin system for extending the surface.
 
 On UE 5.8+ it also wraps Epic's entire native AI Toolset Registry - 830 official Unreal tools, called in-process and surfaced as `epic_*` actions in the matching category: Sequencer in `animation`, PCG in `pcg`, static meshes in `asset`.
 
@@ -137,7 +137,7 @@ flows:
 flow(action="run", flowName="build_and_check")
 ```
 
-Every one of the <!-- count:actions -->760+<!-- /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 -->783+<!-- /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
 

package/dist/action-class.d.ts

@@ -0,0 +1,30 @@
+export type ActionClass = "read" | "mutate" | "unknown";
+/** Where a classification came from. `unresolved` is what the drift guard fails on. */
+export type ActionClassSource = "override" | "lexicon" | "epic-default" | "unresolved";
+export interface ActionClassification {
+    class: ActionClass;
+    source: ActionClassSource;
+}
+/** Split `category.action`, tolerating an action name that contains a dot. */
+export declare function splitTaskName(taskName: string): {
+    tool: string;
+    action: string;
+};
+/**
+ * Classify one action.
+ *
+ * Order: explicit override, then the verb lexicon over every underscore
+ * segment (a mutate verb anywhere wins, because `metasound_add_node` adds a
+ * node and `cue_get_graph` does not), then the Epic default, then unresolved.
+ */
+export declare function classifyActionClass(tool: string, action: string): ActionClassification;
+/** Convenience over a `category.action` task name. */
+export declare function classifyTaskClass(taskName: string): ActionClassification;
+/**
+ * Does this class need the caller to name an editor?
+ *
+ * `unknown` is gated exactly like `mutate`. The whole point of keeping it as a
+ * distinct label is that it is not a guess; the gate treats a thing that might
+ * be a mutation as a mutation.
+ */
+export declare function requiresExplicitEditor(cls: ActionClass): boolean;

package/dist/action-class.js

@@ -0,0 +1,217 @@
+/**
+ * Read / mutate / unknown classification of the action surface (#817, plan 5.1).
+ *
+ * This exists for one decision: while this server drives more than one editor,
+ * a call that does not name its target falls through to the active session. For
+ * a read that is harmless. For anything that changes an editor, its project on
+ * disk, or its process, a wrong guess edits somebody else's project, so those
+ * calls have to name the editor they mean.
+ *
+ * Why this is not `flow/write-methods.ts` or `locking.ts`:
+ *
+ *   - `classifyWrite` (source-control guard) answers "which content paths is
+ *     this call about to write", and returns `writes: false` whenever it cannot
+ *     extract a path. A call with no asset path in its params is still a
+ *     mutation of the editor.
+ *   - `classifyAction` (asset locking) answers "should this call take a lock",
+ *     and deliberately collapses everything it does not recognise into
+ *     `mutates: false` so locking never blocks a call it cannot classify.
+ *
+ * Both are load-bearing where they are and both fail open, which is the exact
+ * opposite of what a routing gate needs. So this module answers a third
+ * question, three-way, and fails closed. It is not a parallel scheme: the verb
+ * lexicon is `locking.ts`'s, imported and extended rather than restated, and a
+ * test asserts this module never contradicts locking's verdict.
+ *
+ * The taxonomy is stated in terms of the ADDRESSED EDITOR:
+ *
+ *   read    observes. Does not change the editor, its project on disk, or its
+ *           process. Landing one in the wrong editor returns the wrong answer
+ *           and changes nothing.
+ *   mutate  may change any of those three, or has an external side effect
+ *           (writes a file, posts an issue, launches or quits a process).
+ *   unknown cannot be determined from the action alone, because what it does is
+ *           decided by a parameter (an arbitrary python string, a wrapped tool
+ *           name). Gated exactly like `mutate`.
+ *
+ * Unclassifiable is a real answer here, not a shrug: an `unknown` action still
+ * requires an explicit target, so the honest label costs nothing at the gate
+ * and stops a guess from being recorded as fact.
+ */
+import { MUTATE_PREFIXES, READ_PREFIXES } from "./locking.js";
+/**
+ * Verbs that mean "this call changes something".
+ *
+ * Seeded from the locking lexicon so the two cannot drift apart, then extended
+ * with the verbs the action surface uses that locking never had to recognise
+ * (locking only cares about asset writes; this also has to catch process
+ * lifecycle, editor UI state, and anything with an effect outside the editor).
+ *
+ * Adding a verb here can only ever ask for an explicit target where one was not
+ * required before. That is the safe direction, so this list is generous.
+ */
+const MUTATE_VERBS = new Set([
+    ...MUTATE_PREFIXES,
+    // Arbitrary code and arbitrary engine commands.
+    "execute", "run", "invoke", "call", "eval",
+    // Process and session lifecycle.
+    "start", "stop", "restart", "quit", "kill", "launch", "request", "hot", "cook", "deploy",
+    // Editor and viewport state a user would see happen in the wrong window.
+    "open", "close", "focus", "select", "play", "simulate", "possess", "eject",
+    "pause", "resume", "teleport", "respond", "stage", "capture", "render",
+    // Authoring verbs the asset lexicon has no reason to know about.
+    "author", "edit", "place", "load", "reload", "force", "regenerate", "recompile",
+    "rebuild", "reparent", "auto", "populate", "bind", "rebind", "fill", "append",
+    "reindex", "migrate", "override", "flush", "cleanup", "configure", "init",
+    "initialize", "step", "go", "submit", "remap", "login", "logout", "sync",
+    "toggle", "reactivate", "reorder", "wrap", "sculpt", "paint", "snap", "aim",
+    "undo", "redo", "purge", "begin", "end", "lock", "unlock", "drop", "retarget",
+    "install", "uninstall", "restore", "revert", "activate", "deactivate",
+    "trigger", "emit", "send", "post", "publish", "upload", "convert", "promote",
+    "mark", "dirty", "refresh", "trim", "crop", "resize", "rotate", "translate",
+    "transform", "split", "merge", "patch", "seek", "mute", "unmute",
+    // Verbs the wrapped engine surface uses that no native action does. Every one
+    // of these names a tool that edits a graph, moves a control, drives the UI, or
+    // writes a file, and without them the Epic default below would let it through
+    // untargeted.
+    "paste", "copy", "press", "type", "click", "drag", "hover", "scroll", "break",
+    "arrange", "reposition", "layout", "commit", "zero", "tween", "key",
+    "collapse", "expand", "change", "tag", "untag", "fix", "draw", "mirror",
+    "blend", "empty", "hide", "show", "construct", "frame", "screenshot", "look",
+]);
+/**
+ * Verbs that mean "this call only looks".
+ *
+ * Kept deliberately short. A wrong entry here is the dangerous direction: it
+ * would let a mutation through untargeted. Anything even slightly ambiguous
+ * gets an explicit override below instead of a verb.
+ */
+const READ_VERBS = new Set([
+    ...READ_PREFIXES,
+    "is", "scan", "sample", "health", "diagnose", "compare", "query", "dump",
+    "fetch", "lookup", "enumerate",
+]);
+/**
+ * Actions the verb lexicon gets wrong, or cannot see.
+ *
+ * Every entry is a decision about one action, so every entry carries the reason
+ * it is not what the verb says. Keyed `category.action`.
+ */
+const OVERRIDES = {
+    // ── Address the server's session registry, never an editor ──────────
+    // Routing cannot land these in the wrong editor: they do not reach a bridge
+    // and they name their subject in their own parameters. Requiring an `editor`
+    // target for "register an editor" would be a riddle, not a safeguard.
+    "project.list_editors": "read",
+    "project.use_editor": "read",
+    "project.add_editor": "read",
+    "project.drop_editor": "read",
+    // Renders a flow's execution plan without running a step of it. `flow.run`
+    // is a mutation by the lexicon, which is correct: a flow is whatever its
+    // steps are.
+    "flow.plan": "read",
+    // ── Arbitrary payload decides the effect ────────────────────────────
+    "epic.call_tool": "unknown",
+    "editor.execute_python": "mutate",
+    "project.execute_python_report": "mutate",
+    "editor.execute_command": "mutate",
+    "editor.invoke_object_function": "unknown",
+    "editor.invoke_object_functions": "unknown",
+    "editor.invoke_static_function": "unknown",
+    "editor.invoke_function": "unknown",
+    "widget.invoke_runtime_function": "unknown",
+    "niagara.batch": "mutate",
+    // ── Reads whose verb reads as a write ───────────────────────────────
+    // Serializers: they render a graph as text or JSON and return it.
+    "blueprint.export_nodes_t3d": "read",
+    "material.export_graph": "read",
+    "pcg.export_graph": "read",
+    // Reads the actor descriptors of an unloaded World Partition level. Nothing
+    // is opened; `level.load` is the action that changes the open map.
+    "level.load_actor_descs": "read",
+    // Extracts a widget subtree as a description. `widget.author` writes one.
+    "widget.extract_subtree": "read",
+    // Cache metadata about the Fab library, not a cache write.
+    "fab.cache_info": "read",
+    // Reads a mirror data table. "mirror" is a mutate verb because the wrapped
+    // engine surface uses it as one (mirror_selected_controls), and a mutate verb
+    // anywhere in the name wins, which is wrong for exactly this action.
+    "animation.read_mirror_data_table": "read",
+    // Reads whose first segment is not a verb at all.
+    "level.line_trace": "read",
+    "level.nav_project_point": "read",
+    "level.count_actors_by_class": "read",
+    "gameplay.project_to_nav": "read",
+    "gameplay.find_nav_path": "read",
+    "editor.hit_test_viewport_pixel": "read",
+    "editor.check_for_crashes": "read",
+    "editor.search_log": "read",
+    "project.live_coding_status": "read",
+    "feedback.route": "read",
+    "epic.status": "read",
+    "fab.status": "read",
+    // ── Writes whose verb reads as a read ───────────────────────────────
+    // Drives the editor's preview: it plays an animation in a viewport.
+    "animation.preview_animation": "mutate",
+    // Renders to a file on disk.
+    "material.render_preview": "mutate",
+    "asset.export": "mutate",
+    "asset.export_texture": "mutate",
+    "level.export_actor_fbx": "mutate",
+    "audio.extract_pcm": "mutate",
+    // Rebuilds the full-text index in the editor's own database.
+    "asset.reindex_fts": "mutate",
+    // Posts to a public issue tracker.
+    "feedback.submit": "mutate",
+};
+/** Split `category.action`, tolerating an action name that contains a dot. */
+export function splitTaskName(taskName) {
+    const i = taskName.indexOf(".");
+    if (i < 0)
+        return { tool: taskName, action: "" };
+    return { tool: taskName.slice(0, i), action: taskName.slice(i + 1) };
+}
+/**
+ * Classify one action.
+ *
+ * Order: explicit override, then the verb lexicon over every underscore
+ * segment (a mutate verb anywhere wins, because `metasound_add_node` adds a
+ * node and `cue_get_graph` does not), then the Epic default, then unresolved.
+ */
+export function classifyActionClass(tool, action) {
+    const key = `${tool}.${action}`;
+    const override = OVERRIDES[key];
+    if (override)
+        return { class: override, source: "override" };
+    const segments = action.toLowerCase().split(/[._]/).filter(Boolean);
+    if (segments.some((s) => MUTATE_VERBS.has(s)))
+        return { class: "mutate", source: "lexicon" };
+    if (segments.some((s) => READ_VERBS.has(s)))
+        return { class: "read", source: "lexicon" };
+    // Epic's wrapped engine tools are injected at runtime from a live catalog, so
+    // no build-time guard can enumerate them: enrichment can invent whole
+    // categories from a toolset this package has never seen. The surface is
+    // overwhelmingly read-shaped and a wrapped tool that writes almost always
+    // says so in its name, which the lexicon above already caught. Defaulting the
+    // remainder to `unknown` would make every unbaked Epic action a hard error
+    // for multi-editor users, so it defaults to `read` (plan 5.1).
+    if (action.startsWith("epic_"))
+        return { class: "read", source: "epic-default" };
+    return { class: "unknown", source: "unresolved" };
+}
+/** Convenience over a `category.action` task name. */
+export function classifyTaskClass(taskName) {
+    const { tool, action } = splitTaskName(taskName);
+    return classifyActionClass(tool, action);
+}
+/**
+ * Does this class need the caller to name an editor?
+ *
+ * `unknown` is gated exactly like `mutate`. The whole point of keeping it as a
+ * distinct label is that it is not a guess; the gate treats a thing that might
+ * be a mutation as a mutation.
+ */
+export function requiresExplicitEditor(cls) {
+    return cls !== "read";
+}
+//# sourceMappingURL=action-class.js.map

package/dist/action-class.js.map

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

package/dist/asset-path.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared Unreal asset path handling (#798).
+ *
+ * Callers spell an asset path several defensible ways: with a `.uasset`
+ * suffix, with the object suffix Unreal prints in the content browser, with
+ * backslashes, or wrapped in the `{ refPath }` object reference that the
+ * engine's own toolsets use. The bridge wants exactly one of those forms.
+ * Repairing the rest at the boundary is cheaper than making every caller
+ * discover the rule by trial and error, and a rejection that names the field
+ * and shows the accepted shape is cheaper than a generic failure.
+ */
+/** Guidance appended to every path rejection, so one error is enough to fix the call. */
+export declare const PATH_FORMAT_HELP: string;
+/**
+ * Fold the accepted spellings of an Unreal asset path into the one form the
+ * bridge wants: a long package path, no extension, no object suffix.
+ *
+ *   `/Game/UI/WBP_Foo.uasset`      -> `/Game/UI/WBP_Foo`
+ *   `/Game/UI/WBP_Foo.WBP_Foo`     -> `/Game/UI/WBP_Foo`
+ *   `/Game/UI/WBP_Foo.WBP_Foo_C`   -> `/Game/UI/WBP_Foo`
+ *   `\Game\UI\WBP_Foo`             -> `/Game/UI/WBP_Foo`
+ *   `/Game/UI/`                    -> rejected (no asset name)
+ *
+ * Rejects, naming the offending field, what cannot be repaired without
+ * guessing: empty values, filesystem paths, and relative paths.
+ */
+export declare function normalizeUnrealAssetPath(raw: unknown, field?: string): string;
+/** Split a normalized package path into the package directory and the asset name. */
+export declare function splitAssetPath(assetPath: string): {
+    packagePath: string;
+    name: string;
+};
+/**
+ * Resolve the destination of a create action from either spelling: the
+ * canonical `assetPath` (or its `path` alias), or the older `packagePath`
+ * plus `name` pair. Returns the normalized package path.
+ *
+ * Throws INVALID_PARAMS naming both spellings when neither is usable, so the
+ * caller is never told to supply an internal field name it cannot see in the
+ * schema.
+ */
+export declare function resolveCreateAssetPath(params: Record<string, unknown>): string;
+/**
+ * Pull an asset path out of any value a caller might use for it: a plain
+ * string, Unreal's `{ refPath }` object reference (what the wrapped engine
+ * toolsets use), or either of those serialized as JSON by a client that
+ * flattens object arguments to strings.
+ */
+export declare function coerceAssetPathValue(value: unknown): string | undefined;

package/dist/asset-path.js

@@ -0,0 +1,124 @@
+import { McpError, ErrorCode } from "./errors.js";
+/**
+ * Shared Unreal asset path handling (#798).
+ *
+ * Callers spell an asset path several defensible ways: with a `.uasset`
+ * suffix, with the object suffix Unreal prints in the content browser, with
+ * backslashes, or wrapped in the `{ refPath }` object reference that the
+ * engine's own toolsets use. The bridge wants exactly one of those forms.
+ * Repairing the rest at the boundary is cheaper than making every caller
+ * discover the rule by trial and error, and a rejection that names the field
+ * and shows the accepted shape is cheaper than a generic failure.
+ */
+/** Guidance appended to every path rejection, so one error is enough to fix the call. */
+export const PATH_FORMAT_HELP = "Expected an Unreal package path such as '/Game/UI/WBP_Example'. " +
+    "A '.uasset' suffix, an object suffix such as '.WBP_Example', and backslashes are accepted and normalized. " +
+    "A filesystem path or a path that does not start with '/' is not.";
+function invalid(message) {
+    return new McpError(ErrorCode.INVALID_PARAMS, message);
+}
+/**
+ * Fold the accepted spellings of an Unreal asset path into the one form the
+ * bridge wants: a long package path, no extension, no object suffix.
+ *
+ *   `/Game/UI/WBP_Foo.uasset`      -> `/Game/UI/WBP_Foo`
+ *   `/Game/UI/WBP_Foo.WBP_Foo`     -> `/Game/UI/WBP_Foo`
+ *   `/Game/UI/WBP_Foo.WBP_Foo_C`   -> `/Game/UI/WBP_Foo`
+ *   `\Game\UI\WBP_Foo`             -> `/Game/UI/WBP_Foo`
+ *   `/Game/UI/`                    -> rejected (no asset name)
+ *
+ * Rejects, naming the offending field, what cannot be repaired without
+ * guessing: empty values, filesystem paths, and relative paths.
+ */
+export function normalizeUnrealAssetPath(raw, field = "assetPath") {
+    if (typeof raw !== "string") {
+        throw invalid(`${field} must be a string. ${PATH_FORMAT_HELP}`);
+    }
+    let value = raw.trim().replace(/\\/g, "/");
+    if (value === "") {
+        throw invalid(`${field} must not be empty. ${PATH_FORMAT_HELP}`);
+    }
+    if (/^[A-Za-z]:\//.test(value) || value.startsWith("file:")) {
+        throw invalid(`${field} '${raw}' is a filesystem path. ${PATH_FORMAT_HELP}`);
+    }
+    value = value.replace(/\/{2,}/g, "/");
+    while (value.length > 1 && value.endsWith("/"))
+        value = value.slice(0, -1);
+    if (!value.startsWith("/")) {
+        throw invalid(`${field} '${raw}' is not a mount-rooted path. ${PATH_FORMAT_HELP}`);
+    }
+    // Everything from the first dot of the final segment is an extension or an
+    // object suffix. The bridge addresses the package, not the object.
+    const cut = value.lastIndexOf("/");
+    const dir = value.slice(0, cut);
+    let leaf = value.slice(cut + 1);
+    const dot = leaf.indexOf(".");
+    if (dot >= 0)
+        leaf = leaf.slice(0, dot);
+    if (leaf === "") {
+        throw invalid(`${field} '${raw}' has no asset name. ${PATH_FORMAT_HELP}`);
+    }
+    const normalized = `${dir}/${leaf}`;
+    if (normalized.split("/").filter(Boolean).length < 2) {
+        throw invalid(`${field} '${raw}' is missing a mount point. ${PATH_FORMAT_HELP}`);
+    }
+    return normalized;
+}
+/** Split a normalized package path into the package directory and the asset name. */
+export function splitAssetPath(assetPath) {
+    const cut = assetPath.lastIndexOf("/");
+    return { packagePath: assetPath.slice(0, cut), name: assetPath.slice(cut + 1) };
+}
+/**
+ * Resolve the destination of a create action from either spelling: the
+ * canonical `assetPath` (or its `path` alias), or the older `packagePath`
+ * plus `name` pair. Returns the normalized package path.
+ *
+ * Throws INVALID_PARAMS naming both spellings when neither is usable, so the
+ * caller is never told to supply an internal field name it cannot see in the
+ * schema.
+ */
+export function resolveCreateAssetPath(params) {
+    for (const field of ["assetPath", "path"]) {
+        const value = coerceAssetPathValue(params[field]);
+        if (value !== undefined)
+            return normalizeUnrealAssetPath(value, field);
+    }
+    const name = typeof params.name === "string" ? params.name.trim() : "";
+    const packagePath = typeof params.packagePath === "string" ? params.packagePath.trim() : "";
+    if (name !== "" && packagePath !== "") {
+        return normalizeUnrealAssetPath(`${packagePath}/${name}`, "packagePath + name");
+    }
+    throw invalid("Missing required parameter 'assetPath'. " +
+        `${PATH_FORMAT_HELP} A 'name' plus 'packagePath' pair is accepted as the same thing.`);
+}
+/**
+ * Pull an asset path out of any value a caller might use for it: a plain
+ * string, Unreal's `{ refPath }` object reference (what the wrapped engine
+ * toolsets use), or either of those serialized as JSON by a client that
+ * flattens object arguments to strings.
+ */
+export function coerceAssetPathValue(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed.startsWith("{")) {
+            try {
+                return coerceAssetPathValue(JSON.parse(trimmed));
+            }
+            catch {
+                return trimmed;
+            }
+        }
+        return trimmed === "" ? undefined : trimmed;
+    }
+    if (value && typeof value === "object") {
+        const rec = value;
+        for (const key of ["refPath", "assetPath", "path"]) {
+            const inner = rec[key];
+            if (typeof inner === "string" && inner.trim() !== "")
+                return inner.trim();
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=asset-path.js.map

package/dist/asset-path.js.map

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

package/dist/auth-cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * `npx ue-mcp auth` — interactive GitHub device-flow auth so feedback(submit)
+ * `npx ue-mcp auth` - interactive GitHub device-flow auth so feedback(submit)
  * can author issues as the user's real GitHub account.
  *
  * The same flow is offered inside `npx ue-mcp init` when the user opts into

package/dist/auth-cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * `npx ue-mcp auth` — interactive GitHub device-flow auth so feedback(submit)
+ * `npx ue-mcp auth` - interactive GitHub device-flow auth so feedback(submit)
  * can author issues as the user's real GitHub account.
  *
  * The same flow is offered inside `npx ue-mcp init` when the user opts into