sbox-mcp-server 1.3.0 → 1.3.2

package/README.md

@@ -1,55 +1,60 @@
 # sbox-mcp-server
 
-MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — 78 working tools for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, and more.
+MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — 99 working tools for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, and type discovery.
 
-## Quick Start
+## Fastest install — the Claude Code plugin
 
-### 1. Install the Bridge Addon in s&box
+If you use Claude Code, the easiest install is the companion plugin. It registers this MCP server automatically, ships a workflow skill, and includes the `sbox-game-dev` specialist agent.
 
-The Bridge Addon runs inside the s&box editor and receives commands from this MCP server.
-
-**From source:**
-```bash
-git clone https://github.com/lousputthole/sbox-claude.git
+```
+/plugin marketplace add LouSputthole/Sbox-Claude
+/plugin install sbox-claude
 ```
 
-Then in s&box:
-1. Open your project in the s&box editor
-2. Go to **Library Manager** and create a new library called **"claudebridge"**
-3. Copy `sbox-bridge-addon/Editor/MyEditorMenu.cs` into the library's `Editor/` folder
-4. Restart s&box
+You still need to install the s&box-side **bridge addon** into your project's `Libraries/` folder (see step 1 below). The plugin handles the Claude side; the addon handles the s&box side.
 
-### 2. Build the MCP Server
+## Manual install — three steps
 
-```bash
-cd sbox-claude/sbox-mcp-server
-npm install
-npm run build
+### 1. Install the bridge addon in s&box
+
+The bridge addon runs inside the s&box editor and receives commands from this MCP server. It MUST live inside a project's `Libraries/` folder — putting it in s&box's global `addons/` will silently fail to compile.
+
+```powershell
+git clone https://github.com/LouSputthole/Sbox-Claude.git
+cd Sbox-Claude
+.\install.ps1 -RemoveStaleAddons      # Windows, auto-detects your s&box project
+./install.sh --remove-stale            # Linux/Mac/WSL
 ```
 
-### 3. Connect to Claude Code
+See [INSTALL.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/INSTALL.md) for the full guide and manual fallback.
+
+### 2. Register the MCP server with Claude Code
 
 ```bash
-claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
+claude mcp add sbox -- npx sbox-mcp-server
 ```
 
-### 4. Open the Bridge Dock
-
-In s&box, go to **View > Claude Bridge** to open the dock panel. The dock **must be visible** for commands to be processed.
+This is the bare command — equivalent to what the plugin's `.mcp.json` does for you.
 
-That's it. Start Claude Code and start building.
+### 3. Open s&box
 
-## How It Works
+Open your project. The bridge starts automatically. Verify with:
 
 ```
-Claude Code --> (stdio) --> sbox-mcp-server --> (file IPC) --> Bridge Addon --> s&box Editor
+Check the bridge status.
 ```
 
-Communication uses **file-based IPC** through `%TEMP%/sbox-bridge-ipc/`. The MCP server writes request JSON files, the Bridge Addon (running inside s&box) polls for them, processes on the main editor thread, and writes response files back.
+You should see `connected: true, handlerCount: 99`.
 
-WebSocket is not used — s&box's sandboxed C# environment does not allow `System.Net`.
+## How it works
 
-## Tools (78 working, 89 defined)
+```
+Claude Code → (stdio) → sbox-mcp-server → (file IPC) → bridge addon → s&box editor
+```
+
+Communication uses file-based IPC through `%TEMP%/sbox-bridge-ipc/`. The MCP server writes request JSON files, the bridge addon (running inside s&box) polls and processes on the main editor thread, then writes response files back. WebSocket is not used — s&box's sandboxed C# environment blocks `System.Net`.
+
+## Tools (99 working)
 
 | Category | Tools |
 |----------|-------|
