sbox-mcp-server 1.2.0

package/dist/tools/publishing.js

@@ -0,0 +1,168 @@
+import { z } from "zod";
+/**
+ * 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 function registerPublishingTools(server, bridge) {
+    // ── get_project_config ───────────────────────────────────────────
+    server.tool("get_project_config", "Read the full project configuration from the .sbproj file including title, description, version, type, package references, metadata, and raw JSON", {}, async (params) => {
+        const res = await bridge.send("get_project_config", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_project_config ───────────────────────────────────────────
+    server.tool("set_project_config", "Update project configuration fields for publishing: title, description, version, type, package ident, summary, visibility. Only provided fields are changed", {
+        title: z.string().optional().describe("Project display title"),
+        description: z
+            .string()
+            .optional()
+            .describe("Project description for publishing"),
+        version: z
+            .string()
+            .optional()
+            .describe("Version string (e.g. '1.0.0', '2.1.3')"),
+        type: z
+            .string()
+            .optional()
+            .describe("Project type: 'game', 'addon', 'library', or 'template'"),
+        packageIdent: z
+            .string()
+            .optional()
+            .describe("Package identifier (e.g. 'myorg.mygame')"),
+        summary: z
+            .string()
+            .optional()
+            .describe("Short summary for asset.party listing"),
+        isPublic: z
+            .boolean()
+            .optional()
+            .describe("Whether the project is publicly visible"),
+    }, async (params) => {
+        const res = await bridge.send("set_project_config", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── validate_project ─────────────────────────────────────────────
+    server.tool("validate_project", "Validate that the project is ready for publishing. Checks: compile errors, metadata completeness, scenes, scripts, thumbnail, and project type", {}, async (params) => {
+        const res = await bridge.send("validate_project", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── build_project ────────────────────────────────────────────────
+    server.tool("build_project", "Trigger a full project build/recompilation. Returns build result with error and warning counts", {
+        configuration: z
+            .enum(["Debug", "Release"])
+            .optional()
+            .describe("Build configuration. Defaults to 'Release'"),
+    }, async (params) => {
+        const res = await bridge.send("build_project", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── get_build_status ─────────────────────────────────────────────
+    server.tool("get_build_status", "Get the current build/compilation status: is compiling, errors, warnings, and full diagnostics list", {}, async (params) => {
+        const res = await bridge.send("get_build_status", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── clean_build ──────────────────────────────────────────────────
+    server.tool("clean_build", "Clean all compiled output (bin, obj) and trigger a fresh rebuild from scratch", {}, async (params) => {
+        const res = await bridge.send("clean_build", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── export_project ───────────────────────────────────────────────
+    server.tool("export_project", "Export the project as a standalone game. Copies assemblies, assets, and scenes to an output directory for distribution", {
+        outputPath: z
+            .string()
+            .optional()
+            .describe("Relative output directory within the project. Defaults to 'export'"),
+        configuration: z
+            .enum(["Debug", "Release"])
+            .optional()
+            .describe("Build configuration for export. Defaults to 'Release'"),
+    }, async (params) => {
+        const res = await bridge.send("export_project", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_project_thumbnail ────────────────────────────────────────
+    server.tool("set_project_thumbnail", "Set or update the project thumbnail image (thumb.png) used for publishing. Provide either a source path or base64 image data", {
+        sourcePath: z
+            .string()
+            .optional()
+            .describe("Relative path to an image file within the project to use as thumbnail"),
+        base64: z
+            .string()
+            .optional()
+            .describe("Base64-encoded image data to write as thumbnail"),
+        format: z
+            .enum(["png", "jpg"])
+            .optional()
+            .describe("Image format when using base64 mode. Defaults to 'png'"),
+    }, async (params) => {
+        const res = await bridge.send("set_project_thumbnail", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── get_package_details ──────────────────────────────────────────
+    server.tool("get_package_details", "Fetch detailed package information from the s&box asset library (asset.party) including title, author, version, downloads, ratings, and dependencies", {
+        ident: z
+            .string()
+            .describe("Package identifier (e.g. 'facepunch.flatgrass', 'myorg.mygame')"),
+    }, async (params) => {
+        const res = await bridge.send("get_package_details", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── prepare_publish ──────────────────────────────────────────────
+    server.tool("prepare_publish", "Comprehensive publish preparation: validates project, compiles, checks metadata, and generates a detailed readiness report with issues, warnings, and next steps", {}, async (params) => {
+        const res = await bridge.send("prepare_publish", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=publishing.js.map

package/dist/tools/scenes.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Scene management tools: list_scenes, load_scene, save_scene, create_scene.
+ * create_scene generates .scene JSON with optional default objects (camera, light, ground).
+ */
+export declare function registerSceneTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=scenes.d.ts.map

