sbox-mcp-server 1.11.0 → 1.13.0

package/dist/tools/assets.js

@@ -76,5 +76,27 @@ export function registerAssetTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── copy_asset_with_dependencies ─────────────────────────────────
+    server.tool("copy_asset_with_dependencies", "Copy a project asset and its full dependency closure (via Asset.GetReferences(deep:true)) into a target directory, preserving relative path structure so material references to textures keep resolving. SHADOW GUARD: refuses to write under core engine trees (models/citizen, models/dev, materials/dev, materials/default) -- copying there triggers an infinite asset-recompile loop (BRIDGE_GOTCHAS #5). Cloud/procedural/transient assets are skipped with a reason. Returns { copied:[{from,to}], skipped:[{path,reason}], count, note }.", {
+        sourcePath: z
+            .string()
+            .describe("Absolute path OR project-relative path of the source asset (e.g. 'models/props/crate.vmdl'). Use search_assets to find the exact path."),
+        targetDir: z
+            .string()
+            .optional()
+            .describe("Project-relative destination directory (e.g. 'Assets/library'). Defaults to 'Assets/library'"),
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("Overwrite existing files at the destination. Defaults to false"),
+    }, async (params) => {
+        const res = await bridge.send("copy_asset_with_dependencies", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=assets.js.map

package/dist/tools/components.js

@@ -24,9 +24,8 @@ export function registerComponentTools(server, bridge) {
         };
     });
     // ── get_all_properties ───────────────────────────────────────────
-    server.tool("get_all_properties", "Dump all public properties of a component as JSON — names, types, and current values", {
+    server.tool("get_all_properties", "Dump all public properties of every component on a GameObject as JSON -- names, types, and current values", {
         id: z.string().describe("GUID of the GameObject"),
-        component: z.string().describe("Component type name"),
     }, async (params) => {
         const res = await bridge.send("get_all_properties", params);
         if (!res.success) {

package/dist/tools/gameplay.js

@@ -257,7 +257,59 @@ export function registerGameplayTools(server, bridge) {
         }
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
-    // ── create_pickup ─────────────────────────────────────────────────
+    // ── create_interactable ───────────────────────────────────────────
+    server.tool("create_interactable", "Generate a Component.IPressable interactable: the built-in PlayerController 'use' key drives Press()/Hover()/Blur() with no custom player code. Includes a static OnPressed event, an optional cooldown (TimeUntil), and a private OnPress() extensionpoint for effects. For host-authoritative side-effects call an [Rpc.Host] from OnPress(). The Prompt property is left to your game's HUD. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z.string().optional().describe("Class name. Defaults to 'Interactable'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        prompt: z
+            .string()
+            .optional()
+            .describe("Prompt string shown by the game's HUD when hovering. Defaults to 'Press'"),
+        cooldownSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds before the interactable can be pressed again. 0 = no cooldown. Defaults to 0"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach the component to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_interactable", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_weighted_loot_table ----------------------------------------
+    server.tool("create_weighted_loot_table", "Generate a cumulative-weight random loot picker: parallel Name/Weight lists (inspector-editable), a Roll() method that returns a winning entry name and fires a static OnLoot event, and optional pity (guarantee the last/rarest entry after PityAfter consecutive non-rare rolls). Roll() is host-authoritative -- only call it on the host and replicate the result (clients rolling their own loot is equivalent to clients writing their own money balance). Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z.string().optional().describe("Class name. Defaults to 'LootTable'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        entries: z
+            .union([
+            z.array(z.object({ name: z.string(), weight: z.number() })),
+            z.string().describe('Compact "name:weight,name:weight" string, e.g. "common:70,uncommon:25,rare:5"'),
+        ])
+            .optional()
+            .describe("Loot table entries. Defaults to common:70 / uncommon:25 / rare:5"),
+        pity: z
+            .boolean()
+            .optional()
+            .describe("If true, guarantee the last (rarest) entry after PityAfter consecutive non-rare rolls. Defaults to false"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach to (only if the type is already loaded -- hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_weighted_loot_table", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_pickup -----------------------------------------------------
     server.tool("create_pickup", "Generate a trigger-based collectible component. On enter by a tagged object it raises OnCollected (wire it to your objective/score system) and despawns. Optionally builds a visible pickup GameObject with a trigger SphereCollider (+ a model) in one call", {
         name: z.string().optional().describe("Class name. Defaults to 'Pickup'"),
         directory: z
@@ -298,5 +350,87 @@ export function registerGameplayTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // -- create_save_system ------------------------------------------------
+    server.tool("create_save_system", "Generate a versioned save-system component: a SaveData POCO with Version bump on schema change, dirty-flag autosave on a TimeUntil timer, clamp-on-load Sanitize() for corrupt/hand-edited saves, and delete-on-version-mismatch to start fresh instead of crashing. Runs only on the owning machine (IsProxy guard). Fires static OnLoaded/OnSaved hooks for HUD and analytics. FileSystem.Data.ReadJsonOrDefault/WriteJson verified live on the current SDK. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z.string().optional().describe("Class name. Defaults to 'SaveSystem'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Save file name under FileSystem.Data (e.g. 'save.json'). Defaults to 'save.json'"),
+        version: z
+            .number()
+            .int()
+            .optional()
+            .describe("Schema version embedded in SaveData. Old saves with a different version start fresh. Defaults to 1"),
+        autosaveSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds between autosave ticks (0 disables autosave). Defaults to 10"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach to (only if the type is already loaded -- hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_save_system", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_leaderboard_panel ------------------------------------------
+    server.tool("create_leaderboard_panel", "Generate a Razor PanelComponent that fetches and displays a Sandbox.Services leaderboard derived from a stat name. Produces TWO files: {name}.razor and {name}.razor.scss. The panel auto-refreshes every 30 s, shows rank/displayName/value rows, handles loading state, and includes a BuildHash() override (razor-lint clean). Must be hosted under a ScreenPanel or WorldPanel. Stats must be configured for the project ident on sbox.game. Uses Leaderboards.Get(statName) + board.Refresh() -- the exact API from ServicesQueryHandler.", {
+        name: z.string().optional().describe("Class name for the panel component. Defaults to 'LeaderboardPanel'"),
+        directory: z.string().optional().describe("Subdirectory for the generated files. Defaults to 'Code/UI'"),
+        statName: z.string().optional().describe("Sandbox.Services stat name the leaderboard is derived from. Defaults to 'score'"),
+        title: z.string().optional().describe("Display title shown at the top of the panel. Defaults to 'Leaderboard'"),
+        maxRows: z.number().int().optional().describe("Maximum leaderboard rows to fetch and display. Defaults to 10"),
+    }, async (params) => {
+        const res = await bridge.send("create_leaderboard_panel", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_inventory --------------------------------------------------
+    server.tool("create_inventory", "Generate a slot-based inventory component using parallel List<string> ItemIds / List<int> Counts (serialization-safe, inspector-editable). Includes TryAdd (stack-first, partial-add rejected), TryRemove, CountOf, Move (swap or merge same-id slots), and Clear. Static OnChanged event fires after every successful mutation. Host-authoritative usage note: mutate on the host in multiplayer, replicate via your own [Sync]/RPC. Pairs with create_pickup.", {
+        name: z.string().optional().describe("Class name. Defaults to 'Inventory'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        capacity: z.number().int().optional().describe("Total slot count. Defaults to 24"),
+        maxStack: z.number().int().optional().describe("Maximum items per slot (stack cap). Defaults to 99"),
+        targetId: z.string().optional().describe("GUID of an existing GameObject to attach to (hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_inventory", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_stat_modifier_system ---------------------------------------
+    server.tool("create_stat_modifier_system", "Generate an enum-keyed stat modifier system with three modifier layers: SET (highest-priority-wins hard override), ADD (summed bonuses), MULT (multiplied factors applied last). Modifier storage uses parallel private Lists of primitive types (serialization-safe). RemoveModifiersFrom(source) cleans up all mods from a buff/debuff source by reference. Static OnStatChanged(stat, value) event fires after every add/remove. Mined from RPG/buff/debuff patterns across shipped s&box games.", {
+        name: z.string().optional().describe("Class name prefix -- generates {name}Stat enum + {name} Component. Defaults to 'StatSystem'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        stats: z.union([z.array(z.string()), z.string()]).optional().describe("Stat names as a JSON array or comma-separated string. Defaults to 'Health,Speed,Damage'"),
+        targetId: z.string().optional().describe("GUID of an existing GameObject to attach to (hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_stat_modifier_system", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_placement_mode ---------------------------------------------
+    server.tool("create_placement_mode", "Generate a ghost-preview + commit placement component (single class). StartPlacing() clones GhostPrefab as a NetworkMode.Never preview with colliders disabled and ModelRenderers tinted semi-transparent. Each frame while placing: ray from Scene.Camera.GetMouseRay(), IgnoreGameObjectHierarchy(ghost), snap hit position to GridSize (0 = freeform), move ghost. On Input.Pressed('attack1') TryPlace() re-validates distance and commits a real clone. StopPlacing() destroys the ghost. Static OnPlaced(GameObject, Vector3) event. Includes a multiplayer RPC note. API grounded in building-placement cookbook (enifun.shop_manager pattern).", {
+        name: z.string().optional().describe("Class name. Defaults to 'PlacementMode'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        gridSize: z.number().optional().describe("Snap grid size in world units (0 = freeform placement). Defaults to 0"),
+        targetId: z.string().optional().describe("GUID of an existing GameObject to attach to (hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_placement_mode", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
 }
 //# sourceMappingURL=gameplay.js.map

package/dist/tools/inspection.js

@@ -38,6 +38,30 @@ export function registerInspectionTools(server, bridge) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
+    // ── sandbox_lint ──────────────────────────────────────────────────
+    server.tool("sandbox_lint", "Static-scan the project's C# for s&box sandbox whitelist violations BEFORE they cause compile errors: System.MathF (use MathX), System.Math (use MathX), Array.Clone() (use .ToArray()), System.Net / raw sockets (use Sandbox.Http), System.IO.File (use FileSystem.Data), and raw System.Threading.Thread (use async/Task or GameTask). Returns { scanned, findings: [{file, line, match, advice}], clean }. Scope to a subdirectory with the directory param.", {
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root to scan (e.g. 'Code', 'Code/Player'). Defaults to 'Code'"),
+    }, async (params) => {
+        const res = await bridge.send("sandbox_lint", params);
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── razor_lint ────────────────────────────────────────────────────
+    server.tool("razor_lint", "Static-scan .razor and .razor.scss files for the silent footguns that crash the Razor transpiler or stylesheet engine with no useful error message: switch expressions inside @code blocks (use if/else instead), non-ASCII/emoji inside @code (move to markup or a string constant), PanelComponent subclasses missing a BuildHash override (panel never re-renders), and root uppercase type-selector rules in .razor.scss (silently skipped -- use a class selector like .my-panel). Returns { scanned, findings: [{file, line, match, advice}], clean } matching the sandbox_lint shape.", {
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root to scan (e.g. 'UI', 'Code'). Defaults to 'Code'"),
+    }, async (params) => {
+        const res = await bridge.send("razor_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", {});
@@ -92,7 +116,7 @@ export function registerInspectionTools(server, bridge) {
             z.string().describe('Comma string "x,y,z", e.g. "1,0,0"'),
         ])
             .optional()
-            .describe('AnalogMove vector to apply (forward/left) — object {x,y,z} or comma string "x,y,z"'),
+            .describe('AnalogMove vector to apply (forward/left) -- object {x,y,z} or comma string "x,y,z"'),
         analogLook: z
             .object({ pitch: z.number(), yaw: z.number(), roll: z.number().default(0) })
             .optional()

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "sbox-mcp-server",
-  "version": "1.11.0",
-  "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "sbox-mcp-server": "dist/index.js",
-    "sbox-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "npm run build && node --test",
-    "start": "node dist/index.js",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "sbox",
-    "s&box",
-    "game-engine",
-    "claude",
-    "ai",
-    "source2",
-    "model-context-protocol"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/LouSputthole/Sbox-Claude.git"
-  },
-  "author": "sboxskins.gg (https://sboxskins.gg)",
-  "homepage": "https://sboxskins.gg",
-  "bugs": {
-    "url": "https://github.com/LouSputthole/Sbox-Claude/issues"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "zod": "^3.24.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "license": "AGPL-3.0-or-later"
-}
+{
+  "name": "sbox-mcp-server",
+  "version": "1.13.0",
+  "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "sbox-mcp-server": "dist/index.js",
+    "sbox-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "sbox",
+    "s&box",
+    "game-engine",
+    "claude",
+    "ai",
+    "source2",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LouSputthole/Sbox-Claude.git"
+  },
+  "author": "sboxskins.gg (https://sboxskins.gg)",
+  "homepage": "https://sboxskins.gg",
+  "bugs": {
+    "url": "https://github.com/LouSputthole/Sbox-Claude/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "AGPL-3.0-or-later"
+}