sbox-mcp-server 1.2.0 → 1.3.1

package/README.md

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

package/dist/index.js

@@ -17,7 +17,6 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { BridgeClient } from "./transport/bridge-client.js";
 import { registerProjectTools } from "./tools/project.js";
 import { registerScriptTools } from "./tools/scripts.js";
-import { registerConsoleTools } from "./tools/console.js";
 import { registerSceneTools } from "./tools/scenes.js";
 import { registerGameObjectTools } from "./tools/gameobjects.js";
 import { registerComponentTools } from "./tools/components.js";
@@ -67,18 +66,17 @@ ENVIRONMENT VARIABLES
 CONNECT TO CLAUDE CODE
   claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
 
-TOOLS (109 total)
+TOOLS (99 working — was 109; 10 unimplementable tools removed in v1.3.0)
   Project:     get_project_info, list_project_files, read_file, write_file
   Scripts:     create_script, edit_script, delete_script, trigger_hotload
-  Console:     get_console_output, get_compile_errors, clear_console
   Scenes:      list_scenes, load_scene, save_scene, create_scene
   GameObjects: create/delete/duplicate/rename_gameobject, set_parent/enabled/transform
   Components:  get/set_property, get_all_properties, list_available_components, add_component_with_properties, set_prefab_ref
-  Hierarchy:   get_scene_hierarchy, get_selected_objects, select_object, focus_object
+  Hierarchy:   get_scene_hierarchy (with maxDepth + rootId), get_selected_objects, select_object, focus_object
   Assets:      search_assets, list_asset_library, install_asset, get_asset_info
   Materials:   assign_model, create_material, assign_material, set_material_property
   Audio:       list_sounds, create_sound_event, assign_sound, play_sound_preview
-  Play Mode:   start/stop/pause/resume_play, is_playing
+  Play Mode:   start_play, stop_play, is_playing
   Runtime:     get/set_runtime_property, take_screenshot
   Editor:      undo, redo
   Prefabs:     create_prefab, instantiate_prefab, list_prefabs, get_prefab_info
@@ -87,8 +85,7 @@ TOOLS (109 total)
   Templates:   create_player_controller, create_npc_controller, create_game_manager, create_trigger_zone
   Networking:  add_network_helper, configure_network, get_network_status, network_spawn, set_ownership
   Net Scripts: add_sync_property, add_rpc_method, create_networked_player, create_lobby_manager, create_network_events
-  Publishing:  get_project_config, set_project_config, validate_project, build_project, get_build_status, clean_build
-  Export:      export_project, set_project_thumbnail, get_package_details, prepare_publish
+  Publishing:  get_project_config, set_project_config, validate_project, set_project_thumbnail, get_package_details
   World Gen:   invoke_button, list_component_buttons, raycast_terrain, build_terrain_mesh
   Map Edit:    add_terrain_hill/clearing/trail, clear_terrain_features, sculpt_terrain
   Caves:       add_cave_waypoint, clear_cave_path
