unity-open-mcp 0.1.0

package/dist/instance-discovery.js

@@ -0,0 +1,202 @@
+// M13 T4.3 / T4.7 — Per-project instance discovery.
+//
+// Mirror of the bridge-side InstancePortResolver (packages/bridge/Editor/Bridge/
+// InstancePortResolver.cs) + BridgeInstanceLock. The MCP server uses these to
+// find the right bridge instance for a given Unity project without any shared
+// config:
+//
+//   1. UNITY_OPEN_MCP_BRIDGE_PORT env var (override wins)
+//   2. ~/.unity-open-mcp/instances/<sha256(projectPath)>.json — the bridge's
+//      instance lock / heartbeat file. We trust its `port` only when its
+//      `pid` is still alive; a stale lock (crashed Unity) falls through.
+//   3. deterministic hash of the project path (20000 + sha256 % 10000).
+//
+// The hash formula MUST match the bridge exactly: first 8 bytes (16 hex chars)
+// of SHA256(normalizedPath) as a big-endian 64-bit unsigned integer, mod 10000,
+// + 20000. Cross-side consistency is pinned by tests in
+// instance-discovery.test.ts and the bridge InstancePortResolverTests.cs.
+//
+// No external deps (only node:crypto, node:fs, node:os, node:path) so the
+// "no runtime deps beyond MCP SDK" rule (mcp-server/AGENTS.md) holds.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const PORT_RANGE_START = 20000;
+export const PORT_RANGE_SIZE = 10000;
+/**
+ * Path normalization applied BEFORE hashing. Mirrors
+ * InstancePortResolver.NormalizePath in the bridge:
+ *   - backslashes -> forward slashes (Windows paths hash the same cross-platform)
+ *   - trailing slashes trimmed
+ * No lowercasing — macOS/Linux paths are case-sensitive.
+ */
+export function normalizePath(projectPath) {
+    if (!projectPath)
+        return "";
+    let norm = projectPath.replace(/\\/g, "/");
+    while (norm.length > 1 && norm.endsWith("/")) {
+        norm = norm.slice(0, -1);
+    }
+    return norm;
+}
+/** Lowercase hex SHA256 of the normalized project path. */
+export function projectHash(projectPath) {
+    return createHash("sha256").update(normalizePath(projectPath), "utf8").digest("hex");
+}
+/**
+ * Deterministic port for a project path: 20000 + (sha256(path) % 10000).
+ * Uses the first 8 bytes of the hash as a BigInt so the modulo matches the
+ * C# UInt64 computation exactly.
+ */
+export function computePort(projectPath) {
+    const hash = projectHash(projectPath);
+    const prefix = BigInt("0x" + hash.slice(0, 16));
+    return PORT_RANGE_START + Number(prefix % BigInt(PORT_RANGE_SIZE));
+}
+/** Directory holding one lock file per running bridge instance. */
+export function instancesDir() {
+    return join(homedir(), ".unity-open-mcp", "instances");
+}
+/** Path to this project's instance lock file. */
+export function lockPath(projectPath) {
+    return join(instancesDir(), `${projectHash(projectPath)}.json`);
+}
+/**
+ * Read this project's instance lock from disk. Returns null if the file is
+ * missing, unreadable, or doesn't parse. Never throws — the caller falls
+ * through to the deterministic hash on any failure.
+ */
+export function readInstanceLock(projectPath) {
+    const path = lockPath(projectPath);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * kill -0 equivalent. Returns true if a process with the given pid exists.
+ * Wrapped in try/catch: EPERM (exists but can't be probed) → true,
+ * ESRCH (no such process) → false. Mirrors the C# Process.GetProcessById
+ * logic in BridgeInstanceLock.IsPidAlive.
+ */
+export function isPidAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EPERM")
+            return true; // exists but we can't probe it
+        return false; // ESRCH or anything else → treat as dead
+    }
+}
+/**
+ * Resolve the bridge port for a project, with override precedence:
+ *   1. explicit envPort (already parsed + validated by the caller)
+ *   2. live instance lock's port (only when its pid is alive)
+ *   3. deterministic hash
+ *
+ * @param projectPath absolute Unity project root
+ * @param envPort     parsed UNITY_OPEN_MCP_BRIDGE_PORT, or undefined
+ */
+export function resolvePort(projectPath, envPort) {
+    if (typeof envPort === "number" && Number.isInteger(envPort) && envPort >= 1 && envPort <= 65535) {
+        return envPort;
+    }
+    const lock = readInstanceLock(projectPath);
+    if (lock && typeof lock.port === "number" && isPidAlive(lock.pid)) {
+        return lock.port;
+    }
+    return computePort(projectPath);
+}
+/**
+ * M14 — Resolve the bridge's per-session bearer token for a project.
+ *
+ * The token is only discoverable from a live instance lock (the same file we
+ * read the port from). When an explicit env port override is in use there is
+ * no lock file to read, so this returns undefined — in that case the MCP
+ * client sends no Authorization header and the bridge must be in authMode
+ * "none" for the request to succeed. Returns undefined when the lock is
+ * missing, stale (dead pid), or predates the token field.
+ *
+ * @param projectPath absolute Unity project root
+ * @param envPort     parsed UNITY_OPEN_MCP_BRIDGE_PORT, or undefined. When set,
+ *                    skips the lock read (no token to discover).
+ */
+export function resolveAuthToken(projectPath, envPort) {
+    if (typeof envPort === "number" && Number.isInteger(envPort) && envPort >= 1 && envPort <= 65535) {
+        return undefined;
+    }
+    const lock = readInstanceLock(projectPath);
+    if (!lock || !isPidAlive(lock.pid))
+        return undefined;
+    const token = lock.authToken;
+    return typeof token === "string" && token.length > 0 ? token : undefined;
+}
+// ---------------------------------------------------------------------------
+// Dead-bridge detection
+//
+// When the bridge assembly itself fails to compile, [InitializeOnLoad] never
+// re-runs after the domain reload, so the HTTP listener never restarts and the
+// heartbeat stops advancing. But the Unity process is still alive (sitting in
+// safe mode / showing compile errors). That stale-heartbeat + live-PID
+// signature is the ONLY out-of-band signal the MCP server has to distinguish
+// "normal reload, will recover" from "bridge assembly is dead, will never
+// recover" — and it only exists because the bridge keeps the lock file on disk
+// during a domain reload (releasing it only on graceful quit). See
+// BridgeHttpServer.Stop(releaseLock) and BridgeInstanceLock.
+/**
+ * A heartbeat is considered "stale" once it is this many milliseconds old.
+ * The bridge writes every 0.5s (BridgeHeartbeat.HeartbeatIntervalSec), so
+ * anything older than a few seconds means the heartbeat writer is no longer
+ * running. The threshold is generous to absorb a slow domain reload + ILPP
+ * pass without a false "dead" classification.
+ */
+export const HEARTBEAT_STALE_MS = 10_000;
+/**
+ * Age of the lock's heartbeat in milliseconds, measured against `nowMs`.
+ * Returns `Infinity` when the heartbeat timestamp is missing or unparseable,
+ * so a malformed lock is treated as maximally stale (and thus, if the PID is
+ * alive, "dead_bridge").
+ */
+export function heartbeatAgeMs(lock, nowMs = Date.now()) {
+    if (!lock || !lock.heartbeatAt)
+        return Infinity;
+    const t = Date.parse(lock.heartbeatAt);
+    if (!Number.isFinite(t))
+        return Infinity;
+    return Math.max(0, nowMs - t);
+}
+/**
+ * Classify a bridge instance from its on-disk lock. `lock` may be null (no
+ * lock file / unreadable) — treated as "gone". This is a pure function over
+ * the lock snapshot + current time + PID liveness; it does no I/O of its own.
+ */
+export function classifyInstance(lock, nowMs = Date.now()) {
+    if (!lock)
+        return "gone";
+    if (!isPidAlive(lock.pid))
+        return "gone";
+    const age = heartbeatAgeMs(lock, nowMs);
+    if (age >= HEARTBEAT_STALE_MS)
+        return "dead_bridge";
+    if (lock.state === "reloading" || lock.state === "compiling")
+        return "reloading";
+    return "healthy";
+}
+//# sourceMappingURL=instance-discovery.js.map

