unity-open-mcp 0.1.0 → 0.3.0

package/dist/server-instructions.js

@@ -0,0 +1,145 @@
+// M22 Plan 1 / T22.1.5 — Rich server instructions.
+//
+// The MCP `initialize` response carries an `instructions` string that clients
+// may inject into the system prompt. This module builds that string: a concise,
+// agent-facing briefing on how to drive Unity through this server cheaply and
+// correctly. Three concerns, in priority order:
+//
+//   1. Payload sizing & paging — start compact, expand on demand, bound with
+//      page_size. The single biggest agent mistake is pulling a full verbose
+//      dump into context when a folded overview + drill-down would do.
+//   2. Unity-API verification workflow — reflect before writing C#. LLM
+//      training data frequently contains incorrect or outdated Unity APIs;
+//      the server exposes the real types/members so an agent can verify.
+//   3. Mutate → gate → fix — every mutation runs a scoped gate; the delta is
+//      inline in the response, so no separate read_console is needed.
+//
+// AGENTS.md §"No internal references" applies: the instructions are a
+// user-visible surface, so they MUST stay clean of internal IDs (no milestone
+// numbers, no specs paths, no execution-plan task references, no `/references`
+// project names). State the contract on its own merits.
+//
+// Pure string builder — no I/O, no cross-file runtime imports — so it loads
+// cleanly under `node --experimental-strip-types` in tests.
+// Banned substrings — the instructions must never reference internal working
+// artifacts. Checked at test time so a future edit cannot regress this.
+//
+// Kept narrow on purpose: milestone IDs (M<n>), specs/ paths, /references
+// project handles, and execution-plan task IDs (T<n>.<n>.<n>). Plain English
+// ("Plan", "milestone", "task") is allowed and used naturally.
+const BANNED_INSTRUCTION_PATTERNS = [
+    /\bM\d+(\.\d+)*\b/, // M1, M4.5, M22.1, ...
+    /\bT\d+\.\d+\.\d+\b/, // T22.1.5, T2.4, ...
+    /specs\//i,
+    /\/references\//i,
+    /\bIvanMurzak\b/i,
+    /\bAnkleBreaker\b/i,
+    /\bUnityLauncherPro\b/i,
+    /\bunity-scanner\b/i,
+    /\bUnity-MCP\b/i,
+    /\bunity-mcp-beta\b/i,
+    /\bCoplay\b/i,
+    /\bUCP\b/,
+];
+/**
+ * Build the server instructions string. Memoized at the module level so
+ * repeated `Server` constructions (tests, multi-project) do not re-stringify.
+ */
+export function buildServerInstructions() {
+    return [
+        "This server drives the Unity Editor. Tool prefixes signal routing:",
+        "`unity_open_mcp_*` tools route through the live bridge (or fall back to a",
+        "headless batch Unity / offline disk parsers); `unity_senses_*` tools are",
+        "live-only and never batch. Call `unity_open_mcp_capabilities` first to",
+        "learn the full surface, then `unity_open_mcp_manage_tools(action=\"list_groups\")`",
+        "to see which tool groups are compiled in and active.",
+        "",
+        "PAYLOAD SIZING & PAGING (avoid flooding context)",
+        "- The heavy tools (`read_asset`, `search_assets`, `scene_get_data`,",
+        "  `find_references`, `validate_edit`, `scan_paths`) return variable-size",
+        "  payloads. Start with the default `compact` profile and expand on demand.",
+        "- `profile`: `compact` (default) | `balanced` | `full`. compact is the",
+        "  folded/counts shape; balanced is the inline-detail shape; full is the",
+        "  verbose tree. An explicit `profile` wins over the legacy `detail` alias.",
+        "- `page_size` + `cursor` / `next_cursor`: uniform paging. Set `page_size`",
+        "  to bound any profile; follow `pagination.next_cursor` to resume. Omit it",
+        "  to receive the whole (profile-shaped) payload in one response.",
+        "- Recommended starting page sizes: ~25 for `search_assets` / `validate_edit`",
+        "  / `scan_paths`, ~40 for `read_asset`, ~50 for `scene_get_data` /",
+        "  `find_references`. See the `costHints` block on `capabilities` for",
+        "  per-tool profile cost bands.",
+        "- Prefer drill-down over re-fetching: `read_asset` exposes `component`,",
+        "  `path`, `id`, `override` flags so a compact response can be expanded",
+        "  without re-reading raw YAML.",
+        "",
+        "UNITY-API VERIFICATION (reflect before you write C#)",
+        "- LLM training data frequently contains incorrect, outdated, or",
+        "  hallucinated Unity APIs. Verify before answering Unity-API questions or",
+        "  writing C#.",
+        "- Workflow: `search_assets` (find the actual shader/material/script in the",
+        "  project) → `find_members` (real type + member signatures) →",
+        "  `type_schema` (fields/properties on a type) → only then",
+        "  `execute_csharp` / `invoke_method` with the verified API.",
+        "- Common hallucination areas: shaders/materials (always search assets for",
+        "  real shader names), package-specific APIs (Input System, Cinemachine,",
+        "  ProBuilder, NavMesh, URP/HDRP), and APIs that changed between Unity",
+        "  versions. The bridge reflects the *actually installed* Unity + packages.",
+        "",
+        "MUTATE → GATE → FIX",
+        "- Mutating tools require non-empty `paths_hint` (empty fails with",
+        "  `paths_hint_required`). Scope it to the assets you touch.",
+        "- Every mutation runs a scoped gate (checkpoint → mutate → validate →",
+        "  delta) and returns the delta inline (`gate.delta`, `agentNextSteps`).",
+        "  Read it — mutation success ≠ project safe.",
+        "- Every response also carries a `logs[]` array: Unity console entries",
+        "  captured *during that call*. You do NOT need to poll `read_console`",
+        "  after a mutation to learn what happened — read `logs` first; escalate to",
+        "  `read_console` only for the global console buffer with stack traces.",
+        "- On gate failure, prefer `apply_fix` with `dry_run: true` first; review",
+        "  the preview, then apply. Some fixes are unsafe (need a `target_guid`).",
+        "",
+        "ROUTING & OFFLINE",
+        "- `list_assets`, `search_assets`, `find_references`, `read_asset`, and",
+        "  `read_compile_errors` work without a live bridge (offline disk parsers).",
+        "  Most other tools need the bridge running.",
+        "- If a tool returns `bridge_offline` or `bridge_compile_failed`, an",
+        "  offline bridge after a C# edit is frequently a *symptom* of a failed",
+        "  compile, not \"Unity isn't running.\" Call `read_compile_errors` — it",
+        "  reads Editor.log offline and survives a dead bridge.",
+        "- One test run at a time: never start a second `unity_senses_run_tests`",
+        "  before the first resolves. Never launch a second Unity instance for the",
+        "  same project (Unity holds a per-project lock).",
+        "",
+        "PATH CONVENTIONS",
+        "- Unless specified otherwise, all asset paths are relative to the",
+        "  project's `Assets/` folder and use forward slashes.",
+    ].join("\n");
+}
+let cached = null;
+/**
+ * Return the server instructions, memoized. The string is constant for the
+ * lifetime of the process, so a single computation is sufficient.
+ */
+export function getServerInstructions() {
+    if (cached === null) {
+        cached = buildServerInstructions();
+    }
+    return cached;
+}
+/**
+ * Test hook: assert the instructions carry no internal IDs / reference-project
+ * handles. Exposed so the test suite can call it without duplicating the
+ * banned-pattern list.
+ *
+ * @returns an array of offending patterns (empty when clean).
+ */
+export function findBannedInstructionsReferences(text) {
+    const offenders = [];
+    for (const pattern of BANNED_INSTRUCTION_PATTERNS) {
+        const match = pattern.exec(text);
+        if (match)
+            offenders.push(match[0]);
+    }
+    return offenders;
+}
+//# sourceMappingURL=server-instructions.js.map

