rbxstudio-mcp 2.3.2 → 2.4.0

package/dist/tools/defs/scripts.js

@@ -0,0 +1,163 @@
+/**
+ * Script editing tools — string-based (Claude Code-style) only.
+ *
+ * The legacy line-based partial editors (edit_script_lines /
+ * insert_script_lines / delete_script_lines) were removed: line numbers
+ * shift on every edit, the model has to count manually, and `edit_script`
+ * does the same job more reliably with exact string matching + automatic
+ * syntax validation.
+ *
+ * `search_script` was also removed: the `grep` tool (inspection.ts)
+ * supersedes it — passing a single script path as `grep`'s `path` does
+ * the exact same single-script search, plus everything `grep` adds
+ * (cross-file, glob/type filters, output modes, head limits). Keeping
+ * two near-identical tools just creates choice paralysis for the LLM.
+ */
+export const scriptTools = [
+    {
+        name: 'get_script_source',
+        description: 'Read the source of a Roblox script (LocalScript, Script, or ModuleScript). Returns both `source` (raw) and `numberedSource` (line-numbered, like `cat -n`). ' +
+            '⚠️ For scripts >500 lines, you SHOULD pass `startLine`/`endLine` instead of slurping the whole file — or better, use `search_script` / `get_script_function` to pull just the part you need.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Roblox instance path to the script using dot notation (e.g., "game.ServerScriptService.MainScript", "game.StarterPlayer.StarterPlayerScripts.LocalScript")',
+                },
+                startLine: {
+                    type: 'number',
+                    description: 'Optional: Start line number (1-indexed). RECOMMENDED for any script >500 lines.',
+                },
+                endLine: {
+                    type: 'number',
+                    description: 'Optional: End line number (inclusive). RECOMMENDED for any script >500 lines.',
+                },
+            },
+            required: ['instancePath'],
+        },
+        handler: (args, { tools }) => tools.getScriptSource(args?.instancePath, args?.startLine, args?.endLine),
+    },
+    {
+        name: 'set_script_source',
+        description: '⚠️ EXPENSIVE — FOR FULL REWRITES OR NEW-SCRIPT POPULATION ONLY. Replaces the ENTIRE source of a script. ' +
+            'For any partial change (adding a function, fixing a bug, refactoring a block) use `edit_script` instead — it is dramatically cheaper in tokens and far less likely to silently truncate the file. ' +
+            'Use this tool only when: (a) you just created the script via `create_object` and are populating it from scratch, or (b) you genuinely want to overwrite >80% of the existing source.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Roblox instance path to the script (e.g., "game.ServerScriptService.MainScript")',
+                },
+                source: {
+                    type: 'string',
+                    description: 'New source code for the script (replaces the entire existing content)',
+                },
+            },
+            required: ['instancePath', 'source'],
+        },
+        handler: (args, { tools }) => tools.setScriptSource(args?.instancePath, args?.source),
+    },
+    {
+        name: 'edit_script',
+        description: "RECOMMENDED for all partial script edits. String-based editing like Claude Code's Edit tool: find exact text and replace it — no line numbers, no shifting offsets, no truncation risk. " +
+            'Fails safely if `old_string` is not found, or appears more than once (unless `replace_all` is true). Validates Luau syntax after the edit and reverts if broken.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Roblox instance path to the script (e.g., "game.ServerScriptService.MainScript")',
+                },
+                old_string: {
+                    type: 'string',
+                    description: 'The exact text to find and replace (must match exactly, including whitespace/indentation)',
+                },
+                new_string: {
+                    type: 'string',
+                    description: 'The text to replace it with (must be different from old_string)',
+                },
+                replace_all: {
+                    type: 'boolean',
+                    description: 'If true, replace ALL occurrences of old_string. If false (default), fails if old_string appears more than once.',
+                    default: false,
+                },
+                validate_after: {
+                    type: 'boolean',
+                    description: 'If true (default), validates the script syntax after editing and reverts if invalid.',
+                    default: true,
+                },
+            },
+            required: ['instancePath', 'old_string', 'new_string'],
+        },
+        handler: (args, { tools }) => tools.editScript(args?.instancePath, args?.old_string, args?.new_string, args?.replace_all ?? false, args?.validate_after ?? true),
+    },
+    {
+        name: 'get_script_function',
+        description: 'Extract a specific function from a script by name. Returns the function source code with start/end line numbers. Perfect for editing just one function without affecting the rest of the script.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Roblox instance path to the script (e.g., "game.ServerScriptService.MainScript")',
+                },
+                function_name: {
+                    type: 'string',
+                    description: 'Name of the function to extract (e.g., "onPlayerJoin", "handleDamage")',
+                },
+            },
+            required: ['instancePath', 'function_name'],
+        },
+        handler: (args, { tools }) => tools.getScriptFunction(args?.instancePath, args?.function_name),
+    },
+    {
+        name: 'find_and_replace_in_scripts',
+        description: 'Find and replace text across multiple scripts at once. Like `edit_script` but for batch operations. Validates all scripts after editing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                paths: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of script paths to search and replace in',
+                },
+                old_string: {
+                    type: 'string',
+                    description: 'The exact text to find and replace',
+                },
+                new_string: {
+                    type: 'string',
+                    description: 'The text to replace it with',
+                },
+                validate_after: {
+                    type: 'boolean',
+                    description: 'If true (default), validates syntax after each edit.',
+                    default: true,
+                },
+            },
+            required: ['paths', 'old_string', 'new_string'],
+        },
+        handler: (args, { tools }) => tools.findAndReplaceInScripts(args?.paths, args?.old_string, args?.new_string, args?.validate_after ?? true),
+    },
+    {
+        name: 'validate_script',
+        description: 'Validate Lua/Luau script syntax without running it. Returns syntax errors and warnings for deprecated patterns (wait, spawn, delay). Can validate either an existing script or raw source code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Path to the script to validate (e.g., "game.ServerScriptService.MainScript")',
+                },
+                source: {
+                    type: 'string',
+                    description: 'Raw Lua source code to validate (alternative to instancePath)',
+                },
+            },
+        },
+        handler: (args, { tools }) => tools.validateScript(args?.instancePath, args?.source),
+    },
+];
+//# sourceMappingURL=scripts.js.map