@@ -57,8 +62,8 @@ WebSocket is not used — s&box's sandboxed C# environment does not allow `Syste
 | **Scripts** | create_script, edit_script, delete_script, trigger_hotload |
 | **Scenes** | list_scenes, load_scene, save_scene, create_scene |
 | **GameObjects** | create/delete/duplicate/rename, set_parent/enabled/transform |
-| **Components** | get/set_property, get_all_properties, list_available, add_component |
-| **Hierarchy** | get_scene_hierarchy, get/select/focus_object |
+| **Components** | get/set_property, get_all_properties, list_available, add_component, set_prefab_ref |
+| **Hierarchy** | get_scene_hierarchy (with `maxDepth` + `rootId`), get/select/focus_object |
 | **Assets** | search_assets, list_asset_library, install_asset, get_asset_info |
 | **Materials** | assign_model, create/assign_material, set_material_property |
 | **Audio** | list_sounds, create_sound_event, assign_sound, play_sound_preview |
@@ -69,20 +74,38 @@ WebSocket is not used — s&box's sandboxed C# environment does not allow `Syste
 | **Physics** | add_physics, add_collider, add_joint, raycast |
 | **UI** | create_razor_ui, add_screen_panel, add_world_panel |
 | **Templates** | create_player/npc_controller, create_game_manager, create_trigger_zone |
-| **Networking** | network_helper, configure/status, spawn, ownership, sync, RPCs, templates |
-| **Publishing** | project_config, validate, thumbnail, package_details, install_asset |
+| **Networking** | network_helper, configure/status, spawn, ownership, sync, RPCs, lobby/event templates |
+| **Publishing** | project_config, validate, thumbnail, package_details |
+| **World gen** | invoke_button, list_component_buttons, raycast_terrain, build_terrain_mesh |
+| **Map edit** | add_terrain_hill/clearing/trail, clear_terrain_features, sculpt_terrain |
+| **Caves / Forest** | add_cave_waypoint, clear_cave_path, add_forest_poi/trail, set_forest_seed, clear_forest_pois, paint_forest_density |
+| **Placement** | place_along_path |
+| **Discovery** | describe_type, search_types, get_method_signature, find_in_project |
 | **Status** | get_bridge_status |
 
-### Not implementable (no s&box API)
+## Working with Claude effectively
 
-pause_play, resume_play, get_console_output, get_compile_errors, clear_console, build_project, get_build_status, clean_build, export_project, prepare_publish
+Two disciplines prevent the iteration-loop trap:
+
+1. **After visual changes, call `take_screenshot` and read the PNG.** Claude is a multimodal model — it can see the result. Guessing about visual outcomes from code alone produces long iteration loops.
+2. **Before writing code that touches an unfamiliar s&box type, call `describe_type` or `search_types`.** Reflection is the source of truth; training data goes stale across SDK versions.
+
+The companion plugin's `sbox-build-feature` skill encodes this workflow plus the common gotchas. If you're not using the plugin, the same rules apply manually.
 
 ## Requirements
 
 - **Node.js 18+**
-- **s&box** with the Bridge Addon installed
+- **s&box** with the bridge addon installed in your project's `Libraries/` folder
 - **Claude Code**
 
