sbox-mcp-server 1.3.1 → 1.4.0

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.1",
+  "version": "1.4.0",
   "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"