sbox-mcp-server 1.3.1 → 1.4.0

package/README.md

@@ -1,113 +1,119 @@
-# 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 — 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.
+
+## 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 (131 — v1.4.0)
+
+| 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 runtime rendering unverified through the bridge; use a legacy `.vpcf` for visible particles |
+
+## 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)

package/dist/index.d.ts

@@ -3,11 +3,11 @@
  * Entry point for the sbox-mcp MCP server.
  *
  * Creates an MCP server (stdio transport), connects to the s&box Bridge Addon
- * via WebSocket, and registers all tool handlers. Each tool domain (project,
+ * via file-based IPC (a shared temp dir), and registers all tool handlers. Each tool domain (project,
  * scripts, console, scenes, etc.) has its own register function in src/tools/.
  *
  * CLI flags: --version / -v, --help / -h
- * Environment: SBOX_BRIDGE_HOST, SBOX_BRIDGE_PORT
+ * Environment: SBOX_BRIDGE_IPC_DIR (the real knob); SBOX_BRIDGE_HOST / SBOX_BRIDGE_PORT (legacy, cosmetic)
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,11 +3,11 @@
  * Entry point for the sbox-mcp MCP server.
  *
  * Creates an MCP server (stdio transport), connects to the s&box Bridge Addon
- * via WebSocket, and registers all tool handlers. Each tool domain (project,
+ * via file-based IPC (a shared temp dir), and registers all tool handlers. Each tool domain (project,
  * scripts, console, scenes, etc.) has its own register function in src/tools/.
  *
  * CLI flags: --version / -v, --help / -h
- * Environment: SBOX_BRIDGE_HOST, SBOX_BRIDGE_PORT
+ * Environment: SBOX_BRIDGE_IPC_DIR (the real knob); SBOX_BRIDGE_HOST / SBOX_BRIDGE_PORT (legacy, cosmetic)
  */
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
@@ -33,6 +33,10 @@ 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";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -60,13 +64,15 @@ USAGE
   node dist/index.js --version    Show version
 
 ENVIRONMENT VARIABLES
-  SBOX_BRIDGE_HOST    Bridge WebSocket host (default: 127.0.0.1)
-  SBOX_BRIDGE_PORT    Bridge WebSocket port (default: 29015)
+  SBOX_BRIDGE_IPC_DIR   IPC directory — MUST match the s&box addon's dir.
+                        Default: <os tmpdir>/sbox-bridge-ipc
+  SBOX_BRIDGE_HOST      Legacy/cosmetic — shown in get_bridge_status only
+  SBOX_BRIDGE_PORT      Legacy/cosmetic — shown in get_bridge_status only
 
 CONNECT TO CLAUDE CODE
   claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
 
-TOOLS (99 working — was 109; 10 unimplementable tools removed in v1.3.0)
+TOOLS (131 — +32 in v1.4.0: visual, characters, scene, environment, utilities)
   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
@@ -93,6 +99,14 @@ 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
 `);
     process.exit(0);
 }
@@ -125,7 +139,7 @@ If you're running inside Claude Code, install the companion plugin for the full
 
 The plugin ships an \`sbox-build-feature\` skill that codifies the workflow above plus a list of common s&box gotchas (MathF not available in sandbox, Cloud assets ephemeral, head bone case-sensitive, CitizenAnimationHelper.IkRightHand works at runtime, etc.). Read its SKILL.md before starting non-trivial features.`,
 });
-// Bridge client connects to s&box editor via WebSocket
+// Bridge client talks to the s&box editor via file IPC. host/port are cosmetic.
 const bridge = new BridgeClient(process.env.SBOX_BRIDGE_HOST ?? "127.0.0.1", parseInt(process.env.SBOX_BRIDGE_PORT ?? "29015", 10));
 // Register all tools
 registerProjectTools(server, bridge);
@@ -146,6 +160,10 @@ registerNetworkingTools(server, bridge);
 registerPublishingTools(server, bridge);
 registerWorldTools(server, bridge);
 registerDiscoveryTools(server, bridge);
+registerVisualTools(server, bridge);
+registerCharacterTools(server, bridge);
+registerLevelTools(server, bridge);
+registerObjectTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();
@@ -159,6 +177,7 @@ async function main() {
     console.error("  ║  https://sboxskins.gg                            ║");
     console.error("  ╚═══════════════════════════════════════════════════╝");
     console.error("");
+    console.error(`[sbox-mcp] IPC directory: ${bridge.getIpcDir()}`);
     // Attempt initial connection to s&box (non-fatal if it fails)
     try {
         await bridge.connect();

package/dist/tools/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/leveltools.d.ts

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