package/dist/server-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../src/server-instructions.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,gDAAgD;AAChD,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,uEAAuE;AACvE,wEAAwE;AACxE,2EAA2E;AAC3E,yEAAyE;AACzE,6EAA6E;AAC7E,sEAAsE;AACtE,EAAE;AACF,sEAAsE;AACtE,8EAA8E;AAC9E,+EAA+E;AAC/E,wDAAwD;AACxD,EAAE;AACF,4EAA4E;AAC5E,4DAA4D;AAE5D,6EAA6E;AAC7E,wEAAwE;AACxE,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,+DAA+D;AAC/D,MAAM,2BAA2B,GAAa;IAC5C,kBAAkB,EAAE,uBAAuB;IAC3C,oBAAoB,EAAE,qBAAqB;IAC3C,UAAU;IACV,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,uBAAuB;IACvB,oBAAoB;IACpB,gBAAgB;IAChB,qBAAqB;IACrB,aAAa;IACb,SAAS;CACV,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,oEAAoE;QACpE,2EAA2E;QAC3E,0EAA0E;QAC1E,wEAAwE;QACxE,oFAAoF;QACpF,sDAAsD;QACtD,EAAE;QACF,kDAAkD;QAClD,qEAAqE;QACrE,0EAA0E;QAC1E,4EAA4E;QAC5E,wEAAwE;QACxE,yEAAyE;QACzE,4EAA4E;QAC5E,2EAA2E;QAC3E,4EAA4E;QAC5E,kEAAkE;QAClE,8EAA8E;QAC9E,oEAAoE;QACpE,sEAAsE;QACtE,gCAAgC;QAChC,yEAAyE;QACzE,wEAAwE;QACxE,gCAAgC;QAChC,EAAE;QACF,sDAAsD;QACtD,iEAAiE;QACjE,2EAA2E;QAC3E,eAAe;QACf,4EAA4E;QAC5E,+DAA+D;QAC/D,2DAA2D;QAC3D,6DAA6D;QAC7D,2EAA2E;QAC3E,yEAAyE;QACzE,uEAAuE;QACvE,4EAA4E;QAC5E,EAAE;QACF,qBAAqB;QACrB,mEAAmE;QACnE,6DAA6D;QAC7D,uEAAuE;QACvE,yEAAyE;QACzE,8CAA8C;QAC9C,uEAAuE;QACvE,uEAAuE;QACvE,4EAA4E;QAC5E,wEAAwE;QACxE,0EAA0E;QAC1E,0EAA0E;QAC1E,EAAE;QACF,mBAAmB;QACnB,wEAAwE;QACxE,4EAA4E;QAC5E,6CAA6C;QAC7C,qEAAqE;QACrE,wEAAwE;QACxE,yEAAyE;QACzE,wDAAwD;QACxD,yEAAyE;QACzE,2EAA2E;QAC3E,kDAAkD;QAClD,EAAE;QACF,kBAAkB;QAClB,mEAAmE;QACnE,uDAAuD;KACxD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC;;;GAGG;AACH,MAAM,UAAU,qBAAqB;IACnC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,GAAG,uBAAuB,EAAE,CAAC;IACrC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAAC,IAAY;IAC3D,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,OAAO,IAAI,2BAA2B,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,KAAK;YAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/tool-router.d.ts

