sbox-mcp-server 1.2.0

package/dist/tools/physics.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+/**
+ * Physics tools: add_physics, add_collider, add_joint, raycast.
+ * Manages rigidbodies, colliders, physics constraints, and ray tracing.
+ */
+export function registerPhysicsTools(server, bridge) {
+    // ── add_physics ───────────────────────────────────────────────────
+    server.tool("add_physics", "Add a Rigidbody and collider to a GameObject, making it a dynamic physics object. Auto-selects BoxCollider if no collider type specified", {
+        id: z.string().describe("GUID of the GameObject"),
+        collider: z
+            .enum(["box", "sphere", "capsule", "mesh"])
+            .optional()
+            .describe("Collider type to add. Defaults to 'box'"),
+        mass: z
+            .number()
+            .optional()
+            .describe("Mass of the physics body in kg"),
+        gravity: z
+            .boolean()
+            .optional()
+            .describe("Whether gravity affects this object. Defaults to true"),
+    }, async (params) => {
+        const res = await bridge.send("add_physics", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_collider ──────────────────────────────────────────────────
+    server.tool("add_collider", "Add a specific collider component to a GameObject. Supports box, sphere, capsule, mesh, and hull types. Can be configured as trigger", {
+        id: z.string().describe("GUID of the GameObject"),
+        type: z
+            .enum(["box", "sphere", "capsule", "mesh", "hull"])
+            .describe("Type of collider to add"),
+        isTrigger: z
+            .boolean()
+            .optional()
+            .describe("If true, the collider acts as a trigger (no physics collision). Defaults to false"),
+        size: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("Size for BoxCollider (x, y, z dimensions)"),
+        radius: z
+            .number()
+            .optional()
+            .describe("Radius for SphereCollider or CapsuleCollider"),
+        height: z
+            .number()
+            .optional()
+            .describe("Height/length for CapsuleCollider"),
+    }, async (params) => {
+        const res = await bridge.send("add_collider", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_joint ─────────────────────────────────────────────────────
+    server.tool("add_joint", "Add a physics joint/constraint between two GameObjects. Supports fixed, spring, and slider joint types", {
+        id: z
+            .string()
+            .describe("GUID of the GameObject to add the joint to"),
+        type: z
+            .enum(["fixed", "spring", "slider"])
+            .describe("Type of joint to create"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of the target GameObject to connect to"),
+        frequency: z
+            .number()
+            .optional()
+            .describe("Spring frequency (spring joints only)"),
+        damping: z
+            .number()
+            .optional()
+            .describe("Damping ratio (spring joints only). 0 = no damping, 1 = critical"),
+    }, async (params) => {
+        const res = await bridge.send("add_joint", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── raycast ───────────────────────────────────────────────────────
+    server.tool("raycast", "Perform a physics raycast (Scene.Trace.Ray) and return hit results. Useful for line-of-sight checks, object placement, and collision detection", {
+        start: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .describe("Ray start position (world space)"),
+        end: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("Ray end position. Use either end or direction+maxDistance"),
+        direction: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("Ray direction (normalized). Used with maxDistance instead of end"),
+        maxDistance: z
+            .number()
+            .optional()
+            .describe("Maximum ray distance when using direction. Defaults to 10000"),
+        radius: z
+            .number()
+            .optional()
+            .describe("Sphere/box trace radius. 0 = thin ray (default)"),
+        ignoreIds: z
+            .array(z.string())
+            .optional()
+            .describe("GUIDs of GameObjects to ignore"),
+        all: z
+            .boolean()
+            .optional()
+            .describe("If true, returns all hits along the ray. Defaults to false (first hit only)"),
+    }, async (params) => {
+        const res = await bridge.send("raycast", 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/playmode.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Play mode control and related editor tools.
+ *
+ * Beyond play/pause/resume/stop, this file also registers: set_property
+ * (editor-mode property writes), get/set_runtime_property (live tweaking
+ * during play mode), take_screenshot, and undo/redo.
+ */
+export declare function registerPlayModeTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=playmode.d.ts.map

package/dist/tools/playmode.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+/**
+ * Play mode control and related editor tools.
+ *
+ * Beyond play/pause/resume/stop, this file also registers: set_property
+ * (editor-mode property writes), get/set_runtime_property (live tweaking
+ * during play mode), take_screenshot, and undo/redo.
+ */
+export function registerPlayModeTools(server, bridge) {
+    // ── start_play ───────────────────────────────────────────────────
+    server.tool("start_play", "Enter play mode — starts running the game in the editor. Scripts execute, physics simulate, everything goes live", {}, async () => {
+        const res = await bridge.send("start_play");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── stop_play ────────────────────────────────────────────────────
+    server.tool("stop_play", "Exit play mode — stops the game and returns to editor. All runtime changes are discarded", {}, async () => {
+        const res = await bridge.send("stop_play");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── pause_play ───────────────────────────────────────────────────
+    server.tool("pause_play", "Pause the running game — freezes simulation but stays in play mode. Use resume_play to continue", {}, async () => {
+        const res = await bridge.send("pause_play");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── resume_play ──────────────────────────────────────────────────
+    server.tool("resume_play", "Resume a paused game — unfreezes simulation", {}, async () => {
+        const res = await bridge.send("resume_play");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── is_playing ───────────────────────────────────────────────────
+    server.tool("is_playing", "Check current play state — returns 'playing', 'paused', or 'stopped'", {}, async () => {
+        const res = await bridge.send("is_playing");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── take_screenshot ──────────────────────────────────────────────
+    server.tool("take_screenshot", "Capture the current editor viewport as a PNG screenshot", {
+        path: z
+            .string()
+            .optional()
+            .describe("Output path (e.g. 'screenshots/test.png'). Defaults to screenshots/screenshot_{timestamp}.png"),
+    }, async (params) => {
+        const res = await bridge.send("take_screenshot", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── undo ─────────────────────────────────────────────────────────
+    server.tool("undo", "Undo the last editor action. Safety net for when a change goes wrong", {}, async () => {
+        const res = await bridge.send("undo");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── redo ─────────────────────────────────────────────────────────
+    server.tool("redo", "Redo the last undone editor action", {}, async () => {
+        const res = await bridge.send("redo");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_property ─────────────────────────────────────────────────
+    server.tool("set_property", "Set a property value on a component (editor mode). Reads the value back to confirm", {
+        id: z.string().describe("GUID of the GameObject"),
+        component: z.string().describe("Component type name"),
+        property: z.string().describe("Property name to set"),
+        value: z.unknown().describe("New value — auto-converted to the correct type"),
+    }, async (params) => {
+        const res = await bridge.send("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) }],
+        };
+    });
+    // ── get_runtime_property ─────────────────────────────────────────
+    server.tool("get_runtime_property", "Read a component property value during play mode. Must call start_play first", {
+        id: z.string().describe("GUID of the GameObject"),
+        component: z.string().describe("Component type name"),
+        property: z.string().describe("Property name to read"),
+    }, async (params) => {
+        const res = await bridge.send("get_runtime_property", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_runtime_property ─────────────────────────────────────────
+    server.tool("set_runtime_property", "Set a component property value during play mode — tweak values live while the game runs", {
+        id: z.string().describe("GUID of the GameObject"),
+        component: z.string().describe("Component type name"),
+        property: z.string().describe("Property name to set"),
+        value: z.unknown().describe("New value"),
+    }, async (params) => {
+        const res = await bridge.send("set_runtime_property", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=playmode.js.map

package/dist/tools/prefabs.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Prefab tools: create_prefab, instantiate_prefab, list_prefabs, get_prefab_info.
+ * Manages .prefab files — saving GameObjects as reusable templates and spawning instances.
+ */
+export declare function registerPrefabTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=prefabs.d.ts.map

package/dist/tools/prefabs.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+/**
+ * Prefab tools: create_prefab, instantiate_prefab, list_prefabs, get_prefab_info.
+ * Manages .prefab files — saving GameObjects as reusable templates and spawning instances.
+ */
+export function registerPrefabTools(server, bridge) {
+    // ── create_prefab ─────────────────────────────────────────────────
+    server.tool("create_prefab", "Save an existing GameObject as a reusable .prefab file. The prefab can be instantiated later", {
+        id: z.string().describe("GUID of the GameObject to save as prefab"),
+        path: z
+            .string()
+            .describe("Path for the prefab file relative to project root (e.g. 'prefabs/enemies/grunt.prefab')"),
+    }, async (params) => {
+        const res = await bridge.send("create_prefab", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── instantiate_prefab ────────────────────────────────────────────
+    server.tool("instantiate_prefab", "Spawn a prefab instance into the active scene at an optional position and rotation", {
+        path: z
+            .string()
+            .describe("Path to the .prefab file (e.g. 'prefabs/enemies/grunt.prefab')"),
+        position: z
+            .object({
+            x: z.number(),
+            y: z.number(),
+            z: z.number(),
+        })
+            .optional()
+            .describe("World position to spawn at. Defaults to origin"),
+        rotation: z
+            .object({
+            pitch: z.number(),
+            yaw: z.number(),
+            roll: z.number(),
+        })
+            .optional()
+            .describe("Rotation as euler angles. Defaults to identity"),
+        scale: z
+            .number()
+            .optional()
+            .describe("Uniform scale multiplier. Defaults to 1.0"),
+        parent: z
+            .string()
+            .optional()
+            .describe("GUID of parent GameObject to attach to"),
+    }, async (params) => {
+        const res = await bridge.send("instantiate_prefab", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── list_prefabs ──────────────────────────────────────────────────
+    server.tool("list_prefabs", "List all .prefab files in the project. Filter by name or path", {
+        filter: z
+            .string()
+            .optional()
+            .describe("Search filter for prefab name or path"),
+        maxResults: z
+            .number()
+            .optional()
+            .describe("Maximum results to return. Defaults to 100"),
+    }, async (params) => {
+        const res = await bridge.send("list_prefabs", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── get_prefab_info ───────────────────────────────────────────────
+    server.tool("get_prefab_info", "Get detailed information about a prefab file including its JSON contents and metadata", {
+        path: z
+            .string()
+            .describe("Path to the .prefab file (e.g. 'prefabs/enemies/grunt.prefab')"),
+    }, async (params) => {
+        const res = await bridge.send("get_prefab_info", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=prefabs.js.map

package/dist/tools/project.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Project and file management tools: get_project_info, list_project_files,
+ * read_file, write_file.
+ *
+ * This is the simplest tool file and serves as a good template for contributors.
+ * Every tool follows the same pattern: define with server.tool(), send the
+ * command to the Bridge, and return the result (or error) as text content.
+ */
+export declare function registerProjectTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=project.d.ts.map

package/dist/tools/project.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+/**
+ * Project and file management tools: get_project_info, list_project_files,
+ * read_file, write_file.
+ *
+ * This is the simplest tool file and serves as a good template for contributors.
+ * Every tool follows the same pattern: define with server.tool(), send the
+ * command to the Bridge, and return the result (or error) as text content.
+ */
+export function registerProjectTools(server, bridge) {
+    // ── get_project_info ─────────────────────────────────────────────
+    server.tool("get_project_info", "Get information about the current s&box project — path, name, game type, dependencies, and configuration", {}, async () => {
+        const res = await bridge.send("get_project_info");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(res.data, null, 2) },
+            ],
+        };
+    });
+    // ── list_project_files ───────────────────────────────────────────
+    server.tool("list_project_files", "Browse the project file tree. Optionally filter by directory path and/or file extension (e.g. '.cs', '.scene')", {
+        path: z
+            .string()
+            .optional()
+            .describe("Relative directory path to list (e.g. 'code/Components'). Defaults to project root"),
+        extension: z
+            .string()
+            .optional()
+            .describe("Filter by file extension, including the dot (e.g. '.cs', '.scene')"),
+        recursive: z
+            .boolean()
+            .optional()
+            .describe("Whether to list files recursively. Defaults to true"),
+    }, async (params) => {
+        const res = await bridge.send("list_project_files", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(res.data, null, 2) },
+            ],
+        };
+    });
+    // ── read_file ────────────────────────────────────────────────────
+    server.tool("read_file", "Read the contents of a file in the s&box project (scripts, scenes, configs, etc.)", {
+        path: z
+            .string()
+            .describe("Relative path to the file within the project (e.g. 'code/PlayerController.cs')"),
+    }, async (params) => {
+        const res = await bridge.send("read_file", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: typeof res.data === "string"
+                        ? res.data
+                        : JSON.stringify(res.data, null, 2),
+                },
+            ],
+        };
+    });
+    // ── write_file ───────────────────────────────────────────────────
+    server.tool("write_file", "Write or overwrite a file in the s&box project. Creates parent directories as needed", {
+        path: z
+            .string()
+            .describe("Relative path for the file (e.g. 'code/Components/Health.cs')"),
+        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}` }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `File written successfully: ${params.path}`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=project.js.map

package/dist/tools/publishing.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Publishing tools: get_project_config, set_project_config, validate_project,
+ * build_project, get_build_status, clean_build, export_project,
+ * set_project_thumbnail, get_package_details, prepare_publish.
+ *
+ * Manages project configuration, building, exporting, and publishing preparation.
+ */
+export declare function registerPublishingTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=publishing.d.ts.map