sbox-mcp-server 1.4.0 → 1.5.1

package/README.md

@@ -1,6 +1,6 @@
 # sbox-mcp-server
 
-MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — 131 working tools for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, and type discovery.
+MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **150 tools / 142 editor handlers** for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, navmesh & spatial queries, particles, self-diagnosis, console/C# execution, live docs search, and type discovery.
 
 ## Fastest install — the Claude Code plugin
 
@@ -44,7 +44,7 @@ Open your project. The bridge starts automatically. Verify with:
 Check the bridge status.
 ```
 
-You should see `connected: true, handlerCount: 99`.
+You should see `connected: true, handlerCount: 142`. (That's the editor-side handler count; the server exposes 150 tools total — a handful run MCP-server-side and need no editor handler.)
 
 ## How it works
 
@@ -54,7 +54,9 @@ Claude Code → (stdio) → sbox-mcp-server → (file IPC) → bridge addon →
 
 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 (131 — v1.4.0)
+## Tools (150 / 142 editor handlers — v1.5.0)
+
+`get_bridge_status` reports `handlerCount: 142` — that's the C# handlers compiled inside the editor. Six tools run **MCP-server-side** and need no editor handler: `read_log`, `get_compile_errors`, `execute_csharp`, `search_docs`, `get_doc_page`, `list_doc_categories`. They read the log / hotload-eval / fetch docs directly, so they keep working even when the editor has crashed or stalled.
 
 | Category | Tools |
 |----------|-------|
@@ -87,14 +89,24 @@ Communication uses file-based IPC through `%TEMP%/sbox-bridge-ipc/`. The MCP ser
 | **Scene & level** *(v1.4.0)* | snap_to_ground, align_objects, distribute_objects, grid_duplicate, measure_distance |
 | **Environment** *(v1.4.0)* | scatter_props, randomize_transforms, group_objects |
 | **Object utilities** *(v1.4.0)* | find_objects, set_tint, replace_model, set_tags |
-| **VFX** *(v1.4.0, experimental)* | spawn_particle, create_particle_effect, add_trail, add_beam — compile but runtime rendering unverified through the bridge; use a legacy `.vpcf` for visible particles |
+| **VFX** *(v1.4.0, experimental)* | spawn_particle, create_particle_effect, add_trail, add_beam — compile but do **not** render through the bridge; use `spawn_vpcf` (below) for visible particles |
+| **Diagnostics** *(v1.5.0, MCP-server-side)* | read_log, get_compile_errors — read `sbox-dev.log` directly; work even when the editor has crashed |
+| **Camera** *(v1.5.0)* | screenshot_from (**aim a shot at any object/point** — `take_screenshot` is fixed to the Main Camera), frame_camera (move the editor viewport) |
+| **Navigation** *(v1.5.0)* | bake_navmesh, get_navmesh_path |
+| **Spatial** *(v1.5.0)* | physics_overlap (volume counterpart to raycast) |
+| **Reflections** *(v1.5.0)* | bake_reflections (a placed EnvmapProbe captures nothing until baked) |
+| **Particles** *(v1.5.0)* | spawn_vpcf — compiled `.vpcf` via LegacyParticleSystem, the **supported** particle path |
+| **Console / Exec** *(v1.5.0)* | console_run, execute_csharp *(experimental)* |
+| **Object utilities** *(v1.5.0)* | remove_component, get_tags |
+| **Docs search** *(v1.5.0, MCP-server-side)* | search_docs, get_doc_page, list_doc_categories — official `Facepunch/sbox-docs` |
 
 ## Working with Claude effectively
 
-Two disciplines prevent the iteration-loop trap:
+Three 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.
+1. **After visual changes, see the result — and aim the camera.** `take_screenshot` renders from the scene's Main Camera (one fixed angle), so it often won't show the thing you just changed. Use **`screenshot_from`** to point the camera at the target object/point, then read the PNG. Claude is a multimodal model — 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.
+3. **When something breaks, read the log instead of guessing.** `get_compile_errors` surfaces the latest C# compile failures and `read_log` tails `sbox-dev.log` — both MCP-server-side, so they work even if the editor crashed.
 
 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.
 
@@ -108,7 +120,7 @@ The companion plugin's `sbox-build-feature` skill encodes this workflow plus the
 
 - [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
+- [TROUBLESHOOTING.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/TROUBLESHOOTING.md) — common failures and fixes
 - [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
 

package/dist/index.js

@@ -37,6 +37,9 @@ import { registerVisualTools } from "./tools/visuals.js";
 import { registerCharacterTools } from "./tools/characters.js";
 import { registerLevelTools } from "./tools/leveltools.js";
 import { registerObjectTools } from "./tools/objecttools.js";
+import { registerDiagnosticTools } from "./tools/diagnostics.js";
+import { registerDocsTools } from "./tools/docs.js";
+import { registerNavigationTools } from "./tools/navigation.js";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -72,7 +75,7 @@ ENVIRONMENT VARIABLES
 CONNECT TO CLAUDE CODE
   claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
 
-TOOLS (131 — +32 in v1.4.0: visual, characters, scene, environment, utilities)
+TOOLS (150 total / 142 s&box-editor handlers — +16 in v1.5.0)
   Project:     get_project_info, list_project_files, read_file, write_file
   Scripts:     create_script, edit_script, delete_script, trigger_hotload
   Scenes:      list_scenes, load_scene, save_scene, create_scene
@@ -107,6 +110,17 @@ TOOLS (131 — +32 in v1.4.0: visual, characters, scene, environment, utilities)
   Environment: scatter_props, randomize_transforms, group_objects
   Utilities:   find_objects, set_tint, replace_model, set_tags
   VFX (exp):   spawn_particle, create_particle_effect, add_trail, add_beam
+
+  ── New in v1.5.0 ───────────────────────────────────
+  Diagnostics: read_log, get_compile_errors  (MCP-server-side — work even if the editor crashed)
+  Camera:      screenshot_from (AIM a shot at an object/point — take_screenshot is fixed to the Main Camera), frame_camera
+  Navigation:  bake_navmesh, get_navmesh_path
+  Spatial:     physics_overlap (volume counterpart to raycast)
+  Reflections: bake_reflections
+  Particles:   spawn_vpcf (compiled .vpcf via LegacyParticleSystem — the supported particle path)
+  Console/Exec: console_run, execute_csharp (experimental)
+  Object utils: remove_component, get_tags
+  Docs search: search_docs, get_doc_page, list_doc_categories  (MCP-server-side — official Facepunch/sbox-docs)
 `);
     process.exit(0);
 }
