ue-mcp 1.2.1 → 1.2.2

package/dist/flow/task-guards.js

@@ -10,20 +10,29 @@
  *   - `afterWrite`  run after a write-classified call
  *
  * No new plugin-activation concept is needed: the loader already registers every
- * `manifest.tasks` entry by name, so a `guard.*.*` task is picked up here. Each
- * matched task becomes one `BridgeGuard`. The core knows nothing about what a
- * guard does - source control, access policy, audit, and rate limiting are all
- * just guards.
+ * `manifest.tasks` entry by name, so a `guard.*.*` task is picked up here. The
+ * core knows nothing about what a guard does - source control, access policy,
+ * audit, and rate limiting are all just guards.
  *
- * A guard task is invoked with `{ method, params, paths }` (paths = the existing
- * on-disk files the call will touch, empty for non-writes) plus, for `after`
- * guards, `result`. A `before` guard denies the call by returning `success:false`
- * or throwing.
+ * The naming convention and the discovery walk are flowkit's; this module binds
+ * them to the bridge: the `write` scope comes from `write-methods.ts`, the guard
+ * task is invoked with `{ method, params, paths }` (plus `result` for `after`
+ * guards), and a denial surfaces as an `McpError` the tool layer already knows
+ * how to render.
  */
 import * as fs from "node:fs";
+import { discoverTaskGuards as discoverFlowkitGuards } from "@db-lyon/flowkit/guard";
+import { writeScope } from "./guard.js";
 import { McpError, ErrorCode } from "../errors.js";