+## Documentation
+
+- [Main README](https://github.com/LouSputthole/Sbox-Claude/blob/main/README.md) — full project overview
+- [INSTALL.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/INSTALL.md) — install + manual fallback
+- [TROUBLESHOOTING.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/TROUBLESHOOTING.md) — 10 most common failures
+- [CHANGELOG.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/CHANGELOG.md) — release history
+- [Plugin README](https://github.com/LouSputthole/Sbox-Claude/blob/main/plugins/sbox-claude/README.md) — Claude Code plugin docs
+
 ## License
 
 **GPL-3.0** — see [LICENSE](../LICENSE) for details.

package/dist/index.d.ts

@@ -3,11 +3,11 @@
  * Entry point for the sbox-mcp MCP server.
  *
  * Creates an MCP server (stdio transport), connects to the s&box Bridge Addon
- * via WebSocket, and registers all tool handlers. Each tool domain (project,
+ * via file-based IPC (a shared temp dir), and registers all tool handlers. Each tool domain (project,
  * scripts, console, scenes, etc.) has its own register function in src/tools/.
  *
  * CLI flags: --version / -v, --help / -h
- * Environment: SBOX_BRIDGE_HOST, SBOX_BRIDGE_PORT
+ * Environment: SBOX_BRIDGE_IPC_DIR (the real knob); SBOX_BRIDGE_HOST / SBOX_BRIDGE_PORT (legacy, cosmetic)
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,11 +3,11 @@
  * Entry point for the sbox-mcp MCP server.
  *
  * Creates an MCP server (stdio transport), connects to the s&box Bridge Addon
- * via WebSocket, and registers all tool handlers. Each tool domain (project,
+ * via file-based IPC (a shared temp dir), and registers all tool handlers. Each tool domain (project,
  * scripts, console, scenes, etc.) has its own register function in src/tools/.
  *
  * CLI flags: --version / -v, --help / -h
- * Environment: SBOX_BRIDGE_HOST, SBOX_BRIDGE_PORT
+ * Environment: SBOX_BRIDGE_IPC_DIR (the real knob); SBOX_BRIDGE_HOST / SBOX_BRIDGE_PORT (legacy, cosmetic)
  */
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
@@ -60,8 +60,10 @@ USAGE
   node dist/index.js --version    Show version
 
 ENVIRONMENT VARIABLES
-  SBOX_BRIDGE_HOST    Bridge WebSocket host (default: 127.0.0.1)
-  SBOX_BRIDGE_PORT    Bridge WebSocket port (default: 29015)
+  SBOX_BRIDGE_IPC_DIR   IPC directory — MUST match the s&box addon's dir.
+                        Default: <os tmpdir>/sbox-bridge-ipc
+  SBOX_BRIDGE_HOST      Legacy/cosmetic — shown in get_bridge_status only
+  SBOX_BRIDGE_PORT      Legacy/cosmetic — shown in get_bridge_status only
 
 CONNECT TO CLAUDE CODE
   claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
@@ -100,8 +102,32 @@ TOOLS (99 working — was 109; 10 unimplementable tools removed in v1.3.0)
 const server = new McpServer({
     name: "sbox-mcp",
     version: getVersion(),
+}, {
+    // The `instructions` field surfaces every Claude Code session that uses this
+    // server (the way other MCP servers like Supabase / TurboTax do). Use it to
+    // tell Claude how to work effectively with the bridge — the disciplines that
+    // are easy to skip without a reminder.
+    instructions: `You are working with the s&box Claude Bridge — a file-based IPC bridge into the s&box game engine editor.
+
+To get good results:
+
+1. Always call \`mcp__sbox__get_bridge_status\` first to confirm the bridge addon is connected and s&box is running. If ping responds but other tools time out, the editor side isn't processing requests.
+
+2. For visual changes (models, positions, animations, UI panels, lighting), call \`mcp__sbox__take_screenshot\` after the change and READ THE PNG yourself. You're a multimodal model — you can see the result. Guessing about visual outcomes from code alone produces long iteration loops. The screenshot tool saves to <sbox-install>/screenshots/sbox.<timestamp>.png — list the newest file and read it.
+
+3. Before writing code that touches an unfamiliar s&box type, call \`mcp__sbox__describe_type\` or \`mcp__sbox__search_types\`. s&box's API changes between SDK versions — reflection is the source of truth, not training data.
+
+4. \`get_scene_hierarchy\` honors \`maxDepth\` (default 10) and accepts optional \`rootId\` to traverse from a specific GameObject. Use these to avoid dumping the entire scene into a tool result.
+
+5. Scene-mutating tools (create_gameobject, set_property, etc.) refuse during play mode and return a clear error. Stop play before making scene edits.
+
+If you're running inside Claude Code, install the companion plugin for the full workflow:
+    /plugin marketplace add LouSputthole/Sbox-Claude
+    /plugin install sbox-claude
+
+The plugin ships an \`sbox-build-feature\` skill that codifies the workflow above plus a list of common s&box gotchas (MathF not available in sandbox, Cloud assets ephemeral, head bone case-sensitive, CitizenAnimationHelper.IkRightHand works at runtime, etc.). Read its SKILL.md before starting non-trivial features.`,
 });
-// Bridge client connects to s&box editor via WebSocket
+// Bridge client talks to the s&box editor via file IPC. host/port are cosmetic.
 const bridge = new BridgeClient(process.env.SBOX_BRIDGE_HOST ?? "127.0.0.1", parseInt(process.env.SBOX_BRIDGE_PORT ?? "29015", 10));
 // Register all tools
 registerProjectTools(server, bridge);
@@ -135,6 +161,7 @@ async function main() {
     console.error("  ║  https://sboxskins.gg                            ║");
     console.error("  ╚═══════════════════════════════════════════════════╝");
     console.error("");
+    console.error(`[sbox-mcp] IPC directory: ${bridge.getIpcDir()}`);
     // Attempt initial connection to s&box (non-fatal if it fails)
     try {
         await bridge.connect();

package/dist/tools/status.js

@@ -6,14 +6,18 @@ export function registerStatusTools(server, bridge) {
     // ── get_bridge_status ────────────────────────────────────────────
     server.tool("get_bridge_status", "Check the connection status to the s&box Bridge — whether it's connected, latency, host/port, and editor info. Useful for debugging", {}, async () => {
         const connected = bridge.isConnected();
-        let latencyMs = -1;
+        const ipcDir = bridge.getIpcDir();
+        const heartbeatAgeMs = bridge.getHeartbeatAgeMs();
+        let latencyMs = null;
         let editorVersion = null;
+        let roundTripOk = false;
         if (connected) {
-            // Measure round-trip ping
             latencyMs = await bridge.ping();
-            // Try to get editor version via project info
+            // A real round-trip — distinguishes a live editor from one whose
+            // heartbeat is fresh but whose request loop is stalled.
             try {
                 const res = await bridge.send("get_project_info", {}, 5000);
+                roundTripOk = res.success;
                 if (res.success && res.data) {
                     const data = res.data;
                     editorVersion = data.editorVersion ?? null;
@@ -25,17 +29,28 @@ export function registerStatusTools(server, bridge) {
         }
         const status = {
             connected,
-            host: bridge.getHost(),
-            port: bridge.getPort(),
+            ipcDir,
+            heartbeatAgeMs,
+            roundTripOk,
             latencyMs: connected ? latencyMs : null,
             lastPong: connected
                 ? new Date(bridge.getLastPongTime()).toISOString()
                 : null,
             editorVersion,
+            // legacy/cosmetic — there is no socket; transport is file IPC
+            host: bridge.getHost(),
+            port: bridge.getPort(),
         };
-        const text = connected
-            ? `Bridge connected (${bridge.getHost()}:${bridge.getPort()}, ${latencyMs}ms latency)`
-            : `Bridge NOT connected (${bridge.getHost()}:${bridge.getPort()}). Is s&box running?`;
+        let text;
+        if (!connected) {
+            text = `Bridge NOT connected — no recent heartbeat in ${ipcDir}. Is s&box running with the Claude Bridge addon?`;
+        }
+        else if (roundTripOk) {
+            text = `Bridge connected and responding (IPC: ${ipcDir}, heartbeat ${heartbeatAgeMs ?? "?"}ms ago).`;
+        }
+        else {
+            text = `Bridge heartbeat is live but a test round-trip FAILED — the editor isn't draining requests. IPC: ${ipcDir}. Check the s&box editor console for [SboxBridge] lines.`;
+        }
         return {
             content: [
                 {

package/dist/transport/bridge-client.d.ts

@@ -1,11 +1,40 @@
 /**
- * File-based IPC transport for communicating with the s&box Bridge Addon.
+ * Max age of the editor's status heartbeat before we consider the bridge dead.
+ * The addon refreshes the heartbeat roughly once per second from its frame
+ * loop, so this gives generous margin for GC pauses / frame hitches while still
+ * catching a closed, crashed, or frame-stalled editor within a few seconds.
+ */
+export declare const STATUS_STALE_MS = 5000;
+/** Resolve the IPC directory, honoring an explicit override. */
+export declare function resolveIpcDir(): string;
+/** Result of inspecting the editor's status.json heartbeat. */
+export interface StatusClassification {
+    /** The editor reported `running: true`. */
+    running: boolean;
+    /** The heartbeat is recent enough to trust (or the addon predates heartbeats). */
+    fresh: boolean;
+    /** Age of the heartbeat in ms, or null if the addon doesn't emit one. */
+    heartbeatMs: number | null;
+}
+/**
+ * Decide whether a parsed status.json means the bridge is live.
  *
- * Instead of WebSocket, this uses a shared temp directory where:
- * - MCP server writes request files (req_*.json)
- * - s&box addon polls for them, processes, and writes response files (res_*.json)
- * - MCP server polls for response files
+ * A recent heartbeat → fresh. A stale heartbeat → not fresh (editor closed,
+ * crashed, or frame loop stalled). No heartbeat field at all → treated as fresh
+ * for backward compatibility with addons built before v1.3.2 (so upgrading the
+ * MCP server alone never regresses a working setup to "disconnected").
  */
+export declare function classifyStatus(status: unknown, nowMs: number, staleMs: number): StatusClassification;
+/**
+ * Build a timeout error that names WHICH side of the IPC broke, so a 30s hang
+ * is actionable instead of opaque.
+ */
+export declare function describeTimeout(opts: {
+    reqConsumed: boolean;
+    ipcDir: string;
+    timeoutMs: number;
+    command: string;
+}): string;
 /** A single command request sent to the s&box Bridge. */
 export interface BridgeRequest {
     id: string;
@@ -32,8 +61,16 @@ export declare class BridgeClient {
     static readonly POLL_INTERVAL_MS = 50;
     static readonly STATUS_CHECK_INTERVAL_MS = 5000;
     constructor(host?: string, port?: number);
+    /** The directory this client reads/writes IPC files in. */
+    getIpcDir(): string;
+    private statusPath;
+    /** Read + classify the editor's status heartbeat. Never throws. */
+    readStatus(): StatusClassification;
+    /** Age of the editor's last heartbeat in ms, or null if unavailable. */
+    getHeartbeatAgeMs(): number | null;
     /**
-     * Check if the s&box Bridge is running by looking for the status file.
+     * Verify the s&box Bridge is live (recent heartbeat), throwing a specific
+     * error if it is missing or stale.
      */
     connect(): Promise<void>;
     /**
@@ -48,7 +85,7 @@ export declare class BridgeClient {
         params?: Record<string, unknown>;
     }>, timeoutMs?: number): Promise<BridgeResponse>;
     /**
-     * Check if bridge is alive by looking for status file.
+     * Liveness check. Returns elapsed ms if the heartbeat is recent, else -1.
      */
     ping(): Promise<number>;
     isConnected(): boolean;

package/dist/transport/bridge-client.js

@@ -1,6 +1,83 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+/**
+ * File-based IPC transport for communicating with the s&box Bridge Addon.
+ *
+ * There is NO socket. Despite the legacy `host`/`port` fields, communication is
+ * entirely through a shared temp directory:
+ * - MCP server writes request files (req_*.json)
+ * - s&box addon polls for them, processes on the main editor thread, and writes
+ *   response files (res_*.json)
+ * - MCP server polls for response files
+ *
+ * The addon also maintains `status.json` as a HEARTBEAT (rewritten from the
+ * editor frame loop). "Connected" means that heartbeat is recent — not merely
+ * that the file exists. A write-once status file used to make the bridge report
+ * "connected" forever after the first run, even with the editor closed.
+ */
+/** Default IPC directory name under the system temp dir. */
+const IPC_DIR_NAME = "sbox-bridge-ipc";
+/** Strip a leading UTF-8 BOM (older addons may prepend one to IPC files). */
+function stripBom(s) {
+    return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
+}
+/**
+ * Max age of the editor's status heartbeat before we consider the bridge dead.
+ * The addon refreshes the heartbeat roughly once per second from its frame
+ * loop, so this gives generous margin for GC pauses / frame hitches while still
+ * catching a closed, crashed, or frame-stalled editor within a few seconds.
+ */
+export const STATUS_STALE_MS = 5000;
+/** Resolve the IPC directory, honoring an explicit override. */
+export function resolveIpcDir() {
+    const override = process.env.SBOX_BRIDGE_IPC_DIR;
+    if (override && override.trim().length > 0)
+        return override;
+    return path.join(os.tmpdir(), IPC_DIR_NAME);
+}
+/**
+ * Decide whether a parsed status.json means the bridge is live.
+ *
+ * A recent heartbeat → fresh. A stale heartbeat → not fresh (editor closed,
+ * crashed, or frame loop stalled). No heartbeat field at all → treated as fresh
+ * for backward compatibility with addons built before v1.3.2 (so upgrading the
+ * MCP server alone never regresses a working setup to "disconnected").
+ */
+export function classifyStatus(status, nowMs, staleMs) {
+    if (!status || typeof status !== "object") {
+        return { running: false, fresh: false, heartbeatMs: null };
+    }
+    const s = status;
+    const running = s.running === true;
+    const hb = s.heartbeat;
+    if (typeof hb === "string") {
+        const t = Date.parse(hb);
+        if (!Number.isNaN(t)) {
+            const heartbeatMs = nowMs - t;
+            return { running, fresh: heartbeatMs <= staleMs, heartbeatMs };
+        }
+    }
+    // Old addon (no parseable heartbeat) — don't regress working setups.
+    return { running, fresh: true, heartbeatMs: null };
+}
+/**
+ * Build a timeout error that names WHICH side of the IPC broke, so a 30s hang
+ * is actionable instead of opaque.
+ */
+export function describeTimeout(opts) {
+    const { reqConsumed, ipcDir, timeoutMs, command } = opts;
+    if (!reqConsumed) {
+        return (`Request '${command}' timed out after ${timeoutMs}ms. The s&box editor never picked up the request ` +
+            `(its req_*.json file was not consumed). Likely causes: s&box isn't running, the Claude Bridge addon ` +
+            `failed to load, or the editor and MCP server resolved different IPC directories (server is using: ` +
+            `${ipcDir}). Open the s&box editor console and check for [SboxBridge] lines — it logs the directory it ` +
+            `is watching; set SBOX_BRIDGE_IPC_DIR on both sides if they disagree.`);
+    }
+    return (`Request '${command}' timed out after ${timeoutMs}ms. The editor consumed the request but never wrote a ` +
+        `response. Its frame loop may be stalled (e.g. the s&box window is unfocused or minimized) or the handler ` +
+        `errored. Check the s&box editor console for [SboxBridge] errors.`);
+}
 /**
  * File-based IPC client that communicates with the s&box Bridge Addon.
  */
@@ -14,33 +91,56 @@ export class BridgeClient {
     static POLL_INTERVAL_MS = 50; // 50ms polling for responses
     static STATUS_CHECK_INTERVAL_MS = 5000;
     constructor(host = "127.0.0.1", port = 29015) {
+        // host/port are legacy/cosmetic — surfaced in get_bridge_status only. The
+        // real transport is the file IPC directory below.
         this.host = host;
         this.port = port;
-        this.ipcDir = path.join(os.tmpdir(), "sbox-bridge-ipc");
+        this.ipcDir = resolveIpcDir();
+    }
+    /** The directory this client reads/writes IPC files in. */
+    getIpcDir() {
+        return this.ipcDir;
+    }
+    statusPath() {
+        return path.join(this.ipcDir, "status.json");
+    }
+    /** Read + classify the editor's status heartbeat. Never throws. */
+    readStatus() {
+        try {
+            // Strip a UTF-8 BOM in case an older addon wrote one.
+            const raw = stripBom(fs.readFileSync(this.statusPath(), "utf8"));
+            return classifyStatus(JSON.parse(raw), Date.now(), STATUS_STALE_MS);
+        }
+        catch {
+            return { running: false, fresh: false, heartbeatMs: null };
+        }
+    }
+    /** Age of the editor's last heartbeat in ms, or null if unavailable. */
+    getHeartbeatAgeMs() {
+        return this.readStatus().heartbeatMs;
     }
     /**
-     * Check if the s&box Bridge is running by looking for the status file.
+     * Verify the s&box Bridge is live (recent heartbeat), throwing a specific
+     * error if it is missing or stale.
      */
     async connect() {
-        // Ensure IPC directory exists
         if (!fs.existsSync(this.ipcDir)) {
             fs.mkdirSync(this.ipcDir, { recursive: true });
         }
-        const statusPath = path.join(this.ipcDir, "status.json");
-        if (fs.existsSync(statusPath)) {
-            try {
-                const status = JSON.parse(fs.readFileSync(statusPath, "utf8"));
-                if (status.running) {
-                    this.connected = true;
-                    this.lastPongTime = Date.now();
-                    return;
-                }
-            }
-            catch {
-                // Status file exists but is malformed
-            }
+        const s = this.readStatus();
+        if (s.running && s.fresh) {
+            this.connected = true;
+            this.lastPongTime = Date.now();
+            return;
+        }
+        this.connected = false;
+        if (s.running && !s.fresh) {
+            throw new Error(`s&box Bridge heartbeat is stale at ${this.statusPath()} (last beat ${s.heartbeatMs}ms ago, ` +
+                `limit ${STATUS_STALE_MS}ms). The editor likely closed, crashed, or its frame loop stalled. ` +
+                `IPC dir: ${this.ipcDir}`);
         }
-        throw new Error(`Cannot connect to s&box Bridge. No status file found at ${statusPath}. Is s&box running with the Bridge Addon?`);
+        throw new Error(`Cannot connect to s&box Bridge. No live status at ${this.statusPath()}. Is s&box running with the ` +
+            `Claude Bridge addon? (MCP server IPC dir: ${this.ipcDir})`);
     }
     /**
      * Send a command to the s&box Bridge and wait for its response.
@@ -51,11 +151,13 @@ export class BridgeClient {
             try {
                 await this.connect();
             }
-            catch {
+            catch (err) {
                 return {
                     id: "",
                     success: false,
-                    error: "Not connected to s&box Bridge. Make sure s&box is running with the Bridge Addon installed.",
+                    error: err instanceof Error
+                        ? err.message
+                        : "Not connected to s&box Bridge. Make sure s&box is running with the Claude Bridge addon installed.",
                 };
             }
         }
@@ -85,6 +187,8 @@ export class BridgeClient {
                 // Check timeout
                 if (Date.now() - startTime > timeoutMs) {
                     clearInterval(poll);
+                    // Whether the editor ever read the request tells us which side broke.
+                    const reqConsumed = !fs.existsSync(reqPath);
                     // Clean up request file if still there
                     try {
                         if (fs.existsSync(reqPath))
@@ -94,15 +198,15 @@ export class BridgeClient {
                     resolve({
                         id,
                         success: false,
-                        error: `Request timed out after ${timeoutMs}ms`,
+                        error: describeTimeout({ reqConsumed, ipcDir: this.ipcDir, timeoutMs, command }),
                     });
                     return;
                 }
                 // Check for response file
                 if (fs.existsSync(resPath)) {
                     try {
-                        // Strip UTF-8 BOM that C#'s File.WriteAllText prepends
-                        const responseJson = fs.readFileSync(resPath, "utf8").replace(/^\uFEFF/, "");
+                        // Defensively strip a BOM in case an older addon wrote one.
+                        const responseJson = stripBom(fs.readFileSync(resPath, "utf8"));
                         const response = JSON.parse(responseJson);
                         // Clean up response file
                         try {
@@ -128,11 +232,11 @@ export class BridgeClient {
             try {
                 await this.connect();
             }
-            catch {
+            catch (err) {
                 return {
                     id: "",
                     success: false,
-                    error: "Not connected to s&box Bridge.",
+                    error: err instanceof Error ? err.message : "Not connected to s&box Bridge.",
                 };
             }
         }
@@ -158,6 +262,7 @@ export class BridgeClient {
             const poll = setInterval(() => {
                 if (Date.now() - startTime > timeoutMs) {
                     clearInterval(poll);
+                    const reqConsumed = !fs.existsSync(reqPath);
                     try {
                         if (fs.existsSync(reqPath))
                             fs.unlinkSync(reqPath);
@@ -166,14 +271,14 @@ export class BridgeClient {
                     resolve({
                         id,
                         success: false,
-                        error: `Batch request timed out after ${timeoutMs}ms`,
+                        error: describeTimeout({ reqConsumed, ipcDir: this.ipcDir, timeoutMs, command: "batch" }),
                     });
                     return;
                 }
                 if (fs.existsSync(resPath)) {
                     try {
-                        // Strip UTF-8 BOM that C#'s File.WriteAllText prepends
-                        const responseJson = fs.readFileSync(resPath, "utf8").replace(/^\uFEFF/, "");
+                        // Defensively strip a BOM in case an older addon wrote one.
+                        const responseJson = stripBom(fs.readFileSync(resPath, "utf8"));
                         const response = JSON.parse(responseJson);
                         try {
                             fs.unlinkSync(resPath);
@@ -189,38 +294,20 @@ export class BridgeClient {
         });
     }
     /**
-     * Check if bridge is alive by looking for status file.
+     * Liveness check. Returns elapsed ms if the heartbeat is recent, else -1.
      */
     async ping() {
-        const statusPath = path.join(this.ipcDir, "status.json");
         const start = Date.now();
-        try {
-            if (fs.existsSync(statusPath)) {
-                const status = JSON.parse(fs.readFileSync(statusPath, "utf8"));
-                if (status.running) {
-                    this.lastPongTime = Date.now();
-                    return Date.now() - start;
-                }
-            }
+        const s = this.readStatus();
+        if (s.running && s.fresh) {
+            this.lastPongTime = Date.now();
+            return Date.now() - start;
         }
-        catch { }
         return -1;
     }
     isConnected() {
-        // Re-check status file
-        const statusPath = path.join(this.ipcDir, "status.json");
-        try {
-            if (fs.existsSync(statusPath)) {
-                const status = JSON.parse(fs.readFileSync(statusPath, "utf8"));
-                this.connected = !!status.running;
-            }
-            else {
-                this.connected = false;
-            }
-        }
-        catch {
-            this.connected = false;
-        }
+        const s = this.readStatus();
+        this.connected = s.running && s.fresh;
         return this.connected;
     }
     getHost() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbox-mcp-server",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
   "type": "module",
   "main": "dist/index.js",
@@ -16,6 +16,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "npm run build && node --test",
     "start": "node dist/index.js",
     "dev": "tsc --watch",
     "prepublishOnly": "npm run build"