@@ -103,13 +100,36 @@ TOOLS (109 total)
 const server = new McpServer({
     name: "sbox-mcp",
     version: getVersion(),
+}, {
+    // The `instructions` field surfaces every Claude Code session that uses this
+    // server (the way other MCP servers like Supabase / TurboTax do). Use it to
+    // tell Claude how to work effectively with the bridge — the disciplines that
+    // are easy to skip without a reminder.
+    instructions: `You are working with the s&box Claude Bridge — a file-based IPC bridge into the s&box game engine editor.
+
+To get good results:
+
+1. Always call \`mcp__sbox__get_bridge_status\` first to confirm the bridge addon is connected and s&box is running. If ping responds but other tools time out, the editor side isn't processing requests.
+
+2. For visual changes (models, positions, animations, UI panels, lighting), call \`mcp__sbox__take_screenshot\` after the change and READ THE PNG yourself. You're a multimodal model — you can see the result. Guessing about visual outcomes from code alone produces long iteration loops. The screenshot tool saves to <sbox-install>/screenshots/sbox.<timestamp>.png — list the newest file and read it.
+
+3. Before writing code that touches an unfamiliar s&box type, call \`mcp__sbox__describe_type\` or \`mcp__sbox__search_types\`. s&box's API changes between SDK versions — reflection is the source of truth, not training data.
+
+4. \`get_scene_hierarchy\` honors \`maxDepth\` (default 10) and accepts optional \`rootId\` to traverse from a specific GameObject. Use these to avoid dumping the entire scene into a tool result.
+
+5. Scene-mutating tools (create_gameobject, set_property, etc.) refuse during play mode and return a clear error. Stop play before making scene edits.
+
+If you're running inside Claude Code, install the companion plugin for the full workflow:
+    /plugin marketplace add LouSputthole/Sbox-Claude
+    /plugin install sbox-claude
+
+The plugin ships an \`sbox-build-feature\` skill that codifies the workflow above plus a list of common s&box gotchas (MathF not available in sandbox, Cloud assets ephemeral, head bone case-sensitive, CitizenAnimationHelper.IkRightHand works at runtime, etc.). Read its SKILL.md before starting non-trivial features.`,
 });
 // Bridge client connects to s&box editor via WebSocket
 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);
 registerScriptTools(server, bridge);
-registerConsoleTools(server, bridge);
 registerSceneTools(server, bridge);
 registerGameObjectTools(server, bridge);
 registerComponentTools(server, bridge);

package/dist/tools/gameobjects.js