-import { debug } from "../log.js";
-const GUARD_TASK_RE = /^guard\.(.+)\.(before|beforeWrite|after|afterWrite)$/;
+import { debug, info } from "../log.js";
+/** Adapts flowkit's logger to this server's `guard`-component logging. */
+const GUARD_LOGGER = {
+    debug: (...args) => debug("guard", args.map(String).join(" ")),
+    info: (...args) => info("guard", args.map(String).join(" ")),
+    warn: (...args) => info("guard", args.map(String).join(" ")),
+    error: (...args) => info("guard", args.map(String).join(" ")),
+    child: () => GUARD_LOGGER,
+};
 /** Resolve a UE content path to an absolute file, or null if it does not exist. */
 export function makeResolveExistingFile(project) {
     return (contentPath) => {
@@ -42,63 +51,30 @@ export function makeResolveExistingFile(project) {
  * guard that itself calls the bridge cannot recurse through the pipeline.
  */
 export function discoverTaskGuards(registry, ctx, rawBridge) {
-    const guards = [];
-    for (const taskName of registry.listRegistered()) {
-        const m = GUARD_TASK_RE.exec(taskName);
-        if (!m)
-            continue;
-        const [, name, phase] = m;
-        const writeScoped = phase.endsWith("Write");
-        const isBefore = phase.startsWith("before");
-        const runTask = async (cc, result) => {
-            // Bind the guard to the editor whose call it is guarding, not to
-            // whichever bridge happened to be built first. cc.bridge is the RAW
-            // bridge of the session serving this call, so a guard can neither
-            // recurse through the pipeline nor act on another project's editor.
-            const guardCtx = cc.session
-                ? { ...ctx, bridge: cc.bridge, project: cc.session.project, session: cc.session }
-                : { ...ctx, bridge: rawBridge };
-            const options = {
-                method: cc.method,
-                params: cc.params,
-                paths: cc.writeFiles(),
-            };
-            if (result !== undefined)
-                options.result = result;
-            try {
-                const task = await registry.create(taskName, guardCtx, options);
-                return await task.run();
-            }
-            catch (e) {
-                throw new McpError(ErrorCode.WRITE_BLOCKED, `guard '${name}' errored on ${cc.method}: ${e.message}`);
-            }
-        };
-        const guard = {
-            name: `${name}.${phase}`,
-            appliesTo: writeScoped ? (cc) => cc.writeFiles().length > 0 : undefined,
-        };
-        if (isBefore) {
-            guard.before = async (cc) => {
-                const r = await runTask(cc);
-                if (!r.success) {
-                    const reason = r.error?.message ?? `denied by guard '${name}'`;
-                    const scope = cc.writeFiles().length ? ` on ${cc.writeFiles().join(", ")}` : "";
-                    throw new McpError(ErrorCode.WRITE_BLOCKED, `blocked (${cc.method})${scope}: ${reason}`);
-                }
-                debug("guard", `guard '${name}' allowed ${cc.method}`);
-            };
-        }
-        else {
-            // `after` guards observe the result for side effects (audit); a failing
-            // after-guard is logged but does not fail the already-completed call.
-            guard.after = async (cc, result) => {
-                const r = await runTask(cc, result);
-                if (!r.success)
-                    debug("guard", `after-guard '${name}' reported failure on ${cc.method}: ${r.error?.message}`);
-            };
-        }
-        guards.push(guard);
-    }
-    return guards;
+    return discoverFlowkitGuards(registry, {
+        scopes: { write: writeScope },
+        // Bind the guard to the editor whose call it is guarding, not to whichever
+        // bridge happened to be built first. cc.bridge is the RAW bridge of the
+        // session serving this call, so a guard can neither recurse through the
+        // pipeline nor act on another project's editor.
+        contextFor: (cc) => cc.session
+            ? { ...ctx, bridge: cc.bridge, project: cc.session.project, session: cc.session }
+            : { ...ctx, bridge: rawBridge },
+        optionsFor: (cc, result) => ({
+            method: cc.method,
+            params: cc.params,
+            paths: cc.writeFiles(),
+            ...(result !== undefined ? { result } : {}),
+        }),
+        onDeny: (info) => {
+            const files = info.ctx.writeFiles();
+            const scope = files.length ? ` on ${files.join(", ")}` : "";
+            return new McpError(ErrorCode.WRITE_BLOCKED, `blocked (${info.ctx.method})${scope}: ${info.reason}`);
+        },
+        onError: (info) => new McpError(ErrorCode.WRITE_BLOCKED, `guard '${info.guard}' errored on ${info.ctx.method}: ${info.reason}`),
+        // A failing after-guard is logged but does not fail the already-completed call.
+        onAfterFailure: (info) => debug("guard", `after-guard '${info.guard}' reported failure on ${info.ctx.method}: ${info.reason}`),
+        logger: GUARD_LOGGER,
+    });
 }
 //# sourceMappingURL=task-guards.js.map

package/dist/flow/task-guards.js.map

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

package/dist/instructions.js

@@ -35,145 +35,145 @@ function categoryList() {
     return lines.join("\n").replace(/\bepic\b(?![\w-])/, "epic (830 wrapped Unreal 5.8 tools; UE 5.8+)");
 }
 const CATEGORIES = categoryList();
-export const SERVER_INSTRUCTIONS = `UE-MCP: Unreal Engine editor bridge (C++ plugin) - ${CATEGORY_COUNT} category tools covering ${ACTION_COUNT} actions, plus 830 official Unreal 5.8 tools wrapped in-process (UE 5.8+; see the epic category).
-
-Every tool takes an "action" parameter that selects the operation. Call project(action="get_status") first.
-
-═══ QUICK START ═══
-1. project(action="get_status") - check if the editor is connected
-2. If not connected: editor(action="start_editor") to launch UE
-3. level(action="get_outliner") - see what's in the current level
-4. asset(action="list") - browse project assets
-5. reflection(action="reflect_class", className="StaticMeshActor") - understand any UE class
-6. demo(action="step", stepIndex=1) through 19 - run the Neon Shrine demo to see the bridge in action
-7. demo(action="cleanup") - clean up after the demo
-
-═══ TOOLS ═══
-
-Every category tool lists its own actions (and each action's parameters) in
-its description - read the description of the category you need. Categories:
-${CATEGORIES}.
-
-═══ TIPS ═══
-• Start with level(action="get_outliner") or asset(action="list") to discover what's in the project.
-• Use reflection(action="reflect_class") to understand any UE class's properties.
-• asset(action="search", query="/Game/Characters/*") accepts wildcards.
-• For BP scripting: blueprint(action="search_node_types") → blueprint(action="add_node") → blueprint(action="connect_pins").
-• editor(action="execute_python") is the escape hatch for any Unreal Python API call.
-• Animation tools need a skeleton path - use animation(action="list_skeletal_meshes") to find it.
-• Editor lifecycle: editor(action="stop_editor") / editor(action="start_editor") / editor(action="restart_editor") manage the UE process. editor(action="build_project") builds the project C++ code (stop the editor first).
-• editor(action="hot_reload") triggers Live Coding compilation without restarting the editor.
-• editor(action="focus_on_actor", actorLabel="MyActor") snaps the viewport to any actor.
-• Log output: editor(action="get_log", category="LogMCPBridge") to see bridge-specific logs.
-
-═══ FLOWS - READ BEFORE ACTING ═══
-
-Before you run bash/npm commands or chain 3+ category tool calls to
-satisfy a user request, look at the \`flows\` field returned by
-project(action="get_status").
-
-That field lists named, pre-built sequences for this project. Each
-entry has a name and description. If ANY flow's description matches
-what the user asked for, you MUST run it instead of building the
-sequence yourself.
-
-Examples:
-  User asks                          | Look for a flow like
-  ---------------------------------- | ------------------------------
-  "rebuild and relaunch the editor"  | rebuild
-  "run the smoke tests"              | smoke
-  "redeploy the plugin"              | deploy, redeploy
-  "package the project"              | package
-
-Run a matched flow with: flow(action="run", flowName="<name>")
-
-DO NOT:
-- Skip the get_status flows check before running bash/npm yourself.
-- Author a new flow on your own. Only the user authors flows.
-- Suggest a flow for a one-off task the user is unlikely to repeat.
-
-DO suggest a new flow IF AND ONLY IF all three are true:
-  1. You just finished a sequence with 3+ steps.
-  2. The sequence had the same shape every run, with only 1-2 values
-     changing.
-  3. The user is likely to ask for the same shape again.
-In that case say: "This sequence (X -> Y -> Z) might be worth registering
-as a flow in ue-mcp.yml. Want me to draft one?" Then STOP. Wait.
-
-═══ FEEDBACK ═══
-If you had to use editor(action="execute_python") as a workaround because a native tool
-couldn't handle the task, keep a mental note of what you did and why. When your task is
-complete, tell the user:
-  "I had to use custom Python scripts to [describe what]. Would you like to submit
-   feedback to help improve ue-mcp?"
-If the user agrees, call feedback(action="submit") with:
-  • title - short, generic description of the gap (no project-specific details)
-  • summary - what was attempted and why the native tool fell short
-  • pythonWorkaround - the Python code that was used
-  • idealTool - what tool/action should handle this natively
-This creates a GitHub issue so the maintainers can add proper support.
-
-Not every gap belongs to ue-mcp core. Plugins (PIE Studio, Perforce, Meshy, ...)
-own their own surfaces and their own trackers. submit checks the plugin registry
-and aims the issue at the owning repo on its own, and the approval prompt lets
-the user change it - do NOT set the repo parameter yourself unless the user
-names a repo. feedback(action="route") answers "where would this land?" without
-posting anything.
+export const SERVER_INSTRUCTIONS = `UE-MCP: Unreal Engine editor bridge (C++ plugin) - ${CATEGORY_COUNT} category tools covering ${ACTION_COUNT} actions, plus 830 official Unreal 5.8 tools wrapped in-process (UE 5.8+; see the epic category).
+
+Every tool takes an "action" parameter that selects the operation. Call project(action="get_status") first.
+
+═══ QUICK START ═══
+1. project(action="get_status") - check if the editor is connected
+2. If not connected: editor(action="start_editor") to launch UE
+3. level(action="get_outliner") - see what's in the current level
+4. asset(action="list") - browse project assets
+5. reflection(action="reflect_class", className="StaticMeshActor") - understand any UE class
+6. demo(action="step", stepIndex=1) through 19 - run the Neon Shrine demo to see the bridge in action
+7. demo(action="cleanup") - clean up after the demo
+
+═══ TOOLS ═══
+
+Every category tool lists its own actions (and each action's parameters) in
+its description - read the description of the category you need. Categories:
+${CATEGORIES}.
+
+═══ TIPS ═══
+• Start with level(action="get_outliner") or asset(action="list") to discover what's in the project.
+• Use reflection(action="reflect_class") to understand any UE class's properties.
+• asset(action="search", query="/Game/Characters/*") accepts wildcards.
+• For BP scripting: blueprint(action="search_node_types") → blueprint(action="add_node") → blueprint(action="connect_pins").
+• editor(action="execute_python") is the escape hatch for any Unreal Python API call.
+• Animation tools need a skeleton path - use animation(action="list_skeletal_meshes") to find it.
+• Editor lifecycle: editor(action="stop_editor") / editor(action="start_editor") / editor(action="restart_editor") manage the UE process. editor(action="build_project") builds the project C++ code (stop the editor first).
+• editor(action="hot_reload") triggers Live Coding compilation without restarting the editor.
+• editor(action="focus_on_actor", actorLabel="MyActor") snaps the viewport to any actor.
+• Log output: editor(action="get_log", category="LogMCPBridge") to see bridge-specific logs.
+
+═══ FLOWS - READ BEFORE ACTING ═══
+
+Before you run bash/npm commands or chain 3+ category tool calls to
+satisfy a user request, look at the \`flows\` field returned by
+project(action="get_status").
+
+That field lists named, pre-built sequences for this project. Each
+entry has a name and description. If ANY flow's description matches
+what the user asked for, you MUST run it instead of building the
+sequence yourself.
+
+Examples:
+  User asks                          | Look for a flow like
+  ---------------------------------- | ------------------------------
+  "rebuild and relaunch the editor"  | rebuild
+  "run the smoke tests"              | smoke
+  "redeploy the plugin"              | deploy, redeploy
+  "package the project"              | package
+
+Run a matched flow with: flow(action="run", flowName="<name>")
+
+DO NOT:
+- Skip the get_status flows check before running bash/npm yourself.
+- Author a new flow on your own. Only the user authors flows.
+- Suggest a flow for a one-off task the user is unlikely to repeat.
+
+DO suggest a new flow IF AND ONLY IF all three are true:
+  1. You just finished a sequence with 3+ steps.
+  2. The sequence had the same shape every run, with only 1-2 values
+     changing.
+  3. The user is likely to ask for the same shape again.
+In that case say: "This sequence (X -> Y -> Z) might be worth registering
+as a flow in ue-mcp.yml. Want me to draft one?" Then STOP. Wait.
+
+═══ FEEDBACK ═══
+If you had to use editor(action="execute_python") as a workaround because a native tool
+couldn't handle the task, keep a mental note of what you did and why. When your task is
+complete, tell the user:
+  "I had to use custom Python scripts to [describe what]. Would you like to submit
+   feedback to help improve ue-mcp?"
+If the user agrees, call feedback(action="submit") with:
+  • title - short, generic description of the gap (no project-specific details)
+  • summary - what was attempted and why the native tool fell short
+  • pythonWorkaround - the Python code that was used
+  • idealTool - what tool/action should handle this natively
+This creates a GitHub issue so the maintainers can add proper support.
+
+Not every gap belongs to ue-mcp core. Plugins (PIE Studio, Perforce, Meshy, ...)
+own their own surfaces and their own trackers. submit checks the plugin registry
+and aims the issue at the owning repo on its own, and the approval prompt lets
+the user change it - do NOT set the repo parameter yourself unless the user
+names a repo. feedback(action="route") answers "where would this land?" without
+posting anything.
 `;
 // Compact instructions used when context.strategy = "lean". The per-action
 // catalog is intentionally omitted: agents pull it on demand via the `catalog`
 // tool or a category's `describe` action. This keeps the initialize handshake
 // small for token-constrained clients while preserving full capability.
-export const SERVER_INSTRUCTIONS_LEAN = `UE-MCP (lean mode): Unreal Engine editor bridge (C++ plugin). ${CATEGORY_COUNT} category tools covering ${ACTION_COUNT} actions; the per-action catalog is loaded on demand to keep context small.
-
-Every tool takes an "action" parameter that selects the operation. Start with project(action="get_status").
-
-═══ DISCOVER ACTIONS ═══
-Tool descriptions are trimmed in lean mode. Find the action you need with:
-- catalog(action="search", query="spawn actor") - rank matching actions across every category
-- catalog(action="list_categories") - the ${CATEGORY_COUNT} categories with one-line summaries
-- <category>(action="describe") - every action in one category (e.g. blueprint(action="describe"))
-
-Each category's "action" parameter is still a validated enum, so unknown actions are rejected up front. Call describe/search first when you are unsure of the exact action name.
-
-═══ CATEGORIES ═══
-${CATEGORIES}.
-
-═══ FLOWS ═══
-Before chaining 3+ tool calls, check the \`flows\` field from project(action="get_status")
-and run a matching flow with flow(action="run", flowName="<name>") instead of rebuilding it.
-
-═══ FEEDBACK ═══
-If you had to fall back to editor(action="execute_python") because a native tool could not
-do the job, tell the user when done and offer to feedback(action="submit") the gap. submit
-routes the issue to the tracker that owns the surface (core, or the plugin that provides it)
-by checking the plugin registry; feedback(action="route") previews that without posting.
-
-Full mode (every action listed inline) is the default. This lean surface is selected by
-context.strategy: lean in ue-mcp.yml or UE_MCP_CONTEXT_STRATEGY=lean.
+export const SERVER_INSTRUCTIONS_LEAN = `UE-MCP (lean mode): Unreal Engine editor bridge (C++ plugin). ${CATEGORY_COUNT} category tools covering ${ACTION_COUNT} actions; the per-action catalog is loaded on demand to keep context small.
+
+Every tool takes an "action" parameter that selects the operation. Start with project(action="get_status").
+
+═══ DISCOVER ACTIONS ═══
+Tool descriptions are trimmed in lean mode. Find the action you need with:
+- catalog(action="search", query="spawn actor") - rank matching actions across every category
+- catalog(action="list_categories") - the ${CATEGORY_COUNT} categories with one-line summaries
+- <category>(action="describe") - every action in one category (e.g. blueprint(action="describe"))
+
+Each category's "action" parameter is still a validated enum, so unknown actions are rejected up front. Call describe/search first when you are unsure of the exact action name.
+
+═══ CATEGORIES ═══
+${CATEGORIES}.
+
+═══ FLOWS ═══
+Before chaining 3+ tool calls, check the \`flows\` field from project(action="get_status")
+and run a matching flow with flow(action="run", flowName="<name>") instead of rebuilding it.
+
+═══ FEEDBACK ═══
+If you had to fall back to editor(action="execute_python") because a native tool could not
+do the job, tell the user when done and offer to feedback(action="submit") the gap. submit
+routes the issue to the tracker that owns the surface (core, or the plugin that provides it)
+by checking the plugin registry; feedback(action="route") previews that without posting.
+
+Full mode (every action listed inline) is the default. This lean surface is selected by
+context.strategy: lean in ue-mcp.yml or UE_MCP_CONTEXT_STRATEGY=lean.
 `;
 // Smallest surface (context.strategy = "micro"). The entire ue-mcp API is
 // reached through one gateway tool, mirroring the native MCP toolset gateway
 // (list_toolsets / describe_toolset / call_tool). Nothing else is advertised.
-export const SERVER_INSTRUCTIONS_MICRO = `UE-MCP (micro mode): Unreal Engine editor bridge (C++ plugin). The entire surface (${CATEGORY_COUNT} categories, ${ACTION_COUNT} actions) is reached through a single gateway tool to keep context tiny.
-
-═══ HOW TO USE ═══
-- tools(action="list_categories") - list every category with a one-line summary
-- tools(action="describe", category="blueprint") - list a category's actions and how to call them
-- tools(action="call", category="blueprint", method="create", args={ ... }) - invoke any action
-
-\`method\` is the action name; \`args\` is the object of that action's parameters.
-Start with: tools(action="call", category="project", method="get_status").
-
-═══ CATEGORIES ═══
-${CATEGORIES}.
-
-═══ FLOWS ═══
-flow(action="run", flowName="<name>") runs a named sequence; see the \`flows\` field
-from tools(action="call", category="project", method="get_status").
-
-Full mode (every action listed inline) is the default. This micro surface is selected by
-context.strategy: micro in ue-mcp.yml or UE_MCP_CONTEXT_STRATEGY=micro.
+export const SERVER_INSTRUCTIONS_MICRO = `UE-MCP (micro mode): Unreal Engine editor bridge (C++ plugin). The entire surface (${CATEGORY_COUNT} categories, ${ACTION_COUNT} actions) is reached through a single gateway tool to keep context tiny.
+
+═══ HOW TO USE ═══
+- tools(action="list_categories") - list every category with a one-line summary
+- tools(action="describe", category="blueprint") - list a category's actions and how to call them
+- tools(action="call", category="blueprint", method="create", args={ ... }) - invoke any action
+
+\`method\` is the action name; \`args\` is the object of that action's parameters.
+Start with: tools(action="call", category="project", method="get_status").
+
+═══ CATEGORIES ═══
+${CATEGORIES}.
+
+═══ FLOWS ═══
+flow(action="run", flowName="<name>") runs a named sequence; see the \`flows\` field
+from tools(action="call", category="project", method="get_status").
+
+Full mode (every action listed inline) is the default. This micro surface is selected by
+context.strategy: micro in ue-mcp.yml or UE_MCP_CONTEXT_STRATEGY=micro.
 `;
 /**
  * Targeting block, appended to whichever instruction variant is in use, and