unity-open-mcp 0.1.0

package/dist/event-stream.js

@@ -0,0 +1,228 @@
+// M13 T4.4 — bridge event stream client.
+//
+// The MCP server runs behind a stdio transport, so it can't directly forward
+// bridge SSE to MCP notifications without a background SSE reader. This module
+// owns that reader: a single SSE subscription per server process, parsed into
+// events and pushed into an in-memory queue. The `unity_senses_pull_events`
+// tool drains the queue per call so an agent can poll incremental console /
+// compile-state events without burning an HTTP round-trip on every check.
+//
+// Lifecycle:
+//   - ensureSubscription() is called on every tool dispatch; it starts the SSE
+//     reader once and is a no-op afterwards.
+//   - The reader reconnects with the last subscriber id so it keeps its cursor
+//     across disconnects (a 10-minute SSE timeout or a Unity domain reload).
+//   - On bridge-unavailable (connection refused), ensureSubscription records
+//     the failure and the tool surfaces a `bridge_unavailable` error to the
+//     agent instead of hanging.
+//
+// No new runtime deps — uses only `node:crypto`, the global `fetch`, and the
+// `node:events` API.
+import { randomBytes } from "node:crypto";
+const QUEUE_CAPACITY = 500;
+export class BridgeEventStream {
+    baseUrl;
+    authToken;
+    subscriberId;
+    queue = [];
+    dropped = 0;
+    connected = false;
+    lastError = null;
+    abortController = null;
+    reconnectTimer = null;
+    started = false;
+    constructor(baseUrl, subscriberId, authToken) {
+        this.baseUrl = baseUrl;
+        this.authToken = authToken;
+        this.subscriberId =
+            subscriberId ?? randomBytes(16).toString("hex");
+    }
+    /**
+     * Start the SSE reader if it isn't running. Safe to call repeatedly; returns
+     * true when a fresh subscription was started this call.
+     */
+    ensureSubscription() {
+        if (this.started)
+            return false;
+        this.started = true;
+        this.connect();
+        return true;
+    }
+    connect() {
+        if (this.abortController)
+            return;
+        this.abortController = new AbortController();
+        const url = `${this.baseUrl}/events?subscriber=${encodeURIComponent(this.subscriberId)}&max_per_poll=100`;
+        // SSE read is streaming; consume body manually so we can split on
+        // double-newline event boundaries. M14 — carry the bearer token so the
+        // stream is gated the same way as tool/ping requests.
+        const headers = { Accept: "text/event-stream" };
+        if (this.authToken)
+            headers["Authorization"] = `Bearer ${this.authToken}`;
+        fetch(url, {
+            method: "GET",
+            headers,
+            signal: this.abortController.signal,
+        })
+            .then((res) => {
+            if (!res.ok || !res.body) {
+                throw new Error(`HTTP ${res.status}`);
+            }
+            this.connected = true;
+            this.lastError = null;
+            this.pump(res.body);
+        })
+            .catch((err) => {
+            this.connected = false;
+            const message = err instanceof Error ? err.message : String(err);
+            // AbortError means we intentionally stopped; treat as clean disconnect.
+            this.lastError = message.includes("abort") ? null : message;
+            this.scheduleReconnect();
+        });
+    }
+    async pump(body) {
+        const reader = body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            // eslint-disable-next-line no-constant-condition
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let sep;
+                // SSE events are separated by a blank line.
+                while ((sep = buffer.indexOf("\n\n")) >= 0) {
+                    const block = buffer.slice(0, sep);
+                    buffer = buffer.slice(sep + 2);
+                    this.handleBlock(block);
+                }
+            }
+        }
+        catch (err) {
+            // Network drop mid-stream — schedule a reconnect.
+            const message = err instanceof Error ? err.message : String(err);
+            this.lastError = message;
+        }
+        finally {
+            this.connected = false;
+            try {
+                await reader.cancel();
+            }
+            catch { /* ignore */ }
+            this.scheduleReconnect();
+        }
+    }
+    handleBlock(block) {
+        const evt = BridgeEventStream.parseSseBlock(block);
+        if (evt)
+            this.enqueue(evt);
+    }
+    /**
+     * Parse one SSE block (the text between two blank-line separators) into a
+     * BridgeEvent, or null when the block carries no data. Exposed for unit
+     * testing — the SSE reader loop calls it via handleBlock.
+     */
+    static parseSseBlock(block) {
+        let eventName = "message";
+        const dataLines = [];
+        for (const line of block.split("\n")) {
+            if (line.startsWith("event:")) {
+                eventName = line.slice(6).trim();
+            }
+            else if (line.startsWith("data:")) {
+                dataLines.push(line.slice(5).replace(/^ /, ""));
+            }
+        }
+        if (dataLines.length === 0)
+            return null;
+        const data = dataLines.join("\n");
+        let parsed = {};
+        try {
+            parsed = JSON.parse(data);
+        }
+        catch {
+            // Non-JSON payload (e.g. "close"); keep raw.
+            parsed = { raw: data };
+        }
+        const evt = {
+            seq: typeof parsed.seq === "number" ? parsed.seq : Date.now(),
+            ts: typeof parsed.ts === "string" ? parsed.ts : new Date().toISOString(),
+            type: eventName,
+        };
+        if (eventName === "log") {
+            evt.logType = typeof parsed.logType === "string" ? parsed.logType : "log";
+            evt.message = typeof parsed.message === "string" ? parsed.message : "";
+            evt.stack = typeof parsed.stack === "string" ? parsed.stack : undefined;
+        }
+        else if (eventName === "editor_state") {
+            evt.state = typeof parsed.state === "string" ? parsed.state : "";
+            evt.isCompiling = parsed.isCompiling === true;
+            evt.isPlaying = parsed.isPlaying === true;
+        }
+        else if (eventName === "missed") {
+            // SSE "missed" marker — surfaces as its own event so the agent sees the gap.
+            evt.message = `missed=${parsed.missed ?? "unknown"}`;
+        }
+        return evt;
+    }
+    enqueue(evt) {
+        this.queue.push(evt);
+        while (this.queue.length > QUEUE_CAPACITY) {
+            this.queue.shift();
+            this.dropped++;
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.abortController = null;
+            this.connect();
+        }, 2000);
+    }
+    /** Drain all queued events. The subscription keeps running. */
+    drain(maxEvents) {
+        const cap = maxEvents > 0 && maxEvents <= 1000 ? maxEvents : 100;
+        const out = this.queue.slice(0, cap);
+        this.queue = this.queue.slice(cap);
+        return out;
+    }
+    /** One-shot pull: start the subscription if needed and drain. */
+    pull(maxEvents) {
+        const started = this.ensureSubscription();
+        const events = this.drain(maxEvents);
+        return {
+            subscriberId: this.subscriberId,
+            events,
+            dropped: this.dropped,
+            connected: this.connected,
+            started,
+            lastError: this.lastError,
+        };
+    }
+    /** Stop the reader and clear state. Idempotent; used in tests. */
+    stop() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+        this.started = false;
+        this.connected = false;
+        this.queue = [];
+        this.dropped = 0;
+    }
+    get isConnected() {
+        return this.connected;
+    }
+    get id() {
+        return this.subscriberId;
+    }
+}
+//# sourceMappingURL=event-stream.js.map