package/dist/instance-discovery.js.map

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

package/dist/live-client.d.ts

@@ -0,0 +1,68 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { Router } from "./router.js";
+import type { PingCache } from "./ping-cache.js";
+import { type PollAndDismissOptions } from "./dialog-dismiss.js";
+export declare class LiveClient implements Router {
+    private baseUrl;
+    private pingCache;
+    private dismissEnabled;
+    private dismissTimeoutMs;
+    private dismissIntervalMs;
+    /** M14 — per-session bearer token auto-discovered from the instance lock.
+     *  Undefined when no live lock was found (older bridge / env port override);
+     *  in that case no Authorization header is sent and the bridge must be in
+     *  authMode "none" for requests to succeed. */
+    private authToken;
+    /** Absolute Unity project path, used to read the instance lock mid-session
+     *  for dead-bridge detection. Optional so existing callers/tests that don't
+     *  exercise the fail-fast path keep working; when absent, a /ping failure
+     *  falls back to the original bridge_offline behavior. */
+    private projectPath;
+    /** One-shot guard so the version-compat warning (server vs bridge) is emitted
+     *  at most once per process — every /ping would otherwise re-warn. */
+    private compatWarned;
+    constructor(port: number, pingCache: PingCache, authToken?: string, projectPath?: string);
+    /**
+     * Emit the server/bridge version-compatibility warning at most once per
+     * process. Advisory only — the caller never blocks on this. Suppressed
+     * entirely by UNITY_OPEN_MCP_SKIP_VERSION_CHECK=1. See docs/versioning.md.
+     */
+    private maybeWarnCompat;
+    isLiveAvailable(): Promise<boolean>;
+    route(toolName: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    private handlePing;
+    private handleToolCall;
+    private handleRunTests;
+    private pollTestResults;
+    private postTool;
+    private ensureReady;
+    private deadBridgeResult;
+    private waitForCompile;
+    /**
+     * Run the launch-errors dismiss polling loop. Indirected through a method
+     * so unit tests can stub the OS-clicking loop without invoking
+     * PowerShell / osascript / xdotool. Production uses the real
+     * `pollAndDismissLaunchErrors`.
+     */
+    protected runDismissLoop(opts: PollAndDismissOptions): Promise<void>;
+    readResource(route: string): Promise<Record<string, unknown>>;
+    /**
+     * M18 Plan 2 / T18.2.3 — fetch the compiled-state tool inventory from the
+     * bridge (`GET /tools`). Returns the set of tool names the bridge compiled
+     * in (KnownTools ∪ BridgeToolRegistry), so the MCP server can report per-
+     * group availability in `unity_open_mcp_capabilities` and
+     * `unity_open_mcp_manage_tools(list_groups)`.
+     *
+     * Returns null when the bridge is unreachable or the response is malformed
+     * — callers fall back to `available: null` (unknown) so the agent is
+     * directed at manage_tools when the bridge comes back up.
+     */
+    listBridgeTools(): Promise<{
+        tools: Set<string>;
+        groups: Array<{
+            id: string;
+            tools: string[];
+        }>;
+    } | null>;
+    private fetchWithTimeout;
+}