package/dist/tools/defs/scripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.js","sourceRoot":"","sources":["../../../src/tools/defs/scripts.ts"],"names":[],"mappings":"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"}

package/dist/tools/defs/tags.d.ts

@@ -0,0 +1,6 @@
+import type { ToolDef } from '../types.js';
+/**
+ * CollectionService tag tools: list, add, remove, query by tag.
+ */
+export declare const tagTools: ToolDef[];
+//# sourceMappingURL=tags.d.ts.map

package/dist/tools/defs/tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.d.ts","sourceRoot":"","sources":["../../../src/tools/defs/tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAO,EAwE7B,CAAC"}

package/dist/tools/defs/tags.js

@@ -0,0 +1,74 @@
+/**
+ * CollectionService tag tools: list, add, remove, query by tag.
+ */
+export const tagTools = [
+    {
+        name: 'get_tags',
+        description: 'Get all CollectionService tags on a Roblox instance',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Roblox instance path using dot notation (e.g., "game.Workspace.Part")',
+                },
+            },
+            required: ['instancePath'],
+        },
+        handler: (args, { tools }) => tools.getTags(args?.instancePath),
+    },
+    {
+        name: 'add_tag',
+        description: 'Add a CollectionService tag to a Roblox instance',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Roblox instance path using dot notation (e.g., "game.Workspace.Part")',
+                },
+                tagName: {
+                    type: 'string',
+                    description: 'Name of the tag to add',
+                },
+            },
+            required: ['instancePath', 'tagName'],
+        },
+        handler: (args, { tools }) => tools.addTag(args?.instancePath, args?.tagName),
+    },
+    {
+        name: 'remove_tag',
+        description: 'Remove a CollectionService tag from a Roblox instance',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Roblox instance path using dot notation (e.g., "game.Workspace.Part")',
+                },
+                tagName: {
+                    type: 'string',
+                    description: 'Name of the tag to remove',
+                },
+            },
+            required: ['instancePath', 'tagName'],
+        },
+        handler: (args, { tools }) => tools.removeTag(args?.instancePath, args?.tagName),
+    },
+    {
+        name: 'get_tagged',
+        description: 'Get all instances with a specific tag',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tagName: {
+                    type: 'string',
+                    description: 'Name of the tag to search for',
+                },
+            },
+            required: ['tagName'],
+        },
+        handler: (args, { tools }) => tools.getTagged(args?.tagName),
+    },
+];
+//# sourceMappingURL=tags.js.map

package/dist/tools/defs/tags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags.js","sourceRoot":"","sources":["../../../src/tools/defs/tags.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAc;IACjC;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EAAE,qDAAqD;QAClE,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uEAAuE;iBACrF;aACF;YACD,QAAQ,EAAE,CAAC,cAAc,CAAC;SAC3B;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC;KAChE;IAED;QACE,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,kDAAkD;QAC/D,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uEAAuE;iBACrF;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wBAAwB;iBACtC;aACF;YACD,QAAQ,EAAE,CAAC,cAAc,EAAE,SAAS,CAAC;SACtC;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,CAAC;KAC9E;IAED;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,uDAAuD;QACpE,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,YAAY,EAAE;oBACZ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,uEAAuE;iBACrF;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2BAA2B;iBACzC;aACF;YACD,QAAQ,EAAE,CAAC,cAAc,EAAE,SAAS,CAAC;SACtC;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,OAAO,CAAC;KACjF;IAED;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EAAE,uCAAuC;QACpD,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+BAA+B;iBAC7C;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC;KAC7D;CACF,CAAC"}

