sbox-mcp-server 1.3.2 → 1.5.0

package/README.md

@@ -1,113 +1,131 @@
-# sbox-mcp-server
-
-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.
-
-## Fastest install — the Claude Code plugin
-
-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.
-
-```
-/plugin marketplace add LouSputthole/Sbox-Claude
-/plugin install sbox-claude
-```
-
-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.
-
-## Manual install — three steps
-
-### 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
-```
-
-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 -- npx sbox-mcp-server
-```
-
-This is the bare command — equivalent to what the plugin's `.mcp.json` does for you.
-
-### 3. Open s&box
-
-Open your project. The bridge starts automatically. Verify with:
-
-```
-Check the bridge status.
-```
-
-You should see `connected: true, handlerCount: 99`.
-
-## How it works
-
-```
-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 |
-|----------|-------|
-| **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 |
-| **GameObjects** | create/delete/duplicate/rename, set_parent/enabled/transform |
-| **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 |
-| **Play Mode** | start/stop_play, is_playing |
-| **Runtime** | get/set_runtime_property, take_screenshot |
-| **Editor** | undo, redo |
-| **Prefabs** | create/instantiate_prefab, list_prefabs, get_prefab_info |
-| **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, 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 |
-
-## Working with Claude effectively
-
-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 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.
-
-Copyright (c) 2026 [sboxskins.gg](https://sboxskins.gg)
+# sbox-mcp-server
+
+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
+
+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.
+
+```
+/plugin marketplace add LouSputthole/Sbox-Claude
+/plugin install sbox-claude
+```
+
+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.
+
+## Manual install — three steps
+
+### 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
+```
+
+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 -- npx sbox-mcp-server
+```
+
+This is the bare command — equivalent to what the plugin's `.mcp.json` does for you.
+
+### 3. Open s&box
+
+Open your project. The bridge starts automatically. Verify with:
+
+```
+Check the bridge status.
+```
+
+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
+
+```
+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 (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 |
+|----------|-------|
+| **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 |
+| **GameObjects** | create/delete/duplicate/rename, set_parent/enabled/transform |
+| **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 |
+| **Play Mode** | start/stop_play, is_playing |
+| **Runtime** | get/set_runtime_property, take_screenshot |
+| **Editor** | undo, redo |
+| **Prefabs** | create/instantiate_prefab, list_prefabs, get_prefab_info |
+| **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, 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 |
+| **Visual & atmosphere** *(v1.4.0)* | add_light, set_fog, add_post_process, set_skybox, add_envmap_probe, apply_atmosphere, apply_post_fx_look |
+| **Characters** *(v1.4.0)* | spawn_model, spawn_citizen, dress_citizen, set_bodygroup, pose_citizen, equip_model, set_look_at, add_ragdoll, set_expression |
+| **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 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
+
+Three disciplines prevent the iteration-loop trap:
+
+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.
+
+## Requirements
+
+- **Node.js 18+**
+- **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) — 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
+
+## License
+
+**GPL-3.0** — see [LICENSE](../LICENSE) for details.
+
+Copyright (c) 2026 [sboxskins.gg](https://sboxskins.gg)

package/dist/index.js

@@ -33,6 +33,13 @@ import { registerNetworkingTools } from "./tools/networking.js";
 import { registerPublishingTools } from "./tools/publishing.js";
 import { registerWorldTools } from "./tools/world.js";
 import { registerDiscoveryTools } from "./tools/discovery.js";
+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. */
@@ -68,7 +75,7 @@ ENVIRONMENT VARIABLES
 CONNECT TO CLAUDE CODE
   claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
 
-TOOLS (99 working — was 109; 10 unimplementable tools removed in v1.3.0)
+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
@@ -95,6 +102,25 @@ TOOLS (99 working — was 109; 10 unimplementable tools removed in v1.3.0)
   Placement:   place_along_path
   Discovery:   describe_type, search_types, get_method_signature, find_in_project
   Status:      get_bridge_status
+
+  ── New in v1.4.0 ───────────────────────────────────
+  Visual:      add_light, set_fog, add_post_process, set_skybox, add_envmap_probe, apply_atmosphere, apply_post_fx_look
+  Characters:  spawn_model, spawn_citizen, dress_citizen, set_bodygroup, pose_citizen, equip_model, set_look_at, add_ragdoll, set_expression
+  Scene:       snap_to_ground, align_objects, distribute_objects, grid_duplicate, measure_distance
+  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);
 }
@@ -148,6 +174,13 @@ registerNetworkingTools(server, bridge);
 registerPublishingTools(server, bridge);
 registerWorldTools(server, bridge);
 registerDiscoveryTools(server, bridge);