@@ -3,6 +3,21 @@ 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";
+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
+ * handler; the default implementation calls the real hub-control functions
+ * (filesystem discovery / Unity archive feed / unityhub:// deep link / Hub
+ * CLI). Tests inject a fake to avoid real subprocess + network side effects
+ * (matching how `live` / `batch` are injected via the constructor).
+ */
+export interface HubControlBackend {
+    listInstalledEditors(): ReturnType<typeof listInstalledEditors>;
+    fetchAvailableReleases(): Promise<AvailableReleasesResult>;
+    openInstallDeepLink(version: string, changeset?: string | null): OpenDeepLinkResult;
+    getInstallPath(): InstallPathResult;
+    setInstallPath(path: string): ReturnType<typeof setInstallPath>;
+}
 import type { ToolSessionState } from "./tool-session-state.js";
 export interface RouteMeta {
     route: "live" | "batch";
@@ -15,9 +30,20 @@ export declare class ToolRouter implements Router {
     private eventStream;
     private sessionState;
     private onToolListChanged?;
+    private hubBackend;
     private readonly modelCache;
-    constructor(live: LiveClient, batch: BatchSpawn, projectPath: string, eventStream: BridgeEventStream, sessionState: ToolSessionState, onToolListChanged?: (() => void | Promise<void>) | undefined);
+    constructor(live: LiveClient, batch: BatchSpawn, projectPath: string, eventStream: BridgeEventStream, sessionState: ToolSessionState, onToolListChanged?: (() => void | Promise<void>) | undefined, hubBackend?: HubControlBackend);
     route(toolName: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    /**
+     * M23 Plan 3 — route with a per-call live-client override. Used when a
+     * per-request `_meta.port` override targets a different bridge instance than
+     * the default. The override client bypasses shared session state (it is a
+     * fresh LiveClient aimed at the override port); all other routing logic is
+     * identical to {@link route}. When `overrideLive` is null the default client
+     * is used (identical to {@link route}).
+     */
+    routeOverride(toolName: string, args: Record<string, unknown>, overrideLive: LiveClient): Promise<CallToolResult>;
+    private routeCore;
     private batchPingResult;
     private routeReadCompileErrors;
     private routeListAssets;
@@ -32,9 +58,20 @@ export declare class ToolRouter implements Router {
      * callback when the active group set is unchanged (e.g. no-op reset).
      */
     private maybeNotifyToolListChanged;
+    private reconcileAutoActivation;
     private resolveCompiledAvailability;
+    private computeCompiledAvailability;
     private manageToolsResult;
     private manageToolsError;
     private routeBridgeStatus;
+    private routeHubListEditors;
+    private routeHubAvailableReleases;
+    private routeHubInstallEditor;
+    private routeHubInstallModules;
+    private routeHubGetInstallPath;
+    private routeHubSetInstallPath;
     private routeFindReferences;
+    private routeDependencies;
+    private routeVerifyResult;
+    private routeSceneGetData;
 }