sbox-mcp-server 1.3.1 → 1.3.2

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
@@ -125,7 +127,7 @@ If you're running inside Claude Code, install the companion plugin for the full
 
 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);
@@ -159,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.1",
+  "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"