+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/characters.d.ts

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

package/dist/tools/characters.js

@@ -0,0 +1,209 @@
+import { z } from "zod";
+/**
+ * Character & model tools (Batch 19): spawn world models, spawn animated
+ * Citizen characters, dress them with clothing, toggle bodygroups, and pose
+ * them via CitizenAnimationHelper.
+ *
+ * Unlike particles (Batch 18), everything here is a STATIC mesh/pose that
+ * renders in the editor viewport — so the screenshot loop works: after a
+ * change, take_screenshot and read the result. Animation *playback* is
+ * runtime, but poses preview in-editor via PlayAnimationsInEditorScene.
+ */
+const ColorSchema = z
+    .object({
+    r: z.number().min(0).describe("Red, 0-1"),
+    g: z.number().min(0).describe("Green, 0-1"),
+    b: z.number().min(0).describe("Blue, 0-1"),
+    a: z.number().min(0).max(1).optional().describe("Alpha, 0-1 (default 1)"),
+})
+    .describe("RGBA colour as 0-1 floats (model tint)");
+const Vector3Schema = z
+    .object({ x: z.number(), y: z.number(), z: z.number() })
+    .describe("World position {x,y,z}");
+const RotationSchema = z
+    .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
+    .describe("Rotation {pitch,yaw,roll} in degrees");
+export function registerCharacterTools(server, bridge) {
+    // ── spawn_model ────────────────────────────────────────────────────
+    server.tool("spawn_model", "Spawn a GameObject with a ModelRenderer showing a model — the quick way to place a prop. Pass an engine/project model path (e.g. 'models/citizen/citizen.vmdl', 'models/dev/box.vmdl'). Cloud (sbox.game) models must be installed first via install_asset, then pass the resulting path. Add physics separately with add_collider/add_physics if needed.", {
+        model: z
+            .string()
+            .describe("Model path, e.g. 'models/dev/box.vmdl' or an installed model path"),
+        name: z.string().optional().describe("GameObject name"),
+        position: Vector3Schema.optional().describe("World position"),
+        rotation: RotationSchema.optional().describe("World rotation"),
+        scale: Vector3Schema.optional().describe("World scale (default 1,1,1)"),
+        tint: ColorSchema.optional().describe("Model tint colour"),
+        parentId: z.string().optional().describe("GUID of a parent GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("spawn_model", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── spawn_citizen ──────────────────────────────────────────────────
+    server.tool("spawn_citizen", "Spawn an animated Citizen character: a SkinnedModelRenderer with the Citizen model, plus (by default) a CitizenAnimationHelper so it idles. PlayAnimationsInEditorScene is enabled so the idle pose shows in the editor view (screenshot-verifiable). Dress it afterward with dress_citizen, pose it with pose_citizen.", {
+        name: z.string().optional().describe("GameObject name (default 'Citizen')"),
+        model: z
+            .string()
+            .optional()
+            .describe("Override the skinned model (default 'models/citizen/citizen.vmdl')"),
+        position: Vector3Schema.optional().describe("World position"),
+        rotation: RotationSchema.optional().describe("World rotation"),
+        scale: Vector3Schema.optional().describe("World scale (default 1,1,1)"),
+        tint: ColorSchema.optional().describe("Body tint colour"),
+        animator: z
+            .boolean()
+            .optional()
+            .describe("Add a CitizenAnimationHelper for idle/pose (default true)"),
+        holdType: z
+            .string()
+            .optional()
+            .describe("Initial hold pose, e.g. None, Pistol, Rifle, Shotgun, HoldItem, Punch, Swing"),
+        moveStyle: z
+            .string()
+            .optional()
+            .describe("Movement style, e.g. Auto, Walk, Run"),
+        parentId: z.string().optional().describe("GUID of a parent GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("spawn_citizen", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── dress_citizen ──────────────────────────────────────────────────
+    server.tool("dress_citizen", "Dress a spawned Citizen (or any GameObject with a SkinnedModelRenderer) by applying .clothing resources. Pass an array of clothing resource paths; they're loaded, added to a ClothingContainer, and applied to the body. Returns which paths applied vs were not found.", {
+        id: z.string().describe("GUID of the Citizen GameObject"),
+        clothing: z
+            .array(z.string())
+            .describe("Clothing resource paths, e.g. ['models/citizen_clothes/jacket/jacket.clothing']"),
+        tint: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("ClothingContainer tint position 0-1 (skin/clothing colour variation)"),
+    }, async (params) => {
+        const res = await bridge.send("dress_citizen", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_bodygroup ──────────────────────────────────────────────────
+    server.tool("set_bodygroup", "Show/hide a bodygroup on a SkinnedModelRenderer (e.g. hide hands when holding a tool, swap head variants). Provide value (int index) or choice (string name).", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        name: z.string().describe("Bodygroup name"),
+        value: z.number().int().optional().describe("Bodygroup choice index"),
+        choice: z.string().optional().describe("Bodygroup choice by name (alternative to value)"),
+    }, async (params) => {
+        const res = await bridge.send("set_bodygroup", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── pose_citizen ───────────────────────────────────────────────────
+    server.tool("pose_citizen", "Pose a Citizen by setting CitizenAnimationHelper params (enables PlayAnimationsInEditorScene so the pose shows in-editor). Set holdType (None/Pistol/Rifle/Shotgun/HoldItem/Punch/Swing), moveStyle (Auto/Walk/Run), specialMove, sitting (bool), and/or duckLevel (0-1).", {
+        id: z.string().describe("GUID of the Citizen GameObject (must have a CitizenAnimationHelper)"),
+        holdType: z.string().optional().describe("Hold pose, e.g. None, Pistol, Rifle, Shotgun, HoldItem"),
+        moveStyle: z.string().optional().describe("Movement style, e.g. Auto, Walk, Run"),
+        specialMove: z.string().optional().describe("Special move style, e.g. None, LedgeGrab, Roll"),
+        sitting: z.boolean().optional().describe("Sit the character (IsSitting)"),
+        duckLevel: z.number().min(0).max(1).optional().describe("Crouch amount, 0-1"),
+    }, async (params) => {
+        const res = await bridge.send("pose_citizen", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── equip_model ────────────────────────────────────────────────────
+    server.tool("equip_model", "Attach a prop model (weapon, hat, tool) to a Citizen's bone or attachment point — the prop is parented so it follows that point. Tries the point as an attachment (hand_R, hand_L, eyes, hat) then as a bone. Great for arming NPCs or adding accessories.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        model: z.string().describe("Prop model path, e.g. 'models/dev/box.vmdl'"),
+        point: z
+            .string()
+            .optional()
+            .describe("Attachment or bone name (default 'hand_R'; try hand_L, eyes, hat, head)"),
+        offset: Vector3Schema.optional().describe("Local position offset from the point"),
+        rotation: RotationSchema.optional().describe("Local rotation offset"),
+        tint: ColorSchema.optional().describe("Prop tint colour"),
+        name: z.string().optional().describe("Name for the prop GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("equip_model", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_look_at ────────────────────────────────────────────────────
+    server.tool("set_look_at", "Aim a Citizen's gaze. Pass target {x,y,z} (spawns a LookTarget) or targetId (existing GameObject) and the head/eyes track it. Pass enabled:false to turn gaze tracking off. Tune eyesWeight/headWeight/bodyWeight (0-1).", {
+        id: z.string().describe("GUID of the Citizen (must have a CitizenAnimationHelper)"),
+        target: Vector3Schema.optional().describe("World point to look at"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to look at (overrides target)"),
+        enabled: z.boolean().optional().describe("false to disable gaze tracking"),
+        eyesWeight: z.number().min(0).max(1).optional().describe("Eye look weight 0-1"),
+        headWeight: z.number().min(0).max(1).optional().describe("Head turn weight 0-1"),
+        bodyWeight: z.number().min(0).max(1).optional().describe("Body turn weight 0-1"),
+    }, async (params) => {
+        const res = await bridge.send("set_look_at", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_ragdoll ────────────────────────────────────────────────────
+    server.tool("add_ragdoll", "Add ModelPhysics to a skinned model so it becomes a ragdoll (physics-driven bones). NOTE: the ragdoll only flops in PLAY mode — it won't move in the static editor view, so this one is verified structurally, not by screenshot.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        motionEnabled: z
+            .boolean()
+            .optional()
+            .describe("Whether physics bodies start with motion enabled"),
+    }, async (params) => {
+        const res = await bridge.send("add_ragdoll", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_expression ─────────────────────────────────────────────────
+    server.tool("set_expression", "Set a facial morph (blendshape) on a skinned model — e.g. smile, frown, blink. Call with NO morph to list the model's available morph names (returned as availableMorphs). weight is typically 0-1.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        morph: z
+            .string()
+            .optional()
+            .describe("Morph/blendshape name (omit to list available morphs)"),
+        weight: z.number().optional().describe("Morph weight, typically 0-1 (default 1)"),
+    }, async (params) => {
+        const res = await bridge.send("set_expression", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=characters.js.map

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