unity-open-mcp 0.5.0 → 0.7.0

package/dist/tool-router.js

@@ -10,6 +10,7 @@ import { generateSkill } from "./skill/generate-skill.js";
 import { knownClientKeys } from "./skill/client-paths.js";
 import { ALL_TOOLS } from "./tools/index.js";
 import { lockPath, readInstanceLock, classifyInstance, isPidAlive } from "./instance-discovery.js";
+import { PORT_ENV_VAR } from "./constants.js";
 import { findUnityForProject } from "./running-unity.js";
 import { listInstalledEditors, fetchAvailableReleases, openInstallDeepLink, getInstallPath, setInstallPath, } from "./hub-control.js";
 /** Default Hub-control backend — calls the real hub-control functions. */
@@ -20,8 +21,50 @@ const defaultHubBackend = {
     getInstallPath: () => getInstallPath(),
     setInstallPath: (path) => setInstallPath(path),
 };
-import { BATCH_TOOL_NAMES } from "./batch-spawn.js";
+import { BATCH_TOOL_NAMES, ALWAYS_BATCH_TOOLS } from "./batch-spawn.js";
 import { readProfileAndDetail, applyPaging, attachPagination, foldVerifyResult, parseResultBody, withResultBody, } from "./output-profile.js";
+/**
+ * Single source of truth for the `_source` tag. Every route-tagging site goes
+ * through one of the two helpers below so live / offline / local stay
+ * symmetric — a new route adding `_source` inline (the omission that slipped
+ * through before T6.1) is caught by the "no inline `_source` outside the
+ * helper" rule and grep.
+ *
+ * - {@link withSource} stamps `_source` on a body object literal (the local /
+ *   offline paths that build the JSON themselves).
+ * - {@link tagSource} stamps `_source` on an already-built {@link
+ *   CallToolResult} (the live / offline-result paths that wrap a bridge or
+ *   disk result).
+ */
+function withSource(body, source) {
+    return { ...body, _source: source };
+}
+/**
+ * Tag a CallToolResult's JSON body with `_source` so callers switching on the
+ * field see a defined value for live-routed drill-downs (find_references /
+ * dependencies). A no-op when the first content block is not parseable JSON;
+ * preserves `isError` and other content blocks.
+ */
+function tagSource(result, source) {
+    const body = parseResultBody(result);
+    if (body === null)
+        return result;
+    return withResultBody(result, withSource(body, source));
+}
+/**
+ * Build a single-block CallToolResult from a body object, tagging it with
+ * `_source`. The common shape for local/offline routes that synthesize the
+ * entire response in the MCP server (no bridge tool endpoint). Accepts the
+ * typed result shapes (ListAssetsResult, CapabilitiesResult, …) returned by
+ * the offline/local builders.
+ */
+function sourceResult(body, source, isError = false) {
+    const tagged = withSource(body, source);
+    return {
+        content: [{ type: "text", text: JSON.stringify(tagged) }],
+        isError,
+    };
+}
 function injectRouteMeta(result, meta) {
     if (result.content.length === 0)
         return result;
@@ -50,12 +93,7 @@ function injectRouteMeta(result, meta) {
 // missing-parameter refusals before any side effect runs). Tagged _source=local
 // because it is resolved entirely in the MCP server.
 function localError(code, message) {
-    return {
-        content: [
-            { type: "text", text: JSON.stringify({ error: { code, message }, _source: "local" }) },
-        ],
-        isError: true,
-    };
+    return sourceResult({ error: { code, message } }, "local", true);
 }
 // M26 Plan 2 — gate-consistent envelope shape for the mutating Hub control
 // tools (install_editor / install_modules / set_install_path). These are
@@ -63,7 +101,7 @@ function localError(code, message) {
 // gate is skipped (gate.skipped=true). The shape matches MutationEnvelope so
 // agents parse it uniformly alongside bridge-routed mutating tools.
 function hubMutationEnvelope(opts) {
-    const body = {
+    return sourceResult({
         mutation: {
             success: opts.success,
             output: opts.output,
@@ -76,12 +114,7 @@ function hubMutationEnvelope(opts) {
             delta: null,
         },
         agentNextSteps: opts.nextSteps,
-        _source: "local",
-    };
-    return {
-        content: [{ type: "text", text: JSON.stringify(body) }],
-        isError: opts.isError,
-    };
+    }, "local", opts.isError);
 }
 function activeGroupsEqual(a, b) {
     if (a.length !== b.length)
@@ -239,6 +272,50 @@ export class ToolRouter {
     onToolListChanged;
     hubBackend;
     modelCache = new AssetModelCache();
+    /**
+     * M28-refactoring Plan 3 (T3.2) — named-tool dispatch map. Replaces the
+     * former ~70-block `if (toolName === "...")` chain in routeCore. Each entry
+     * binds the tool name to its route-handler method. The map is built lazily on
+     * first use (the handlers are bound instance methods, so it cannot be a
+     * static field). Adding a new named-tool route is now a map entry, not a new
+     * `if` block. Tools that share a handler (validate_edit + scan_paths) or are
+     * reached via a predicate (isCompressible) are handled below the lookup — the
+     * map covers only exact-name dispatch.
+     */
+    routeHandlers;
+    getRouteHandlers() {
+        if (this.routeHandlers)
+            return this.routeHandlers;
+        const handlers = new Map([
+            // Offline-routed tools (resolved from disk; never hit the bridge).
+            ["unity_open_mcp_list_assets", (_l, a) => this.routeListAssets(a)],
+            ["unity_open_mcp_read_compile_errors", (_l, a) => this.routeReadCompileErrors(a)],
+            // Local-routed tools (server-only; no live/batch hop).
+            ["unity_senses_pull_events", (l, a) => this.routePullEvents(a, l)],
+            ["unity_open_mcp_capabilities", (l, a) => this.routeCapabilities(a, l)],
+            ["unity_open_mcp_list_rules", (_l, a) => this.routeListRules(a)],
+            ["unity_open_mcp_generate_skill", (_l, a) => this.routeGenerateSkill(a)],
+            ["unity_open_mcp_manage_tools", (l, a) => this.routeManageTools(a, l)],
+            ["unity_open_mcp_bridge_status", (l, a) => this.routeBridgeStatus(a, l)],
+            // Hub control tools (local-routed; system-level ops).
+            ["unity_open_mcp_hub_list_editors", () => this.routeHubListEditors()],
+            ["unity_open_mcp_hub_available_releases", () => this.routeHubAvailableReleases()],
+            ["unity_open_mcp_hub_install_editor", (_l, a) => this.routeHubInstallEditor(a)],
+            ["unity_open_mcp_hub_install_modules", (_l, a) => this.routeHubInstallModules(a)],
+            ["unity_open_mcp_hub_get_install_path", () => this.routeHubGetInstallPath()],
+            ["unity_open_mcp_hub_set_install_path", (_l, a) => this.routeHubSetInstallPath(a)],
+            // Offline-first reference tools (fall back to live when the bridge is up).
+            ["unity_open_mcp_find_references", (l, a) => this.routeFindReferences(a, l)],
+            ["unity_open_mcp_dependencies", (l, a) => this.routeDependencies(a, l)],
+            // Verify tools — share a single handler (toolName carried through).
+            ["unity_open_mcp_validate_edit", (l, a) => this.routeVerifyResult("unity_open_mcp_validate_edit", a, l)],
+            ["unity_open_mcp_scan_paths", (l, a) => this.routeVerifyResult("unity_open_mcp_scan_paths", a, l)],
+            // Scene data — output-profile + paging applied server-side.
+            ["unity_open_mcp_scene_get_data", (l, a) => this.routeSceneGetData(a, l)],
+        ]);
+        this.routeHandlers = handlers;
+        return handlers;
+    }
     constructor(live, batch, projectPath, eventStream, sessionState, onToolListChanged, 
     // M26 Plan 2 — injectable Hub-control backend. Omit in production (the
     // default calls the real hub-control functions); tests pass a fake to
@@ -267,101 +344,13 @@ export class ToolRouter {
         return this.routeCore(overrideLive, toolName, args);
     }
     async routeCore(live, toolName, args) {
-        // list_assets — always offline (no live equivalent needed).
-        if (toolName === "unity_open_mcp_list_assets") {
-            return this.routeListAssets(args);
-        }
-        // read_compile_errors — always offline. Reads Unity's Editor.log directly;
-        // the one channel that works when the bridge assembly itself has failed to
-        // compile (every in-bridge channel is dead with it, and compile_check can't
-        // run). Never touches the bridge or spawns Unity.
-        if (toolName === "unity_open_mcp_read_compile_errors") {
-            return this.routeReadCompileErrors(args);
-        }
-        // M13 T4.4 — bridge event stream pull. The MCP server is the only long-lived
-        // hop between the bridge and the agent; a per-process SSE reader amortizes
-        // the connection and shares the queue across pulls. Lives only when the
-        // bridge is reachable; an unreachable bridge returns a clear error instead
-        // of hanging on connect.
-        if (toolName === "unity_senses_pull_events") {
-            return this.routePullEvents(args, live);
-        }
-        // capabilities — local capability-discovery surface (no live/batch hop).
-        if (toolName === "unity_open_mcp_capabilities") {
-            return this.routeCapabilities(args, live);
-        }
-        // list_rules — local rule catalog (no live/batch hop). Lets an agent
-        // discover which rules apply to which asset kinds before calling
-        // scan_paths / validate_edit.
-        if (toolName === "unity_open_mcp_list_rules") {
-            return this.routeListRules(args);
-        }
-        // generate_skill — local skill generation (no live/batch hop).
-        if (toolName === "unity_open_mcp_generate_skill") {
-            return this.routeGenerateSkill(args);
-        }
-        // M18 Plan 2 / T18.2.2 — manage_tools is server-only. It mutates the
-        // per-session tool-group visibility state that lives in the MCP server
-        // (ToolSessionState). The bridge does not track session state — it answers
-        // manage_tools meta-calls by reporting the compiled tool set; the MCP
-        // server applies the activate / deactivate filter to ListTools. Always
-        // visible regardless of the current active set (meta-tool).
-        if (toolName === "unity_open_mcp_manage_tools") {
-            return this.routeManageTools(args, live);
-        }
-        // testsuite-tauri phase-3 — bridge_status. Operator-only health snapshot.
-        // Server-resolved (classifyInstance + one /ping via the LiveClient); never
-        // hits the bridge tool endpoint and never spawns Unity. Returns a coarse
-        // `status` token (running/compiling/stopped/dead_bridge) the Validation
-        // Suite app drives its offline-scenario gate off. Read-only, gate-free.
-        if (toolName === "unity_open_mcp_bridge_status") {
-            return this.routeBridgeStatus(args, live);
-        }
-        // M26 Plan 2 — Unity Hub control tools. Local-routed: resolved inside the
-        // MCP server (filesystem discovery + Unity archive feed + unityhub:// deep
-        // link + Hub CLI). Never hit the bridge tool endpoint, never spawn Unity.
-        // Mutating members are system-level ops (paths_hint N/A, gate-free).
-        if (toolName === "unity_open_mcp_hub_list_editors") {
-            return this.routeHubListEditors();
-        }
-        if (toolName === "unity_open_mcp_hub_available_releases") {
-            return this.routeHubAvailableReleases();
-        }
-        if (toolName === "unity_open_mcp_hub_install_editor") {
-            return this.routeHubInstallEditor(args);
-        }
-        if (toolName === "unity_open_mcp_hub_install_modules") {
-            return this.routeHubInstallModules(args);
-        }
-        if (toolName === "unity_open_mcp_hub_get_install_path") {
-            return this.routeHubGetInstallPath();
-        }
-        if (toolName === "unity_open_mcp_hub_set_install_path") {
-            return this.routeHubSetInstallPath(args);
-        }
-        // find_references — offline-first when no bridge is connected; live
-        // ReferenceGraph remains available when the bridge is up.
-        if (toolName === "unity_open_mcp_find_references") {
-            return this.routeFindReferences(args, live);
-        }
-        // dependencies — offline-first (M24 Plan 2 / T24.2). Forward + reverse
-        // edges + impact analysis all compute from YAML on disk when no bridge is
-        // connected; the live DependenciesTool remains available when the bridge
-        // is up. The offline path is the only one that exposes include_impact
-        // (transitive reverse closure) today.
-        if (toolName === "unity_open_mcp_dependencies") {
-            return this.routeDependencies(args, live);
-        }
-        // M22 — verify tools. The bridge returns the full issues[] list; we fold +
-        // page server-side per the output profile (compact = counts only).
-        if (toolName === "unity_open_mcp_validate_edit" || toolName === "unity_open_mcp_scan_paths") {
-            return this.routeVerifyResult(toolName, args, live);
-        }
-        // M22 — scene_get_data. Resolves the output profile (onto detail) and pages
-        // the node stream server-side; the bridge detail/max_nodes params keep
-        // working as back-compat aliases.
-        if (toolName === "unity_open_mcp_scene_get_data") {
-            return this.routeSceneGetData(args, live);
+        // Named-tool dispatch (T3.2): the handler map covers every exact-name
+        // route. The per-tool policy rationale (offline / local / hub / offline-
+        // first / verify-fold / scene-paging) lives in each routeXxx method's
+        // header comment.
+        const handler = this.getRouteHandlers().get(toolName);
+        if (handler) {
+            return handler(live, args);
         }
         // Compact drill-down reads: offline-first for text-serialized assets, fall
         // back to live bridge for binary formats. The compressible-router handles
@@ -377,12 +366,27 @@ export class ToolRouter {
         // running it against a live Editor that already compiled successfully
         // would trivially report "compile_passed" and never surface the broken
         // state the tool exists to diagnose.
-        if (toolName === "unity_open_mcp_compile_check") {
-            console.error(`[unity-open-mcp] Route: ${toolName} -> batch (compile check always spawns fresh)`);
+        //
+        // Verify-family tools (scan_all / baseline_create / regression_check) are
+        // batch-only: they require the headless verify package and are NOT
+        // registered on the live bridge. Routing them live (the previous default
+        // when the bridge was up) yielded a bare `tool_not_found`. An open Editor
+        // holding the project lock surfaces as `editor_instance_locked` from the
+        // batch spawn (the expected degraded outcome — agents should read the lock
+        // code, not chase a live registration miss).
+        //
+        // validate_edit / scan_paths are intentionally excluded: those ARE
+        // registered on the live bridge and stay live-first (routeVerifyResult
+        // below handles their output-profile folding). The always-batch policy is
+        // declared once in ALWAYS_BATCH_TOOLS (tool name → reason); do not add a
+        // second pinned branch for a new always-batch tool — extend the map.
+        const alwaysBatchReason = ALWAYS_BATCH_TOOLS.get(toolName);
+        if (alwaysBatchReason !== undefined) {
+            console.error(`[unity-open-mcp] Route: ${toolName} -> batch (always-batch: ${alwaysBatchReason})`);
             const result = await this.batch.route(toolName, args);
             return injectRouteMeta(result, {
                 route: "batch",
-                fallbackReason: "compile_check_always_batch",
+                fallbackReason: alwaysBatchReason,
             });
         }
         if (!canBatch && !isPing) {
@@ -500,38 +504,29 @@ export class ToolRouter {
             if (stale.staleLogSuspected)
                 staleLog = stale;
         }
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        status,
-                        unhealthy: health.unhealthy,
-                        headline: health.headline,
-                        errorCount: errors.length,
-                        errors,
-                        // Package / assembly issues from the same log tail. Empty when the
-                        // only red flags are compiler errors (the common case).
-                        issues: health.issues,
-                        issueCount: health.issues.length,
-                        logPath,
-                        tailBytes: tail.bytes,
-                        // Present ONLY when at least one cited source file is newer than
-                        // Editor.log — the log's most-recent error block may be stale and
-                        // the agent should force a recompile before trusting the errors.
-                        ...(staleLog
-                            ? {
-                                staleLogSuspected: true,
-                                staleLogHint: staleLog.hint,
-                                staleLogNewerFiles: staleLog.newerFiles,
-                            }
-                            : {}),
-                        _source: "offline",
-                    }),
-                },
-            ],
-            isError: false,
-        };
+        return sourceResult({
+            status,
+            unhealthy: health.unhealthy,
+            headline: health.headline,
+            errorCount: errors.length,
+            errors,
+            // Package / assembly issues from the same log tail. Empty when the
+            // only red flags are compiler errors (the common case).
+            issues: health.issues,
+            issueCount: health.issues.length,
+            logPath,
+            tailBytes: tail.bytes,
+            // Present ONLY when at least one cited source file is newer than
+            // Editor.log — the log's most-recent error block may be stale and
+            // the agent should force a recompile before trusting the errors.
+            ...(staleLog
+                ? {
+                    staleLogSuspected: true,
+                    staleLogHint: staleLog.hint,
+                    staleLogNewerFiles: staleLog.newerFiles,
+                }
+                : {}),
+        }, "offline");
     }
     async routeListAssets(args) {
         try {
@@ -541,10 +536,7 @@ export class ToolRouter {
                 maxPerFolder: typeof args.max_per_folder === "number" ? args.max_per_folder : 30,
                 projectRoot: this.projectPath,
             });
-            return {
-                content: [{ type: "text", text: JSON.stringify({ ...result, _source: "offline" }) }],
-                isError: false,
-            };
+            return sourceResult(result, "offline");
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -576,7 +568,7 @@ export class ToolRouter {
                                     "Ensure the Unity Editor is open with the Agent Bridge running. " +
                                     "The bridge port is per-project (20000 + sha256(projectPath) % 10000), not fixed — " +
                                     `if Unity is open, check the instance lock at ${lockPath(this.projectPath)} ` +
-                                    "for the live port/pid, or set UNITY_OPEN_MCP_BRIDGE_PORT.",
+                                    `for the live port/pid, or set ${PORT_ENV_VAR}.`,
                             },
                         }),
                     },
@@ -623,24 +615,14 @@ export class ToolRouter {
             fixes: FIX_CATALOG,
             availableBridgeTools,
         }, { kind, includePlanned });
-        return {
-            content: [
-                { type: "text", text: JSON.stringify({ ...result, _source: "local" }) },
-            ],
-            isError: false,
-        };
+        return sourceResult(result, "local");
     }
     async routeListRules(args) {
         const assetKind = typeof args.asset_kind === "string" ? args.asset_kind : undefined;
         const extension = typeof args.extension === "string" ? args.extension : undefined;
         const implementedOnly = args.implemented_only === true;
         const result = listRules({ rules: RULE_CATALOG, fixes: FIX_CATALOG }, { assetKind, extension, implementedOnly });
-        return {
-            content: [
-                { type: "text", text: JSON.stringify({ ...result, _source: "local" }) },
-            ],
-            isError: false,
-        };
+        return sourceResult(result, "local");
     }
     async routeGenerateSkill(args) {
         const write = args.write === true;
@@ -664,20 +646,11 @@ export class ToolRouter {
                 clients: clients.length > 0 ? clients : undefined,
                 includeWorkflow,
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            skill: result.skill,
-                            project: result.project,
-                            written: result.written,
-                            _source: "local",
-                        }),
-                    },
-                ],
-                isError: false,
-            };
+            return sourceResult({
+                skill: result.skill,
+                project: result.project,
+                written: result.written,
+            }, "local");
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -719,7 +692,7 @@ export class ToolRouter {
             return this.manageToolsResult({
                 reset: true,
                 activeGroups: this.sessionState.activeGroups(),
-                message: "Tool-group visibility restored to defaults (`core` only). " +
+                message: "Tool-group visibility restored to the five default-on groups. " +
                     "MCP clients that support listChanged will refresh ListTools automatically.",
             });
         }
