sbox-mcp-server 1.20.0 → 2.0.0

package/dist/index.js

@@ -59,6 +59,10 @@ import { registerInteractionPackTools } from "./tools/interactionpack.js";
 import { registerLootEconomyTools } from "./tools/looteconomy.js";
 import { registerUiFeedbackTools } from "./tools/uifeedback.js";
 import { registerCinematicsTools } from "./tools/cinematics.js";
+import { registerAuditTools } from "./tools/audit.js";
+import { registerBatchTools } from "./tools/batch.js";
+import { registerWorkflowTools } from "./tools/workflow.js";
+import { registerVehicleTools } from "./tools/vehicles.js";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -78,68 +82,68 @@ if (args.includes("--version") || args.includes("-v")) {
     process.exit(0);
 }
 if (args.includes("--help") || args.includes("-h")) {
-    console.log(`sbox-mcp ${getVersion()} — MCP Server for s&box game engine
-
-USAGE
-  node dist/index.js              Start the MCP server (stdio transport)
-  node dist/index.js --help       Show this help
-  node dist/index.js --version    Show version
-
-ENVIRONMENT VARIABLES
-  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 (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
-  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 (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_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
-  Physics:     add_physics, add_collider, add_joint, raycast
-  UI:          create_razor_ui, add_screen_panel, add_world_panel
-  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, 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
-  Forest:      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
-
-  ── 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)
+    console.log(`sbox-mcp ${getVersion()} — MCP Server for s&box game engine
+
+USAGE
+  node dist/index.js              Start the MCP server (stdio transport)
+  node dist/index.js --help       Show this help
+  node dist/index.js --version    Show version
+
+ENVIRONMENT VARIABLES
+  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 (245 total / 237 editor handlers · v2: the native editor MCP server at http://127.0.0.1:7269/mcp is the primary path — this stdio server is the full-surface fallback; --lifeline exposes just the editor-down diagnostics)
+  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_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 (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_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
+  Physics:     add_physics, add_collider, add_joint, raycast
+  UI:          create_razor_ui, add_screen_panel, add_world_panel
+  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, 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
+  Forest:      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
+
+  ── 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);
 }
@@ -152,30 +156,47 @@ const server = new McpServer({
     // 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.
-
-6. First session with the bridge (or when the user asks "how do I start?" / "what can this do?")? Offer to run setup — invoke the \`sbox-setup\` skill: it verifies the connection, detects the user's installed libraries (\`list_libraries\`), recommends a first move, and points to help + feedback.
-
-If you're running inside Claude Code, install the companion plugin for the full workflow:
-    /plugin marketplace add LouSputthole/Sbox-Claude
-    /plugin install sbox-claude
-
+    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.
+
+6. First session with the bridge (or when the user asks "how do I start?" / "what can this do?")? Offer to run setup — invoke the \`sbox-setup\` skill: it verifies the connection, detects the user's installed libraries (\`list_libraries\`), recommends a first move, and points to help + feedback.
+
+If you're running inside Claude Code, install the companion plugin for the full workflow:
+    /plugin marketplace add LouSputthole/Sbox-Claude
+    /plugin install sbox-claude
+
 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 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));
+// ── Lifeline mode (v2 migration) ───────────────────────────────────
+// With the native editor MCP server carrying the full tool surface, this stdio
+// server's long-term job is "editor-down diagnostics": the native server dies
+// with the editor; these tools read the log / docs directly and don't. --lifeline
+// registers ONLY that set by filtering server.tool() — everything else is a no-op.
+const LIFELINE_TOOLS = new Set([
+    "read_log", "get_compile_errors", "search_docs", "get_doc_page",
+    "list_doc_categories", "run_self_test", "get_bridge_status",
+]);
+if (args.includes("--lifeline")) {
+    const realTool = server.tool.bind(server);
+    server.tool = (...toolArgs) => {
+        if (LIFELINE_TOOLS.has(toolArgs[0]))
+            return realTool(...toolArgs);
+        return undefined;
+    };
+}
 // Register all tools
 registerProjectTools(server, bridge);
 registerScriptTools(server, bridge);
@@ -221,6 +242,10 @@ registerInteractionPackTools(server, bridge);
 registerLootEconomyTools(server, bridge);
 registerUiFeedbackTools(server, bridge);
 registerCinematicsTools(server, bridge);
+registerAuditTools(server, bridge);
+registerBatchTools(server, bridge);
+registerWorkflowTools(server, bridge);
+registerVehicleTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/assets.js

@@ -28,19 +28,19 @@ export function registerAssetTools(server, bridge) {
         };
     });
     // ── list_asset_library ───────────────────────────────────────────
-    server.tool("list_asset_library", "Browse the s&box community asset library. Search for packages by name, description, or type to find models, maps, and tools to install", {
+    server.tool("list_asset_library", "List assets visible to the editor's AssetSystem — project assets plus mounted engine/installed-package content (it does NOT query the remote sbox.game library; use install_asset to pull in new packages). Returns { count, assets:[{ name, path, relativePath, assetType }] } — pass a returned path to spawn_model, assign_model, or get_asset_info", {
         query: z
             .string()
             .optional()
-            .describe("Search term for packages"),
+            .describe("Search term, case-insensitive substring match against asset NAMES"),
         type: z
             .string()
             .optional()
-            .describe("Package type filter (e.g. 'model', 'map', 'library')"),
+            .describe("Asset type filter, substring-matched against the asset's type (e.g. 'model', 'material', 'sound')"),
         maxResults: z
             .number()
             .optional()
-            .describe("Maximum results. Defaults to 25"),
+            .describe("Maximum results. Defaults to 200"),
     }, async (params) => {
         const res = await bridge.send("list_asset_library", params);
         if (!res.success) {
@@ -51,7 +51,7 @@ export function registerAssetTools(server, bridge) {
         };
     });
     // ── install_asset ────────────────────────────────────────────────
-    server.tool("install_asset", "Install a community asset package into the project by its ident (e.g. 'facepunch.flatgrass'). Adds it as a project dependency", {
+    server.tool("install_asset", "Install a community asset package into the project by its ident (e.g. 'facepunch.flatgrass'). Adds it as a project dependency. Returns { installed, ident, name, path, relativePath, restartRecommended, note } — pass the returned path to spawn_model / assign_model. CAUTION: if the package is a code LIBRARY (adds a PackageReference), trigger_hotload will NOT surface its types — call restart_editor so the new package compiles into the project", {
         ident: z
             .string()
             .describe("Package identifier (e.g. 'facepunch.flatgrass', 'author.package_name')"),

package/dist/tools/audio.js

@@ -5,15 +5,15 @@ import { z } from "zod";
  */
 export function registerAudioTools(server, bridge) {
     // ── list_sounds ──────────────────────────────────────────────────
-    server.tool("list_sounds", "List available sound assets in the project and installed packages. Filter by name", {
+    server.tool("list_sounds", "List the project's .sound event files (recursive scan of the project root for *.sound). Returns { count, sounds } — project-relative paths ready to pass to assign_sound, play_sound_preview, or add_lipsync. NOTE: the current handler returns every match (filter/maxResults are not applied) and only covers .sound files in the project tree — use search_assets type='sound' for other sound assets", {
         filter: z
             .string()
             .optional()
-            .describe("Search filter for sound name or path"),
+            .describe("Search filter for sound name or path (currently not applied by the handler — all .sound files are returned)"),
         maxResults: z
             .number()
             .optional()
-            .describe("Maximum results. Defaults to 50"),
+            .describe("Maximum results. Defaults to 50 (currently not applied by the handler)"),
     }, async (params) => {
         const res = await bridge.send("list_sounds", params);
         if (!res.success) {
@@ -24,13 +24,14 @@ export function registerAudioTools(server, bridge) {
         };
     });
     // ── create_sound_event ───────────────────────────────────────────
-    server.tool("create_sound_event", "Create a new sound event file (.sound) with volume, pitch, distance falloff, and looping settings", {
+    server.tool("create_sound_event", "Create a .sound event file wired to a source .vsnd. Returns { created, path, soundReferenced, note } (path is project-relative); errors if the file already exists. Preview the result with play_sound_preview or attach it to an object with assign_sound. Note: .sound events have no loop flag — looping lives on the SoundPointComponent that plays the event", {
         path: z
             .string()
-            .describe("Path for the sound event file (e.g. 'sounds/footstep.sound')"),
+            .describe("Project-relative path for the sound event file (e.g. 'sounds/footstep.sound'; '.sound' appended if missing)"),
         sound: z
             .string()
-            .describe("Path to the source sound asset (.vsnd)"),
+            .optional()
+            .describe("Path to the source sound asset (.vsnd) the event plays. Omit to create an empty event and wire it later"),
         volume: z
             .number()
             .optional()
@@ -39,18 +40,10 @@ export function registerAudioTools(server, bridge) {
             .number()
             .optional()
             .describe("Pitch multiplier. Defaults to 1.0"),
-        minDistance: z
-            .number()
-            .optional()
-            .describe("Minimum distance before falloff starts (units). Defaults to 100"),
         maxDistance: z
             .number()
             .optional()
-            .describe("Maximum audible distance (units). Defaults to 2000"),
-        loop: z
-            .boolean()
-            .optional()
-            .describe("Whether the sound should loop. Defaults to false"),
+            .describe("Maximum audible distance in units (sets Distance + enables DistanceAttenuation). Omit for the engine default"),
     }, async (params) => {
         const res = await bridge.send("create_sound_event", params);
         if (!res.success) {
@@ -61,7 +54,7 @@ export function registerAudioTools(server, bridge) {
         };
     });
     // ── assign_sound ─────────────────────────────────────────────────
-    server.tool("assign_sound", "Attach a sound event to a GameObject via SoundPointComponent. Creates the component if needed", {
+    server.tool("assign_sound", "Attach a sound event to a GameObject via SoundPointComponent. Creates the component if needed. Returns { assigned, id, sound, soundLoaded, playOnStart } — soundLoaded:false means the .sound path did not resolve (the component is still added with no event; verify the path with list_sounds)", {
         id: z.string().describe("GUID of the GameObject"),
         sound: z
             .string()
@@ -69,7 +62,7 @@ export function registerAudioTools(server, bridge) {
         playOnStart: z
             .boolean()
             .optional()
-            .describe("Whether the sound plays automatically when the game starts"),
+            .describe("If true, the handler calls StartSound() immediately, so the sound starts playing right away (audible in the editor)"),
     }, async (params) => {
         const res = await bridge.send("assign_sound", params);
         if (!res.success) {
@@ -80,14 +73,14 @@ export function registerAudioTools(server, bridge) {
         };
     });
     // ── play_sound_preview ───────────────────────────────────────────
-    server.tool("play_sound_preview", "Play a sound in the editor for testing without entering play mode", {
+    server.tool("play_sound_preview", "Play a sound in the editor for testing without entering play mode. Returns { playing, sound, volume }. Fire-and-forget via Sound.Play — there is no stop control, and the volume param is echoed back but not currently applied to playback", {
         sound: z
             .string()
             .describe("Sound event or asset path to preview"),
         volume: z
             .number()
             .optional()
-            .describe("Preview volume (0-1). Defaults to 1.0"),
+            .describe("Preview volume (0-1). Defaults to 1.0 (echoed in the response but not currently applied to playback)"),
     }, async (params) => {
         const res = await bridge.send("play_sound_preview", params);
         if (!res.success) {

package/dist/tools/audit.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Project audit & batch operation tools (v2 relaunch wave 1, Batch 51):
+ * find_broken_references, batch_set_property, describe_project.
+ */
+export declare function registerAuditTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=audit.d.ts.map

package/dist/tools/audit.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/**
+ * Project audit & batch operation tools (v2 relaunch wave 1, Batch 51):
+ * find_broken_references, batch_set_property, describe_project.
+ */
+export function registerAuditTools(server, bridge) {
+    // ── find_broken_references ───────────────────────────────────────
+    server.tool("find_broken_references", "Scan the project for broken references, two layers in one call: (1) every GameObject in the open scene — renderers with no Model (missing_model), component properties pointing at DESTROYED GameObjects/Components (dead_gameobject_ref / dead_component_ref), null component entries whose type no longer exists (missing_component); (2) every .scene/.prefab FILE — prefab references to deleted/renamed files (missing_prefab_file). Returns { total, showing, truncated, objectsScanned, filesScanned, issues } — each issue has { id, name, component, kind, detail } (file-level issues carry the file path in name). Fix missing models with assign_model, dead refs with set_property/set_component_reference, missing prefab files by fixing the path or recreating via create_prefab. Read-only; safe any time. Results cap at `limit` (default 100, max 500)", {
+        limit: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max issues to return (default 100, max 500). total still counts everything"),
+        scanFiles: z
+            .boolean()
+            .optional()
+            .describe("Include the .scene/.prefab file scan for missing prefab references. Default true"),
+    }, async (params) => {
+        const res = await bridge.send("find_broken_references", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── batch_set_property ───────────────────────────────────────────
+    server.tool("batch_set_property", "Set ONE component property to the same value across MANY GameObjects in a single call (e.g. Tint on 40 props, Enabled on every light). Pass dryRun:true first to validate — it reports each object's current value and what would change WITHOUT applying anything. Returns { total, succeeded, failed, dryRun, results } with per-object ok/error and the previous value on success. Get ids from find_objects or get_selected_objects. Scene-mutating: refused during play mode. Value coercion matches set_property (numbers, bools, enums, 'x,y,z' vectors, colors, asset paths)", {
+        ids: z
+            .array(z.string())
+            .describe("GUIDs of the GameObjects to modify (from find_objects, get_scene_hierarchy, or get_selected_objects)"),
+        component: z
+            .string()
+            .describe("Component type name present on each object, e.g. 'ModelRenderer', 'PointLight'"),
+        property: z
+            .string()
+            .describe("Property name to set, e.g. 'Tint', 'Enabled', 'LightColor' (see get_all_properties)"),
+        value: z
+            .any()
+            .describe("New value — number, bool, string, enum name, 'x,y,z' vector, color, or asset path"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("true = validate and report current values without changing anything. Default false"),
+    }, async (params) => {
+        const res = await bridge.send("batch_set_property", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── describe_project ─────────────────────────────────────────────
+    server.tool("describe_project", "One-call project orientation: identity (name/ident/org/type), the open scene with object count, scene and prefab file lists (capped at 50 each, Libraries/.sbox excluded), code footprint (.cs/.razor counts), custom Component types (up to 100, engine types excluded), and installed libraries. Returns a structured summary — orient here first, then get_scene_hierarchy for the scene, describe_type for components, find_broken_references for project health. Read-only", {}, async (params) => {
+        const res = await bridge.send("describe_project", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=audit.js.map

package/dist/tools/batch.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Batch operation tools (Batch 52): batch_delete, batch_add_component,
+ * batch_reparent. All follow the dryRun convention from batch_set_property.
+ */
+export declare function registerBatchTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=batch.d.ts.map

package/dist/tools/batch.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/**
+ * Batch operation tools (Batch 52): batch_delete, batch_add_component,
+ * batch_reparent. All follow the dryRun convention from batch_set_property.
+ */
+export function registerBatchTools(server, bridge) {
+    // ── batch_delete ─────────────────────────────────────────────────
+    server.tool("batch_delete", "Delete MANY GameObjects (and their entire subtrees) in one call. ALWAYS pass dryRun:true first — it reports each object's name and child count WITHOUT deleting, so you can confirm the target list. Returns { total, succeeded, failed, dryRun, results } with per-object ok/error. Destructive and NOT undoable — get ids from find_objects or get_selected_objects and verify the dry-run before applying. Scene-mutating: refused during play mode", {
+        ids: z
+            .array(z.string())
+            .describe("GUIDs of the GameObjects to delete (subtrees included)"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("true = report names/child counts without deleting anything. Default false — but run a dry pass first"),
+    }, async (params) => {
+        const res = await bridge.send("batch_delete", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── batch_add_component ──────────────────────────────────────────
+    server.tool("batch_add_component", "Add one component type to MANY GameObjects in one call (e.g. BoxCollider on every crate). Skips objects that already have the component unless skipExisting:false. dryRun:true validates the type and reports per-object alreadyHas WITHOUT adding. Returns { total, succeeded, failed, skipped, dryRun, results }. Follow with batch_set_property to configure the new components. Scene-mutating: refused during play mode", {
+        ids: z
+            .array(z.string())
+            .describe("GUIDs of the target GameObjects (from find_objects or get_selected_objects)"),
+        component: z
+            .string()
+            .describe("Component type name to add, e.g. 'BoxCollider', 'PointLight' (search with list_available_components)"),
+        skipExisting: z
+            .boolean()
+            .optional()
+            .describe("Skip objects that already have this component type. Default true"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("true = validate and report without adding anything. Default false"),
+    }, async (params) => {
+        const res = await bridge.send("batch_add_component", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── batch_reparent ───────────────────────────────────────────────
+    server.tool("batch_reparent", "Move MANY GameObjects under a new parent (or to the scene root) in one call — organize scattered props into a folder object, or regroup a level section. dryRun:true reports each object's current parent and destination WITHOUT moving. Returns { total, succeeded, failed, dryRun, keepWorldPosition, results }. Errors if parent is among ids (no cycles). Scene-mutating: refused during play mode", {
+        ids: z
+            .array(z.string())
+            .describe("GUIDs of the GameObjects to move"),
+        parent: z
+            .string()
+            .optional()
+            .describe("GUID of the new parent GameObject. Omit (or empty) to move to the scene root"),
+        keepWorldPosition: z
+            .boolean()
+            .optional()
+            .describe("Preserve each object's world position while reparenting. Default true"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("true = report current parents and the destination without moving anything. Default false"),
+    }, async (params) => {
+        const res = await bridge.send("batch_reparent", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=batch.js.map

package/dist/tools/characters.js

@@ -56,7 +56,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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). Returns { created, hasAnimator, gameObject:{ id, name, position, components, ... } } — pass gameObject.id to the follow-ups: dress_citizen, pose_citizen, set_expression, equip_model.", {
         name: z.string().optional().describe("GameObject name (default 'Citizen')"),
         model: z
             .string()
@@ -110,7 +110,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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).", {
+    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). Returns { set, bodygroup } on success (errors if the object has no SkinnedModelRenderer or neither value nor choice is given); take_screenshot to verify the visual change.", {
         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"),
@@ -125,7 +125,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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).", {
+    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). Returns { posed, changed:[...], gameObject } — changed lists which helper params were applied; take_screenshot to verify the pose.", {
         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"),
@@ -184,7 +184,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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. Returns { ragdoll, note, gameObject } — check gameObject.components for ModelPhysics, then verify at runtime with start_play + capture_view.", {
         id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
         motionEnabled: z
             .boolean()
@@ -200,7 +200,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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. Returns { set, morph, weight, availableMorphs } — availableMorphs is included in every response, so a wrong name can be corrected without an extra listing call.", {
         id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
         morph: z
             .string()
@@ -244,7 +244,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── set_animgraph_param ────────────────────────────────────────────
-    server.tool("set_animgraph_param", "Set an AnimationGraph parameter on a GameObject's SkinnedModelRenderer (calls Set). This drives Citizen/animgraph motion — e.g. 'move_x'/'move_y' (float), 'b_grounded'/'b_ducked' (bool), or a Vector3. Pose previews in-editor when PlayAnimationsInEditorScene is on; screenshot to verify. Param names are defined by the model's animation graph.", {
+    server.tool("set_animgraph_param", "Set an AnimationGraph parameter on a GameObject's SkinnedModelRenderer (calls Set). This drives Citizen/animgraph motion — e.g. 'move_x'/'move_y' (float), 'b_grounded'/'b_ducked' (bool), or a Vector3. Pose previews in-editor when PlayAnimationsInEditorScene is on; screenshot to verify. Param names are defined by the model's animation graph — use list_animations to check whether the model is animgraph-driven. Returns { set, param, kind, note } — kind is the type actually applied (float/int/bool/vector).", {
         id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
         param: z.string().describe("Animgraph parameter name, e.g. 'move_x', 'b_grounded'"),
         value: z

package/dist/tools/cinematics.js

@@ -16,7 +16,7 @@ import { z } from "zod";
  */
 export function registerCinematicsTools(server, bridge) {
     // ── create_cutscene_director ──────────────────────────────────────
-    server.tool("create_cutscene_director", "Generate a hand-authored cutscene player component that needs NO .movie asset — the zero-asset alternative to the MovieMaker family (add_movie_player/play_movie, which play keyframed .movie clips authored in the editor's Movie Maker dock). You author the shots directly in the inspector as parallel lists: ShotPositions (Vector3), ShotAngles (pitch/yaw/roll — Angles, not raw quaternions), ShotHoldSeconds, ShotBlendSeconds, and an optional per-shot ShotLookAt GameObject (aim at a target instead of using ShotAngles). At runtime it takes over the main camera (Scene.Camera) in OnPreRender ONLY while playing — smoothstep-eased Vector3.Lerp + Rotation.Slerp between shots — captures the camera's prior transform and restores it exactly when finished (same un-apply discipline as create_camera_shake). Play from any game code via the static <Name>.Play() (first director) or <Name>.Play(\"name\") (matches CutsceneName); subscribe the static <Name>.OnCutsceneFinished, or gate game logic on the static <Name>.IsCutscenePlaying. LockInput freezes player input each frame via Input.ClearActions() while still reading the SkipAction press first so the cutscene stays skippable. Optional letterbox generates a razor_lint-safe black-bars overlay panel (host under a ScreenPanel) shown while IsCutscenePlaying. LOCAL-only (each client renders its own view) — trigger inside an [Rpc.Broadcast] for all clients. Attach to ANY GameObject; it drives the camera itself and does not need to sit on the camera. Compile with trigger_hotload afterward.", {
+    server.tool("create_cutscene_director", "Generate a hand-authored cutscene player component that needs NO .movie asset — the zero-asset alternative to the MovieMaker family (add_movie_player/play_movie, which play keyframed .movie clips authored in the editor's Movie Maker dock). You author the shots directly in the inspector as parallel lists: ShotPositions (Vector3), ShotAngles (pitch/yaw/roll — Angles, not raw quaternions), ShotHoldSeconds, ShotBlendSeconds, and an optional per-shot ShotLookAt GameObject (aim at a target instead of using ShotAngles). At runtime it takes over the main camera (Scene.Camera) in OnPreRender ONLY while playing — smoothstep-eased Vector3.Lerp + Rotation.Slerp between shots — captures the camera's prior transform and restores it exactly when finished (same un-apply discipline as create_camera_shake). Play from any game code via the static <Name>.Play() (first director) or <Name>.Play(\"name\") (matches CutsceneName); subscribe the static <Name>.OnCutsceneFinished, or gate game logic on the static <Name>.IsCutscenePlaying. LockInput freezes player input each frame via Input.ClearActions() while still reading the SkipAction press first so the cutscene stays skippable. Optional letterbox generates a razor_lint-safe black-bars overlay panel (host under a ScreenPanel) shown while IsCutscenePlaying. LOCAL-only (each client renders its own view) — trigger inside an [Rpc.Broadcast] for all clients. Attach to ANY GameObject; it drives the camera itself and does not need to sit on the camera. Returns { created, path, className, skipAction, lockInput, letterbox, nextSteps } — path is the generated .cs (letterbox lists the overlay files when enabled). Follow with trigger_hotload, then get_compile_errors, then attach via add_component_with_properties (component=className).", {
         name: z
             .string()
             .optional()
@@ -45,7 +45,7 @@ export function registerCinematicsTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── create_dialogue_system ────────────────────────────────────────
-    server.tool("create_dialogue_system", "Generate an NPC/story dialogue system — a sealed state+data Component paired with a razor_lint-safe Razor HUD panel. Lines are authored in the inspector as a List<string> using the 'Speaker: text' convention (the part before the first colon is the speaker). The generated HUD panel binds to <Name>.Current automatically (no wiring) and renders the current line with a TimeSince-driven typewriter reveal at CharsPerSecond, folding the visible substring into BuildHash so it re-renders as characters appear. Press the AdvanceAction once to snap the whole line into view instantly, again to move to the next line; dismissing the last line ends the conversation. Start from any game code via the static <Name>.StartDialogue(string[] lines) or set Lines and call the instance Begin(). Static events for hooks: OnLineShown(index, speaker) — pair with add_lipsync to drive facial morphs / audio per line — and OnDialogueFinished when the conversation ends. Pairs with create_interactable to trigger dialogue on use. LOCAL-only (per-client HUD) — call StartDialogue inside an [Rpc.Broadcast] if every client should see it. Attach the panel under a ScreenPanel (add_screen_panel) so the HUD renders. Compile with trigger_hotload afterward.", {
+    server.tool("create_dialogue_system", "Generate an NPC/story dialogue system — a sealed state+data Component paired with a razor_lint-safe Razor HUD panel. Lines are authored in the inspector as a List<string> using the 'Speaker: text' convention (the part before the first colon is the speaker). The generated HUD panel binds to <Name>.Current automatically (no wiring) and renders the current line with a TimeSince-driven typewriter reveal at CharsPerSecond, folding the visible substring into BuildHash so it re-renders as characters appear. Press the AdvanceAction once to snap the whole line into view instantly, again to move to the next line; dismissing the last line ends the conversation. Start from any game code via the static <Name>.StartDialogue(string[] lines) or set Lines and call the instance Begin(). Static events for hooks: OnLineShown(index, speaker) — pair with add_lipsync to drive facial morphs / audio per line — and OnDialogueFinished when the conversation ends. Pairs with create_interactable to trigger dialogue on use. LOCAL-only (per-client HUD) — call StartDialogue inside an [Rpc.Broadcast] if every client should see it. Attach the panel under a ScreenPanel (add_screen_panel) so the HUD renders. Returns { created, path, className, charsPerSecond, advanceAction, panel, nextSteps } — panel lists the generated '<Name>Panel' HUD files. Follow with trigger_hotload, then get_compile_errors, then attach both components via add_component_with_properties.", {
         name: z
             .string()
             .optional()