sbox-mcp-server 1.7.0 → 1.9.0

package/README.md

@@ -1,10 +1,10 @@
 # sbox-mcp-server
 
-MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **150+ tools** 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.
+MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **170+ tools** for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, navmesh & spatial queries, particles, animation, NPC brains, playable-game scaffolds, networking & scene inspection/lint, save & services queries, 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.
+If you use Claude Code, the easiest install is the companion plugin. It registers this MCP server automatically, ships the workflow + recipe skills (`sbox-build-feature`, `sbox-api`, `sbox-cookbook`, `sbox-scaffold-game`, `sbox-setup`), and includes the `sbox-game-dev` specialist agent.
 
 ```
 /plugin marketplace add LouSputthole/Sbox-Claude
@@ -54,7 +54,7 @@ Claude Code → (stdio) → sbox-mcp-server → (file IPC) → bridge addon →
 
 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 (v1.5.2)
+## Tools (v1.9.0)
 
 `get_bridge_status` reports the `handlerCount` — 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.
 
@@ -99,6 +99,7 @@ Communication uses file-based IPC through `%TEMP%/sbox-bridge-ipc/`. The MCP ser
 | **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` |
+| **Inspection & validation** *(v1.9.0)* | inspect_networked_object (per-object `Network.*` + every component's `[Sync]` fields/values), networking_lint (static scan for `[Sync]`/RPC footguns), scene_validate (no-camera / stray root Rigidbody / trigger-vs-trace), save_inspect (list/read/diff `FileSystem.Data` saves), services_query (`Sandbox.Services` stats + leaderboards), simulate_input (drive named input actions in play mode) |
 
 ## Working with Claude effectively
 
@@ -126,6 +127,6 @@ The companion plugin's `sbox-build-feature` skill encodes this workflow plus the
 
 ## License
 
-**GPL-3.0** — see [LICENSE](../LICENSE) for details.
+**AGPL-3.0-or-later** — see [LICENSE](../LICENSE) and [NOTICE](../NOTICE) for details. The code is open under AGPL; the "s&box Claude Bridge" / "sboxskins.gg" name and branding may not be reused to pass a fork off as the original.
 
 Copyright (c) 2026 [sboxskins.gg](https://sboxskins.gg)

package/dist/index.js

@@ -43,6 +43,7 @@ import { registerNavigationTools } from "./tools/navigation.js";
 import { registerSelfTestTools } from "./tools/selftest.js";
 import { registerGameplayTools } from "./tools/gameplay.js";
 import { registerNpcTools } from "./tools/npc.js";
+import { registerInspectionTools } from "./tools/inspection.js";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -189,6 +190,7 @@ registerNavigationTools(server, bridge);
 registerSelfTestTools(server, bridge);
 registerGameplayTools(server, bridge);
 registerNpcTools(server, bridge);
+registerInspectionTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/inspection.d.ts

@@ -0,0 +1,17 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Inspection & validation tools — the high-leverage gaps surfaced by mining 27 shipped
+ * s&box games. These let an assistant VERIFY the things that are otherwise invisible from
+ * a single editor instance: networking authority, save state, input-driven behavior, and
+ * scene/networking correctness.
+ *
+ *   inspect_networked_object — per-object Network.Owner/IsProxy/[Sync] values (vs session-only get_network_status)
+ *   networking_lint          — static scan for unguarded [Sync] mutators, money-as-[Sync], List-as-[Sync], etc.
+ *   scene_validate           — missing camera/controller, multiple root Rigidbodies, IsTrigger-vs-trace footguns
+ *   save_inspect             — list/read/diff FileSystem.Data save files (21 of 27 games persist; assistant was blind)
+ *   services_query           — Sandbox.Services Stats / leaderboard reads
+ *   simulate_input           — press/release a named action + AnalogMove/Look during play (drive movement/IPressable/weapons)
+ */
+export declare function registerInspectionTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=inspection.d.ts.map

package/dist/tools/inspection.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+/**
+ * Inspection & validation tools — the high-leverage gaps surfaced by mining 27 shipped
+ * s&box games. These let an assistant VERIFY the things that are otherwise invisible from
+ * a single editor instance: networking authority, save state, input-driven behavior, and
+ * scene/networking correctness.
+ *
+ *   inspect_networked_object — per-object Network.Owner/IsProxy/[Sync] values (vs session-only get_network_status)
+ *   networking_lint          — static scan for unguarded [Sync] mutators, money-as-[Sync], List-as-[Sync], etc.
+ *   scene_validate           — missing camera/controller, multiple root Rigidbodies, IsTrigger-vs-trace footguns
+ *   save_inspect             — list/read/diff FileSystem.Data save files (21 of 27 games persist; assistant was blind)
+ *   services_query           — Sandbox.Services Stats / leaderboard reads
+ *   simulate_input           — press/release a named action + AnalogMove/Look during play (drive movement/IPressable/weapons)
+ */
+export function registerInspectionTools(server, bridge) {
+    // ── inspect_networked_object ──────────────────────────────────────
+    server.tool("inspect_networked_object", "Inspect the live networking contract of a GameObject: Network.Owner/IsProxy/IsOwner/Active, OwnerTransfer + OrphanedMode, and every component's [Sync] property names, SyncFlags, and current values (host vs proxy). Unlike get_network_status (session-only), this is per-object — the way to verify a host-authoritative or ownership change actually replicated. Works in edit or play mode.", {
+        id: z.string().describe("GUID of the GameObject to inspect"),
+        allProps: z
+            .boolean()
+            .default(false)
+            .describe("Include all component properties, not just [Sync]-marked ones"),
+    }, async (params) => {
+        const res = await bridge.send("inspect_networked_object", params);
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── networking_lint ───────────────────────────────────────────────
+    server.tool("networking_lint", "Static-scan the project's C# for the highest-frequency networking/authority bugs: a mutator that writes a [Sync] field with no IsProxy/Networking.IsHost guard; money/health/score-shaped fields marked plain [Sync] (should be SyncFlags.FromHost); List<>/Dictionary<> marked [Sync] (should be NetList/NetDictionary); [Sync] fields typed Connection/GameObject (sync a Guid instead); [Rpc.Host] methods that mutate without re-checking Rpc.Caller; and component swaps / reflection writes missing Network.Refresh(). Returns findings with file:line + the suggested fix.", {
+        path: z
+            .string()
+            .optional()
+            .describe("Optional sub-path under the project (e.g. 'Code/Player') to scope the scan; omit for the whole project"),
+    }, async (params) => {
+        const res = await bridge.send("networking_lint", params);
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── scene_validate ────────────────────────────────────────────────
+    server.tool("scene_validate", "Validate the active scene for the silent setup footguns that break controllers/physics/cameras: no CameraComponent, no player controller, multiple root Rigidbodies, a Rigidbody with MotionEnabled=false fighting a kinematic root, IsTrigger colliders that Scene.Trace will ignore, child Rigidbodies breaking collider binding, and missing required child anchors. Returns each issue with the GameObject and the exact fix.", {}, async () => {
+        const res = await bridge.send("scene_validate", {});
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── save_inspect ──────────────────────────────────────────────────
+    server.tool("save_inspect", "Inspect the game's FileSystem.Data save files — the assistant is otherwise blind to persisted state. action='list' enumerates files under a folder (with size/mtime); action='read' dumps a save file's JSON; action='diff' compares two save files key-by-key. Use to verify a save actually wrote, debug a load/migration, or confirm a sanitize/clamp ran.", {
+        action: z.enum(["list", "read", "diff"]).default("list"),
+        path: z
+            .string()
+            .optional()
+            .describe("File or folder path under FileSystem.Data (e.g. 'lumber_corp2_progress' or '<folder>/steam_123.json')"),
+        pathB: z
+            .string()
+            .optional()
+            .describe("Second file path for action='diff'"),
+    }, async (params) => {
+        const res = await bridge.send("save_inspect", params);
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── services_query ────────────────────────────────────────────────
+    server.tool("services_query", "Read from Sandbox.Services — the cloud stats/leaderboard layer many games use as their real DB. action='stats' lists/reads the project's stat definitions and the local player's values; action='leaderboard' fetches a leaderboard board's top entries. Read-only. Use to verify a Stats.Increment/SetValue path or a leaderboard wired correctly.", {
+        action: z.enum(["stats", "leaderboard"]).default("stats"),
+        name: z
+            .string()
+            .optional()
+            .describe("Stat name (action='stats') or leaderboard/board name (action='leaderboard')"),
+        limit: z.number().int().default(10).describe("Max leaderboard entries to return"),
+    }, async (params) => {
+        const res = await bridge.send("services_query", params);
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── simulate_input ────────────────────────────────────────────────
+    server.tool("simulate_input", "Synthesize player input during PLAY mode so behavior can be verified without a human at the keyboard: press/hold/release a named input action (e.g. 'jump','attack1','use','reload') and/or set AnalogMove / AnalogLook for a duration. Drives movement, IPressable interactions, weapon fire/cooldown/reload, vehicle controls, and HUD advance-on-click. Requires play mode.", {
+        action: z
+            .string()
+            .optional()
+            .describe("Named input action to drive (must exist in Input.config), e.g. 'jump', 'attack1', 'use'"),
+        state: z
+            .enum(["press", "hold", "release"])
+            .default("press")
+            .describe("press = one tick (Pressed); hold = held for durationMs; release = clear a held action"),
+        analogMove: z
+            .object({ x: z.number(), y: z.number(), z: z.number().default(0) })
+            .optional()
+            .describe("AnalogMove vector to apply (forward/left)"),
+        analogLook: z
+            .object({ pitch: z.number(), yaw: z.number(), roll: z.number().default(0) })
+            .optional()
+            .describe("AnalogLook angles delta to apply"),
+        durationMs: z
+            .number()
+            .int()
+            .default(100)
+            .describe("How long to hold the action / apply the analog values"),
+    }, async (params) => {
+        const res = await bridge.send("simulate_input", params);
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=inspection.js.map

package/dist/tools/networking.js

@@ -114,7 +114,7 @@ export function registerNetworkingTools(server, bridge) {
         syncFlags: z
             .string()
             .optional()
-            .describe("Currently ignored — not yet implemented. The addon emits a plain [Sync] with no SyncFlags"),
+            .describe("Optional SyncFlags to emit as [Sync( SyncFlags.X )] — e.g. 'Interpolate' (smooth interpolation), 'Query', 'FromHost'. Omit for a plain [Sync]"),
         defaultValue: z
             .string()
             .optional()
@@ -129,7 +129,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── add_rpc_method ────────────────────────────────────────────────
-    server.tool("add_rpc_method", "Generate an EMPTY, no-argument RPC method stub in a C# script for you to fill in. The addon inserts the chosen RPC attribute ([Rpc.Broadcast] all clients, [Rpc.Host] host only, [Rpc.Owner] owner only) above a parameterless method with an empty body — it does NOT add parameters or generate body code", {
+    server.tool("add_rpc_method", "Generate an RPC method stub in a C# script. Inserts the chosen RPC attribute ([Rpc.Broadcast] all clients, [Rpc.Host] host only, [Rpc.Owner] owner only) above a method with an empty body. Pass methodParams to give it a parameter list (e.g. 'Vector3 pos, int damage'); the body is left as a TODO for you to fill in", {
         path: z
             .string()
             .describe("Relative path to the script file"),
@@ -141,7 +141,7 @@ export function registerNetworkingTools(server, bridge) {
         methodParams: z
             .string()
             .optional()
-            .describe("Currently ignored — not yet implemented. The addon emits a no-argument method; add parameters yourself afterward"),
+            .describe("Optional parameter list for the RPC method signature, e.g. 'Vector3 pos, int damage'. Omit for a parameterless method"),
         body: z
             .string()
             .optional()

package/dist/tools/playmode.js

@@ -82,7 +82,7 @@ export function registerPlayModeTools(server, bridge) {
         property: z.string().describe("Property name to set"),
         value: z
             .unknown()
-            .describe("New value as a string. Primitive: '5', 'true'. Color/Vector3: '1,0,0,1' / '0,0,200'. Enum: the member name. Asset ref (Model/Material/...): the asset path e.g. 'models/dev/box.vmdl'. GameObject/Component ref: the target GameObject's GUID. Empty/'null' clears the property"),
+            .describe("New value. Primitive: '5', 'true'. Color/Vector3: a comma string ('1,0,0,1' / '0,0,200'), an array ([0,0,200]), or an object ({r,g,b,a} / {x,y,z}). Enum: the member name. Asset ref (Model/Material/...): the asset path e.g. 'models/dev/box.vmdl'. GameObject/Component ref: the target GameObject's GUID. Empty/'null' clears the property"),
     }, async (params) => {
         const res = await bridge.send("set_property", params);
         if (!res.success) {

package/dist/tools/visuals.js

@@ -61,30 +61,30 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── set_fog ────────────────────────────────────────────────────────
-    server.tool("set_fog", "Add or update distance fog in the active scene. v1 supports gradient fog (atmospheric distance haze — great for mood/horror). Re-running on the same target updates it rather than duplicating.", {
+    server.tool("set_fog", "Add or update fog in the active scene. Types: 'gradient' (distance haze — great for mood/horror), 'cubemap' (sky-tinted distance fog), 'volumetric' (a localized fog volume). Re-running on the same target updates it rather than duplicating.", {
         type: z
-            .enum(["gradient"])
+            .enum(["gradient", "cubemap", "volumetric"])
             .optional()
-            .describe("Fog type (default gradient; cubemap/volumetric coming later)"),
+            .describe("Fog type (default gradient)"),
         name: z.string().optional().describe("GameObject name when creating a new fog object"),
         targetId: z
             .string()
             .optional()
-            .describe("GUID of an existing GameObject to host the fog (else a new 'Gradient Fog' object is created)"),
-        color: ColorSchema.optional().describe("Fog colour"),
-        startDistance: z
-            .number()
-            .optional()
-            .describe("Distance (units) where fog begins"),
-        endDistance: z
-            .number()
-            .optional()
-            .describe("Distance (units) where fog reaches full density"),
-        height: z.number().optional().describe("World height the fog settles around"),
-        falloff: z
-            .number()
+            .describe("GUID of an existing GameObject to host the fog (else a new fog object is created)"),
+        color: ColorSchema.optional().describe("Fog colour (gradient/volumetric Color, cubemap Tint)"),
+        startDistance: z.number().optional().describe("gradient/cubemap: distance (units) where fog begins"),
+        endDistance: z.number().optional().describe("gradient/cubemap: distance (units) where fog reaches full density"),
+        height: z.number().optional().describe("gradient: world height the fog settles around"),
+        falloff: z.number().optional().describe("Distance/density falloff exponent (higher = sharper onset)"),
+        blur: z.number().optional().describe("cubemap: sky blur amount"),
+        heightStart: z.number().optional().describe("cubemap: world height where height-fog starts"),
+        heightWidth: z.number().optional().describe("cubemap: height-fog band width"),
+        heightExponent: z.number().optional().describe("cubemap: height-fog falloff exponent"),
+        strength: z.number().optional().describe("volumetric: fog density/strength"),
+        size: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
             .optional()
-            .describe("Distance falloff exponent (higher = sharper onset)"),
+            .describe("volumetric: bounds size (units) centred on the object"),
     }, async (params) => {
         const res = await bridge.send("set_fog", params);
         if (!res.success) {

package/dist/tools/world.js

@@ -17,17 +17,21 @@ import { z } from "zod";
  */
 export function registerWorldTools(server, bridge) {
     // ── invoke_button ────────────────────────────────────────────────
-    server.tool("invoke_button", "Call a no-argument public method on a component. Matching is tried in order: (1) a [Button] attribute label, (2) the exact method NAME, (3) case-insensitive name with spaces stripped. So this calls ANY parameterless public method, not only [Button]-attributed ones (e.g. 'StartGame' works even without a [Button]). This is the general 'call a component method to drive game state' tool. LIMITATION: parameterless methods only — methods that take arguments are skipped. (list_component_buttons only lists [Button] methods, so a plain method may be invokable yet not appear there.)", {
+    server.tool("invoke_button", "Call a public method on a component. Matching is tried in order: (1) a [Button] attribute label, (2) the exact method NAME, (3) case-insensitive name with spaces stripped. Calls ANY public method, not only [Button]-attributed ones (e.g. 'StartGame'). Pass `args` to call methods that take parameters — the arg count must match and each value is coerced to the parameter type (primitives: string/number/bool work; complex types like Vector3 may not coerce). Omit args (or []) for parameterless methods. (list_component_buttons only lists [Button] methods, so a plain method may be invokable yet not appear there.)", {
         component: z
             .string()
             .describe("Component type name (e.g. 'MapBuilder', 'SasquatchedGame')"),
         button: z
             .string()
-            .describe("A [Button] label OR a public no-arg method name (e.g. 'Build Terrain', 'StartGame'); case- and space-insensitive"),
+            .describe("A [Button] label OR a public method name (e.g. 'Build Terrain', 'StartGame'); case- and space-insensitive"),
         id: z
             .string()
             .optional()
             .describe("Optional GameObject GUID — if omitted, finds first matching component in scene"),
+        args: z
+            .array(z.unknown())
+            .optional()
+            .describe("Arguments to pass (must match the method's parameter count); coerced to each parameter type"),
     }, async (params) => {
         const res = await bridge.send("invoke_button", params);
         if (!res.success)
@@ -49,6 +53,10 @@ export function registerWorldTools(server, bridge) {
         x: z.number().describe("World X coordinate"),
         y: z.number().describe("World Y coordinate"),
         id: z.string().optional().describe("Optional GameObject GUID for MapBuilder"),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the terrain component type name (default MapBuilder)"),
     }, async (params) => {
         const res = await bridge.send("raycast_terrain", params);
         if (!res.success)
@@ -63,6 +71,10 @@ export function registerWorldTools(server, bridge) {
         height: z.number().default(100).describe("Peak height (negative for depression)"),
         rebuild: z.boolean().default(true).describe("Rebuild terrain after adding (set false to batch)"),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("add_terrain_hill", params);
         if (!res.success)
@@ -76,6 +88,10 @@ export function registerWorldTools(server, bridge) {
         radius: z.number().default(300),
         rebuild: z.boolean().default(true),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("add_terrain_clearing", params);
         if (!res.success)
@@ -88,6 +104,10 @@ export function registerWorldTools(server, bridge) {
         to: z.object({ x: z.number(), y: z.number() }),
         rebuild: z.boolean().default(true),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("add_terrain_trail", params);
         if (!res.success)
@@ -101,6 +121,10 @@ export function registerWorldTools(server, bridge) {
             .default("all"),
         rebuild: z.boolean().default(true),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("clear_terrain_features", params);
         if (!res.success)
@@ -119,6 +143,10 @@ export function registerWorldTools(server, bridge) {
             .describe("Optional insert position (default: append to end)"),
         rebuild: z.boolean().default(true),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("add_cave_waypoint", params);
         if (!res.success)
@@ -128,6 +156,10 @@ export function registerWorldTools(server, bridge) {
     // ── clear_cave_path ──────────────────────────────────────────────
     server.tool("clear_cave_path", "Clear all waypoints in CaveBuilder and remove the cave from the scene.", {
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("clear_cave_path", params);
         if (!res.success)
@@ -149,6 +181,10 @@ export function registerWorldTools(server, bridge) {
             .default(false)
             .describe("Forest gen is slow (~1s); default false to batch"),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("add_forest_poi", params);
         if (!res.success)
@@ -161,6 +197,10 @@ export function registerWorldTools(server, bridge) {
         to_index: z.number().int(),
         rebuild: z.boolean().default(false),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("add_forest_trail", params);
         if (!res.success)
@@ -172,6 +212,10 @@ export function registerWorldTools(server, bridge) {
         seed: z.number().int().default(77),
         rebuild: z.boolean().default(true),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("set_forest_seed", params);
         if (!res.success)
@@ -181,6 +225,10 @@ export function registerWorldTools(server, bridge) {
     // ── clear_forest_pois ────────────────────────────────────────────
     server.tool("clear_forest_pois", "Wipe all POIs and trails in ForestGenerator and clear placed forest objects from the scene.", {
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("clear_forest_pois", params);
         if (!res.success)
@@ -195,6 +243,10 @@ export function registerWorldTools(server, bridge) {
         strength: z.number().default(50).describe("Height delta (units) for raise/lower; ignored for flatten/smooth"),
         mode: z.enum(["raise", "lower", "flatten", "smooth"]).default("raise"),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("sculpt_terrain", params);
         if (!res.success)
@@ -209,6 +261,10 @@ export function registerWorldTools(server, bridge) {
         density: z.number().default(1).describe("Density multiplier (0=clear, 1=normal, 2=dense)"),
         rebuild: z.boolean().default(false),
         id: z.string().optional(),
+        component: z
+            .string()
+            .optional()
+            .describe("Override the builder component type name — set this if your project's terrain/cave/forest component is named differently than the default (MapBuilder/CaveBuilder/ForestGenerator)"),
     }, async (params) => {
         const res = await bridge.send("paint_forest_density", params);
         if (!res.success)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbox-mcp-server",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
   "type": "module",
   "main": "dist/index.js",
@@ -51,5 +51,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "license": "GPL-3.0-or-later"
+  "license": "AGPL-3.0-or-later"
 }