sbox-mcp-server 1.3.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

@@ -100,6 +100,30 @@ TOOLS (99 working — was 109; 10 unimplementable tools removed in v1.3.0)
 const server = new McpServer({
     name: "sbox-mcp",
     version: getVersion(),
+}, {
+    // The `instructions` field surfaces every Claude Code session that uses this
+    // server (the way other MCP servers like Supabase / TurboTax do). Use it to
+    // tell Claude how to work effectively with the bridge — the disciplines that
+    // are easy to skip without a reminder.
+    instructions: `You are working with the s&box Claude Bridge — a file-based IPC bridge into the s&box game engine editor.
+
+To get good results:
+
+1. Always call \`mcp__sbox__get_bridge_status\` first to confirm the bridge addon is connected and s&box is running. If ping responds but other tools time out, the editor side isn't processing requests.
+
+2. For visual changes (models, positions, animations, UI panels, lighting), call \`mcp__sbox__take_screenshot\` after the change and READ THE PNG yourself. You're a multimodal model — you can see the result. Guessing about visual outcomes from code alone produces long iteration loops. The screenshot tool saves to <sbox-install>/screenshots/sbox.<timestamp>.png — list the newest file and read it.
+
+3. Before writing code that touches an unfamiliar s&box type, call \`mcp__sbox__describe_type\` or \`mcp__sbox__search_types\`. s&box's API changes between SDK versions — reflection is the source of truth, not training data.
+
+4. \`get_scene_hierarchy\` honors \`maxDepth\` (default 10) and accepts optional \`rootId\` to traverse from a specific GameObject. Use these to avoid dumping the entire scene into a tool result.
+
+5. Scene-mutating tools (create_gameobject, set_property, etc.) refuse during play mode and return a clear error. Stop play before making scene edits.
+
+If you're running inside Claude Code, install the companion plugin for the full workflow:
+    /plugin marketplace add LouSputthole/Sbox-Claude
+    /plugin install sbox-claude
+
+The plugin ships an \`sbox-build-feature\` skill that codifies the workflow above plus a list of common s&box gotchas (MathF not available in sandbox, Cloud assets ephemeral, head bone case-sensitive, CitizenAnimationHelper.IkRightHand works at runtime, etc.). Read its SKILL.md before starting non-trivial features.`,
 });
 // Bridge client connects to s&box editor via WebSocket
 const bridge = new BridgeClient(process.env.SBOX_BRIDGE_HOST ?? "127.0.0.1", parseInt(process.env.SBOX_BRIDGE_PORT ?? "29015", 10));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbox-mcp-server",
-  "version": "1.3.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",