rbxstudio-mcp 2.3.1 → 2.4.0

package/dist/index.js

@@ -2,17 +2,16 @@
 /**
  * Roblox Studio MCP Server
  *
- * This server provides Model Context Protocol (MCP) tools for interacting with Roblox Studio.
- * It allows AI assistants to access Studio data, scripts, and objects through a bridge plugin.
+ * This server provides Model Context Protocol (MCP) tools for interacting
+ * with Roblox Studio. It allows AI assistants to access Studio data,
+ * scripts, and objects through a bridge plugin.
  *
- * Usage:
- *   npx robloxstudio-mcp
+ * Tools are defined declaratively in `src/tools/defs/*.ts` and aggregated
+ * by `src/tools/registry.ts`. To add a new tool, edit one of those files —
+ * this bootstrap doesn't need to change.
  *
- * Or add to your MCP configuration:
- *   "robloxstudio": {
- *     "command": "npx",
- *     "args": ["-y", "robloxstudio-mcp"]
- *   }
+ * Usage:
+ *   npx rbxstudio-mcp
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -20,6 +19,8 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } f
 import { createHttpServer } from './http-server.js';
 import { RobloxStudioTools } from './tools/index.js';
 import { BridgeService } from './bridge-service.js';
+import { allTools, toolsByName, applyNudge } from './tools/registry.js';
+import { SERVER_INSTRUCTIONS } from './instructions.js';
 class RobloxStudioMCPServer {
     server;
     tools;
@@ -32,1039 +33,35 @@ class RobloxStudioMCPServer {
             capabilities: {
                 tools: {},
             },
+            // Always-on operating manual (mental model + cross-tool workflow);
+            // returned in the initialize response and usually folded into the
+            // client's system prompt. See src/instructions.ts.
+            instructions: SERVER_INSTRUCTIONS,
         });
         this.bridge = new BridgeService();
         this.tools = new RobloxStudioTools(this.bridge);
         this.setupToolHandlers();
     }
     setupToolHandlers() {
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-            return {
-                tools: [
-                    // Studio Context Tools
-                    {
-                        name: 'get_place_info',
-                        description: 'Get place ID, name, and game settings',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {}
-                        }
-                    },
-                    {
-                        name: 'get_services',
-                        description: 'Get available Roblox services and their children',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                serviceName: {
-                                    type: 'string',
-                                    description: 'Optional specific service name to query'
-                                }
-                            }
-                        }
-                    },
-                    // Property & Instance Tools
-                    {
-                        name: 'get_instance_properties',
-                        description: 'Get all properties of a specific Roblox instance in Studio',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Roblox instance path using dot notation (e.g., "game.Workspace.Part", "game.ServerScriptService.MainScript", "game.ReplicatedStorage.ModuleScript")'
-                                }
-                            },
-                            required: ['instancePath']
-                        }
-                    },
-                    {
-                        name: 'get_class_info',
-                        description: 'Get available properties/methods for Roblox classes',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                className: {
-                                    type: 'string',
-                                    description: 'Roblox class name'
-                                }
-                            },
-                            required: ['className']
-                        }
-                    },
-                    // Project Tools
-                    {
-                        name: 'get_project_structure',
-                        description: 'Get complete game hierarchy. IMPORTANT: Use maxDepth parameter (default: 3) to explore deeper levels of the hierarchy. Set higher values like 5-10 for comprehensive exploration',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                path: {
-                                    type: 'string',
-                                    description: 'Optional path to start from (defaults to workspace root)',
-                                    default: ''
-                                },
-                                maxDepth: {
-                                    type: 'number',
-                                    description: 'Maximum depth to traverse (default: 3). RECOMMENDED: Use 5-10 for thorough exploration. Higher values provide more complete structure',
-                                    default: 3
-                                },
-                                scriptsOnly: {
-                                    type: 'boolean',
-                                    description: 'Show only scripts and script containers',
-                                    default: false
-                                }
-                            }
-                        }
-                    },
-                    // Property Modification Tools
-                    {
-                        name: 'set_property',
-                        description: 'Set a property on any Roblox instance',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Path to the instance (e.g., "game.Workspace.Part")'
-                                },
-                                propertyName: {
-                                    type: 'string',
-                                    description: 'Name of the property to set'
-                                },
-                                propertyValue: {
-                                    description: 'Value to set the property to (any type)'
-                                }
-                            },
-                            required: ['instancePath', 'propertyName', 'propertyValue']
-                        }
-                    },
-                    {
-                        name: 'mass_set_property',
-                        description: 'Set the same property on multiple instances at once',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                paths: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Array of instance paths to modify'
-                                },
-                                propertyName: {
-                                    type: 'string',
-                                    description: 'Name of the property to set'
-                                },
-                                propertyValue: {
-                                    description: 'Value to set the property to (any type)'
-                                }
-                            },
-                            required: ['paths', 'propertyName', 'propertyValue']
-                        }
-                    },
-                    {
-                        name: 'mass_get_property',
-                        description: 'Get the same property from multiple instances at once',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                paths: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Array of instance paths to read from'
-                                },
-                                propertyName: {
-                                    type: 'string',
-                                    description: 'Name of the property to get'
-                                }
-                            },
-                            required: ['paths', 'propertyName']
-                        }
-                    },
-                    // Object Creation/Deletion Tools
-                    {
-                        name: 'create_object',
-                        description: 'Create a new Roblox object instance (basic, without properties)',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                className: {
-                                    type: 'string',
-                                    description: 'Roblox class name (e.g., "Part", "Script", "Folder")'
-                                },
-                                parent: {
-                                    type: 'string',
-                                    description: 'Path to the parent instance (e.g., "game.Workspace")'
-                                },
-                                name: {
-                                    type: 'string',
-                                    description: 'Optional name for the new object'
-                                }
-                            },
-                            required: ['className', 'parent']
-                        }
-                    },
-                    {
-                        name: 'delete_object',
-                        description: 'Delete a Roblox object instance',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Path to the instance to delete'
-                                }
-                            },
-                            required: ['instancePath']
-                        }
-                    },
-                    // Script Management Tools (for Roblox Studio scripts - NOT local files)
-                    {
-                        name: 'get_script_source',
-                        description: 'Get the source code of a Roblox script (LocalScript, Script, or ModuleScript). Returns both "source" (raw code) and "numberedSource" (with line numbers prefixed like "1: code"). Use numberedSource to accurately identify line numbers for editing. For large scripts (>1500 lines), use startLine/endLine to read specific sections.',
-                        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). Use for reading specific sections of large scripts.'
-                                },
-                                endLine: {
-                                    type: 'number',
-                                    description: 'Optional: End line number (inclusive). Use for reading specific sections of large scripts.'
-                                }
-                            },
-                            required: ['instancePath']
-                        }
-                    },
-                    {
-                        name: 'set_script_source',
-                        description: 'Replace the entire source code of a Roblox script. Uses ScriptEditorService:UpdateSourceAsync (works with open editors). For partial edits, prefer edit_script_lines, insert_script_lines, or delete_script_lines.',
-                        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'
-                                }
-                            },
-                            required: ['instancePath', 'source']
-                        }
-                    },
-                    // Partial Script Editing Tools - use "numberedSource" from get_script_source to identify correct line numbers
-                    {
-                        name: 'edit_script_lines',
-                        description: 'Replace specific lines in a Roblox script without rewriting the entire source. IMPORTANT: Use the "numberedSource" field from get_script_source to identify the correct line numbers. Lines are 1-indexed and ranges are inclusive.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Roblox instance path to the script (e.g., "game.ServerScriptService.MainScript")'
-                                },
-                                startLine: {
-                                    type: 'number',
-                                    description: 'First line to replace (1-indexed). Get this from the "numberedSource" field.'
-                                },
-                                endLine: {
-                                    type: 'number',
-                                    description: 'Last line to replace (inclusive). Get this from the "numberedSource" field.'
-                                },
-                                newContent: {
-                                    type: 'string',
-                                    description: 'New content to replace the specified lines (can be multiple lines separated by newlines)'
-                                }
-                            },
-                            required: ['instancePath', 'startLine', 'endLine', 'newContent']
-                        }
-                    },
-                    {
-                        name: 'insert_script_lines',
-                        description: 'Insert new lines into a Roblox script at a specific position. IMPORTANT: Use the "numberedSource" field from get_script_source to identify the correct line numbers.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Roblox instance path to the script (e.g., "game.ServerScriptService.MainScript")'
-                                },
-                                afterLine: {
-                                    type: 'number',
-                                    description: 'Insert after this line number (0 = insert at very beginning, 1 = after first line). Get line numbers from "numberedSource".',
-                                    default: 0
-                                },
-                                newContent: {
-                                    type: 'string',
-                                    description: 'Content to insert (can be multiple lines separated by newlines)'
-                                }
-                            },
-                            required: ['instancePath', 'newContent']
-                        }
-                    },
-                    {
-                        name: 'delete_script_lines',
-                        description: 'Delete specific lines from a Roblox script. IMPORTANT: Use the "numberedSource" field from get_script_source to identify the correct line numbers.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Roblox instance path to the script (e.g., "game.ServerScriptService.MainScript")'
-                                },
-                                startLine: {
-                                    type: 'number',
-                                    description: 'First line to delete (1-indexed). Get this from the "numberedSource" field.'
-                                },
-                                endLine: {
-                                    type: 'number',
-                                    description: 'Last line to delete (inclusive). Get this from the "numberedSource" field.'
-                                }
-                            },
-                            required: ['instancePath', 'startLine', 'endLine']
-                        }
-                    },
-                    // ============================================
-                    // CLAUDE CODE-STYLE SCRIPT EDITING TOOLS
-                    // ============================================
-                    {
-                        name: 'edit_script',
-                        description: 'RECOMMENDED: String-based script editing like Claude Code\'s Edit tool. Find exact text and replace it - no line numbers needed! This is the safest and most reliable way to edit scripts. The edit will FAIL safely if old_string is not found or appears multiple times (unless replace_all is true). Always validates syntax after editing.',
-                        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']
-                        }
-                    },
-                    {
-                        name: 'search_script',
-                        description: 'Search for patterns within a script source code (like grep). Returns matching lines with line numbers and optional context.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Roblox instance path to the script (e.g., "game.ServerScriptService.MainScript")'
-                                },
-                                pattern: {
-                                    type: 'string',
-                                    description: 'Search pattern (literal string or regex if use_regex is true)'
-                                },
-                                use_regex: {
-                                    type: 'boolean',
-                                    description: 'If true, treat pattern as a Lua regex pattern. Default false (literal match).',
-                                    default: false
-                                },
-                                context_lines: {
-                                    type: 'number',
-                                    description: 'Number of lines to show before and after each match (like grep -C). Default 0.',
-                                    default: 0
-                                }
-                            },
-                            required: ['instancePath', 'pattern']
-                        }
-                    },
-                    {
-                        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']
-                        }
-                    },
-                    {
-                        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']
-                        }
-                    },
-                    // Attribute Tools (for Roblox instance attributes)
-                    {
-                        name: 'get_attribute',
-                        description: 'Get a single attribute value from a Roblox instance',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Roblox instance path using dot notation (e.g., "game.Workspace.Part", "game.ServerStorage.DataStore")'
-                                },
-                                attributeName: {
-                                    type: 'string',
-                                    description: 'Name of the attribute to get'
-                                }
-                            },
-                            required: ['instancePath', 'attributeName']
-                        }
-                    },
-                    {
-                        name: 'set_attribute',
-                        description: 'Set an attribute value on a Roblox instance. Supports string, number, boolean, Vector3, Color3, UDim2, and BrickColor.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Roblox instance path using dot notation (e.g., "game.Workspace.Part")'
-                                },
-                                attributeName: {
-                                    type: 'string',
-                                    description: 'Name of the attribute to set'
-                                },
-                                attributeValue: {
-                                    description: 'Value to set. For Vector3: {X, Y, Z}, Color3: {R, G, B}, UDim2: {X: {Scale, Offset}, Y: {Scale, Offset}}'
-                                },
-                                valueType: {
-                                    type: 'string',
-                                    description: 'Optional type hint: "Vector3", "Color3", "UDim2", "BrickColor"'
-                                }
-                            },
-                            required: ['instancePath', 'attributeName', 'attributeValue']
-                        }
-                    },
-                    {
-                        name: 'get_attributes',
-                        description: 'Get all attributes 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']
-                        }
-                    },
-                    {
-                        name: 'delete_attribute',
-                        description: 'Delete an attribute from a Roblox instance',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Roblox instance path using dot notation (e.g., "game.Workspace.Part")'
-                                },
-                                attributeName: {
-                                    type: 'string',
-                                    description: 'Name of the attribute to delete'
-                                }
-                            },
-                            required: ['instancePath', 'attributeName']
-                        }
-                    },
-                    // Tag Tools (CollectionService) - for Roblox instance tags
-                    {
-                        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']
-                        }
-                    },
-                    {
-                        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']
-                        }
-                    },
-                    {
-                        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']
-                        }
-                    },
-                    {
-                        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']
-                        }
-                    },
-                    {
-                        name: 'get_selection',
-                        description: 'Get all currently selected objects',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {}
-                        }
-                    },
-                    // ============================================
-                    // OUTPUT CAPTURE TOOL
-                    // ============================================
-                    {
-                        name: 'get_output',
-                        description: 'Read the Output window content from Roblox Studio. Captures print(), warn(), and error() messages. Use after play_solo to debug scripts.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                limit: {
-                                    type: 'number',
-                                    description: 'Maximum number of messages to return (default: 100)',
-                                    default: 100
-                                },
-                                since: {
-                                    type: 'number',
-                                    description: 'Only return messages after this Unix timestamp'
-                                },
-                                messageTypes: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Filter by message type: MessageOutput, MessageInfo, MessageWarning, MessageError'
-                                },
-                                clear: {
-                                    type: 'boolean',
-                                    description: 'Clear the output buffer after reading (default: false)',
-                                    default: false
-                                }
-                            }
-                        }
-                    },
-                    // ============================================
-                    // INSTANCE MANIPULATION TOOLS
-                    // ============================================
-                    {
-                        name: 'clone_instance',
-                        description: 'Clone (copy) a Roblox instance to a new parent location. Creates a deep copy including all children and properties.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                sourcePath: {
-                                    type: 'string',
-                                    description: 'Path to the instance to clone (e.g., "game.Workspace.walkietalkie")'
-                                },
-                                targetParent: {
-                                    type: 'string',
-                                    description: 'Path to the new parent (e.g., "game.ReplicatedStorage")'
-                                },
-                                newName: {
-                                    type: 'string',
-                                    description: 'Optional new name for the cloned instance'
-                                }
-                            },
-                            required: ['sourcePath', 'targetParent']
-                        }
-                    },
-                    {
-                        name: 'move_instance',
-                        description: 'Move a Roblox instance to a new parent location. Changes the Parent property.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Path to the instance to move (e.g., "game.Workspace.Tool")'
-                                },
-                                newParent: {
-                                    type: 'string',
-                                    description: 'Path to the new parent (e.g., "game.StarterPack")'
-                                }
-                            },
-                            required: ['instancePath', 'newParent']
-                        }
-                    },
-                    // ============================================
-                    // SCRIPT VALIDATION TOOL
-                    // ============================================
-                    {
-                        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)'
-                                }
-                            }
-                        }
-                    },
-                    // ============================================
-                    // UNDO/REDO TOOLS
-                    // ============================================
-                    {
-                        name: 'undo',
-                        description: 'Undo the last change made in Roblox Studio. All MCP mutations are automatically recorded for undo support. Use this to revert mistakes.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {}
-                        }
-                    },
-                    {
-                        name: 'redo',
-                        description: 'Redo a previously undone change in Roblox Studio.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {}
-                        }
-                    },
-                    // ============================================
-                    // ASSET INSERTION TOOL (Creator Store)
-                    // ============================================
-                    {
-                        name: 'insert_asset',
-                        description: 'Download and insert a Creator Store asset (model, package, etc.) into Roblox Studio for reference. Uses game:GetObjects() which works with any free/public asset. Perfect for loading reference code, example implementations, or asset libraries that the AI can then read and analyze using get_instance_children and get_script_source.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                assetId: {
-                                    type: 'number',
-                                    description: 'The Creator Store asset ID (the number from the asset URL, e.g., 104116977416770)'
-                                },
-                                folderName: {
-                                    type: 'string',
-                                    description: 'Name of the folder to create/use for storing assets (default: "AIReferences")',
-                                    default: 'AIReferences'
-                                },
-                                targetParent: {
-                                    type: 'string',
-                                    description: 'Parent path where the folder should be created (default: "game.Workspace"). Use "game.ReplicatedStorage" or "game.ServerStorage" to keep assets out of the visible workspace.',
-                                    default: 'game.Workspace'
-                                }
-                            },
-                            required: ['assetId']
-                        }
-                    },
-                    // ============================================
-                    // PLAYTEST CONTROL TOOLS
-                    // ============================================
-                    {
-                        name: 'play_solo',
-                        description: 'Start a play test (Play Solo) in Roblox Studio via StudioTestService:ExecutePlayModeAsync. Automatically injects an in-test companion script so stop_play and get_playtest_output work. If a previous test is still tracked, stops it first. Returns a sessionId that ties together start, stop, and output reads.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {}
-                        }
-                    },
-                    {
-                        name: 'stop_play',
-                        description: 'Stop the current play test cleanly via StudioTestService:EndTest (called from inside the test by an injected companion script). Restores pre-play state — unlike RunService:Stop, this is the proper way to end a Play Solo session. Idempotent: returns successfully if no test is running.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {}
-                        }
-                    },
-                    {
-                        name: 'get_playtest_output',
-                        description: 'Read script output (print/warn/error) captured DURING a play test session. Streamed live from the test\'s Server DataModel by the injected companion. Survives after the test ends so you can debug post-hoc. For non-playtest output (Edit-mode plugin output, build messages), use get_output instead. Use the sinceSeq cursor returned in nextSinceSeq to tail incrementally.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                sinceSeq: {
-                                    type: 'number',
-                                    description: 'Only return entries with seq > this value. Pass back nextSinceSeq from a prior call to avoid re-reading.',
-                                },
-                                limit: {
-                                    type: 'number',
-                                    description: 'Max entries to return (default 500, max 5000).',
-                                    default: 500,
-                                },
-                                messageTypes: {
-                                    type: 'array',
-                                    items: { type: 'string' },
-                                    description: 'Filter by MessageType: MessageOutput, MessageInfo, MessageWarning, MessageError.',
-                                },
-                            },
-                        },
-                    },
-                    // ============================================
-                    // SCREENSHOT TOOL
-                    // ============================================
-                    {
-                        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
-                                }
-                            }
-                        }
-                    },
-                    // ============================================
-                    // VIEWPORTFRAME RENDERING (Visual feedback)
-                    // ============================================
-                    {
-                        name: 'render_object_view',
-                        description: `Render an object as an image from any angle using ViewportFrame. This is the PRIMARY tool for visual feedback - use it whenever you need to "see" what you've created or verify visual appearance.
-
-Works in ANY Studio state (Edit/Play/Run) - no CaptureService limitations!
-Instant rendering with full control over camera, lighting, and background.
-
-Use cases:
-- Verify visual appearance of created objects
-- Generate thumbnails/previews
-- Debug positioning and orientation
-- Iterate on visual designs
-- Show users what their objects look like
-
-Available camera angles: front, back, left, right, top, bottom, iso (isometric), iso_front, iso_back, low_angle, high_angle
-Or provide custom angles with pitch/yaw/roll in degrees.
-
-Lighting presets: bright (3-point lighting), studio (flat/even), dark (dramatic), default (ambient only)`,
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                instancePath: {
-                                    type: 'string',
-                                    description: 'Path to the object to render (e.g., "game.Workspace.Model1")',
-                                },
-                                angle: {
-                                    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' },
-                                            },
-                                        },
-                                    ],
-                                },
-                                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'],
-                        },
-                    },
-                    // ============================================
-                    // CAMERA CONTROL (Focus Studio camera)
-                    // ============================================
-                    {
-                        name: 'focus_camera',
-                        description: `Position the Studio camera to focus on an object (like pressing F in Studio).
-Automatically calculates distance to fit the object in view, works with any object size.
-
-Perfect combo with capture_screenshot:
-1. focus_camera({instancePath: "...", angle: "front"})
-2. capture_screenshot()
-
-Supported angles:
-- Standard views: front, back, left, right, top, bottom
-- Isometric: iso (default), iso_front, iso_back
-- Dramatic: low_angle, high_angle
-- Custom: {pitch: 30, yaw: 45, roll: 0}
-
-Auto-sizing:
-- Tiny objects (0.1 studs): Camera backs up to minimum 5 studs
-- Normal objects (10 studs): Camera positioned perfectly
-- Huge objects (1000 studs): Camera backs up far enough to see everything`,
-                        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'],
-                        },
-                    },
-                    // ============================================
-                    // EXECUTE LUA TOOL (Run arbitrary Lua code)
-                    // ============================================
-                    {
-                        name: 'execute_lua',
-                        description: 'Execute arbitrary Lua/Luau code in Roblox Studio. This is a powerful tool that runs code directly in the Studio plugin context with access to all services, Instance constructors, and the full Roblox API. Use this for complex operations that would require multiple tool calls, debugging, prototyping, or any task that\'s easier to express in code. Returns the result of the last expression.',
-                        inputSchema: {
-                            type: 'object',
-                            properties: {
-                                code: {
-                                    type: 'string',
-                                    description: 'The Lua/Luau code to execute. Has access to: game, workspace, all services (Players, ReplicatedStorage, etc.), Instance constructors (Vector3, CFrame, Color3, etc.), and helper function getInstanceByPath(path). Return a value to get it back in the response.'
-                                }
-                            },
-                            required: ['code']
-                        }
-                    }
-                ]
-            };
-        });
+        // List tools — strip handlers, expose only MCP-visible fields.
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: allTools.map(({ name, description, inputSchema }) => ({
+                name,
+                description,
+                inputSchema,
+            })),
+        }));
+        // Dispatch a single tool call via the registry.
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
+            const tool = toolsByName[name];
+            if (!tool) {
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+            }
             try {
-                switch (name) {
-                    // Studio Context Tools
-                    case 'get_place_info':
-                        return await this.tools.getPlaceInfo();
-                    case 'get_services':
-                        return await this.tools.getServices(args?.serviceName);
-                    // Property & Instance Tools
-                    case 'get_instance_properties':
-                        return await this.tools.getInstanceProperties(args?.instancePath);
-                    case 'get_class_info':
-                        return await this.tools.getClassInfo(args?.className);
-                    // Project Tools
-                    case 'get_project_structure':
-                        return await this.tools.getProjectStructure(args?.path, args?.maxDepth, args?.scriptsOnly);
-                    // Property Modification Tools
-                    case 'set_property':
-                        return await this.tools.setProperty(args?.instancePath, args?.propertyName, args?.propertyValue);
-                    // Mass Property Tools
-                    case 'mass_set_property':
-                        return await this.tools.massSetProperty(args?.paths, args?.propertyName, args?.propertyValue);
-                    case 'mass_get_property':
-                        return await this.tools.massGetProperty(args?.paths, args?.propertyName);
-                    // Object Creation/Deletion Tools
-                    case 'create_object':
-                        return await this.tools.createObject(args?.className, args?.parent, args?.name);
-                    case 'delete_object':
-                        return await this.tools.deleteObject(args?.instancePath);
-                    // Script Management Tools
-                    case 'get_script_source':
-                        return await this.tools.getScriptSource(args?.instancePath, args?.startLine, args?.endLine);
-                    case 'set_script_source':
-                        return await this.tools.setScriptSource(args?.instancePath, args?.source);
-                    // Partial Script Editing Tools (line-based - legacy)
-                    case 'edit_script_lines':
-                        return await this.tools.editScriptLines(args?.instancePath, args?.startLine, args?.endLine, args?.newContent);
-                    case 'insert_script_lines':
-                        return await this.tools.insertScriptLines(args?.instancePath, args?.afterLine, args?.newContent);
-                    case 'delete_script_lines':
-                        return await this.tools.deleteScriptLines(args?.instancePath, args?.startLine, args?.endLine);
-                    // Claude Code-Style Script Editing Tools (RECOMMENDED)
-                    case 'edit_script':
-                        return await this.tools.editScript(args?.instancePath, args?.old_string, args?.new_string, args?.replace_all ?? false, args?.validate_after ?? true);
-                    case 'search_script':
-                        return await this.tools.searchScript(args?.instancePath, args?.pattern, args?.use_regex ?? false, args?.context_lines ?? 0);
-                    case 'get_script_function':
-                        return await this.tools.getScriptFunction(args?.instancePath, args?.function_name);
-                    case 'find_and_replace_in_scripts':
-                        return await this.tools.findAndReplaceInScripts(args?.paths, args?.old_string, args?.new_string, args?.validate_after ?? true);
-                    // Attribute Tools
-                    case 'get_attribute':
-                        return await this.tools.getAttribute(args?.instancePath, args?.attributeName);
-                    case 'set_attribute':
-                        return await this.tools.setAttribute(args?.instancePath, args?.attributeName, args?.attributeValue, args?.valueType);
-                    case 'get_attributes':
-                        return await this.tools.getAttributes(args?.instancePath);
-                    case 'delete_attribute':
-                        return await this.tools.deleteAttribute(args?.instancePath, args?.attributeName);
-                    // Tag Tools (CollectionService)
-                    case 'get_tags':
-                        return await this.tools.getTags(args?.instancePath);
-                    case 'add_tag':
-                        return await this.tools.addTag(args?.instancePath, args?.tagName);
-                    case 'remove_tag':
-                        return await this.tools.removeTag(args?.instancePath, args?.tagName);
-                    case 'get_tagged':
-                        return await this.tools.getTagged(args?.tagName);
-                    // Selection Tools
-                    case 'get_selection':
-                        return await this.tools.getSelection();
-                    // Output Capture Tool
-                    case 'get_output':
-                        return await this.tools.getOutput(args?.limit, args?.since, args?.messageTypes, args?.clear);
-                    // Instance Manipulation Tools
-                    case 'clone_instance':
-                        return await this.tools.cloneInstance(args?.sourcePath, args?.targetParent, args?.newName);
-                    case 'move_instance':
-                        return await this.tools.moveInstance(args?.instancePath, args?.newParent);
-                    // Script Validation Tool
-                    case 'validate_script':
-                        return await this.tools.validateScript(args?.instancePath, args?.source);
-                    // Undo/Redo Tools
-                    case 'undo':
-                        return await this.tools.undo();
-                    case 'redo':
-                        return await this.tools.redo();
-                    // Asset Insertion Tool
-                    case 'insert_asset':
-                        return await this.tools.insertAsset(args?.assetId, args?.folderName, args?.targetParent);
-                    // Playtest Control Tools
-                    case 'play_solo':
-                        return await this.tools.playSolo();
-                    case 'stop_play':
-                        return await this.tools.stopPlay();
-                    case 'get_playtest_output':
-                        return await this.tools.getPlaytestOutput(args?.sinceSeq, args?.limit, args?.messageTypes);
-                    // Screenshot Tool
-                    case 'capture_screenshot':
-                        return await this.tools.captureScreenshot(args?.maxWidth, args?.maxHeight);
-                    // ViewportFrame Rendering
-                    case 'render_object_view':
-                        return await this.tools.renderObjectView(args?.instancePath, {
-                            angle: args?.angle,
-                            resolution: args?.resolution,
-                            lighting: args?.lighting,
-                            background: args?.background,
-                            autoDistance: args?.autoDistance,
-                        });
-                    // Camera Control
-                    case 'focus_camera':
-                        return await this.tools.focusCamera(args?.instancePath, {
-                            angle: args?.angle,
-                            distance: args?.distance,
-                            autoDistance: args?.autoDistance,
-                        });
-                    // Execute Lua Tool
-                    case 'execute_lua':
-                        return await this.tools.executeLua(args?.code);
-                    default:
-                        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
-                }
+                const result = await tool.handler(args ?? {}, { tools: this.tools });
+                // Append the tool's just-in-time steering (no-op if it has none).
+                return applyNudge(result, tool.nudge);
             }
             catch (error) {
                 throw new McpError(ErrorCode.InternalError, `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -1072,7 +69,9 @@ Auto-sizing:
         });
     }
     async run() {
-        const port = process.env.ROBLOX_STUDIO_PORT ? parseInt(process.env.ROBLOX_STUDIO_PORT) : 3002;
+        const port = process.env.ROBLOX_STUDIO_PORT
+            ? parseInt(process.env.ROBLOX_STUDIO_PORT)
+            : 3002;
         const host = process.env.ROBLOX_STUDIO_HOST || '0.0.0.0';
         const httpServer = createHttpServer(this.tools, this.bridge);
         await new Promise((resolve) => {
@@ -1086,11 +85,12 @@ Auto-sizing:
         console.error('Roblox Studio MCP server running on stdio');
         httpServer.setMCPServerActive(true);
         console.error('MCP server marked as active');
-        console.error('Waiting for Studio plugin to connect...');
+        console.error(`Registered ${allTools.length} tools, waiting for Studio plugin...`);
         setInterval(() => {
             const pluginConnected = httpServer.isPluginConnected();
             const mcpActive = httpServer.isMCPServerActive();
             if (pluginConnected && mcpActive) {
+                // both up; quiet
             }
             else if (pluginConnected && !mcpActive) {
                 console.error('Studio plugin connected, but MCP server inactive');