robloxstudio-mcp 1.6.0 → 1.7.0

package/README.md

@@ -1,280 +1,296 @@
-# Roblox Studio MCP Server
-
-MCP server for AI-powered Roblox Studio integration. 18 specialized tools for exploring projects, analyzing scripts, and performing bulk operations.
-
-<a href="https://glama.ai/mcp/servers/@boshyxd/robloxstudio-mcp">
-  <img width="380" height="200" src="https://glama.ai/mcp/servers/@boshyxd/robloxstudio-mcp/badge" alt="Roblox Studio Server MCP server" />
-</a>
-
-## Quick Start
-
-**For Claude Code users:**
-```bash
-claude mcp add robloxstudio -- npx -y robloxstudio-mcp
-```
-
-**For other MCP clients (Claude Desktop, etc.):**
-```json
-{
-  "mcpServers": {
-    "robloxstudio-mcp": {
-      "command": "npx",
-      "args": ["-y", "robloxstudio-mcp"],
-      "description": "Advanced Roblox Studio integration for AI assistants"
-    }
-  }
-}
-```
-
-## Studio Plugin Setup (Required)
-
-The MCP server requires a companion Roblox Studio plugin:
-
-1. **Roblox Creator Store**:
-   - Install from: https://create.roblox.com/store/asset/75577477776988
-   - Click "Install" - Opens in Studio automatically
-
-2. **Manual download**:
-   - Download [MCPPlugin.rbxmx](https://github.com/boshyxd/robloxstudio-mcp/releases/latest/download/MCPPlugin.rbxmx)
-   - Save to your `%LOCALAPPDATA%/Roblox/Plugins` folder
-
-3. **Advanced setup**:
-   - See [studio-plugin/INSTALLATION.md](studio-plugin/INSTALLATION.md) for other methods
-
-**After installation:**
-- Enable "Allow HTTP Requests" in Game Settings > Security
-- Click the "MCP Server" button in the Plugins toolbar
-- Status should show "Connected" when working
-
-## Architecture Overview
-
-Dual-component system bridging Roblox Studio with AI assistants:
-
-```mermaid
-%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#718096', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#2b6cb0', 'tertiaryColor':'#319795'}}}%%
-graph TB
-    subgraph AI_ENV ["AI Environment"]
-        AI["AI Assistant<br/>Claude Code/Desktop"]
-        MCP["MCP Server<br/>Node.js + TypeScript"]
-    end
-    
-    subgraph COMM_LAYER ["Communication Layer"]
-        HTTP["HTTP Bridge<br/>localhost:3002"]
-        QUEUE["Request Queue<br/>UUID tracking"]
-    end
-    
-    subgraph STUDIO_ENV ["Roblox Studio Environment"]
-        PLUGIN["Studio Plugin<br/>Luau Script"]
-        STUDIO["Roblox Studio<br/>APIs & Data"]
-    end
-    
-    subgraph TOOLS ["18 AI Tools"]
-        FILE["File System<br/>Trees, Search"]
-        CONTEXT["Studio Context<br/>Services, Objects"]
-        PROPS["Properties<br/>Get, Set, Mass Ops"]
-        CREATE["Object Creation<br/>Single, Mass, Properties"]
-        PROJECT["Project Analysis<br/>Smart Structure"]
-    end
-    
-    AI -->|stdio| MCP
-    MCP -->|HTTP POST| HTTP
-    HTTP -->|Queue Request| QUEUE
-    PLUGIN -->|Poll every 500ms| HTTP
-    HTTP -->|Pending Work| PLUGIN
-    PLUGIN -->|Execute APIs| STUDIO
-    STUDIO -->|Return Data| PLUGIN
-    PLUGIN -->|HTTP Response| HTTP
-    HTTP -->|Resolve Promise| MCP
-    MCP -->|Tool Result| AI
-    
-    MCP -.->|Exposes| FILE
-    MCP -.->|Exposes| CONTEXT  
-    MCP -.->|Exposes| PROPS
-    MCP -.->|Exposes| CREATE
-    MCP -.->|Exposes| PROJECT
-    
-    classDef aiStyle fill:#1e40af,stroke:#3b82f6,stroke-width:2px,color:#ffffff
-    classDef mcpStyle fill:#7c3aed,stroke:#8b5cf6,stroke-width:2px,color:#ffffff
-    classDef httpStyle fill:#ea580c,stroke:#f97316,stroke-width:2px,color:#ffffff
-    classDef pluginStyle fill:#059669,stroke:#10b981,stroke-width:2px,color:#ffffff
-    classDef studioStyle fill:#dc2626,stroke:#ef4444,stroke-width:2px,color:#ffffff
-    classDef toolStyle fill:#0891b2,stroke:#06b6d4,stroke-width:2px,color:#ffffff
-    
-    class AI aiStyle
-    class MCP mcpStyle
-    class HTTP,QUEUE httpStyle
-    class PLUGIN pluginStyle
-    class STUDIO studioStyle
-    class FILE,CONTEXT,PROPS,CREATE,PROJECT toolStyle
-```
-
-### Key Components:
-- MCP Server (Node.js/TypeScript) - Exposes 18 tools via stdio
-- HTTP Bridge - Request/response queue on localhost:3002
-- Studio Plugin (Luau) - Polls server and executes API calls
-- Smart Caching - Efficient data transfer
-
-## 18 AI Tools
-
-### File System Tools
-- `get_file_tree` - Complete project hierarchy with scripts, models, folders
-- `search_files` - Find files by name, type, or content patterns  
-
-### Studio Context Tools  
-- `get_place_info` - Place ID, name, game settings, workspace info
-- `get_services` - All Roblox services and their child counts
-- `search_objects` - Find instances by name, class, or properties
-
-### Instance & Property Tools
-- `get_instance_properties` - Complete property dump for any object
-- `get_instance_children` - Child objects with metadata
-- `search_by_property` - Find objects with specific property values
-- `get_class_info` - Available properties/methods for Roblox classes
-
-### Property Modification Tools 
-- `set_property` - Set a property on any Roblox instance
-- `mass_set_property` - Set the same property on multiple instances
-- `mass_get_property` - Get the same property from multiple instances
-
-### Object Creation Tools
-- `create_object` - Create a new Roblox object instance
-- `create_object_with_properties` - Create objects with initial properties
-- `mass_create_objects` - Create multiple objects at once
-- `mass_create_objects_with_properties` - Create multiple objects with properties
-- `delete_object` - Delete a Roblox object instance
-
-### Project Analysis Tools
-- `get_project_structure` - Smart hierarchy with depth control (recommended: 5-10)
-
-> Note: Previous tools removed: `get_file_content`, `get_file_properties`, `get_selection`, `get_dependencies`, `validate_references`. Use Rojo/Argon workflows instead.
-
-## AI-Optimized Features
-
-### Mass Operations (v1.3.0)
-- Bulk property editing
-- Mass object creation
-- Batch property reading
-- Atomic undo/redo operations
-
-```typescript
-// Example: Set multiple parts to red
-mass_set_property(["game.Workspace.Part1", "game.Workspace.Part2"], "BrickColor", "Really red")
-```
-
-### Smart Project Structure
-- Service overview with child counts
-- Path-based exploration: `get_project_structure("game.ServerStorage", maxDepth=5)`
-- Script-only filtering for code analysis
-- Intelligent grouping for large folders
-- Recommended maxDepth=5-10
-
-### Rich Metadata
-- Script status tracking
-- GUI intelligence
-- Performance optimized
-
-## Development & Testing
-
-### Commands
-```bash
-npm run dev         # Development server with hot reload  
-npm run build       # Production build
-npm start           # Run built server
-npm run lint        # ESLint code quality
-npm run typecheck   # TypeScript validation
-```
-
-### Plugin Development
-- Live reload
-- Robust error handling
-- Debug logging
-- Visual status indicators
-
-## Communication Protocol
-
-```mermaid
-%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#10b981', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#3b82f6', 'tertiaryColor':'#8b5cf6', 'background':'#1a202c', 'mainBkg':'#2d3748', 'secondBkg':'#374151', 'tertiaryColor':'#6366f1'}}}%%
-sequenceDiagram
-    participant AI as AI Assistant
-    participant MCP as MCP Server  
-    participant HTTP as HTTP Bridge
-    participant PLUGIN as Studio Plugin
-    participant STUDIO as Roblox Studio
-    
-    Note over AI,STUDIO: Tool Request Flow
-    
-    AI->>+MCP: Call tool (e.g., get_file_tree)
-    MCP->>+HTTP: Queue request with UUID
-    HTTP->>HTTP: Store in pending requests map
-    HTTP-->>-MCP: Request queued
-    
-    Note over PLUGIN: Polling every 500ms
-    PLUGIN->>+HTTP: GET /poll
-    HTTP->>-PLUGIN: Return pending request + UUID
-    
-    PLUGIN->>+STUDIO: Execute Studio APIs
-    Note over STUDIO: game.ServerStorage<br/>Selection:Get()<br/>Instance properties
-    STUDIO->>-PLUGIN: Return Studio data
-    
-    PLUGIN->>+HTTP: POST /response with UUID + data
-    HTTP->>-MCP: Resolve promise with data
-    MCP->>-AI: Return tool result
-    
-    Note over AI,STUDIO: Error Handling
-    
-    alt Request Timeout (30s)
-        HTTP->>MCP: Reject promise with timeout
-        MCP->>AI: Return error message
-    end
-    
-    alt Plugin Disconnected
-        PLUGIN->>HTTP: Connection lost
-        HTTP->>HTTP: Exponential backoff retry
-        Note over PLUGIN: Status: "Waiting for server..."
-    end
-```
-
-**Features:**
-- 30-second timeouts with exponential backoff
-- Automatic retries
-- Response limiting
-- Request deduplication
-
-## Example Usage
-
-```javascript
-// Get service overview
-get_project_structure()
-
-// Explore weapons folder
-get_project_structure("game.ServerStorage.Weapons", maxDepth=2)
-
-// Find all Sound objects  
-search_by_property("ClassName", "Sound")
-
-// Check script dependencies
-get_dependencies("game.ServerScriptService.MainScript")
-
-// Find broken references
-validate_references()
-
-// Get UI component details
-get_instance_properties("game.StarterGui.MainMenu.SettingsFrame")
-```
-
-## Configuration
-
-**Environment Variables:**
-- `MCP_SERVER_PORT` - MCP server port (default: stdio)
-- `HTTP_SERVER_PORT` - HTTP bridge port (default: 3002)
-- `PLUGIN_POLL_INTERVAL` - Plugin poll frequency (default: 500ms)
-- `REQUEST_TIMEOUT` - Request timeout (default: 30000ms)
-
-**Studio Settings:**
-- **Allow HTTP Requests** (Game Settings > Security)
-- **HttpService.HttpEnabled = true**
-- **Plugin activated** via toolbar button
-
-## License
-
+# Roblox Studio MCP Server
+
+MCP server for AI-powered Roblox Studio integration. 18 specialized tools for exploring projects, analyzing scripts, and performing bulk operations.
+
+<a href="https://glama.ai/mcp/servers/@boshyxd/robloxstudio-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@boshyxd/robloxstudio-mcp/badge" alt="Roblox Studio Server MCP server" />
+</a>
+
+## Quick Start
+
+**For Claude Code users:**
+```bash
+claude mcp add robloxstudio -- npx -y robloxstudio-mcp
+```
+
+**For other MCP clients (Claude Desktop, etc.):**
+```json
+{
+  "mcpServers": {
+    "robloxstudio-mcp": {
+      "command": "npx",
+      "args": ["-y", "robloxstudio-mcp"],
+      "description": "Advanced Roblox Studio integration for AI assistants"
+    }
+  }
+}
+```
+
+<details>
+<summary>Note for native Windows users</summary>
+If you encounter issues, you may need to run it through `cmd`. Update your configuration like this:
+
+```json
+{
+  "mcpServers": {
+    "robloxstudio-mcp": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "robloxstudio-mcp@latest"]
+    }
+  }
+}
+```
+</details>
+
+## Studio Plugin Setup (Required)
+
+The MCP server requires a companion Roblox Studio plugin:
+
+1. **Roblox Creator Store**:
+   - Install from: https://create.roblox.com/store/asset/75577477776988
+   - Click "Install" - Opens in Studio automatically
+
+2. **Manual download**:
+   - Download [MCPPlugin.rbxmx](https://github.com/boshyxd/robloxstudio-mcp/releases/latest/download/MCPPlugin.rbxmx)
+   - Save to your `%LOCALAPPDATA%/Roblox/Plugins` folder
+
+3. **Advanced setup**:
+   - See [studio-plugin/INSTALLATION.md](studio-plugin/INSTALLATION.md) for other methods
+
+**After installation:**
+- Enable "Allow HTTP Requests" in Game Settings > Security
+- Click the "MCP Server" button in the Plugins toolbar
+- Status should show "Connected" when working
+
+## Architecture Overview
+
+Dual-component system bridging Roblox Studio with AI assistants:
+
+```mermaid
+%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#718096', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#2b6cb0', 'tertiaryColor':'#319795'}}}%%
+graph TB
+    subgraph AI_ENV ["AI Environment"]
+        AI["AI Assistant<br/>Claude Code/Desktop"]
+        MCP["MCP Server<br/>Node.js + TypeScript"]
+    end
+    
+    subgraph COMM_LAYER ["Communication Layer"]
+        HTTP["HTTP Bridge<br/>localhost:3002"]
+        QUEUE["Request Queue<br/>UUID tracking"]
+    end
+    
+    subgraph STUDIO_ENV ["Roblox Studio Environment"]
+        PLUGIN["Studio Plugin<br/>Luau Script"]
+        STUDIO["Roblox Studio<br/>APIs & Data"]
+    end
+    
+    subgraph TOOLS ["18 AI Tools"]
+        FILE["File System<br/>Trees, Search"]
+        CONTEXT["Studio Context<br/>Services, Objects"]
+        PROPS["Properties<br/>Get, Set, Mass Ops"]
+        CREATE["Object Creation<br/>Single, Mass, Properties"]
+        PROJECT["Project Analysis<br/>Smart Structure"]
+    end
+    
+    AI -->|stdio| MCP
+    MCP -->|HTTP POST| HTTP
+    HTTP -->|Queue Request| QUEUE
+    PLUGIN -->|Poll every 500ms| HTTP
+    HTTP -->|Pending Work| PLUGIN
+    PLUGIN -->|Execute APIs| STUDIO
+    STUDIO -->|Return Data| PLUGIN
+    PLUGIN -->|HTTP Response| HTTP
+    HTTP -->|Resolve Promise| MCP
+    MCP -->|Tool Result| AI
+    
+    MCP -.->|Exposes| FILE
+    MCP -.->|Exposes| CONTEXT  
+    MCP -.->|Exposes| PROPS
+    MCP -.->|Exposes| CREATE
+    MCP -.->|Exposes| PROJECT
+    
+    classDef aiStyle fill:#1e40af,stroke:#3b82f6,stroke-width:2px,color:#ffffff
+    classDef mcpStyle fill:#7c3aed,stroke:#8b5cf6,stroke-width:2px,color:#ffffff
+    classDef httpStyle fill:#ea580c,stroke:#f97316,stroke-width:2px,color:#ffffff
+    classDef pluginStyle fill:#059669,stroke:#10b981,stroke-width:2px,color:#ffffff
+    classDef studioStyle fill:#dc2626,stroke:#ef4444,stroke-width:2px,color:#ffffff
+    classDef toolStyle fill:#0891b2,stroke:#06b6d4,stroke-width:2px,color:#ffffff
+    
+    class AI aiStyle
+    class MCP mcpStyle
+    class HTTP,QUEUE httpStyle
+    class PLUGIN pluginStyle
+    class STUDIO studioStyle
+    class FILE,CONTEXT,PROPS,CREATE,PROJECT toolStyle
+```
+
+### Key Components:
+- MCP Server (Node.js/TypeScript) - Exposes 18 tools via stdio
+- HTTP Bridge - Request/response queue on localhost:3002
+- Studio Plugin (Luau) - Polls server and executes API calls
+- Smart Caching - Efficient data transfer
+
+## 18 AI Tools
+
+### File System Tools
+- `get_file_tree` - Complete project hierarchy with scripts, models, folders
+- `search_files` - Find files by name, type, or content patterns  
+
+### Studio Context Tools  
+- `get_place_info` - Place ID, name, game settings, workspace info
+- `get_services` - All Roblox services and their child counts
+- `search_objects` - Find instances by name, class, or properties
+
+### Instance & Property Tools
+- `get_instance_properties` - Complete property dump for any object
+- `get_instance_children` - Child objects with metadata
+- `search_by_property` - Find objects with specific property values
+- `get_class_info` - Available properties/methods for Roblox classes
+
+### Property Modification Tools 
+- `set_property` - Set a property on any Roblox instance
+- `mass_set_property` - Set the same property on multiple instances
+- `mass_get_property` - Get the same property from multiple instances
+
+### Object Creation Tools
+- `create_object` - Create a new Roblox object instance
+- `create_object_with_properties` - Create objects with initial properties
+- `mass_create_objects` - Create multiple objects at once
+- `mass_create_objects_with_properties` - Create multiple objects with properties
+- `delete_object` - Delete a Roblox object instance
+
+### Project Analysis Tools
+- `get_project_structure` - Smart hierarchy with depth control (recommended: 5-10)
+
+> Note: Previous tools removed: `get_file_content`, `get_file_properties`, `get_selection`, `get_dependencies`, `validate_references`. Use Rojo/Argon workflows instead.
+
+## AI-Optimized Features
+
+### Mass Operations (v1.3.0)
+- Bulk property editing
+- Mass object creation
+- Batch property reading
+- Atomic undo/redo operations
+
+```typescript
+// Example: Set multiple parts to red
+mass_set_property(["game.Workspace.Part1", "game.Workspace.Part2"], "BrickColor", "Really red")
+```
+
+### Smart Project Structure
+- Service overview with child counts
+- Path-based exploration: `get_project_structure("game.ServerStorage", maxDepth=5)`
+- Script-only filtering for code analysis
+- Intelligent grouping for large folders
+- Recommended maxDepth=5-10
+
+### Rich Metadata
+- Script status tracking
+- GUI intelligence
+- Performance optimized
+
+## Development & Testing
+
+### Commands
+```bash
+npm run dev         # Development server with hot reload  
+npm run build       # Production build
+npm start           # Run built server
+npm run lint        # ESLint code quality
+npm run typecheck   # TypeScript validation
+```
+
+### Plugin Development
+- Live reload
+- Robust error handling
+- Debug logging
+- Visual status indicators
+
+## Communication Protocol
+
+```mermaid
+%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#10b981', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#3b82f6', 'tertiaryColor':'#8b5cf6', 'background':'#1a202c', 'mainBkg':'#2d3748', 'secondBkg':'#374151', 'tertiaryColor':'#6366f1'}}}%%
+sequenceDiagram
+    participant AI as AI Assistant
+    participant MCP as MCP Server  
+    participant HTTP as HTTP Bridge
+    participant PLUGIN as Studio Plugin
+    participant STUDIO as Roblox Studio
+    
+    Note over AI,STUDIO: Tool Request Flow
+    
+    AI->>+MCP: Call tool (e.g., get_file_tree)
+    MCP->>+HTTP: Queue request with UUID
+    HTTP->>HTTP: Store in pending requests map
+    HTTP-->>-MCP: Request queued
+    
+    Note over PLUGIN: Polling every 500ms
+    PLUGIN->>+HTTP: GET /poll
+    HTTP->>-PLUGIN: Return pending request + UUID
+    
+    PLUGIN->>+STUDIO: Execute Studio APIs
+    Note over STUDIO: game.ServerStorage<br/>Selection:Get()<br/>Instance properties
+    STUDIO->>-PLUGIN: Return Studio data
+    
+    PLUGIN->>+HTTP: POST /response with UUID + data
+    HTTP->>-MCP: Resolve promise with data
+    MCP->>-AI: Return tool result
+    
+    Note over AI,STUDIO: Error Handling
+    
+    alt Request Timeout (30s)
+        HTTP->>MCP: Reject promise with timeout
+        MCP->>AI: Return error message
+    end
+    
+    alt Plugin Disconnected
+        PLUGIN->>HTTP: Connection lost
+        HTTP->>HTTP: Exponential backoff retry
+        Note over PLUGIN: Status: "Waiting for server..."
+    end
+```
+
+**Features:**
+- 30-second timeouts with exponential backoff
+- Automatic retries
+- Response limiting
+- Request deduplication
+
+## Example Usage
+
+```javascript
+// Get service overview
+get_project_structure()
+
+// Explore weapons folder
+get_project_structure("game.ServerStorage.Weapons", maxDepth=2)
+
+// Find all Sound objects  
+search_by_property("ClassName", "Sound")
+
+// Check script dependencies
+get_dependencies("game.ServerScriptService.MainScript")
+
+// Find broken references
+validate_references()
+
+// Get UI component details
+get_instance_properties("game.StarterGui.MainMenu.SettingsFrame")
+```
+
+## Configuration
+
+**Environment Variables:**
+- `MCP_SERVER_PORT` - MCP server port (default: stdio)
+- `HTTP_SERVER_PORT` - HTTP bridge port (default: 3002)
+- `PLUGIN_POLL_INTERVAL` - Plugin poll frequency (default: 500ms)
+- `REQUEST_TIMEOUT` - Request timeout (default: 30000ms)
+
+**Studio Settings:**
+- **Allow HTTP Requests** (Game Settings > Security)
+- **HttpService.HttpEnabled = true**
+- **Plugin activated** via toolbar button
+
+## License
+
 MIT License - Feel free to use in commercial and personal projects!