sbox-mcp-server 1.3.2 → 1.5.0

package/dist/tools/leveltools.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+/**
+ * Scene & level-building tools (Batch 21): snap-to-ground, align, distribute,
+ * grid-duplicate, and measure. Transform-level operations for arranging a
+ * scene — all verifiable via the editor (screenshot or hierarchy/state).
+ */
+const Vector3Schema = z
+    .object({ x: z.number(), y: z.number(), z: z.number() })
+    .describe("Vector {x,y,z}");
+export function registerLevelTools(server, bridge) {
+    // ── snap_to_ground ─────────────────────────────────────────────────
+    server.tool("snap_to_ground", "Drop a GameObject straight down onto the surface below it (physics raycast). Works best on collider-less props (an object with its own collider may self-hit). Optional offset lifts it off the surface.", {
+        id: z.string().describe("GUID of the GameObject to snap"),
+        offset: z.number().optional().describe("Height above the surface to place it (default 0)"),
+        startHeight: z.number().optional().describe("How far above the object to start the trace (default 2000)"),
+        maxDistance: z.number().optional().describe("Max trace distance downward (default 20000)"),
+    }, async (params) => {
+        const res = await bridge.send("snap_to_ground", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── align_objects ──────────────────────────────────────────────────
+    server.tool("align_objects", "Align several GameObjects on one axis so they share a coordinate. mode = first (match the first object), min, max, or average.", {
+        ids: z.array(z.string()).describe("GUIDs of the GameObjects to align (>= 2)"),
+        axis: z.enum(["x", "y", "z"]).describe("Axis to align on"),
+        mode: z
+            .enum(["first", "min", "max", "average"])
+            .optional()
+            .describe("Target coordinate to align to (default first)"),
+    }, async (params) => {
+        const res = await bridge.send("align_objects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── distribute_objects ─────────────────────────────────────────────
+    server.tool("distribute_objects", "Evenly space GameObjects along an axis between the lowest and highest (keeps the two ends fixed, spreads the rest evenly).", {
+        ids: z.array(z.string()).describe("GUIDs of the GameObjects to distribute (>= 3)"),
+        axis: z.enum(["x", "y", "z"]).describe("Axis to distribute along"),
+    }, async (params) => {
+        const res = await bridge.send("distribute_objects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── grid_duplicate ─────────────────────────────────────────────────
+    server.tool("grid_duplicate", "Clone a GameObject into an X/Y/Z grid with fixed spacing (the original stays in place). Each count is clamped to 50 and total clones to 500. Great for fences, crates, pillars, foliage rows.", {
+        id: z.string().describe("GUID of the GameObject to clone"),
+        countX: z.number().int().optional().describe("Copies along X (default 1)"),
+        countY: z.number().int().optional().describe("Copies along Y (default 1)"),
+        countZ: z.number().int().optional().describe("Copies along Z (default 1)"),
+        spacing: Vector3Schema.optional().describe("Spacing between copies per axis (default 100,100,100)"),
+    }, async (params) => {
+        const res = await bridge.send("grid_duplicate", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── measure_distance ───────────────────────────────────────────────
+    server.tool("measure_distance", "Measure the distance between two points or two GameObjects. Provide a/b as {x,y,z} or idA/idB as GUIDs. Returns straight-line distance, horizontal (ground) distance, and the delta vector. Read-only (works during play).", {
+        a: Vector3Schema.optional().describe("First point {x,y,z}"),
+        b: Vector3Schema.optional().describe("Second point {x,y,z}"),
+        idA: z.string().optional().describe("First GameObject GUID (overrides a)"),
+        idB: z.string().optional().describe("Second GameObject GUID (overrides b)"),
+    }, async (params) => {
+        const res = await bridge.send("measure_distance", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── scatter_props ──────────────────────────────────────────────────
+    server.tool("scatter_props", "Scatter N copies of a model randomly within a radius around a center point — instant foliage, rocks, debris. Each copy gets a random yaw and (by default) is snapped to the ground. Seeded for reproducibility; copies are grouped under one parent by default. Count capped at 300.", {
+        model: z.string().describe("Model path to scatter, e.g. 'models/dev/box.vmdl'"),
+        center: Vector3Schema.optional().describe("Centre of the scatter area (default origin)"),
+        radius: z.number().optional().describe("Scatter radius in units (default 256)"),
+        count: z.number().int().optional().describe("How many to place (default 10, max 300)"),
+        randomYaw: z.boolean().optional().describe("Randomly rotate each around Z (default true)"),
+        snapToGround: z.boolean().optional().describe("Raycast each onto the surface below (default true)"),
+        scaleMin: z.number().optional().describe("Min uniform scale (default 1)"),
+        scaleMax: z.number().optional().describe("Max uniform scale (default 1; set >min for size variation)"),
+        tint: z
+            .object({
+            r: z.number().min(0),
+            g: z.number().min(0),
+            b: z.number().min(0),
+            a: z.number().min(0).max(1).optional(),
+        })
+            .optional()
+            .describe("Tint applied to every copy"),
+        seed: z.number().int().optional().describe("PRNG seed for a reproducible layout (default 1)"),
+        group: z.boolean().optional().describe("Parent all copies under one group object (default true)"),
+        name: z.string().optional().describe("Base name for the props/group (default 'Prop')"),
+    }, async (params) => {
+        const res = await bridge.send("scatter_props", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── randomize_transforms ───────────────────────────────────────────
+    server.tool("randomize_transforms", "Add natural variation to existing objects: random yaw and/or random uniform scale within a range. Great for breaking up repetition in placed foliage/rocks/crates. Seeded.", {
+        ids: z.array(z.string()).describe("GUIDs of the GameObjects to randomize"),
+        randomYaw: z.boolean().optional().describe("Randomize Z rotation (default true)"),
+        scaleMin: z.number().optional().describe("Min uniform scale (default 1)"),
+        scaleMax: z.number().optional().describe("Max uniform scale (default 1; set >min to vary)"),
+        seed: z.number().int().optional().describe("PRNG seed (default 1)"),
+    }, async (params) => {
+        const res = await bridge.send("randomize_transforms", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── group_objects ──────────────────────────────────────────────────
+    server.tool("group_objects", "Parent a set of GameObjects under a new empty group object (placed at their centroid) — tidies the hierarchy and lets you move/rotate them together.", {
+        ids: z.array(z.string()).describe("GUIDs of the GameObjects to group"),
+        name: z.string().optional().describe("Name for the group object (default 'Group')"),
+    }, async (params) => {
+        const res = await bridge.send("group_objects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=leveltools.js.map

package/dist/tools/navigation.d.ts

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

package/dist/tools/navigation.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+/**
+ * Navigation tools (Batch 27) — REAL editor operations, not component wrappers.
+ *
+ * bake_navmesh runs the editor's static NavMesh bake (NavMesh.BakeNavMesh) so
+ * NavMeshAgents can pathfind; get_navmesh_path queries the baked mesh for a
+ * route (NavMesh.GetSimplePath). Neither is reachable via add_component — they
+ * operate on the scene's navmesh itself, which is why they earn dedicated tools.
+ */
+const Vec3 = z
+    .object({
+    x: z.number().describe("X"),
+    y: z.number().describe("Y"),
+    z: z.number().describe("Z"),
+})
+    .describe("A world-space Vector3");
+export function registerNavigationTools(server, bridge) {
+    // ── bake_navmesh ────────────────────────────────────────────────────
+    server.tool("bake_navmesh", "Enable + bake the active scene's navigation mesh so NavMeshAgents can pathfind. This is an editor operation (NavMesh.BakeNavMesh), not a component. The bake runs ASYNC — it returns immediately with baking:true; the editor shows a progress bar and isGenerating flips false when done (give it a moment before querying paths). Optional agent params let you size the mesh to your characters.", {
+        agentRadius: z.number().optional().describe("Agent radius (default scene setting)"),
+        agentHeight: z.number().optional().describe("Agent height"),
+        agentStepSize: z.number().optional().describe("Max step-up height"),
+        agentMaxSlope: z.number().optional().describe("Max walkable slope, degrees"),
+        includeStaticBodies: z
+            .boolean()
+            .optional()
+            .describe("Include static physics bodies in the bake"),
+    }, async (params) => {
+        const res = await bridge.send("bake_navmesh", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── get_navmesh_path ────────────────────────────────────────────────
+    server.tool("get_navmesh_path", "Query the baked navmesh for a walkable path between two world points (NavMesh.GetSimplePath). Returns the ordered path points, or reachable:false if no route exists. Requires bake_navmesh to have run first. Read-only — useful for validating connectivity, AI patrol routes, and spawn reachability.", {
+        from: Vec3.describe("Start point (world space)"),
+        to: Vec3.describe("Destination point (world space)"),
+    }, async (params) => {
+        const res = await bridge.send("get_navmesh_path", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=navigation.js.map

package/dist/tools/networking.js

@@ -100,23 +100,25 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── add_sync_property ─────────────────────────────────────────────
-    server.tool("add_sync_property", "Add a [Sync] networked property to a C# script. The property auto-replicates across the network", {
+    server.tool("add_sync_property", "Annotate an EXISTING public property in a C# script with the [Sync] attribute so s&box replicates it across the network. This does NOT create a new property — the property named by `propertyName` must already be declared in the file; the tool only inserts the [Sync] attribute above it", {
         path: z
             .string()
             .describe("Relative path to the script file (e.g. 'code/Player.cs')"),
-        propertyName: z.string().describe("Name for the new property"),
+        propertyName: z
+            .string()
+            .describe("Name of the existing public property to annotate with [Sync]"),
         propertyType: z
             .string()
             .optional()
-            .describe("C# type (float, int, string, Vector3, bool, etc.). Defaults to 'float'"),
+            .describe("Currently ignored — not yet implemented. The addon only annotates an existing property; it does not declare a new one, so the type comes from the existing declaration"),
         syncFlags: z
             .string()
             .optional()
-            .describe("Sync flags: 'FromHost' (host→clients only). Omit for bidirectional"),
+            .describe("Currently ignored — not yet implemented. The addon emits a plain [Sync] with no SyncFlags"),
         defaultValue: z
             .string()
             .optional()
-            .describe("Default value expression (e.g. '100f', 'true', 'Vector3.Zero')"),
+            .describe("Currently ignored — not yet implemented. The addon does not create or initialize a property, so no default is written"),
     }, async (params) => {
         const res = await bridge.send("add_sync_property", params);
         if (!res.success) {
@@ -127,7 +129,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── add_rpc_method ────────────────────────────────────────────────
-    server.tool("add_rpc_method", "Add an RPC method to a C# script. Supports [Rpc.Broadcast] (all clients), [Rpc.Host] (host only), [Rpc.Owner] (owner only)", {
+    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", {
         path: z
             .string()
             .describe("Relative path to the script file"),
@@ -139,11 +141,11 @@ export function registerNetworkingTools(server, bridge) {
         methodParams: z
             .string()
             .optional()
-            .describe("Method parameters as C# signature (e.g. 'float damage, Vector3 hitPos')"),
+            .describe("Currently ignored — not yet implemented. The addon emits a no-argument method; add parameters yourself afterward"),
         body: z
             .string()
             .optional()
-            .describe("Method body code (without braces). Defaults to a log statement"),
+            .describe("Currently ignored — not yet implemented. The addon emits an empty method body; fill it in yourself afterward"),
     }, async (params) => {
         const res = await bridge.send("add_rpc_method", params);
         if (!res.success) {

package/dist/tools/objecttools.d.ts

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

package/dist/tools/objecttools.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+/**
+ * Object utility & query tools (Batch 23): find objects in the scene, and
+ * bulk-edit tint / model / tags across one or many objects. find_objects is
+ * the composable workhorse — query GUIDs, then feed them to align/distribute/
+ * set_tint/group/etc.
+ */
+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");
+export function registerObjectTools(server, bridge) {
+    // ── find_objects ───────────────────────────────────────────────────
+    server.tool("find_objects", "Query the scene for GameObjects by name (case-insensitive substring), component type name, and/or tag — combine filters (AND). Returns {id,name} for matches (limit default 50, max 500). Read-only; works during play. Use it to get GUIDs to feed into align/distribute/set_tint/group/delete/etc.", {
+        name: z.string().optional().describe("Name substring (case-insensitive)"),
+        component: z
+            .string()
+            .optional()
+            .describe("Component type name, e.g. 'PointLight', 'SkinnedModelRenderer'"),
+        tag: z.string().optional().describe("Tag the object must have"),
+        limit: z.number().int().optional().describe("Max results (default 50, max 500)"),
+    }, async (params) => {
+        const res = await bridge.send("find_objects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_tint ───────────────────────────────────────────────────────
+    server.tool("set_tint", "Set the renderer tint colour on one object (id) or many (ids) at once. Works on any ModelRenderer/SkinnedModelRenderer.", {
+        id: z.string().optional().describe("Single GameObject GUID"),
+        ids: z.array(z.string()).optional().describe("Multiple GameObject GUIDs"),
+        tint: ColorSchema.describe("Tint colour to apply"),
+    }, async (params) => {
+        const res = await bridge.send("set_tint", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── replace_model ──────────────────────────────────────────────────
+    server.tool("replace_model", "Swap the model on one object (id) or many (ids) — e.g. retheme a row of props in one call.", {
+        id: z.string().optional().describe("Single GameObject GUID"),
+        ids: z.array(z.string()).optional().describe("Multiple GameObject GUIDs"),
+        model: z.string().describe("New model path, e.g. 'models/dev/sphere.vmdl'"),
+    }, async (params) => {
+        const res = await bridge.send("replace_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_tags ───────────────────────────────────────────────────────
+    server.tool("set_tags", "Add, remove, and/or clear gameplay tags on one object (id) or many (ids). Tags drive collision groups, queries, and triggers.", {
+        id: z.string().optional().describe("Single GameObject GUID"),
+        ids: z.array(z.string()).optional().describe("Multiple GameObject GUIDs"),
+        add: z.array(z.string()).optional().describe("Tags to add"),
+        remove: z.array(z.string()).optional().describe("Tags to remove"),
+        clear: z.boolean().optional().describe("Remove all existing tags first"),
+    }, async (params) => {
+        const res = await bridge.send("set_tags", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── remove_component ───────────────────────────────────────────────
+    server.tool("remove_component", "Remove a component from a GameObject by type name (e.g. 'PointLight', 'ModelRenderer'). Removes the first match; pass all:true to remove every matching one. The counterpart to add_component_with_properties.", {
+        id: z.string().describe("GUID of the GameObject"),
+        component: z.string().describe("Component type name to remove"),
+        all: z.boolean().optional().describe("Remove all matching components, not just the first"),
+    }, async (params) => {
+        const res = await bridge.send("remove_component", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── get_tags ───────────────────────────────────────────────────────
+    server.tool("get_tags", "Read the tags currently on a GameObject. (Pair with set_tags to add/remove/clear, and find_objects to query by tag.)", {
+        id: z.string().describe("GUID of the GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("get_tags", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=objecttools.js.map

package/dist/tools/physics.js

@@ -126,5 +126,27 @@ export function registerPhysicsTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── physics_overlap ───────────────────────────────────────────────
+    server.tool("physics_overlap", "Spatial volume query: return the GameObjects whose colliders intersect a SPHERE (center + radius) or a BOX (center + size) — the volume counterpart to raycast's ray. Use it for 'what's near this point' / 'what's inside this trigger volume' checks (proximity, blast radius, spawn-clearance). Read-only.", {
+        center: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .describe("Center of the query volume (world space)"),
+        radius: z
+            .number()
+            .optional()
+            .describe("Sphere radius. Provide this OR size (box), not both"),
+        size: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("Full box size (not half-extents). Provide this OR radius"),
+    }, async (params) => {
+        const res = await bridge.send("physics_overlap", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=physics.js.map

package/dist/tools/project.js

@@ -74,8 +74,18 @@ export function registerProjectTools(server, bridge) {
         content: z.string().describe("The full file content to write"),
     }, async (params) => {
         const res = await bridge.send("write_file", params);
-        if (!res.success) {
-            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        // The handler can report a logical failure inside res.data even when the
+        // transport call "succeeded" (res.success === true). Only claim success
+        // when there is no error field anywhere; otherwise surface the real error
+        // instead of a misleading "written successfully".
+        const dataError = res.data && typeof res.data === "object"
+            ? res.data.error
+            : undefined;
+        if (!res.success || dataError) {
+            const message = res.error ?? (dataError ? String(dataError) : undefined);
+            return {
+                content: [{ type: "text", text: `Error: ${message ?? "write_file failed"}` }],
+            };
         }
         return {
             content: [

package/dist/tools/visuals.d.ts

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