@@ -133,6 +147,8 @@ To get good results:
 
 5. Scene-mutating tools (create_gameobject, set_property, etc.) refuse during play mode and return a clear error. Stop play before making scene edits.
 
+6. First session with the bridge (or when the user asks "how do I start?" / "what can this do?")? Offer to run setup — invoke the \`sbox-setup\` skill: it verifies the connection, detects the user's installed libraries (\`list_libraries\`), recommends a first move, and points to help + feedback.
+
 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
@@ -164,6 +180,9 @@ registerVisualTools(server, bridge);
 registerCharacterTools(server, bridge);
 registerLevelTools(server, bridge);
 registerObjectTools(server, bridge);
+registerDiagnosticTools(server, bridge);
+registerDocsTools(server, bridge);
+registerNavigationTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/diagnostics.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+export declare function registerDiagnosticTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/tools/diagnostics.js

@@ -0,0 +1,325 @@
+import { z } from "zod";
+import { existsSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+/**
+ * Diagnostic tools (Batch 24 — "let Claude see its own errors"): read s&box's
+ * editor log so Claude can check compile errors, exceptions, and Log.Info
+ * output directly — instead of flying blind or relying on the user to relay
+ * them.
+ *
+ * Deliberately reads the log FILE on the Node side (not over the bridge IPC),
+ * so it works even when the s&box editor has crashed and the bridge is down —
+ * which is exactly when you need the log most.
+ *
+ * Log path resolution:
+ *   1. SBOX_LOG_PATH env var (explicit override — use this on macOS/Linux or
+ *      non-Steam installs).
+ *   2. Windows Steam auto-detect: parse steamapps/libraryfolders.vdf for each
+ *      library, look for steamapps/common/sbox/logs/sbox-dev.log, pick newest.
+ */
+function locateSboxLog() {
+    const tried = [];
+    const env = process.env.SBOX_LOG_PATH;
+    if (env) {
+        tried.push(env);
+        if (existsSync(env))
+            return { path: env, tried };
+    }
+    if (process.platform === "win32") {
+        const steamRoots = [
+            "C:\\Program Files (x86)\\Steam",
+            "C:\\Program Files\\Steam",
+        ];
+        const libs = [];
+        for (const steam of steamRoots) {
+            const vdf = join(steam, "steamapps", "libraryfolders.vdf");
+            if (existsSync(vdf)) {
+                libs.push(steam);
+                try {
+                    const txt = readFileSync(vdf, "utf-8");
+                    for (const m of txt.matchAll(/"path"\s+"([^"]+)"/g)) {
+                        libs.push(m[1].replace(/\\\\/g, "\\"));
+                    }
+                }
+                catch {
+                    /* ignore unreadable vdf */
+                }
+            }
+        }
+        const candidates = [];
+        for (const lib of libs) {
+            const p = join(lib, "steamapps", "common", "sbox", "logs", "sbox-dev.log");
+            tried.push(p);
+            if (existsSync(p))
+                candidates.push(p);
+        }
+        if (candidates.length > 0) {
+            candidates.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+            return { path: candidates[0], tried };
+        }
+    }
+    return { path: null, tried };
+}
+function tailLines(text, n) {
+    const lines = text.split(/\r?\n/);
+    return lines.slice(Math.max(0, lines.length - n));
+}
+export function registerDiagnosticTools(server, bridge) {
+    // ── read_log ───────────────────────────────────────────────────────
+    server.tool("read_log", "Read s&box's editor log (sbox-dev.log) so Claude can see compile errors, exceptions, and Log.Info output directly. Reads the log file (not via the bridge), so it works even when the editor has crashed. If auto-detection fails (non-Windows / non-Steam install), set the SBOX_LOG_PATH environment variable to the full log path.", {
+        lines: z
+            .number()
+            .int()
+            .optional()
+            .describe("How many lines from the end to return (default 80, max 1000)"),
+        filter: z
+            .string()
+            .optional()
+            .describe("Only return lines containing this substring (case-insensitive)"),
+    }, async (params) => {
+        const { path, tried } = locateSboxLog();
+        if (!path) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't locate sbox-dev.log. Set the SBOX_LOG_PATH environment variable to its full path.\nTried:\n" +
+                            tried.join("\n"),
+                    },
+                ],
+            };
+        }
+        let n = params.lines ?? 80;
+        if (n < 1)
+            n = 1;
+        if (n > 1000)
+            n = 1000;
+        let text;
+        try {
+            text = readFileSync(path, "utf-8");
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: `Error reading ${path}: ${e.message}` }],
+            };
+        }
+        let out = tailLines(text, n);
+        if (params.filter) {
+            const f = params.filter.toLowerCase();
+            out = out.filter((l) => l.toLowerCase().includes(f));
+        }
+        const header = `# ${path}\n# last ${n} lines${params.filter ? ` · filter "${params.filter}"` : ""}\n\n`;
+        return { content: [{ type: "text", text: header + out.join("\n") }] };
+    });
+    // ── get_compile_errors ─────────────────────────────────────────────
+    server.tool("get_compile_errors", "Scan the recent s&box log for compile errors and exceptions — the fast way for Claude to confirm whether its last script/addon edit actually compiled. Reads sbox-dev.log directly (works even if the editor is mid-crash). Returns the matching lines, or an all-clear.", {
+        lines: z
+            .number()
+            .int()
+            .optional()
+            .describe("How many lines from the end to scan (default 400, max 4000)"),
+    }, async (params) => {
+        const { path } = locateSboxLog();
+        if (!path) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't locate sbox-dev.log. Set the SBOX_LOG_PATH environment variable.",
+                    },
+                ],
+            };
+        }
+        let n = params.lines ?? 400;
+        if (n < 1)
+            n = 1;
+        if (n > 4000)
+            n = 4000;
+        let text;
+        try {
+            text = readFileSync(path, "utf-8");
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: `Error reading ${path}: ${e.message}` }],
+            };
+        }
+        const recent = tailLines(text, n);
+        const re = /(error CS\d+|Compile of .* Failed|Exception|Couldn't add project|Broken Reference|StackTrace|^\s*at Sandbox\.)/i;
+        const hits = recent.filter((l) => re.test(l));
+        if (hits.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No compile errors or exceptions in the last ${n} log lines — looks clean.\n(${path})`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${hits.length} error/exception line(s) in the last ${n} log lines:\n\n${hits.join("\n")}`,
+                },
+            ],
+        };
+    });
+    // ── frame_camera ─────────────────────────────────────────────────── (bridge)
+    server.tool("frame_camera", "Aim the s&box EDITOR viewport camera at a GameObject (by id) or a world point (position + optional radius), then call take_screenshot to capture that view. This is how Claude points its own screenshots at what it's working on — frame a spawned object, then screenshot to verify it actually looks right.", {
+        id: z.string().optional().describe("GUID of a GameObject to frame on"),
+        position: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("World point to frame on (use instead of id)"),
+        radius: z
+            .number()
+            .optional()
+            .describe("Frame radius around the position, in units (default 128)"),
+    }, async (params) => {
+        const res = await bridge.send("frame_camera", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── screenshot_from ──────────────────────────────────────────────── (bridge)
+    server.tool("screenshot_from", "Take a screenshot from a chosen angle. take_screenshot is locked to the scene's main camera; this temporarily moves that camera to frame your target, captures, then restores it — so Claude can finally AIM its own screenshots. Pass id (frame an object) OR position {x,y,z} with optional lookAt {x,y,z} or rotation {pitch,yaw,roll}. After it returns, read the newest PNG in the editor's screenshots folder.", {
+        id: z.string().optional().describe("GUID of a GameObject to frame"),
+        position: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("Camera world position (use instead of id)"),
+        lookAt: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("World point to look at (pair with position)"),
+        rotation: z
+            .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
+            .optional()
+            .describe("Explicit camera rotation (pair with position)"),
+        width: z.number().int().optional().describe("Screenshot width (default 1920)"),
+        height: z.number().int().optional().describe("Screenshot height (default 1080)"),
+    }, async (params) => {
+        const res = await bridge.send("screenshot_from", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── console_run ──────────────────────────────────────────────────── (bridge)
+    server.tool("console_run", "Run an s&box console command / ConCmd via Sandbox.ConsoleSystem.Run — e.g. a cvar ('sv_cheats 1') or a registered command. Also the invocation primitive behind execute_csharp.", {
+        command: z.string().describe("The console command line to run"),
+    }, async (params) => {
+        const res = await bridge.send("console_run", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── execute_csharp ───────────────────────────────────────────────── (orchestrated)
+    let execCounter = 0;
+    server.tool("execute_csharp", "EXPERIMENTAL. Compile + run a C# snippet inside the s&box EDITOR (which is unsandboxed): writes a temp [ConCmd] into the project's Editor/ folder, hotloads, runs it, reads the result/exception from the log, then deletes the temp file. With expression:true, returns the JSON value of a single expression; otherwise runs statements. CAVEATS: each call triggers a hotload (~2-8s) and recompiles the project's editor assembly; a snippet that fails to compile is reported + cleaned up, but briefly taints the editor assembly until cleanup.", {
+        code: z
+            .string()
+            .describe("C# to run (editor-context, unsandboxed). With expression:true, a single expression; otherwise statements."),
+        expression: z
+            .boolean()
+            .optional()
+            .describe("Treat code as an expression and return its JSON value (default false)"),
+        timeoutMs: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max wait for compile + run, ms (default 20000)"),
+    }, async (params) => {
+        const id = `${Date.now().toString(36)}${++execCounter}`;
+        const cmd = `claude_exec_${id}`;
+        const filePath = `Editor/__Exec_${id}.cs`;
+        const marker = `[EXEC ${id}]`;
+        const inner = params.expression
+            ? `var __r = (${params.code});\n\t\t\tSandbox.Log.Info( "${marker} RESULT=" + System.Text.Json.JsonSerializer.Serialize( __r ) );`
+            : `${params.code}\n\t\t\tSandbox.Log.Info( "${marker} DONE" );`;
+        const cs = `using Editor;\nusing Sandbox;\nusing System;\n\n` +
+            `public static class __Exec_${id}\n{\n` +
+            `\t[ConCmd( "${cmd}" )]\n\tpublic static void Run()\n\t{\n` +
+            `\t\ttry\n\t\t{\n\t\t\t${inner}\n\t\t}\n` +
+            `\t\tcatch ( System.Exception __e ) { Sandbox.Log.Error( "${marker} ERROR=" + __e.Message ); }\n` +
+            `\t}\n}\n`;
+        const timeout = params.timeoutMs ?? 20000;
+        const wr = await bridge.send("write_file", { path: filePath, content: cs });
+        if (!wr.success) {
+            return { content: [{ type: "text", text: `execute_csharp: failed to write temp file: ${wr.error}` }] };
+        }
+        await bridge.send("trigger_hotload", {});
+        const { path: logPath } = locateSboxLog();
+        const startedAt = Date.now();
+        let found = null;
+        let compileErr = null;
+        while (Date.now() - startedAt < timeout) {
+            await new Promise((r) => setTimeout(r, 1500));
+            await bridge.send("console_run", { command: cmd });
+            if (logPath) {
+                try {
+                    const txt = readFileSync(logPath, "utf-8");
+                    const tail = txt.slice(Math.max(0, txt.length - 30000));
+                    const mi = tail.lastIndexOf(marker);
+                    if (mi >= 0) {
+                        found = tail.slice(mi).split(/\r?\n/)[0];
+                        break;
+                    }
+                    if (/__Exec_/.test(tail) && /(error CS\d+|Compile of .* Failed)/i.test(tail)) {
+                        const errs = tail.split(/\r?\n/).filter((l) => /error CS\d+/i.test(l)).slice(-6).join("\n");
+                        if (errs) {
+                            compileErr = errs;
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    /* log not ready yet */
+                }
+            }
+        }
+        // cleanup: remove the temp file + hotload back to a clean assembly
+        try {
+            await bridge.send("delete_script", { path: filePath });
+        }
+        catch {
+            /* best effort */
+        }
+        try {
+            await bridge.send("trigger_hotload", {});
+        }
+        catch {
+            /* best effort */
+        }
+        if (compileErr) {
+            return { content: [{ type: "text", text: `execute_csharp: compile error —\n${compileErr}` }] };
+        }
+        if (found) {
+            let out = found;
+            if (found.includes("RESULT="))
+                out = "RESULT = " + found.split("RESULT=")[1].trim();
+            else if (found.includes("ERROR="))
+                out = "Runtime exception: " + found.split("ERROR=")[1].trim();
+            else if (found.includes("DONE"))
+                out = "Executed (no return value).";
+            return { content: [{ type: "text", text: `execute_csharp ${id}: ${out}` }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `execute_csharp ${id}: no result captured within ${timeout}ms — the snippet may still be compiling, or the log marker wasn't found. Try read_log with filter "${marker}".`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/tools/discovery.js

@@ -18,6 +18,13 @@ export function registerDiscoveryTools(server, bridge) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
+    // ── list_libraries ───────────────────────────────────────────────
+    server.tool("list_libraries", "List the s&box libraries/addons installed in this project (reads Libraries/ + each .sbproj). Discovers what's available to build ON — e.g. character controllers (fish.scc = Shrimple Character Controller, facepunch.playercontroller), world/spline/road tools — so you can leverage an installed library (add its components via add_component_with_properties, or generate code against its API) instead of writing from scratch. Returns ident/org/title/type/enabled per library. Read-only.", {}, async () => {
+        const res = await bridge.send("list_libraries", {});
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
     // ── search_types ─────────────────────────────────────────────────
     server.tool("search_types", "Find types matching a name pattern. Pass components_only=true to filter to Component subclasses only. Useful for discovering 'is there a built-in X for this?'", {
         pattern: z.string().describe("Substring to match against type name (case-insensitive)"),

package/dist/tools/docs.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+export declare function registerDocsTools(server: McpServer, _bridge: BridgeClient): void;
+//# sourceMappingURL=docs.d.ts.map

package/dist/tools/docs.js

@@ -0,0 +1,334 @@
+import { z } from "zod";
+/**
+ * Documentation tools (Batch 25 — "let Claude read the real s&box docs"): search
+ * and fetch the official s&box guide documentation so Claude can ground itself in
+ * Facepunch's own pages instead of guessing from possibly-stale training data.
+ *
+ * The s&box guide docs live in the PUBLIC GitHub repo Facepunch/sbox-docs
+ * (branch master): ~225 Markdown pages under docs/<category>/.../<page>.md, each
+ * starting with YAML frontmatter (title, icon, created, updated).
+ *
+ * Two HTTP sources, both fetched with Node 18+ built-in fetch (no npm deps):
+ *   1. INDEX (once, cached in memory): the GitHub git-tree API lists every file
+ *      in the repo. Requires a User-Agent header or GitHub returns 403. Honors an
+ *      optional GITHUB_TOKEN env var for a higher rate limit (never required).
+ *   2. PAGE CONTENT: raw.githubusercontent.com serves the Markdown as text/plain
+ *      with no rate limit and no UA needed.
+ *
+ * Per page we derive:
+ *   - category: the 2nd path segment (docs/networking/rpcs.md -> "networking")
+ *   - slug:     the path with leading "docs/" and trailing ".md" removed
+ *   - webUrl:   https://sbox.game/dev/doc/<slug> (a trailing "/index" is stripped)
+ *
+ * All three tools are read-only and never throw — fetch failures are caught and
+ * surfaced as a plain text error in the tool result.
+ */
+/** GitHub git-tree API for the docs repo (lists every file, recursive). */
+const TREE_URL = "https://api.github.com/repos/Facepunch/sbox-docs/git/trees/master?recursive=1";
+/** Base for raw Markdown page content (text/plain, no rate limit). */
+const RAW_BASE = "https://raw.githubusercontent.com/Facepunch/sbox-docs/master/";
+/** Public web home for a rendered doc page. */
+const WEB_BASE = "https://sbox.game/dev/doc/";
+/** Module-level cache so the index is fetched at most once per ~30 min. */
+let indexCache = null;
+let indexFetchedAt = 0;
+/** Re-fetch the index if it is older than this (handles long-lived processes). */
+const INDEX_TTL_MS = 30 * 60 * 1000;
+/** Compute slug/category/webUrl for a repo-relative docs path. */
+function buildEntry(path) {
+    // "docs/networking/rpcs.md" -> "networking/rpcs"
+    const slug = path.replace(/^docs\//, "").replace(/\.md$/i, "");
+    const segments = path.split("/");
+    // path[0] is "docs"; the category is the next segment (if any).
+    const category = segments.length > 2 ? segments[1] : "";
+    // A trailing "/index" doesn't appear in the public web URL.
+    const webSlug = slug.replace(/\/index$/i, "");
+    return { path, slug, category, webUrl: WEB_BASE + webSlug };
+}
+/**
+ * Ensure the doc index is loaded (fetching + building it once), reusing the
+ * module-level cache. Returns null on any fetch/parse failure so callers can
+ * report a clean error. Never throws.
+ */
+async function getIndex() {
+    const now = Date.now();
+    if (indexCache && now - indexFetchedAt < INDEX_TTL_MS) {
+        return indexCache;
+    }
+    try {
+        const headers = {
+            // GitHub API rejects requests without a User-Agent (403).
+            "User-Agent": "sbox-mcp-server",
+            Accept: "application/vnd.github+json",
+        };
+        const token = process.env.GITHUB_TOKEN;
+        if (token)
+            headers["Authorization"] = `Bearer ${token}`;
+        const res = await fetch(TREE_URL, { headers });
+        if (!res.ok) {
+            return null;
+        }
+        const json = await res.json();
+        const tree = Array.isArray(json?.tree) ? json.tree : [];
+        const entries = [];
+        for (const node of tree) {
+            const p = node?.path ?? "";
+            // Keep only Markdown pages under docs/.
+            if (node?.type === "blob" &&
+                p.startsWith("docs/") &&
+                /\.md$/i.test(p)) {
+                entries.push(buildEntry(p));
+            }
+        }
+        if (entries.length === 0) {
+            // Empty tree almost certainly means an API hiccup, not a real result.
+            return null;
+        }
+        indexCache = entries;
+        indexFetchedAt = now;
+        return indexCache;
+    }
+    catch {
+        return null;
+    }
+}
+/** Tokenize a query into lowercased, non-empty words. */
+function tokenize(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter((t) => t.length > 0);
+}
+/** Strip the leading YAML frontmatter block from a Markdown document. */
+function stripFrontmatter(md) {
+    return md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "");
+}
+/** Pull the `title:` value out of YAML frontmatter, if present. */
+function parseTitle(md) {
+    const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+    if (!fm)
+        return null;
+    const line = fm[1].match(/^\s*title\s*:\s*(.+?)\s*$/m);
+    if (!line)
+        return null;
+    // Drop surrounding quotes if the title was quoted.
+    return line[1].replace(/^["']|["']$/g, "").trim() || null;
+}
+/** Derive a human title for an entry without fetching its content. */
+function titleFromSlug(slug) {
+    const last = slug.split("/").pop() ?? slug;
+    return last.replace(/[-_]/g, " ");
+}
+export function registerDocsTools(server, _bridge) {
+    // ── search_docs ────────────────────────────────────────────────────
+    server.tool("search_docs", "Search the official s&box guide documentation (the Facepunch/sbox-docs pages rendered at sbox.game/dev/doc) by keyword. Returns the best-matching pages with their title, category, slug, and web URL — use the slug with get_doc_page to read one. The s&box API changes between SDK versions, so prefer these real docs over guessing. Read-only.", {
+        query: z
+            .string()
+            .describe("Keywords to match against page titles, slugs, and paths"),
+        category: z
+            .string()
+            .optional()
+            .describe('Optional category filter (the 2nd path segment, e.g. "networking", "ui"). Use list_doc_categories to see them.'),
+        limit: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max results to return (default 10, max 50)"),
+    }, async (params) => {
+        const index = await getIndex();
+        if (!index) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't load the s&box docs index from GitHub (network error or rate limit). Try again shortly; set the GITHUB_TOKEN environment variable to raise the rate limit.",
+                    },
+                ],
+            };
+        }
+        let limit = params.limit ?? 10;
+        if (limit < 1)
+            limit = 1;
+        if (limit > 50)
+            limit = 50;
+        const cat = params.category?.toLowerCase().trim();
+        let pages = index;
+        if (cat) {
+            pages = pages.filter((p) => p.category.toLowerCase() === cat);
+        }
+        const tokens = tokenize(params.query);
+        const scored = pages
+            .map((p) => {
+            const title = titleFromSlug(p.slug).toLowerCase();
+            const slug = p.slug.toLowerCase();
+            const path = p.path.toLowerCase();
+            let score = 0;
+            for (const t of tokens) {
+                // Title and slug are the strongest signals; path is a weak fallback.
+                if (title.includes(t))
+                    score += 5;
+                if (slug.includes(t))
+                    score += 4;
+                if (path.includes(t))
+                    score += 1;
+            }
+            return { p, score };
+        })
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        if (scored.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No s&box docs matched "${params.query}"${cat ? ` in category "${params.category}"` : ""}. Try broader keywords, or call list_doc_categories.`,
+                    },
+                ],
+            };
+        }
+        const results = scored.map(({ p }) => ({
+            title: titleFromSlug(p.slug),
+            category: p.category,
+            slug: p.slug,
+            webUrl: p.webUrl,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    });
+    // ── get_doc_page ───────────────────────────────────────────────────
+    server.tool("get_doc_page", "Fetch the full Markdown of one s&box guide page (from search_docs). Pass a slug like \"networking/rpcs\", a raw repo path like \"docs/networking/rpcs.md\", or a full sbox.game/dev/doc URL. YAML frontmatter is stripped. Long pages are paginated: pass chunk to read further (the footer tells you when there's more). Read-only.", {
+        slug: z
+            .string()
+            .describe('Page slug (e.g. "networking/rpcs"), a "docs/...md" path, or a full sbox.game/dev/doc URL'),
+        chunk: z
+            .number()
+            .int()
+            .optional()
+            .describe("1-based chunk index for long pages (default 1)"),
+        chunkSize: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max characters per chunk (default 8000)"),
+    }, async (params) => {
+        const index = await getIndex();
+        if (!index) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't load the s&box docs index from GitHub (network error or rate limit). Try again shortly; set the GITHUB_TOKEN environment variable to raise the rate limit.",
+                    },
+                ],
+            };
+        }
+        // Normalize the input into a slug: accept a full web URL, a raw repo path,
+        // or a bare slug.
+        let raw = params.slug.trim();
+        if (raw.startsWith("http")) {
+            const idx = raw.indexOf("/dev/doc/");
+            if (idx >= 0)
+                raw = raw.slice(idx + "/dev/doc/".length);
+        }
+        // Strip a leading "docs/" and a trailing ".md" if a path was passed.
+        const wanted = raw
+            .replace(/^\/+/, "")
+            .replace(/^docs\//, "")
+            .replace(/\.md$/i, "")
+            .replace(/\/+$/, "");
+        // Resolve against the index: exact slug, then a slug that points at the
+        // page's index file (e.g. "networking" -> "networking/index").
+        const entry = index.find((p) => p.slug.toLowerCase() === wanted.toLowerCase()) ??
+            index.find((p) => p.slug.toLowerCase() === `${wanted.toLowerCase()}/index`);
+        if (!entry) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: no s&box doc page matched "${params.slug}". Use search_docs to find a valid slug.`,
+                    },
+                ],
+            };
+        }
+        let md;
+        try {
+            const res = await fetch(RAW_BASE + entry.path);
+            if (!res.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: failed to fetch ${entry.path} (HTTP ${res.status}).`,
+                        },
+                    ],
+                };
+            }
+            md = await res.text();
+        }
+        catch (e) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching ${entry.path}: ${e.message}`,
+                    },
+                ],
+            };
+        }
+        const title = parseTitle(md) ?? titleFromSlug(entry.slug);
+        const body = stripFrontmatter(md);
+        const header = `# ${title}\nSource: ${entry.webUrl}\n\n`;
+        let chunkSize = params.chunkSize ?? 8000;
+        if (chunkSize < 500)
+            chunkSize = 500;
+        // Short pages: return the whole body in one shot.
+        if (body.length <= chunkSize) {
+            return { content: [{ type: "text", text: header + body }] };
+        }
+        // Long pages: slice into chunks and return the requested 1-based chunk.
+        const total = Math.ceil(body.length / chunkSize);
+        let i = params.chunk ?? 1;
+        if (i < 1)
+            i = 1;
+        if (i > total)
+            i = total;
+        const start = (i - 1) * chunkSize;
+        const slice = body.slice(start, start + chunkSize);
+        let footer = `\n\n— chunk ${i}/${total}`;
+        if (i < total) {
+            footer += `; call get_doc_page again with chunk=${i + 1} for more —`;
+        }
+        else {
+            footer += " (end) —";
+        }
+        return { content: [{ type: "text", text: header + slice + footer }] };
+    });
+    // ── list_doc_categories ────────────────────────────────────────────
+    server.tool("list_doc_categories", "List the categories of the official s&box guide documentation, with how many pages each has. Use a category name to filter search_docs. Read-only.", {}, async () => {
+        const index = await getIndex();
+        if (!index) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't load the s&box docs index from GitHub (network error or rate limit). Try again shortly; set the GITHUB_TOKEN environment variable to raise the rate limit.",
+                    },
+                ],
+            };
+        }
+        const counts = new Map();
+        for (const p of index) {
+            const key = p.category || "(root)";
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        const result = Array.from(counts.entries())
+            .map(([category, pageCount]) => ({ category, pageCount }))
+            .sort((a, b) => b.pageCount - a.pageCount);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=docs.js.map

package/dist/tools/navigation.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+export declare function registerNavigationTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/tools/navigation.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+/**
+ * Navigation tools (Batch 27) — REAL editor operations, not component wrappers.
+ *
+ * bake_navmesh runs the editor's static NavMesh bake (NavMesh.BakeNavMesh) so
+ * NavMeshAgents can pathfind; get_navmesh_path queries the baked mesh for a
+ * route (NavMesh.GetSimplePath). Neither is reachable via add_component — they
+ * operate on the scene's navmesh itself, which is why they earn dedicated tools.
+ */
+const Vec3 = z
+    .object({
+    x: z.number().describe("X"),
+    y: z.number().describe("Y"),
+    z: z.number().describe("Z"),
+})
+    .describe("A world-space Vector3");
+export function registerNavigationTools(server, bridge) {
+    // ── bake_navmesh ────────────────────────────────────────────────────
+    server.tool("bake_navmesh", "Enable + bake the active scene's navigation mesh so NavMeshAgents can pathfind. This is an editor operation (NavMesh.BakeNavMesh), not a component. The bake runs ASYNC — it returns immediately with baking:true; the editor shows a progress bar and isGenerating flips false when done (give it a moment before querying paths). Optional agent params let you size the mesh to your characters.", {
+        agentRadius: z.number().optional().describe("Agent radius (default scene setting)"),
+        agentHeight: z.number().optional().describe("Agent height"),
+        agentStepSize: z.number().optional().describe("Max step-up height"),
+        agentMaxSlope: z.number().optional().describe("Max walkable slope, degrees"),
+        includeStaticBodies: z
+            .boolean()
+            .optional()
+            .describe("Include static physics bodies in the bake"),
+    }, async (params) => {
+        const res = await bridge.send("bake_navmesh", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── get_navmesh_path ────────────────────────────────────────────────
+    server.tool("get_navmesh_path", "Query the baked navmesh for a walkable path between two world points (NavMesh.GetSimplePath). Returns the ordered path points, or reachable:false if no route exists. Requires bake_navmesh to have run first. Read-only — useful for validating connectivity, AI patrol routes, and spawn reachability.", {
+        from: Vec3.describe("Start point (world space)"),
+        to: Vec3.describe("Destination point (world space)"),
+    }, async (params) => {
+        const res = await bridge.send("get_navmesh_path", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=navigation.js.map

package/dist/tools/networking.js

@@ -100,23 +100,25 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── add_sync_property ─────────────────────────────────────────────
-    server.tool("add_sync_property", "Add a [Sync] networked property to a C# script. The property auto-replicates across the network", {
+    server.tool("add_sync_property", "Annotate an EXISTING public property in a C# script with the [Sync] attribute so s&box replicates it across the network. This does NOT create a new property — the property named by `propertyName` must already be declared in the file; the tool only inserts the [Sync] attribute above it", {
         path: z
             .string()
             .describe("Relative path to the script file (e.g. 'code/Player.cs')"),
-        propertyName: z.string().describe("Name for the new property"),
+        propertyName: z
+            .string()
+            .describe("Name of the existing public property to annotate with [Sync]"),
         propertyType: z
             .string()
             .optional()
-            .describe("C# type (float, int, string, Vector3, bool, etc.). Defaults to 'float'"),
+            .describe("Currently ignored — not yet implemented. The addon only annotates an existing property; it does not declare a new one, so the type comes from the existing declaration"),
         syncFlags: z
             .string()
             .optional()
-            .describe("Sync flags: 'FromHost' (host→clients only). Omit for bidirectional"),
+            .describe("Currently ignored — not yet implemented. The addon emits a plain [Sync] with no SyncFlags"),
         defaultValue: z
             .string()
             .optional()
-            .describe("Default value expression (e.g. '100f', 'true', 'Vector3.Zero')"),
+            .describe("Currently ignored — not yet implemented. The addon does not create or initialize a property, so no default is written"),
     }, async (params) => {
         const res = await bridge.send("add_sync_property", params);
         if (!res.success) {
@@ -127,7 +129,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── add_rpc_method ────────────────────────────────────────────────
-    server.tool("add_rpc_method", "Add an RPC method to a C# script. Supports [Rpc.Broadcast] (all clients), [Rpc.Host] (host only), [Rpc.Owner] (owner only)", {
+    server.tool("add_rpc_method", "Generate an EMPTY, no-argument RPC method stub in a C# script for you to fill in. The addon inserts the chosen RPC attribute ([Rpc.Broadcast] all clients, [Rpc.Host] host only, [Rpc.Owner] owner only) above a parameterless method with an empty body — it does NOT add parameters or generate body code", {
         path: z
             .string()
             .describe("Relative path to the script file"),
@@ -139,11 +141,11 @@ export function registerNetworkingTools(server, bridge) {
         methodParams: z
             .string()
             .optional()
-            .describe("Method parameters as C# signature (e.g. 'float damage, Vector3 hitPos')"),
+            .describe("Currently ignored — not yet implemented. The addon emits a no-argument method; add parameters yourself afterward"),
         body: z
             .string()
             .optional()
-            .describe("Method body code (without braces). Defaults to a log statement"),
+            .describe("Currently ignored — not yet implemented. The addon emits an empty method body; fill it in yourself afterward"),
     }, async (params) => {
         const res = await bridge.send("add_rpc_method", params);
         if (!res.success) {

package/dist/tools/objecttools.js

@@ -76,5 +76,31 @@ export function registerObjectTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── remove_component ───────────────────────────────────────────────
+    server.tool("remove_component", "Remove a component from a GameObject by type name (e.g. 'PointLight', 'ModelRenderer'). Removes the first match; pass all:true to remove every matching one. The counterpart to add_component_with_properties.", {
+        id: z.string().describe("GUID of the GameObject"),
+        component: z.string().describe("Component type name to remove"),
+        all: z.boolean().optional().describe("Remove all matching components, not just the first"),
+    }, async (params) => {
+        const res = await bridge.send("remove_component", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── get_tags ───────────────────────────────────────────────────────
+    server.tool("get_tags", "Read the tags currently on a GameObject. (Pair with set_tags to add/remove/clear, and find_objects to query by tag.)", {
+        id: z.string().describe("GUID of the GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("get_tags", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=objecttools.js.map

package/dist/tools/physics.js

@@ -126,5 +126,27 @@ export function registerPhysicsTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── physics_overlap ───────────────────────────────────────────────
+    server.tool("physics_overlap", "Spatial volume query: return the GameObjects whose colliders intersect a SPHERE (center + radius) or a BOX (center + size) — the volume counterpart to raycast's ray. Use it for 'what's near this point' / 'what's inside this trigger volume' checks (proximity, blast radius, spawn-clearance). Read-only.", {
+        center: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .describe("Center of the query volume (world space)"),
+        radius: z
+            .number()
+            .optional()
+            .describe("Sphere radius. Provide this OR size (box), not both"),
+        size: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("Full box size (not half-extents). Provide this OR radius"),
+    }, async (params) => {
+        const res = await bridge.send("physics_overlap", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=physics.js.map

package/dist/tools/project.js

@@ -74,8 +74,18 @@ export function registerProjectTools(server, bridge) {
         content: z.string().describe("The full file content to write"),
     }, async (params) => {
         const res = await bridge.send("write_file", params);
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        // The handler can report a logical failure inside res.data even when the
+        // transport call "succeeded" (res.success === true). Only claim success
+        // when there is no error field anywhere; otherwise surface the real error
+        // instead of a misleading "written successfully".
+        const dataError = res.data && typeof res.data === "object"
+            ? res.data.error
+            : undefined;
+        if (!res.success || dataError) {
+            const message = res.error ?? (dataError ? String(dataError) : undefined);
+            return {
+                content: [{ type: "text", text: `Error: ${message ?? "write_file failed"}` }],
+            };
         }
         return {
             content: [

package/dist/tools/status.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /**
  * Diagnostic and health-check tool (get_bridge_status).
  * Reports connection state, latency, host/port, and editor version.
@@ -60,5 +61,62 @@ export function registerStatusTools(server, bridge) {
             ],
         };
     });
+    // ── restart_editor ────────────────────────────────────────────────
+    server.tool("restart_editor", "Restart the s&box editor and wait for the bridge to reconnect — closes the C#-edit→recompile loop so addon/bridge changes apply without a manual restart. Relaunches straight back into the current project (EditorUtility.RestartEditor). Saves unsaved scenes by default (pass save:false to discard them). Blocks until the bridge is back (or waitMs elapses), then reports the handler count.", {
+        save: z
+            .boolean()
+            .optional()
+            .describe("Save unsaved scenes before restarting (default true; false discards them)"),
+        waitMs: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max ms to wait for reconnect (default 150000)"),
+    }, async (params) => {
+        const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+        // Fire the restart. The editor closes mid-request, so a timeout/no-response here is EXPECTED.
+        try {
+            await bridge.send("restart_editor", { save: params.save ?? true }, 5000);
+        }
+        catch {
+            /* editor going down — expected */
+        }
+        const waitMs = params.waitMs ?? 150000;
+        const deadline = Date.now() + waitMs;
+        // Let the old process actually exit (heartbeat goes stale) before checking, so we
+        // don't false-positive on the pre-restart connection.
+        await sleep(8000);
+        while (Date.now() < deadline) {
+            await sleep(2500);
+            if (bridge.isConnected()) {
+                // Heartbeat is fresh again — confirm the request loop drains + read the count.
+                try {
+                    const st = await bridge.send("get_bridge_status", {}, 5000);
+                    if (st.success && st.data) {
+                        const hc = st.data.handlerCount;
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Editor restarted — bridge reconnected${hc ? ` with ${hc} handlers` : ""}.`,
+                                },
+                            ],
+                        };
+                    }
+                }
+                catch {
+                    /* still settling — keep polling */
+                }
+            }
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Restart fired, but the bridge didn't reconnect within ${waitMs}ms — the editor may still be compiling. Try get_bridge_status in a moment.`,
+                },
+            ],
+        };
+    });
 }
 //# sourceMappingURL=status.js.map

package/dist/tools/visuals.js

@@ -255,5 +255,35 @@ export function registerVisualTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── spawn_vpcf ──────────────────────────────────────────────────────
+    server.tool("spawn_vpcf", "Spawn a REAL particle system by playing a compiled .vpcf asset through LegacyParticleSystem — the reliable path that actually renders, unlike spawn_particle/create_particle_effect (which build a runtime ParticleEffect graph that shows nothing). Defaults to 'particles/impact.generic.vpcf' (a sparks/impact burst — the only particle .vpcf reliably present; set looped + a warm tint for a fire-ish effect). Pass your own compiled .vpcf logical path if you have one. Screenshot-verifiable in edit mode.", {
+        vpcf: z
+            .string()
+            .optional()
+            .describe("Logical .vpcf path (default 'particles/impact.generic.vpcf'). NOT the .vpcf_c or .sbox/cloud cache path."),
+        position: Vector3Schema.optional().describe("World position (default origin)"),
+        name: z.string().optional().describe("GameObject name"),
+        looped: z.boolean().optional().describe("Loop the effect (default true)"),
+        playbackSpeed: z.number().optional().describe("Playback speed multiplier"),
+        tint: ColorSchema.optional().describe("Color tint (e.g. orange for fire); applied to the live SceneObject if it's ready this frame"),
+    }, async (params) => {
+        const res = await bridge.send("spawn_vpcf", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── bake_reflections ────────────────────────────────────────────────
+    server.tool("bake_reflections", "Bake all EnvmapProbe reflection probes in the scene (EnvmapProbe.BakeAll) so they actually capture their surroundings — placing a probe with add_envmap_probe does nothing visible until it's baked. This is a real editor compute step, not a component setter. Runs async; re-screenshot after a moment to see reflections appear on shiny surfaces.", {}, async (params) => {
+        const res = await bridge.send("bake_reflections", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=visuals.js.map

package/dist/transport/bridge-client.js

@@ -6,7 +6,10 @@ import * as os from "os";
  *
  * 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)
+ * - MCP server writes request files (req_*.json) atomically — it writes
+ *   req_*.json.tmp first, then renames it into place so the addon can never
+ *   read a half-written request. The addon consumes only req_*.json and
+ *   ignores *.tmp.
  * - s&box addon polls for them, processes on the main editor thread, and writes
  *   response files (res_*.json)
  * - MCP server polls for response files
@@ -167,13 +170,24 @@ export class BridgeClient {
         if (!fs.existsSync(this.ipcDir)) {
             fs.mkdirSync(this.ipcDir, { recursive: true });
         }
-        // Write request file
+        // Write request file atomically: write to a .tmp sibling, then rename into
+        // place. The C# poller only consumes `req_*.json` (it ignores `*.tmp`), so
+        // it can never observe a half-written request for a large payload — the
+        // rename is atomic on the same volume.
         const reqPath = path.join(this.ipcDir, `req_${id}.json`);
+        const tmpPath = `${reqPath}.tmp`;
         const resPath = path.join(this.ipcDir, `res_${id}.json`);
         try {
-            fs.writeFileSync(reqPath, JSON.stringify(request), "utf8");
+            fs.writeFileSync(tmpPath, JSON.stringify(request), "utf8");
+            fs.renameSync(tmpPath, reqPath);
         }
         catch (err) {
+            // Best-effort cleanup of a partial temp file so it doesn't linger.
+            try {
+                if (fs.existsSync(tmpPath))
+                    fs.unlinkSync(tmpPath);
+            }
+            catch { }
             return {
                 id,
                 success: false,
@@ -245,11 +259,20 @@ export class BridgeClient {
         if (!fs.existsSync(this.ipcDir)) {
             fs.mkdirSync(this.ipcDir, { recursive: true });
         }
+        // Write atomically (temp + rename) so the C# poller never reads a partial
+        // batch request file. See the note in send() above.
         const reqPath = path.join(this.ipcDir, `req_${id}.json`);
+        const tmpPath = `${reqPath}.tmp`;
         try {
-            fs.writeFileSync(reqPath, JSON.stringify(request), "utf8");
+            fs.writeFileSync(tmpPath, JSON.stringify(request), "utf8");
+            fs.renameSync(tmpPath, reqPath);
         }
         catch (err) {
+            try {
+                if (fs.existsSync(tmpPath))
+                    fs.unlinkSync(tmpPath);
+            }
+            catch { }
             return {
                 id,
                 success: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbox-mcp-server",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
   "type": "module",
   "main": "dist/index.js",