@@ -141,11 +141,17 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── get_scene_hierarchy ──────────────────────────────────────────
-    server.tool("get_scene_hierarchy", "Get the full scene tree — all GameObjects with their names, GUIDs, components, positions, and parent/child relationships. This is how you 'see' the scene", {
+    server.tool("get_scene_hierarchy", "Get the scene tree — GameObjects with their names, GUIDs, components, and parent/child relationships. Pair maxDepth with rootId to drill into a subtree without paying for the whole scene", {
         maxDepth: z
             .number()
+            .int()
+            .nonnegative()
             .optional()
-            .describe("Maximum depth of the tree to return. Defaults to 10"),
+            .describe("Maximum recursion depth. Defaults to 10. Use 1 or 2 for cheap top-level overviews"),
+        rootId: z
+            .string()
+            .optional()
+            .describe("Optional GUID of a GameObject to start traversal from. Omit to walk from the scene roots"),
     }, async (params) => {
         const res = await bridge.send("get_scene_hierarchy", params);
         if (!res.success) {

package/dist/tools/playmode.js

@@ -27,26 +27,9 @@ export function registerPlayModeTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
-    // ── pause_play ───────────────────────────────────────────────────
-    server.tool("pause_play", "Pause the running game — freezes simulation but stays in play mode. Use resume_play to continue", {}, async () => {
-        const res = await bridge.send("pause_play");
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
-        };
-    });
-    // ── resume_play ──────────────────────────────────────────────────
-    server.tool("resume_play", "Resume a paused game — unfreezes simulation", {}, async () => {
-        const res = await bridge.send("resume_play");
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
-        };
-    });
+    // pause_play / resume_play removed in v1.3.0 — s&box does not expose a public
+    // API for pausing the editor's play mode, so the addon has no handler and the
+    // tool only ever returned "Unknown command". See GitHub issue #3.
     // ── is_playing ───────────────────────────────────────────────────
     server.tool("is_playing", "Check current play state — returns 'playing', 'paused', or 'stopped'", {}, async () => {
         const res = await bridge.send("is_playing");

package/dist/tools/publishing.d.ts

@@ -2,10 +2,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BridgeClient } from "../transport/bridge-client.js";
 /**
  * Publishing tools: get_project_config, set_project_config, validate_project,
- * build_project, get_build_status, clean_build, export_project,
- * set_project_thumbnail, get_package_details, prepare_publish.
+ * set_project_thumbnail, get_package_details.
  *
- * Manages project configuration, building, exporting, and publishing preparation.
+ * Manages project configuration and publishing metadata.
+ *
+ * build_project / get_build_status / clean_build / export_project / prepare_publish
+ * were removed in v1.3.0 — s&box does not expose a public API for these from
+ * inside an addon, so the bridge never had handlers for them and the tools only
+ * ever returned "Unknown command". See GitHub issue #3.
  */
 export declare function registerPublishingTools(server: McpServer, bridge: BridgeClient): void;
 //# sourceMappingURL=publishing.d.ts.map

package/dist/tools/publishing.js

@@ -1,10 +1,14 @@
 import { z } from "zod";
 /**
  * Publishing tools: get_project_config, set_project_config, validate_project,
- * build_project, get_build_status, clean_build, export_project,
- * set_project_thumbnail, get_package_details, prepare_publish.
+ * set_project_thumbnail, get_package_details.
  *
- * Manages project configuration, building, exporting, and publishing preparation.
+ * Manages project configuration and publishing metadata.
+ *
+ * build_project / get_build_status / clean_build / export_project / prepare_publish
+ * were removed in v1.3.0 — s&box does not expose a public API for these from
+ * inside an addon, so the bridge never had handlers for them and the tools only
+ * ever returned "Unknown command". See GitHub issue #3.
  */
 export function registerPublishingTools(server, bridge) {
     // ── get_project_config ───────────────────────────────────────────
@@ -63,60 +67,8 @@ export function registerPublishingTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
-    // ── build_project ────────────────────────────────────────────────
-    server.tool("build_project", "Trigger a full project build/recompilation. Returns build result with error and warning counts", {
-        configuration: z
-            .enum(["Debug", "Release"])
-            .optional()
-            .describe("Build configuration. Defaults to 'Release'"),
-    }, async (params) => {
-        const res = await bridge.send("build_project", params);
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
-        };
-    });
-    // ── get_build_status ─────────────────────────────────────────────
-    server.tool("get_build_status", "Get the current build/compilation status: is compiling, errors, warnings, and full diagnostics list", {}, async (params) => {
-        const res = await bridge.send("get_build_status", params);
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
-        };
-    });
-    // ── clean_build ──────────────────────────────────────────────────
-    server.tool("clean_build", "Clean all compiled output (bin, obj) and trigger a fresh rebuild from scratch", {}, async (params) => {
-        const res = await bridge.send("clean_build", params);
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
-        };
-    });
-    // ── export_project ───────────────────────────────────────────────
-    server.tool("export_project", "Export the project as a standalone game. Copies assemblies, assets, and scenes to an output directory for distribution", {
-        outputPath: z
-            .string()
-            .optional()
-            .describe("Relative output directory within the project. Defaults to 'export'"),
-        configuration: z
-            .enum(["Debug", "Release"])
-            .optional()
-            .describe("Build configuration for export. Defaults to 'Release'"),
-    }, async (params) => {
-        const res = await bridge.send("export_project", params);
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
-        };
-    });
+    // build_project / get_build_status / clean_build / export_project removed
+    // in v1.3.0 — no addon handler exists. See GitHub issue #3.
     // ── set_project_thumbnail ────────────────────────────────────────
     server.tool("set_project_thumbnail", "Set or update the project thumbnail image (thumb.png) used for publishing. Provide either a source path or base64 image data", {
         sourcePath: z
@@ -154,15 +106,7 @@ export function registerPublishingTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
-    // ── prepare_publish ──────────────────────────────────────────────
-    server.tool("prepare_publish", "Comprehensive publish preparation: validates project, compiles, checks metadata, and generates a detailed readiness report with issues, warnings, and next steps", {}, async (params) => {
-        const res = await bridge.send("prepare_publish", params);
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
-        }
-        return {
-            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
-        };
-    });
+    // prepare_publish removed in v1.3.0 — no addon handler. Equivalent intent is
+    // covered by validate_project (which IS implemented). GitHub issue #3.
 }
 //# sourceMappingURL=publishing.js.map

package/package.json

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