package/dist/event-stream.js.map

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

package/dist/gate-error.d.ts

@@ -0,0 +1,18 @@
+export interface MutationEnvelope {
+    mutation: {
+        success: boolean;
+        output: unknown;
+        error: {
+            code: string;
+            message: string;
+        } | null;
+    };
+    gate: {
+        mode: string;
+        skipped: boolean;
+        validation: unknown;
+        delta: Record<string, unknown> | null;
+    };
+    agentNextSteps: string[];
+}
+export declare function deriveIsError(envelope: MutationEnvelope): boolean;

package/dist/gate-error.js

@@ -0,0 +1,11 @@
+export function deriveIsError(envelope) {
+    if (!envelope.mutation.success)
+        return true;
+    if (envelope.gate.mode === "enforce" && envelope.gate.delta) {
+        const newErrors = envelope.gate.delta.newErrors;
+        if (typeof newErrors === "number" && newErrors > 0)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=gate-error.js.map

package/dist/gate-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-error.js","sourceRoot":"","sources":["../src/gate-error.ts"],"names":[],"mappings":"AAeA,MAAM,UAAU,aAAa,CAAC,QAA0B;IACtD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAE5C,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAC5D,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;QAChD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IAClE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare function createServer(projectPath: string, port: number, authToken?: string): Server;

package/dist/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.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 } from "./schema-defaults.js";
+import { resolvePort, resolveAuthToken } from "./instance-discovery.js";
+import { BridgeEventStream } from "./event-stream.js";
+import { KNOWN_COMMANDS } from "./cli/args.js";
+import { runCli } from "./cli/cli.js";
+import { readPackageVersion } from "./package-version.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.
+ */
+function getEnv() {
+    const projectPath = process.env.UNITY_PROJECT_PATH;
+    if (!projectPath) {
+        console.error("unity-open-mcp: UNITY_PROJECT_PATH environment variable is required.");
+        process.exit(1);
+    }
+    const rawEnvPort = process.env.UNITY_OPEN_MCP_BRIDGE_PORT;
+    const envPort = rawEnvPort ? parseInt(rawEnvPort, 10) : undefined;
+    const port = resolvePort(projectPath, Number.isInteger(envPort) ? envPort : undefined);
+    const source = rawEnvPort && Number.isInteger(envPort)
+        ? "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, Number.isInteger(envPort) ? 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 };
+}
+export function createServer(projectPath, port, authToken) {
+    const server = new Server({ name: "unity-open-mcp", version: PACKAGE_VERSION }, { capabilities: { tools: { listChanged: true }, resources: {} } });
+    const pingCache = new PingCache();
+    const liveClient = new LiveClient(port, pingCache, authToken, projectPath);
+    const batchSpawn = new BatchSpawn();
+    // 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(`http://127.0.0.1:${port}`, undefined, authToken);
+    // M18 Plan 2 / T18.2.2 — per-session tool-group visibility state. Lives in
+    // the MCP server (matches the Coplay model and the resolved decision in
+    // M18 execution-plan.md). Resets to `core`-only 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,
+    });
+    // M18 Plan 2 / T18.2.2 — ListTools filters per the session's active groups.
+    // A fresh session sees only `core` + always-visible meta-tools (capabilities,
+    // manage_tools, ping, ...). Activating a group via manage_tools adds its
+    // tools to subsequent ListTools responses in the same session.
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: filterVisibleTools(ALL_TOOLS, sessionState),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const callArgs = (args ?? {});
+        // 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, callArgs) : callArgs;
+        return router.route(name, routedArgs);
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: ALL_RESOURCES,
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        return resourceRouter.read(uri);
+    });
+    return server;
+}
+async function main() {
+    // M15 T6.1 — CLI dispatch. When argv[0] is a known subcommand (ping,
+    // wait-for-ready, status, run-tool) or an explicit --help/--version, run
+    // the thin CLI and exit. Otherwise fall through to the stdio MCP server so
+    // a single `bin` works for both MCP clients and scripting.
+    const firstArg = process.argv[2];
+    const looksLikeCli = firstArg !== undefined &&
+        (KNOWN_COMMANDS.includes(firstArg) ||
+            firstArg === "--help" ||
+            firstArg === "-h" ||
+            firstArg === "--version" ||
+            firstArg === "-V");
+    if (looksLikeCli) {
+        const outcome = await runCli({ version: PACKAGE_VERSION });
+        if (outcome.handled) {
+            process.exit(outcome.exitCode);
+        }
+        // runCli only returns handled:false when argv had no recognized command;
+        // in that case fall through to the stdio server below.
+    }
+    const { port, projectPath, authToken } = getEnv();
+    const server = createServer(projectPath, port, authToken);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("unity-open-mcp fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/instance-discovery.d.ts

@@ -0,0 +1,117 @@
+export declare const PORT_RANGE_START = 20000;
+export declare const PORT_RANGE_SIZE = 10000;
+/** Editor state values the bridge writes into its lock / heartbeat file. */
+export type InstanceState = "idle" | "compiling" | "reloading" | "entering_playmode" | "playing" | "exiting_playmode";
+/** Shape of ~/.unity-open-mcp/instances/<hash>.json (bridge BridgeInstanceLock). */
+export interface InstanceLock {
+    pid: number;
+    port: number;
+    /** M14 — per-session bearer token. Optional for back-compat with locks
+     *  written by older bridges; when absent the MCP client sends no header
+     *  (authMode "none" accepts that). */
+    authToken?: string;
+    projectPath: string;
+    projectHash: string;
+    startedAt: string;
+    updatedAt: string;
+    heartbeatAt: string;
+    state: InstanceState;
+    isPlaying: boolean;
+    isCompiling: boolean;
+    bridgeVersion: string;
+    unityVersion: string;
+}
+/**
+ * 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 declare function normalizePath(projectPath: string): string;
+/** Lowercase hex SHA256 of the normalized project path. */
+export declare function projectHash(projectPath: string): string;
+/**
+ * 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 declare function computePort(projectPath: string): number;
+/** Directory holding one lock file per running bridge instance. */
+export declare function instancesDir(): string;
+/** Path to this project's instance lock file. */
+export declare function lockPath(projectPath: string): string;
+/**
+ * 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 declare function readInstanceLock(projectPath: string): InstanceLock | 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 declare function isPidAlive(pid: number): boolean;
+/**
+ * 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 declare function resolvePort(projectPath: string, envPort?: number): number;
+/**
+ * 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 declare function resolveAuthToken(projectPath: string, envPort?: number): string | undefined;
+/**
+ * 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 declare const HEARTBEAT_STALE_MS = 10000;
+/**
+ * Coarse health classification of a bridge instance derived from its on-disk
+ * lock. Used by the live-client to decide whether a /ping failure is
+ * recoverable (keep waiting) or fatal (fail fast).
+ *
+ *   - "healthy"     — lock fresh and PID alive; bridge is (or just was) up.
+ *   - "reloading"   — lock fresh + state="reloading" + PID alive; a normal
+ *                     domain reload in flight, expected to recover.
+ *   - "dead_bridge" — PID alive BUT heartbeat is stale. The Unity process is
+ *                     running but the bridge's heartbeat writer is gone — the
+ *                     signature of a bridge assembly that failed to recompile.
+ *                     /ping will not recover until the C# error is fixed.
+ *   - "gone"        — no lock, or PID no longer alive. No live instance.
+ */
+export type InstanceClassification = "healthy" | "reloading" | "dead_bridge" | "gone";
+/**
+ * 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 declare function heartbeatAgeMs(lock: InstanceLock | null, nowMs?: number): number;
+/**
+ * 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 declare function classifyInstance(lock: InstanceLock | null, nowMs?: number): InstanceClassification;