@@ -796,26 +769,17 @@ export class ToolRouter {
                 tools,
             };
         });
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({
-                        groups,
-                        activeGroups: this.sessionState.activeGroups(),
-                        note: "Activate a group to add its tools to your ListTools surface; " +
-                            "deactivate to hide them. State is per-session and ephemeral — " +
-                            "it resets to `core`-only when the MCP server restarts. " +
-                            "Compiled-state availability (the `available` field) reflects " +
-                            "whether the Unity domain dependency is compiled in; use " +
-                            "unity_open_mcp_capabilities for the authoritative compiled-state " +
-                            "report.",
-                        _source: "local",
-                    }),
-                },
-            ],
-            isError: false,
-        };
+        return sourceResult({
+            groups,
+            activeGroups: this.sessionState.activeGroups(),
+            note: "Activate a group to add its tools to your ListTools surface; " +
+                "deactivate to hide them. State is per-session and ephemeral — " +
+                "it resets to the five default-on groups when the MCP server restarts. " +
+                "Compiled-state availability (the `available` field) reflects " +
+                "whether the Unity domain dependency is compiled in; use " +
+                "unity_open_mcp_capabilities for the authoritative compiled-state " +
+                "report.",
+        }, "local");
     }
     /**
      * Notify MCP clients when the filtered ListTools surface changed. Skips the
@@ -927,23 +891,10 @@ export class ToolRouter {
         return out;
     }
     manageToolsResult(body) {
-        return {
-            content: [
-                { type: "text", text: JSON.stringify({ ...body, _source: "local" }) },
-            ],
-            isError: false,
-        };
+        return sourceResult(body, "local");
     }
     manageToolsError(code, message) {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: JSON.stringify({ error: { code, message }, _source: "local" }),
-                },
-            ],
-            isError: true,
-        };
+        return sourceResult({ error: { code, message } }, "local", true);
     }
     // testsuite-tauri phase-3 — bridge_status. Combines the instance-lock
     // classifier (the same pure function the LiveClient uses for dead-bridge
@@ -1089,15 +1040,11 @@ export class ToolRouter {
                 }
                 : { reachable: false },
             nextStep: bridgeStatusNextStep(status),
-            _source: "local",
         };
         // bridge_status never reports an error — even a stopped bridge is a
         // successful status read. _source=local because the synthesis happens in
         // the MCP server (no bridge tool endpoint, no batch Unity).
-        return {
-            content: [{ type: "text", text: JSON.stringify(body) }],
-            isError: false,
-        };
+        return sourceResult(body, "local");
     }
     // ── M26 Plan 2 — Unity Hub control (local-routed) ────────────────
     //
@@ -1109,29 +1056,16 @@ export class ToolRouter {
     // level ops where the project-asset gate does not apply (paths_hint N/A).
     async routeHubListEditors() {
         const editors = this.hubBackend.listInstalledEditors();
-        const body = {
-            editors,
-            count: editors.length,
-            _source: "local",
-        };
-        return {
-            content: [{ type: "text", text: JSON.stringify(body) }],
-            isError: false,
-        };
+        return sourceResult({ editors, count: editors.length }, "local");
     }
     async routeHubAvailableReleases() {
         const result = await this.hubBackend.fetchAvailableReleases();
-        const body = {
+        return sourceResult({
             entries: result.entries,
             count: result.entries.length,
             stale: result.stale,
             fetchedAt: result.fetchedAt,
-            _source: "local",
-        };
-        return {
-            content: [{ type: "text", text: JSON.stringify(body) }],
-            isError: false,
-        };
+        }, "local");
     }
     async routeHubInstallEditor(args) {
         const version = typeof args.version === "string" ? args.version : "";
@@ -1192,16 +1126,7 @@ export class ToolRouter {
     }
     async routeHubGetInstallPath() {
         const res = this.hubBackend.getInstallPath();
-        const body = {
-            path: res.path,
-            source: res.source,
-            error: res.error,
-            _source: "local",
-        };
-        return {
-            content: [{ type: "text", text: JSON.stringify(body) }],
-            isError: res.error !== null,
-        };
+        return sourceResult({ path: res.path, source: res.source, error: res.error }, "local", res.error !== null);
     }
     async routeHubSetInstallPath(args) {
         const path = typeof args.path === "string" ? args.path : "";
@@ -1231,14 +1156,19 @@ export class ToolRouter {
             console.error("[unity-open-mcp] Route: find_references -> live");
             // The live bridge only honors max_results (no detail/per-file/threshold).
             // Ask for the full set when paging so the cursor can walk it; otherwise
-            // honor the legacy max_results cap.
+            // honor the legacy max_results cap. The 0 here is the server-internal
+            // "unlimited" sentinel (documented in the find-references schema); callers
+            // never pass it — the schema declares minimum: 1 for caller-facing use.
             const liveArgs = {
                 ...args,
                 max_results: wantPaging ? 0 : (typeof args.max_results === "number" ? args.max_results : 100),
             };
             const result = await live.route("unity_open_mcp_find_references", liveArgs);
             const folded = foldFindReferencesLive(result, profile, wantPaging, args);
-            return injectRouteMeta(folded, { route: "live" });
+            // T6.1 — tag _source=live so the response matches the offline path's
+            // _source=offline tag (clients switching on _source get a defined value
+            // for the common live case instead of undefined).
+            return injectRouteMeta(tagSource(folded, "live"), { route: "live" });
         }
         console.error("[unity-open-mcp] Route: find_references -> offline (live bridge unavailable)");
         const assetPath = typeof args.asset_path === "string" ? args.asset_path : undefined;
@@ -1265,6 +1195,8 @@ export class ToolRouter {
                 guid,
                 detail,
                 // When paging, fetch the full set; otherwise honor the legacy cap.
+                // 0 is the server-internal "unlimited" sentinel (see find-references
+                // schema description); the schema's caller-facing minimum is 1.
                 maxResults: wantPaging ? 0 : (typeof args.max_results === "number" ? args.max_results : 100),
                 maxPerFile: typeof args.max_per_file === "number" ? args.max_per_file : 5,
                 patternThreshold: typeof args.pattern_threshold === "number" ? args.pattern_threshold : 0,
@@ -1275,12 +1207,7 @@ export class ToolRouter {
             const withPaging = wantPaging
                 ? pageFindReferencesResult(result, args.page_size, typeof args.cursor === "string" ? args.cursor : undefined)
                 : result;
-            return {
-                content: [
-                    { type: "text", text: JSON.stringify({ ...withPaging, _source: "offline" }) },
-                ],
-                isError: false,
-            };
+            return sourceResult(withPaging, "offline");
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -1338,7 +1265,8 @@ export class ToolRouter {
                 max_results: typeof args.max_results === "number" ? args.max_results : 100,
             };
             const result = await live.route("unity_open_mcp_dependencies", liveArgs);
-            return injectRouteMeta(result, { route: "live" });
+            // T6.1 — tag _source=live for parity with the offline route's _source.
+            return injectRouteMeta(tagSource(result, "live"), { route: "live" });
         }
         console.error(includeImpact && liveAvailable
             ? "[unity-open-mcp] Route: dependencies -> offline (include_impact is offline-only)"