unity-open-mcp 1.1.0 → 1.3.0

package/README.md

@@ -16,6 +16,19 @@ You do not need to install this package yourself — your MCP client spawns it v
 `npx`. The sections below show both the zero-install `npx` path and the optional
 global install.
 
+For a first installation, the setup command merges the Unity package pins,
+project MCP config, and bundled core skill without requiring a running Editor:
+
+```bash
+npx -y unity-open-mcp@latest setup \
+  --project /absolute/path/to/MyGame \
+  --client cursor
+```
+
+Supported project-config ids are `cursor`, `claude`, `opencode`, and `agents`.
+Run `npx -y unity-open-mcp@latest setup --help` for dry-run, skill-skip, JSON,
+and exit-code details.
+
 ### Configure your MCP client
 
 Pick your client and merge a `unity-open-mcp` entry using the canonical
@@ -39,7 +52,7 @@ npm install -g unity-open-mcp
 
 Then use `"command": "unity-open-mcp", "args": []` (Cursor / Claude Desktop) or
 `"command": ["unity-open-mcp"]` (OpenCode) in your client config. Update with
-`npm update -g unity-open-mcp`.
+`unity-open-mcp update` (or `npm update -g unity-open-mcp`).
 
 Core environment variables and modal-policy options are documented in the
 [client configuration reference](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/setup/client-configuration.md)
@@ -73,10 +86,24 @@ npx unity-open-mcp run-tool unity_open_mcp_capabilities \
 ```
 
 Commands also include event streaming, verify, baseline, and regression
-automation. All accept `--json` for machine-readable output. See the
+automation, plus bridge-independent project setup. All accept `--json` for
+machine-readable output. See the
 [CLI and automation reference](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/api/cli-automation.md)
 for the full option reference.
 
+Check or apply an MCP server update without a Unity project path:
+
+```bash
+unity-open-mcp update --check
+unity-open-mcp update
+```
+
+The command updates global and project-local npm installs. When launched by
+`npx`, it prints the pin to change instead of modifying the npx cache. It never
+changes Unity package pins or MCP client configuration; use the repository's
+[Updating guide](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/updating.md)
+for the coordinated and air-gapped paths.
+
 ## Version pinning
 
 The client configuration reference pins the server so it stays in lockstep
@@ -89,8 +116,12 @@ client and Unity package pins together — see
 - [Agent setup](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/setup/agent-setup.md)
 - [Full manual setup](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/setup/manual-setup.md)
 - [MCP client configuration](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/setup/client-configuration.md)
+- [Portable, committable MCP configuration](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/setup/portable-config.md)
 - [Unity Hub Pro wizard walkthrough](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/setup/wizard-setup.md)
+- [Updating and air-gapped installs](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/updating.md)
 - [MCP tool catalog and routing](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/api/mcp-tools.md)
+- [Project-defined commands](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/api/project-commands.md)
+- [Asynchronous jobs](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/api/jobs.md)
 - [Bridge HTTP API](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/api/bridge-http.md)
 - [Architecture](https://github.com/AlexeyPerov/Unity-Open-MCP/blob/master/docs/architecture.md)
 

package/dist/agent-identity.d.ts

@@ -5,6 +5,18 @@
  * an explicit `_meta.agentId` override.
  */
 export declare const PROCESS_AGENT_ID: string;
+/**
+ * Who made a call and which bridge port it pinned for that call alone: the key
+ * session-owned jobs are filed under. `port` is the per-request override only,
+ * never the default client's env pin. The router threads it through every entry
+ * point (direct call, `manage_tools` invoke, port override).
+ */
+export interface RequestIdentity {
+    agent: string;
+    port?: number;
+}
+/** Identity of a call that carries no routing metadata. */
+export declare const PROCESS_IDENTITY: RequestIdentity;
 /** Minimum/maximum valid TCP port for an override. */
 export declare const MIN_PORT = 1;
 export declare const MAX_PORT = 65535;

package/dist/agent-identity.js

@@ -32,6 +32,8 @@ import { randomBytes } from "node:crypto";
  * an explicit `_meta.agentId` override.
  */
 export const PROCESS_AGENT_ID = `agent-${process.pid}-${randomBytes(3).toString("hex")}`;
+/** Identity of a call that carries no routing metadata. */
+export const PROCESS_IDENTITY = { agent: PROCESS_AGENT_ID };
 /** Minimum/maximum valid TCP port for an override. */
 export const MIN_PORT = 1;
 export const MAX_PORT = 65535;

package/dist/agent-identity.js.map

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

package/dist/batch-spawn.d.ts

@@ -1,8 +1,33 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { Router } from "./router.js";
+export declare const FAILED_RESOLUTION_TTL_MS = 30000;
+/**
+ * A headless Unity run this server is currently driving for a project. Held
+ * for exactly as long as the per-project batch lease: from just before the
+ * spawn until the child closes (or fails to start).
+ */
+export interface HeadlessRunInfo {
+    /** MCP tool whose call spawned the run, e.g. `unity_open_mcp_compile_check`. */
+    tool: string;
+    /** Batch operation passed to the Unity entry point, e.g. `compile_check`. */
+    operation: string;
+    /** Epoch ms when the lease was taken. */
+    startedAt: number;
+    /** Overall batch timeout; the child is killed once it elapses. */
+    timeoutMs: number;
+    /** OS pid of the Unity child; null until the spawn returned one. */
+    pid: number | null;
+}
+/**
+ * The headless run this server is driving for `projectPath`, or null when no
+ * batch lease is held for it. Returns a copy; callers cannot mutate the lease.
+ */
+export declare function activeHeadlessRun(projectPath: string | null | undefined): HeadlessRunInfo | null;
 export declare const VERIFY_BATCH_TOOL_NAMES: ReadonlySet<string>;
 export declare const ALWAYS_BATCH_TOOLS: ReadonlyMap<string, string>;
 export declare const BATCH_TOOL_NAMES: Set<string>;
+export declare function extractJson(stdout: string): string | null;
 export declare class BoundedTextAccumulator {
     private decoder;
     private bytes;
@@ -67,6 +92,13 @@ export interface BatchSpawnOptions {
      * UNITY_PROJECT_PATH env var, then the instance lock's projectPath.
      */
     projectPath?: string;
+    /**
+     * Optional replacement for `child_process.spawn` (test hook), for child
+     * event sequences a real process does not produce on demand.
+     */
+    spawnProcess?: (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+    /** Optional clock (test hook) for the failed-resolution TTL. */
+    now?: () => number;
 }
 export declare class BatchSpawn implements Router {
     private unityPath;
@@ -74,10 +106,17 @@ export declare class BatchSpawn implements Router {
     private projectPath;
     private timeoutMs;
     private readonly discoveryRoots?;
+    private readonly spawnProcess;
+    private readonly now;
+    private resolutionError?;
+    private resolutionKey?;
+    private resolvedAt;
     constructor(options?: BatchSpawnOptions);
     isBatchTool(toolName: string): boolean;
     getProjectPath(): string;
+    headlessAvailable(): boolean;
     route(toolName: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    private refreshUnityPath;
     private validateUnityPath;
     private spawnUnity;
 }