sbox-mcp-server 1.8.0 → 1.9.0

package/README.md

@@ -1,10 +1,10 @@
 # sbox-mcp-server
 
-MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **150+ tools** for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, navmesh & spatial queries, particles, self-diagnosis, console/C# execution, live docs search, and type discovery.
+MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **170+ tools** for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, navmesh & spatial queries, particles, animation, NPC brains, playable-game scaffolds, networking & scene inspection/lint, save & services queries, self-diagnosis, console/C# execution, live docs search, and type discovery.
 
 ## Fastest install — the Claude Code plugin
 
-If you use Claude Code, the easiest install is the companion plugin. It registers this MCP server automatically, ships a workflow skill, and includes the `sbox-game-dev` specialist agent.
+If you use Claude Code, the easiest install is the companion plugin. It registers this MCP server automatically, ships the workflow + recipe skills (`sbox-build-feature`, `sbox-api`, `sbox-cookbook`, `sbox-scaffold-game`, `sbox-setup`), and includes the `sbox-game-dev` specialist agent.
 
 ```
 /plugin marketplace add LouSputthole/Sbox-Claude
@@ -54,7 +54,7 @@ Claude Code → (stdio) → sbox-mcp-server → (file IPC) → bridge addon →
 
 Communication uses file-based IPC through `%TEMP%/sbox-bridge-ipc/`. The MCP server writes request JSON files, the bridge addon (running inside s&box) polls and processes on the main editor thread, then writes response files back. WebSocket is not used — s&box's sandboxed C# environment blocks `System.Net`.
 
-## Tools (v1.5.2)
+## Tools (v1.9.0)
 
 `get_bridge_status` reports the `handlerCount` — that's the C# handlers compiled inside the editor. Six tools run **MCP-server-side** and need no editor handler: `read_log`, `get_compile_errors`, `execute_csharp`, `search_docs`, `get_doc_page`, `list_doc_categories`. They read the log / hotload-eval / fetch docs directly, so they keep working even when the editor has crashed or stalled.
 
@@ -99,6 +99,7 @@ Communication uses file-based IPC through `%TEMP%/sbox-bridge-ipc/`. The MCP ser
 | **Console / Exec** *(v1.5.0)* | console_run, execute_csharp *(experimental)* |
 | **Object utilities** *(v1.5.0)* | remove_component, get_tags |
 | **Docs search** *(v1.5.0, MCP-server-side)* | search_docs, get_doc_page, list_doc_categories — official `Facepunch/sbox-docs` |
+| **Inspection & validation** *(v1.9.0)* | inspect_networked_object (per-object `Network.*` + every component's `[Sync]` fields/values), networking_lint (static scan for `[Sync]`/RPC footguns), scene_validate (no-camera / stray root Rigidbody / trigger-vs-trace), save_inspect (list/read/diff `FileSystem.Data` saves), services_query (`Sandbox.Services` stats + leaderboards), simulate_input (drive named input actions in play mode) |
 
 ## Working with Claude effectively
 
@@ -126,6 +127,6 @@ The companion plugin's `sbox-build-feature` skill encodes this workflow plus the
 
 ## License
 
-**GPL-3.0** — see [LICENSE](../LICENSE) for details.
+**AGPL-3.0-or-later** — see [LICENSE](../LICENSE) and [NOTICE](../NOTICE) for details. The code is open under AGPL; the "s&box Claude Bridge" / "sboxskins.gg" name and branding may not be reused to pass a fork off as the original.
 
 Copyright (c) 2026 [sboxskins.gg](https://sboxskins.gg)

package/dist/index.js

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

package/dist/tools/inspection.d.ts

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

package/dist/tools/inspection.js

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

package/package.json

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