unity-open-mcp 0.7.0 → 0.8.2

package/dist/server.js

@@ -0,0 +1,195 @@
+// M31 Plan 6 / T6.6 — heavy server module, dynamically imported by index.ts.
+//
+// This module owns the stdio MCP server construction (the `Server`, the
+// `ALL_TOOLS` graph, the live/batch/router stack). It is imported lazily by
+// `index.ts` so the `--version` / `--help` / no-command fast paths never
+// evaluate the ~270-tool surface. Splitting it out keeps `index.ts` a thin
+// launcher whose only static imports are the light CLI + version helpers.
+//
+// Prior to this split, `index.ts` statically imported `ALL_TOOLS` and the full
+// router stack at the top of the file, so every `unity-open-mcp --version`
+// paid for the whole graph. The createServer + getEnv functions moved here
+// unchanged; `index.ts`'s `main()` awaits `import("./server.js")` only on the
+// stdio-server code path.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ALL_TOOLS } from "./tools/index.js";
+import { ALL_RESOURCES } from "./resources/index.js";
+import { LiveClient } from "./live-client.js";
+import { BatchSpawn } from "./batch-spawn.js";
+import { ToolRouter } from "./tool-router.js";
+import { PingCache } from "./ping-cache.js";
+import { ResourceRouter } from "./resource-router.js";
+import { withSchemaDefaults, missingRequiredArgs } from "./schema-defaults.js";
+import { makeErrorResult } from "./results.js";
+import { resolvePort, resolveAuthToken } from "./instance-discovery.js";
+import { PORT_ENV_VAR, PROJECT_PATH_ENV_VAR, bridgeBaseUrl, } from "./constants.js";
+// M23 Plan 3 — per-request routing (port override + agent identity).
+import { extractRouting } from "./agent-identity.js";
+import { BridgeEventStream } from "./event-stream.js";
+import { readPackageVersion } from "./package-version.js";
+import { getServerInstructions } from "./server-instructions.js";
+import { ToolSessionState, filterVisibleTools, } from "./tool-session-state.js";
+// Read the version from package.json at runtime so `npm version` (and the
+// maintainer-panel version-bump in the Hub) keep the reported server + CLI
+// version in sync without editing this source file.
+const PACKAGE_VERSION = readPackageVersion();
+/** Name → tool lookup, built once for default-injection in the CallTool handler. */
+const TOOL_BY_NAME = new Map(ALL_TOOLS.map((t) => [t.name, t]));
+/**
+ * Resolve env for the MCP server. UNITY_PROJECT_PATH is mandatory. The port
+ * uses M13 T4.3 instance discovery:
+ *   1. UNITY_OPEN_MCP_BRIDGE_PORT env var (override wins; users who pin a
+ *      port keep working as before)
+ *   2. ~/.unity-open-mcp/instances/<hash>.json lock file (when its pid is alive)
+ *   3. deterministic hash of the project path (20000 + sha256 % 10000)
+ * The resolved port is logged so users can see which bridge was picked.
+ */
+export function getEnv() {
+    const projectPath = process.env[PROJECT_PATH_ENV_VAR];
+    if (!projectPath) {
+        console.error(`unity-open-mcp: ${PROJECT_PATH_ENV_VAR} environment variable is required.`);
+        process.exit(1);
+    }
+    const rawEnvPort = process.env[PORT_ENV_VAR];
+    // A port of 0 is a valid integer but an invalid *bridge* port: it would be
+    // treated as an authoritative env override and, because LiveClient checks
+    // only `typeof envPort === "number"`, permanently disable the mid-session
+    // endpoint refresh that re-points at a bridge after a Unity restart. Require
+    // >= 1 so 0/NaN/non-numeric values all fall through to instance discovery.
+    const envPort = rawEnvPort ? parseInt(rawEnvPort, 10) : undefined;
+    const hasValidEnvPort = typeof envPort === "number" && Number.isInteger(envPort) && envPort >= 1;
+    const resolvedEnvPort = rawEnvPort && hasValidEnvPort ? envPort : undefined;
+    const port = resolvePort(projectPath, resolvedEnvPort);
+    const source = rawEnvPort && hasValidEnvPort
+        ? "env override"
+        : "instance discovery";
+    console.error(`[unity-open-mcp] Bridge port resolved to ${port} (${source}) for project ${projectPath}`);
+    // M14 — auto-discover the bridge's per-session bearer token from the same
+    // instance lock we read the port from. Undefined when no live lock exists
+    // (older bridge / env port override); in that case the client sends no
+    // Authorization header and the bridge must be in authMode "none".
+    const authToken = resolveAuthToken(projectPath, hasValidEnvPort ? envPort : undefined);
+    if (authToken) {
+        console.error("[unity-open-mcp] Bridge auth token discovered from instance lock.");
+    }
+    else {
+        console.error("[unity-open-mcp] No bridge auth token discovered (authMode must be \"none\").");
+    }
+    return { projectPath, port, authToken, envPort: resolvedEnvPort };
+}
+export function createServer(projectPath, port, authToken, envPort) {
+    const server = new Server({ name: "unity-open-mcp", version: PACKAGE_VERSION }, {
+        capabilities: { tools: { listChanged: true }, resources: {} },
+        // M22 Plan 1 / T22.1.5 — rich server instructions surfaced via the MCP
+        // `initialize` response. Clients may inject this into the system prompt;
+        // it covers payload sizing + paging, Unity-API verification workflow,
+        // and the mutate→gate→fix loop. Kept clean of internal IDs (no
+        // milestone / specs / reference-project handles).
+        instructions: getServerInstructions(),
+    });
+    const pingCache = new PingCache();
+    const liveClient = new LiveClient(port, pingCache, authToken, projectPath, undefined, envPort);
+    const batchSpawn = new BatchSpawn({ projectPath });
+    // M13 T4.4 — one SSE subscription per server process. The MCP server is the
+    // only long-lived hop between the bridge and the LLM; a per-process reader
+    // amortizes the connection and lets every `unity_senses_pull_events` call
+    // share the same buffered queue.
+    const eventStream = new BridgeEventStream(bridgeBaseUrl(port), undefined, authToken);
+    // Per-session tool-group visibility state. Lives in the MCP server and
+    // restores the catalog's default-on groups on every server restart; mutated
+    // only by unity_open_mcp_manage_tools and consulted by ListTools.
+    const sessionState = new ToolSessionState();
+    const notifyToolListChanged = async () => {
+        try {
+            await server.notification({ method: "notifications/tools/list_changed" });
+        }
+        catch (err) {
+            console.error("[unity-open-mcp] Failed to send tools/list_changed notification:", err);
+        }
+    };
+    const router = new ToolRouter(liveClient, batchSpawn, projectPath, eventStream, sessionState, notifyToolListChanged);
+    const resourceRouter = new ResourceRouter({
+        live: liveClient,
+        pingCache,
+        projectPath,
+        port,
+    });
+    // ListTools filters per the session's active groups. A fresh session sees
+    // the two default-on groups (core + gate-and-verify) plus always-visible
+    // meta-tools. Activating a group via manage_tools adds its tools to
+    // subsequent ListTools responses.
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: filterVisibleTools(ALL_TOOLS, sessionState),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const callArgs = (args ?? {});
+        // M23 Plan 3 — extract per-request routing (port override + agent id)
+        // BEFORE schema defaults are applied, so the routing keys (_meta, port)
+        // are stripped and never forwarded to the bridge. The default path (no
+        // override) is zero-overhead: the default LiveClient + process agent id.
+        const routing = extractRouting(callArgs);
+        // Fill missing top-level scalar defaults (e.g. timeout_ms) from the
+        // tool's documented schema. MCP clients may omit these; without this
+        // step every downstream layer falls back to its own hardcoded value and
+        // silently contradicts the schema (historically 30s vs run_tests' 60s).
+        const tool = TOOL_BY_NAME.get(name);
+        const routedArgs = tool
+            ? withSchemaDefaults(tool, routing.strippedArgs)
+            : routing.strippedArgs;
+        // M15 — the MCP SDK does not validate `inputSchema.required`, so a missing
+        // required argument (e.g. regression_check without baseline_path) would
+        // flow downstream as the literal `undefined` (Unity spawned with
+        // `--baseline-path undefined`). Reject it up front with a stable code.
+        if (tool) {
+            const missing = missingRequiredArgs(tool, routedArgs);
+            if (missing.length > 0) {
+                return makeErrorResult({
+                    code: "missing_required_argument",
+                    message: `Missing required argument(s): ${missing.join(", ")}. ` +
+                        `Provide each as a non-null value and retry.`,
+                    detail: {
+                        error: {
+                            code: "missing_required_argument",
+                            message: `Missing required argument(s): ${missing.join(", ")}.`,
+                        },
+                        missing,
+                    },
+                });
+            }
+        }
+        // No port override → default router (the common single-bridge case).
+        if (routing.portOverride === undefined) {
+            return router.route(name, routedArgs);
+        }
+        // Port override → build a transient LiveClient aimed at the override
+        // port. The override bypasses shared session state: it is a fresh client
+        // that resolves its own auth token from the override port's instance
+        // lock (when one exists). The agent id travels as X-Agent-Id so the
+        // target bridge's fair queue can schedule it.
+        const overrideAuth = resolveAuthToken(projectPath, routing.portOverride);
+        // M23 Plan 3 review (M2) — the override client targets a different bridge
+        // port than the default client, so it must NOT share the default
+        // PingCache: a fresh snapshot from the default bridge would let a call
+        // to bridge B short-circuit its own /ping and bypass
+        // bridge_not_connected / compile-wait checks. A private per-client cache
+        // (matching the client's per-request, session-bypassing nature) keeps
+        // each port's ready-state isolated.
+        const overrideLive = new LiveClient(routing.portOverride, new PingCache(), overrideAuth, projectPath, routing.agentId, 
+        // A per-request _meta.port override is authoritative exactly like an
+        // env-port override: pass it as envPort so refreshEndpointFromLock is
+        // a no-op for this transient client (no lock re-resolution).
+        routing.portOverride);
+        return router.routeOverride(name, routedArgs, overrideLive);
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: ALL_RESOURCES,
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        return resourceRouter.read(uri);
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/skill/client-paths.d.ts

@@ -39,6 +39,10 @@ export declare function resolveTemplateSkillPath(): string | null;
  * `UNITY_OPEN_MCP_TOOLKIT_ROOT` after a prior test already warmed the
  * cache need this to observe the override. Do not call from runtime
  * code.
+ *
+ * M31-optimizations Plan 4 / T4.4 — also clears the derived client-keys
+ * singleton so the next `getKnownClientKeys()` reflects the re-resolved
+ * manifest.
  */
 export declare function _clearClientPathsCacheForTests(): void;
 /**
@@ -51,5 +55,24 @@ export declare function clientSkillRelativePath(clientKey: string): string;
  * All known client keys from the manifest — used to derive the
  * `unity_open_mcp_generate_skill` `clients` enum and the allowlist in
  * the tool router.
+ *
+ * M31-optimizations Plan 4 / T4.4 (L6) — returns `Array.from(KNOWN_CLIENT_KEYS)`
+ * so callers that need an array share the underlying ReadonlySet singleton
+ * instead of allocating a fresh `Object.keys(...)` array per call.
  */
 export declare function knownClientKeys(): string[];
+/**
+ * The set of known client keys from the resolved skill manifest. Lazy on
+ * first access (the manifest itself is lazy); re-derived if the manifest
+ * cache is reset for tests. Returns the same Set reference on every call,
+ * so callers can compare by identity and avoid per-call allocation.
+ */
+export declare function getKnownClientKeys(): ReadonlySet<string>;
+/**
+ * @internal Test-only cache reset. Mirrors
+ * `_clearClientPathsCacheForTests`: clears the lazy client-keys singleton so
+ * a test that mutates `UNITY_OPEN_MCP_TOOLKIT_ROOT` and resets the manifest
+ * cache observes the new client-keys set on the next access. Do not call
+ * from runtime code.
+ */
+export declare function _clearKnownClientKeysCacheForTests(): void;

package/dist/skill/client-paths.js

@@ -164,9 +164,14 @@ export function resolveTemplateSkillPath() {
  * `UNITY_OPEN_MCP_TOOLKIT_ROOT` after a prior test already warmed the
  * cache need this to observe the override. Do not call from runtime
  * code.
+ *
+ * M31-optimizations Plan 4 / T4.4 — also clears the derived client-keys
+ * singleton so the next `getKnownClientKeys()` reflects the re-resolved
+ * manifest.
  */
 export function _clearClientPathsCacheForTests() {
     cached = null;
+    cachedClientKeys = null;
 }
 /**
  * Project-relative skill path for a client key
@@ -185,8 +190,48 @@ export function clientSkillRelativePath(clientKey) {
  * All known client keys from the manifest — used to derive the
  * `unity_open_mcp_generate_skill` `clients` enum and the allowlist in
  * the tool router.
+ *
+ * M31-optimizations Plan 4 / T4.4 (L6) — returns `Array.from(KNOWN_CLIENT_KEYS)`
+ * so callers that need an array share the underlying ReadonlySet singleton
+ * instead of allocating a fresh `Object.keys(...)` array per call.
  */
 export function knownClientKeys() {
-    return Object.keys(loadClientPathsManifest().clients);
+    return Array.from(getKnownClientKeys());
+}
+// ---------------------------------------------------------------------------
+// M31-optimizations Plan 4 / T4.4 (L6) — module-level ReadonlySet over the
+// resolved manifest's client keys. Mirrors the manifest cache: derived once on
+// first access and re-derived when the manifest cache is cleared
+// (`_clearClientPathsCacheForTests`). `routeGenerateSkill` previously
+// allocated `new Set(knownClientKeys())` per call; it now imports this
+// accessor and reuses one Set reference.
+//
+// Exposed as `getKnownClientKeys()` rather than a top-level `const` so the
+// laziness can mirror `getResolvedManifest` (which itself is lazy). The
+// function returns the SAME Set reference on every call after the first —
+// identity is the contract (asserted by a unit test).
+// ---------------------------------------------------------------------------
+let cachedClientKeys = null;
+/**
+ * The set of known client keys from the resolved skill manifest. Lazy on
+ * first access (the manifest itself is lazy); re-derived if the manifest
+ * cache is reset for tests. Returns the same Set reference on every call,
+ * so callers can compare by identity and avoid per-call allocation.
+ */
+export function getKnownClientKeys() {
+    if (cachedClientKeys === null) {
+        cachedClientKeys = new Set(Object.keys(loadClientPathsManifest().clients));
+    }
+    return cachedClientKeys;
+}
+/**
+ * @internal Test-only cache reset. Mirrors
+ * `_clearClientPathsCacheForTests`: clears the lazy client-keys singleton so
+ * a test that mutates `UNITY_OPEN_MCP_TOOLKIT_ROOT` and resets the manifest
+ * cache observes the new client-keys set on the next access. Do not call
+ * from runtime code.
+ */
+export function _clearKnownClientKeysCacheForTests() {
+    cachedClientKeys = null;
 }
 //# sourceMappingURL=client-paths.js.map

package/dist/skill/client-paths.js.map

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

package/dist/tool-router.d.ts

@@ -3,6 +3,11 @@ import type { Router } from "./router.js";
 import type { LiveClient } from "./live-client.js";
 import type { BatchSpawn } from "./batch-spawn.js";
 import type { BridgeEventStream } from "./event-stream.js";
+export declare function resolveRouteLogEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare const ROUTE_LOG_ENABLED: boolean;
+/** Log a happy-path route trace iff the opt-in env flag is set. No-op by
+ *  default so high-throughput agents do not pay a console.error per dispatch. */
+export declare function logRoute(message: string): void;
 import { listInstalledEditors, setInstallPath, type AvailableReleasesResult, type InstallPathResult, type OpenDeepLinkResult } from "./hub-control.js";
 /**
  * Injectable Hub-control backend. Each method maps 1:1 to a hub_* route
@@ -66,6 +71,21 @@ export declare class ToolRouter implements Router {
     private routeGenerateSkill;
     private routeManageTools;
     private manageToolsListGroups;
+    private manageToolsSuggest;
+    private manageToolsActivateFor;
+    /**
+     * Fetch the live bridge inventory (or null when offline) and reconcile auto-
+     * activation against it. Shared by `suggest` / `activate_for` so both see the
+     * same compiled-state + auto-activated snapshot as `list_groups` without
+     * duplicating the GET /tools hop.
+     */
+    private fetchInventoryAndReconcile;
+    /**
+     * Augment a {@link RecommendedGroup} with the session + compiled-state
+     * fields the agent needs to act on it: whether it is already active, its
+     * availability, and its catalog description / Unity package dependency.
+     */
+    private augmentRecommendation;
     /**
      * Notify MCP clients when the filtered ListTools surface changed. Skips the
      * callback when the active group set is unchanged (e.g. no-op reset).
@@ -77,6 +97,40 @@ export declare class ToolRouter implements Router {
     private manageToolsResult;
     private manageToolsError;
     private routeBridgeStatus;
+    /**
+     * T31.3 — terminate the hung Unity Editor after confirming the
+     * `editor_fd_exhaustion` signature is present in Editor.log. Requires
+     * explicit `confirm: true`. The relaunch half is intentionally deferred
+     * (the Hub owns the interactive-Editor launch recipe); the response tells
+     * the operator/agent to relaunch via the Hub.
+     *
+     * Safety contract (the plan's "explicit confirmation" requirement):
+     *   1. Refuses unless `confirm: true` is passed. A dry-run call (confirm
+     *      false or absent) returns the PID + diagnosis it would act on, no
+     *      side effect.
+     *   2. Refuses when the fd-exhaustion signature is ABSENT from Editor.log.
+     *      Never restart on a plain `dead_bridge` (usually a fixable compile
+     *      failure) or a merely offline bridge.
+     *   3. Surfaces unsaved-scene risk when the bridge is still reachable
+     *      enough to report dirty scenes. Does NOT block the kill — the Editor
+     *      is hung — but makes the risk visible in the response.
+     */
+    private routeRestartEditor;
+    /** Build the confirmed-kill response from a {@link KillResult}. */
+    private restartEditorKillResponse;
+    /**
+     * T31.4 — sample the live Unity process's file-descriptor usage and report
+     * headroom against Mono's ~1024 fd ceiling (the real trip point for the Bee
+     * build-driver hang). Proactive counterpart to restart_editor: lets an agent
+     * warn the operator to save + restart BEFORE the Editor hangs, while the
+     * bridge is still healthy. The probe runs server-side (lsof / /proc / Handle
+     * Count) and does NOT require the bridge to be reachable — the bridge is
+     * what dies on fd-exhaustion.
+     *
+     * Records the sample in the session-scoped in-memory ring so successive
+     * calls build a trend (monotonic climb = leak in progress). No disk cache.
+     */
+    private routeResourcePressure;
     private routeHubListEditors;
     private routeHubAvailableReleases;
     private routeHubInstallEditor;