package/dist/tools/scenes.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/**
+ * Scene management tools: list_scenes, load_scene, save_scene, create_scene.
+ * create_scene generates .scene JSON with optional default objects (camera, light, ground).
+ */
+export function registerSceneTools(server, bridge) {
+    // ── list_scenes ──────────────────────────────────────────────────
+    server.tool("list_scenes", "List all .scene files in the project with their paths and basic metadata", {}, async () => {
+        const res = await bridge.send("list_scenes");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(res.data, null, 2) },
+            ],
+        };
+    });
+    // ── load_scene ───────────────────────────────────────────────────
+    server.tool("load_scene", "Open a scene in the s&box editor by its path", {
+        path: z
+            .string()
+            .describe("Relative path to the .scene file (e.g. 'scenes/main.scene')"),
+    }, async (params) => {
+        const res = await bridge.send("load_scene", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                { type: "text", text: `Scene loaded: ${params.path}` },
+            ],
+        };
+    });
+    // ── save_scene ───────────────────────────────────────────────────
+    server.tool("save_scene", "Save the currently open scene in the s&box editor", {
+        path: z
+            .string()
+            .optional()
+            .describe("Path to save to. If omitted, saves to the current scene's path"),
+    }, async (params) => {
+        const res = await bridge.send("save_scene", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: "Scene saved" }],
+        };
+    });
+    // ── create_scene ─────────────────────────────────────────────────
+    server.tool("create_scene", "Create a new empty scene file. Optionally include basic objects like a camera, directional light, and ground plane", {
+        path: z
+            .string()
+            .describe("Relative path for the new scene (e.g. 'scenes/level_01.scene')"),
+        name: z.string().optional().describe("Display name for the scene"),
+        includeDefaults: z
+            .boolean()
+            .optional()
+            .describe("If true, includes a Camera, Directional Light, and ground plane. Defaults to true"),
+    }, async (params) => {
+        const res = await bridge.send("create_scene", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Scene created: ${params.path}`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=scenes.js.map

package/dist/tools/scripts.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Script management tools: create_script, edit_script, delete_script, trigger_hotload.
+ * create_script generates boilerplate from parameters or writes raw C# content.
+ * edit_script supports find/replace, line insert, append, and line deletion operations.
+ */
+export declare function registerScriptTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=scripts.d.ts.map

package/dist/tools/scripts.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+/**
+ * Script management tools: create_script, edit_script, delete_script, trigger_hotload.
+ * create_script generates boilerplate from parameters or writes raw C# content.
+ * edit_script supports find/replace, line insert, append, and line deletion operations.
+ */
+export function registerScriptTools(server, bridge) {
+    // ── create_script ────────────────────────────────────────────────
+    server.tool("create_script", "Create a new C# component script in the project. Generates proper s&box component boilerplate with the specified class name, namespace, and optional properties", {
+        name: z
+            .string()
+            .describe("Class name for the component (e.g. 'PlayerController'). Will also be the filename"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under code/ to place the script (e.g. 'Components'). Defaults to 'code/'"),
+        description: z
+            .string()
+            .optional()
+            .describe("Description of what this component does — used to generate appropriate code"),
+        properties: z
+            .array(z.object({
+            name: z.string().describe("Property name"),
+            type: z.string().describe("C# type (e.g. 'float', 'Vector3', 'GameObject')"),
+            default: z
+                .string()
+                .optional()
+                .describe("Default value as a string"),
+            description: z
+                .string()
+                .optional()
+                .describe("Property description for the editor tooltip"),
+        }))
+            .optional()
+            .describe("List of [Property] fields to include in the component"),
+        content: z
+            .string()
+            .optional()
+            .describe("Full C# file content. If provided, ignores name/properties and writes this directly"),
+    }, async (params) => {
+        const res = await bridge.send("create_script", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(res.data, null, 2),
+                },
+            ],
+        };
+    });
+    // ── edit_script ──────────────────────────────────────────────────
+    server.tool("edit_script", "Edit an existing C# script. Supports find/replace, inserting code at a line number, or appending code to the class body", {
+        path: z
+            .string()
+            .describe("Relative path to the script file (e.g. 'code/PlayerController.cs')"),
+        operations: z
+            .array(z.object({
+            type: z
+                .enum(["replace", "insert", "append", "delete_lines"])
+                .describe("Type of edit operation"),
+            find: z
+                .string()
+                .optional()
+                .describe("Text to find (for 'replace' operation)"),
+            replacement: z
+                .string()
+                .optional()
+                .describe("Replacement text (for 'replace' and 'insert' operations)"),
+            line: z
+                .number()
+                .optional()
+                .describe("Line number (for 'insert' and 'delete_lines' operations)"),
+            endLine: z
+                .number()
+                .optional()
+                .describe("End line number (for 'delete_lines' operation)"),
+            content: z
+                .string()
+                .optional()
+                .describe("Content to append (for 'append' operation)"),
+        }))
+            .describe("List of edit operations to apply in order"),
+    }, async (params) => {
+        const res = await bridge.send("edit_script", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(res.data, null, 2),
+                },
+            ],
+        };
+    });
+    // ── delete_script ────────────────────────────────────────────────
+    server.tool("delete_script", "Delete a C# script from the project", {
+        path: z
+            .string()
+            .describe("Relative path to the script file to delete"),
+    }, async (params) => {
+        const res = await bridge.send("delete_script", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                { type: "text", text: `Script deleted: ${params.path}` },
+            ],
+        };
+    });
+    // ── trigger_hotload ──────────────────────────────────────────────
+    server.tool("trigger_hotload", "Force s&box to recompile and hotload all C# scripts immediately. Use after creating or editing scripts to see changes in real-time", {}, async () => {
+        const res = await bridge.send("trigger_hotload");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Hotload triggered — s&box is recompiling scripts",
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=scripts.js.map

package/dist/tools/status.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Diagnostic and health-check tool (get_bridge_status).
+ * Reports connection state, latency, host/port, and editor version.
+ */
+export declare function registerStatusTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=status.d.ts.map

package/dist/tools/status.js

@@ -0,0 +1,49 @@
+/**
+ * Diagnostic and health-check tool (get_bridge_status).
+ * Reports connection state, latency, host/port, and editor version.
+ */
+export function registerStatusTools(server, bridge) {
+    // ── get_bridge_status ────────────────────────────────────────────
+    server.tool("get_bridge_status", "Check the connection status to the s&box Bridge — whether it's connected, latency, host/port, and editor info. Useful for debugging", {}, async () => {
+        const connected = bridge.isConnected();
+        let latencyMs = -1;
+        let editorVersion = null;
+        if (connected) {
+            // Measure round-trip ping
+            latencyMs = await bridge.ping();
+            // Try to get editor version via project info
+            try {
+                const res = await bridge.send("get_project_info", {}, 5000);
+                if (res.success && res.data) {
+                    const data = res.data;
+                    editorVersion = data.editorVersion ?? null;
+                }
+            }
+            catch {
+                // Non-fatal
+            }
+        }
+        const status = {
+            connected,
+            host: bridge.getHost(),
+            port: bridge.getPort(),
+            latencyMs: connected ? latencyMs : null,
+            lastPong: connected
+                ? new Date(bridge.getLastPongTime()).toISOString()
+                : null,
+            editorVersion,
+        };
+        const text = connected
+            ? `Bridge connected (${bridge.getHost()}:${bridge.getPort()}, ${latencyMs}ms latency)`
+            : `Bridge NOT connected (${bridge.getHost()}:${bridge.getPort()}). Is s&box running?`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${text}\n\n${JSON.stringify(status, null, 2)}`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=status.js.map

package/dist/tools/templates.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Game logic template tools: create_player_controller, create_npc_controller,
+ * create_game_manager, create_trigger_zone.
+ *
+ * These generate fully functional C# scripts with configurable boilerplate,
+ * saving non-coders from writing game logic from scratch.
+ */
+export declare function registerTemplateTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=templates.d.ts.map

package/dist/tools/templates.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+/**
+ * Game logic template tools: create_player_controller, create_npc_controller,
+ * create_game_manager, create_trigger_zone.
+ *
+ * These generate fully functional C# scripts with configurable boilerplate,
+ * saving non-coders from writing game logic from scratch.
+ */
+export function registerTemplateTools(server, bridge) {
+    // ── create_player_controller ──────────────────────────────────────
+    server.tool("create_player_controller", "Generate a player controller script with WASD movement, mouse look, jumping, and sprint. Supports first-person and third-person camera modes", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name. Defaults to 'PlayerController'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under code/ for the file"),
+        type: z
+            .enum(["first_person", "third_person"])
+            .optional()
+            .describe("Camera mode: 'first_person' or 'third_person'. Defaults to 'first_person'"),
+        moveSpeed: z
+            .number()
+            .optional()
+            .describe("Movement speed in units/sec. Defaults to 300"),
+        jumpForce: z
+            .number()
+            .optional()
+            .describe("Jump force. Defaults to 350"),
+        sprintMultiplier: z
+            .number()
+            .optional()
+            .describe("Sprint speed multiplier. Defaults to 1.5"),
+    }, async (params) => {
+        const res = await bridge.send("create_player_controller", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_npc_controller ─────────────────────────────────────────
+    server.tool("create_npc_controller", "Generate an NPC controller script with NavMeshAgent pathfinding. Supports patrol, chase, and patrol-chase behaviors", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name. Defaults to 'NpcController'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under code/ for the file"),
+        behavior: z
+            .enum(["patrol", "chase", "patrol_chase"])
+            .optional()
+            .describe("AI behavior: 'patrol' (follow waypoints), 'chase' (follow player), 'patrol_chase' (patrol until player nearby). Defaults to 'patrol'"),
+        moveSpeed: z
+            .number()
+            .optional()
+            .describe("Movement speed. Defaults to 150"),
+        chaseRange: z
+            .number()
+            .optional()
+            .describe("Detection range for chase behavior. Defaults to 500"),
+    }, async (params) => {
+        const res = await bridge.send("create_npc_controller", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_game_manager ───────────────────────────────────────────
+    server.tool("create_game_manager", "Generate a game manager script with configurable game loop features: score tracking, round timer, player spawning, and game state machine", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name. Defaults to 'GameManager'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under code/ for the file"),
+        includeScore: z
+            .boolean()
+            .optional()
+            .describe("Include score tracking. Defaults to true"),
+        includeTimer: z
+            .boolean()
+            .optional()
+            .describe("Include round timer with countdown. Defaults to false"),
+        includeSpawning: z
+            .boolean()
+            .optional()
+            .describe("Include player spawning from prefab at spawn point. Defaults to false"),
+    }, async (params) => {
+        const res = await bridge.send("create_game_manager", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_trigger_zone ───────────────────────────────────────────
+    server.tool("create_trigger_zone", "Generate a trigger zone script that detects when GameObjects enter/exit a collider volume. Supports teleport, damage, spawn, and log actions", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name. Defaults to 'TriggerZone'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under code/ for the file"),
+        action: z
+            .enum(["log", "teleport", "damage", "spawn"])
+            .optional()
+            .describe("What happens on trigger: 'log' (print message), 'teleport' (move to destination), 'damage' (apply damage), 'spawn' (create prefab). Defaults to 'log'"),
+        filterTag: z
+            .string()
+            .optional()
+            .describe("Only trigger for objects with this tag. Defaults to 'player'"),
+    }, async (params) => {
+        const res = await bridge.send("create_trigger_zone", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=templates.js.map

package/dist/tools/ui.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * UI tools: create_razor_ui, add_screen_panel, add_world_panel.
+ * Manages s&box's Razor-based UI system — .razor component files, ScreenPanel, and WorldPanel.
+ */
+export declare function registerUITools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=ui.d.ts.map