package/dist/tools/defs/visual.d.ts

@@ -0,0 +1,7 @@
+import type { ToolDef } from '../types.js';
+/**
+ * Visual feedback tools: viewport screenshot, off-screen ViewportFrame
+ * render at any angle, and Studio camera focus (no image).
+ */
+export declare const visualTools: ToolDef[];
+//# sourceMappingURL=visual.d.ts.map

package/dist/tools/defs/visual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual.d.ts","sourceRoot":"","sources":["../../../src/tools/defs/visual.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAkC3C;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,EAqLhC,CAAC"}

package/dist/tools/defs/visual.js

@@ -0,0 +1,208 @@
+import { STILL_FRAME_NUDGE } from '../nudges.js';
+const cameraAngleSchema = {
+    description: 'Camera angle - use preset string or custom object with pitch/yaw/roll/distance',
+    oneOf: [
+        {
+            type: 'string',
+            enum: [
+                'front',
+                'back',
+                'left',
+                'right',
+                'top',
+                'bottom',
+                'iso',
+                'iso_front',
+                'iso_back',
+                'low_angle',
+                'high_angle',
+            ],
+        },
+        {
+            type: 'object',
+            properties: {
+                pitch: { type: 'number', description: 'Pitch angle in degrees' },
+                yaw: { type: 'number', description: 'Yaw angle in degrees' },
+                roll: { type: 'number', description: 'Roll angle in degrees' },
+                distance: { type: 'number', description: 'Camera distance from object' },
+            },
+        },
+    ],
+};
+/**
+ * Visual feedback tools: viewport screenshot, off-screen ViewportFrame
+ * render at any angle, and Studio camera focus (no image).
+ */
+export const visualTools = [
+    {
+        name: 'capture_screenshot',
+        description: 'Capture a screenshot of the current Roblox Studio viewport. Returns the image as base64-encoded RGBA pixel data. Use this to "see" what you\'ve built - GUIs, 3D objects, scene layout, etc. The screenshot captures exactly what\'s visible in the Studio viewport.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                maxWidth: {
+                    type: 'number',
+                    description: 'Maximum width of the returned image (default: 768). Smaller = faster + less data.',
+                    default: 768,
+                },
+                maxHeight: {
+                    type: 'number',
+                    description: 'Maximum height of the returned image (default: 768). Smaller = faster + less data.',
+                    default: 768,
+                },
+            },
+        },
+        nudge: STILL_FRAME_NUDGE,
+        handler: (args, { tools }) => tools.captureScreenshot(args?.maxWidth, args?.maxHeight),
+    },
+    {
+        name: 'render_object_view',
+        description: `Render a 3D object as an image from any angle using an off-screen ViewportFrame — the PRIMARY tool for visual feedback on what you've built. Works in ANY Studio state (Edit/Play/Run) with no CaptureService limits, and gives full control over camera, lighting, and background.
+
+Angles: front, back, left, right, top, bottom, iso, iso_front, iso_back, low_angle, high_angle, or a custom {pitch, yaw, roll} in degrees.
+Lighting presets: bright (3-point), studio (flat/even), dark (dramatic), default (ambient only).
+For 2D GUIs use render_gui instead.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Path to the object to render (e.g., "game.Workspace.Model1")',
+                },
+                angle: cameraAngleSchema,
+                resolution: {
+                    type: 'object',
+                    properties: {
+                        width: { type: 'number', description: 'Image width (64-2048, default: 768)' },
+                        height: { type: 'number', description: 'Image height (64-2048, default: 768)' },
+                    },
+                    description: 'Render resolution',
+                },
+                lighting: {
+                    type: 'string',
+                    enum: ['default', 'bright', 'studio', 'dark', 'showcase', 'dramatic', 'flat'],
+                    description: 'Lighting preset to use (default: bright)',
+                },
+                background: {
+                    type: 'string',
+                    enum: ['transparent', 'grid', 'solid'],
+                    description: 'Background style (default: transparent)',
+                },
+                autoDistance: {
+                    type: 'boolean',
+                    description: 'Automatically calculate camera distance to fit object (default: true)',
+                },
+            },
+            required: ['instancePath'],
+        },
+        nudge: STILL_FRAME_NUDGE,
+        handler: (args, { tools }) => tools.renderObjectView(args?.instancePath, {
+            angle: args?.angle,
+            resolution: args?.resolution,
+            lighting: args?.lighting,
+            background: args?.background,
+            autoDistance: args?.autoDistance,
+        }),
+    },
+    {
+        name: 'render_gui',
+        description: `Render a 2D GUI as an image — the visual-feedback tool for ScreenGuis, Frames, TextLabels, and other UI. render_object_view uses a ViewportFrame (3D only), so it cannot show UI; this captures a real on-screen rendering instead.
+
+Pass any GUI by path (it doesn't have to live under StarterGui — e.g. "game.StarterGui.MainMenu", "game.StarterGui.HUD.HealthBar", or a ScreenGui you stored in ReplicatedStorage). Give a GuiObject (Frame, TextLabel, ImageLabel, …) to render that element, or a ScreenGui/SurfaceGui/BillboardGui to render all of its GuiObject children. Placement is faithful: elements are rendered inside a clone of their real ScreenGui (siblings, layout, and GUI inset intact), not repositioned to a corner.
+
+region:
+- "element" (default): crop tight to the element's on-screen rect — best for inspecting one component's visual correctness. Scale-based sizing renders at its real proportions.
+- "screen": return the full viewport so you can verify WHERE the element actually lands (placement, overlaps, off-screen overflow) relative to the whole screen.
+
+Optionally clamp the output with maxWidth/maxHeight (downscale only, aspect preserved).`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Path to the GUI to render (e.g. "game.StarterGui.MainMenu" or "game.StarterGui.HUD.HealthBar"). Any path works — not just StarterGui. Must be a GuiObject or a ScreenGui/SurfaceGui/BillboardGui.',
+                },
+                region: {
+                    type: 'string',
+                    enum: ['element', 'screen'],
+                    description: 'Crop mode. "element" (default) crops tight to the GUI; "screen" returns the full viewport to check on-screen placement.',
+                    default: 'element',
+                },
+                maxWidth: {
+                    type: 'number',
+                    description: 'Optional max output width in pixels (downscale only, aspect preserved).',
+                },
+                maxHeight: {
+                    type: 'number',
+                    description: 'Optional max output height in pixels (downscale only, aspect preserved).',
+                },
+            },
+            required: ['instancePath'],
+        },
+        nudge: STILL_FRAME_NUDGE,
+        handler: (args, { tools }) => tools.renderGui(args?.instancePath, {
+            region: args?.region,
+            maxWidth: args?.maxWidth,
+            maxHeight: args?.maxHeight,
+        }),
+    },
+    {
+        name: 'focus_camera',
+        description: `Point the Studio camera at an object (like pressing F), auto-fitting distance for any object size. Pairs with capture_screenshot: focus_camera then capture_screenshot.
+
+Angles: front, back, left, right, top, bottom, iso (default), iso_front, iso_back, low_angle, high_angle, or custom {pitch, yaw, roll}. Distance auto-fits from tiny (clamped to ~5 studs) to huge (1000+ studs) objects; override with \`distance\`.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instancePath: {
+                    type: 'string',
+                    description: 'Path to the object to focus on (e.g., "game.Workspace.Model1")',
+                },
+                angle: {
+                    description: 'Camera angle - preset string or custom {pitch, yaw, roll}',
+                    oneOf: [
+                        {
+                            type: 'string',
+                            enum: [
+                                'front',
+                                'back',
+                                'left',
+                                'right',
+                                'top',
+                                'bottom',
+                                'iso',
+                                'iso_front',
+                                'iso_back',
+                                'low_angle',
+                                'high_angle',
+                            ],
+                        },
+                        {
+                            type: 'object',
+                            properties: {
+                                pitch: { type: 'number', description: 'Pitch angle in degrees' },
+                                yaw: { type: 'number', description: 'Yaw angle in degrees' },
+                                roll: { type: 'number', description: 'Roll angle in degrees' },
+                            },
+                        },
+                    ],
+                },
+                distance: {
+                    type: 'number',
+                    description: 'Manual camera distance (overrides auto-distance)',
+                },
+                autoDistance: {
+                    type: 'boolean',
+                    description: 'Automatically calculate distance to fit object (default: true)',
+                },
+            },
+            required: ['instancePath'],
+        },
+        handler: (args, { tools }) => tools.focusCamera(args?.instancePath, {
+            angle: args?.angle,
+            distance: args?.distance,
+            autoDistance: args?.autoDistance,
+        }),
+    },
+];
+//# sourceMappingURL=visual.js.map

package/dist/tools/defs/visual.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual.js","sourceRoot":"","sources":["../../../src/tools/defs/visual.ts"],"names":[],"mappings":"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"}