robloxstudio-mcp 1.0.3 → 1.1.0

package/README.md

@@ -1,104 +1,181 @@
 # Roblox Studio MCP Server
 
-An MCP (Model Context Protocol) server that provides AI tools access to Roblox Studio data through a plugin-based architecture.
+A powerful MCP (Model Context Protocol) server that gives AI assistants comprehensive access to Roblox Studio projects. Explore game architecture, analyze scripts, debug issues, and understand complex Roblox projects through 15 specialized AI tools.
 
-## Quick Installation
+## ⚡ Quick Start (One Command)
 
-### For End Users (Easy Setup)
-
-Add to your MCP configuration (like in Claude Desktop or other MCP clients):
+**For Claude Code users:**
+```bash
+claude mcp add robloxstudio-mcp
+```
 
+**For other MCP clients (Claude Desktop, etc.):**
 ```json
 {
   "mcpServers": {
-    "robloxstudio": {
+    "robloxstudio-mcp": {
       "command": "npx",
       "args": ["-y", "robloxstudio-mcp"],
-      "description": "Roblox Studio integration for AI assistants"
+      "description": "Advanced Roblox Studio integration for AI assistants"
     }
   }
 }
 ```
 
-Or use with Claude Code MCP add command:
-```bash
-claude mcp add robloxstudio -- npx -y robloxstudio-mcp
-```
+## 🔌 Studio Plugin Setup (Required)
+
+The MCP server requires a companion Roblox Studio plugin:
 
-### For Developers
+1. **Auto-install** (Recommended):
+   - Download from [studio-plugin/plugin.luau](studio-plugin/plugin.luau)
+   - Save as `RobloxStudioMCP.luau` in your `%LOCALAPPDATA%/Roblox/Plugins` folder
 
-1. **Clone and install:**
-   ```bash
-   git clone <repo-url>
-   cd robloxstudio-mcp
-   npm install
-   ```
+2. **Manual setup**:
+   - See [studio-plugin/INSTALLATION.md](studio-plugin/INSTALLATION.md) for detailed instructions
 
-2. **Build and test:**
-   ```bash
-   npm run build
-   npm start
-   ```
+3. **Enable in Studio**:
+   - ✅ Enable "Allow HTTP Requests" in Game Settings → Security
+   - 🔘 Click the "MCP Server" button in the Plugins toolbar
+   - 🟢 Status should show "Connected" when working
 
-## Studio Plugin Setup
+## 🏗️ Architecture Overview
 
-**Required for both installation methods:**
+This is a **dual-component system** bridging Roblox Studio with AI assistants:
 
-1. **Install the Studio plugin:**
-   - See [studio-plugin/INSTALLATION.md](studio-plugin/INSTALLATION.md) for detailed instructions
-   - Enable HTTP Requests in Game Settings
-   - Activate the plugin using the toolbar button
+```
+AI Assistant ←→ MCP Server ←→ HTTP Bridge ←→ Studio Plugin ←→ Roblox Studio APIs
+```
+
+- **🧠 MCP Server** (Node.js/TypeScript) - Exposes 15 tools via stdio for AI integration
+- **🔗 HTTP Bridge** - Request/response queue on localhost:3002 with 30s timeouts  
+- **🎮 Studio Plugin** (Luau) - Polls every 500ms, executes Studio API calls, handles errors
+- **📊 Smart Caching** - Efficient data transfer with intelligent response limiting
+
+## 🛠️ 15 Powerful AI Tools
+
+### 📁 **File System Tools**
+- **`get_file_tree`** - Complete project hierarchy with scripts, models, folders
+- **`get_file_content`** - Extract source code from any script
+- **`search_files`** - Find files by name, type, or content patterns  
+- **`get_file_properties`** - Script metadata, parent/child relationships
+
+### 🎯 **Studio Context Tools**  
+- **`get_place_info`** - Place ID, name, game settings, workspace info
+- **`get_services`** - All Roblox services and their child counts
+- **`get_selection`** - Currently selected objects in Studio Explorer
+- **`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 (scripts, GUI types, etc.)
+- **`search_by_property`** - Find objects with specific property values
+- **`get_class_info`** - Available properties/methods for Roblox classes
+
+### 🏢 **Project Analysis Tools**
+- **`get_project_structure`** - **🆕 AI-Optimized!** Smart hierarchy with depth control
+- **`get_dependencies`** - Module dependency mapping and require() analysis  
+- **`validate_references`** - Find broken script references and missing modules
+
+## 🧠 AI-Optimized Features
+
+### **Smart Project Structure** 
+- **Service Overview Mode**: Clean service list with child counts
+- **Path-based Exploration**: `get_project_structure("game.ServerStorage", maxDepth=3)`
+- **Script-only Filtering**: `scriptsOnly=true` for code analysis
+- **Intelligent Grouping**: Large folders auto-group by class type
+- **Progressive Discovery**: Depth limits prevent context bloat
+
+### **Rich Metadata**
+- **Script Status**: Enabled/disabled, source detection, script types
+- **GUI Intelligence**: Text content, visibility, container vs interactive
+- **Dependency Mapping**: Complete require() call analysis
+- **Reference Validation**: 27+ issue types detected automatically
+
+## 🎮 Perfect for Game Analysis
+
+This tool excels at understanding complex Roblox projects. Based on testing with a professional FPS game:
+
+**Discovered Architecture:**
+- ✅ **9 weapon categories** (Assault, Shotgun, SMG, Pistol, Sniper, DMR, etc.)
+- ✅ **74 settings-related modules** (comprehensive settings system)  
+- ✅ **Modular MainModule design** (professional organization)
+- ✅ **Custom frameworks** ("Vaunt" networking, BetterReplication)
+- ✅ **27 broken references** found and categorized
+
+**Use Cases:**
+- 🔍 **Code Review**: Find all scripts using a specific module
+- 🐛 **Debugging**: Locate broken requires and missing dependencies  
+- 📐 **Architecture Analysis**: Understand game structure and patterns
+- ⚡ **Performance Audit**: Find heavy scripts and unused assets
+- 🎨 **UI Exploration**: Map GUI hierarchies and text content
+
+## 🚀 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**: Plugin updates automatically detect server changes
+- **Error handling**: Robust timeout and retry mechanisms  
+- **Debug mode**: Detailed logging in Studio Output window
+- **Connection status**: Visual indicators in plugin UI
 
-## Architecture
+## 📊 Communication Protocol
 
-- **MCP Server** (TypeScript/Node.js) - Handles AI tool calls via stdio
-- **Studio Plugin** (Luau) - Extracts Studio data and communicates with MCP server
-- **HTTP Bridge** - Communication layer between plugin and server (localhost:3002)
+**Request Flow:**
+1. 🤖 AI calls MCP tool → 📡 MCP server queues request
+2. 🔄 Studio plugin polls /poll endpoint every 500ms  
+3. ⚙️ Plugin executes Studio API calls (game.ServerStorage, etc.)
+4. 📤 Plugin posts response to /response endpoint
+5. ✅ MCP server resolves promise → AI receives data
 
-## Development
+**Features:**
+- **🕐 30-second timeouts** with exponential backoff
+- **🔄 Automatic retries** for network issues  
+- **📏 Response limiting** prevents context overflow
+- **🎯 Request deduplication** for efficiency
 
-- `npm run dev` - Start development server with hot reload
-- `npm run build` - Build TypeScript to JavaScript
-- `npm run lint` - Run ESLint
-- `npm run typecheck` - Run TypeScript type checking
+## 🎯 Example Usage
 
-## Available Tools
+```javascript
+// Get service overview
+get_project_structure()
 
-### File System Tools
-- `get_file_tree` - Complete hierarchy with script types, models, folders
-- `get_file_content` - Retrieve script source code
-- `search_files` - Find files by name, type, or content patterns
-- `get_file_properties` - Script properties, parent/child relationships
+// Explore weapons folder
+get_project_structure("game.ServerStorage.Weapons", maxDepth=2)
 
-### Studio Context Tools
-- `get_place_info` - Place ID, name, game settings
-- `get_services` - Available Roblox services and their children
-- `get_selection` - Currently selected objects in Studio
-- `search_objects` - Find instances by name, class, properties
+// Find all Sound objects  
+search_by_property("ClassName", "Sound")
 
-### Property & Instance Tools
-- `get_instance_properties` - All properties of a specific instance
-- `get_instance_children` - Child objects and their types
-- `search_by_property` - Find objects with specific property values
-- `get_class_info` - Available properties/methods for Roblox classes
+// Check script dependencies
+get_dependencies("game.ServerScriptService.MainScript")
 
-### Project Tools
-- `get_project_structure` - Complete game hierarchy
-- `get_dependencies` - Module dependencies and relationships
-- `validate_references` - Check for broken script references
+// Find broken references
+validate_references()
+
+// Get UI component details
+get_instance_properties("game.StarterGui.MainMenu.SettingsFrame")
+```
 
-## Communication Protocol
+## 🔧 Configuration
 
-The MCP server exposes tools via stdio for AI integration. The Studio plugin polls the server on port 3002 using HTTP requests. When an AI tool is called:
+**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)
 
-1. MCP server queues the request
-2. Studio plugin polls and receives the request
-3. Plugin extracts data using Studio APIs
-4. Plugin sends response back to server
-5. Server returns result to AI tool
+**Studio Settings:**
+- ✅ **Allow HTTP Requests** (Game Settings → Security)
+- 🌐 **HttpService.HttpEnabled = true**
+- 🔌 **Plugin activated** via toolbar button
 
-## Configuration
+## 📄 License
 
-The server can be configured through environment variables:
-- `MCP_SERVER_PORT` - Server port (default: 3001)
-- `STUDIO_PLUGIN_URL` - Studio plugin URL (default: http://localhost:3002)
+MIT License - Feel free to use in commercial and personal projects!

package/dist/tools/index.d.ts

@@ -74,7 +74,7 @@ export declare class RobloxStudioTools {
             text: string;
         }[];
     }>;
-    getProjectStructure(): Promise<{
+    getProjectStructure(path?: string, maxDepth?: number, scriptsOnly?: boolean): Promise<{
         content: {
             type: string;
             text: string;

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,EAAE,aAAa;IAK3B,WAAW,CAAC,IAAI,GAAE,MAAW;;;;;;IAY7B,cAAc,CAAC,IAAI,EAAE,MAAM;;;;;;IAe3B,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAe;;;;;;IAYtD,iBAAiB,CAAC,IAAI,EAAE,MAAM;;;;;;IAgB9B,YAAY;;;;;;IAYZ,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM;;;;;;IAYhC,YAAY;;;;;;IAYZ,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAe,EAAE,YAAY,CAAC,EAAE,MAAM;;;;;;IAiB/E,qBAAqB,CAAC,YAAY,EAAE,MAAM;;;;;;IAe1C,mBAAmB,CAAC,YAAY,EAAE,MAAM;;;;;;IAexC,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;;;;;;IAkB5D,YAAY,CAAC,SAAS,EAAE,MAAM;;;;;;IAgB9B,mBAAmB;;;;;;IAYnB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM;;;;;;IAYnC,kBAAkB;;;;;;CAWzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,EAAE,aAAa;IAK3B,WAAW,CAAC,IAAI,GAAE,MAAW;;;;;;IAY7B,cAAc,CAAC,IAAI,EAAE,MAAM;;;;;;IAe3B,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAe;;;;;;IAYtD,iBAAiB,CAAC,IAAI,EAAE,MAAM;;;;;;IAgB9B,YAAY;;;;;;IAYZ,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM;;;;;;IAYhC,YAAY;;;;;;IAYZ,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,GAAE,MAAe,EAAE,YAAY,CAAC,EAAE,MAAM;;;;;;IAiB/E,qBAAqB,CAAC,YAAY,EAAE,MAAM;;;;;;IAe1C,mBAAmB,CAAC,YAAY,EAAE,MAAM;;;;;;IAexC,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;;;;;;IAkB5D,YAAY,CAAC,SAAS,EAAE,MAAM;;;;;;IAgB9B,mBAAmB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO;;;;;;IAgB3E,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM;;;;;;IAYnC,kBAAkB;;;;;;CAWzB"}

package/dist/tools/index.js

@@ -165,8 +165,12 @@ export class RobloxStudioTools {
         };
     }
     // Project Tools
-    async getProjectStructure() {
-        const response = await this.client.request('/api/project-structure', {});
+    async getProjectStructure(path, maxDepth, scriptsOnly) {
+        const response = await this.client.request('/api/project-structure', {
+            path,
+            maxDepth,
+            scriptsOnly
+        });
         return {
             content: [
                 {

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGtD,MAAM,OAAO,iBAAiB;IACpB,MAAM,CAAmB;IAEjC,YAAY,MAAqB;QAC/B,IAAI,CAAC,MAAM,GAAG,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,oBAAoB;IACpB,KAAK,CAAC,WAAW,CAAC,OAAe,EAAE;QACjC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,IAAY;QAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;QAC3D,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1E,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,aAAqB,MAAM;QAC1D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;QACvF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,iBAAiB,CAAC,IAAY;QAClC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7E,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,uBAAuB;IACvB,KAAK,CAAC,YAAY;QAChB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;QAClE,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,WAAoB;QACpC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QAC7E,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY;QAChB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;QACjE,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,KAAa,EAAE,aAAqB,MAAM,EAAE,YAAqB;QACnF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE;YAChE,KAAK;YACL,UAAU;YACV,YAAY;SACb,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,4BAA4B;IAC5B,KAAK,CAAC,qBAAqB,CAAC,YAAoB;QAC9C,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,0BAA0B,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;QACzF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAC,YAAoB;QAC5C,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;QACvF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,YAAoB,EAAE,aAAqB;QAChE,IAAI,CAAC,YAAY,IAAI,CAAC,aAAa,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,yBAAyB,EAAE;YACpE,YAAY;YACZ,aAAa;SACd,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,YAAY,CAAC,SAAiB;QAClC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC/D,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7E,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,gBAAgB;IAChB,KAAK,CAAC,mBAAmB;QACvB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC,CAAC;QACzE,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,UAAmB;QACvC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;QAChF,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,kBAAkB;QACtB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC;QAC3E,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;iBACxC;aACF;SACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "robloxstudio-mcp",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "MCP Server for Roblox Studio Integration - Access Studio data, scripts, and objects through AI tools",
   "main": "dist/index.js",
   "type": "module",

package/studio-plugin/INSTALLATION.md

@@ -1,105 +1,126 @@
 # Roblox Studio MCP Plugin Installation Guide
 
-## Prerequisites
+Complete your AI assistant integration with this easy-to-install Studio plugin. Works with Claude Code, Claude Desktop, and any MCP-compatible AI.
 
-1. Roblox Studio installed and running
-2. MCP server running on your local machine
-3. HTTP Requests enabled in Studio (Game Settings > Security > Allow HTTP Requests)
+## 🚀 Quick Installation (Recommended)
 
-## Installation Steps
+### **Method 1: Direct Download** ⭐
+1. **Download the plugin:**
+   - **GitHub Release**: [Download plugin.luau](https://github.com/boshyxd/robloxstudio-mcp/releases/latest/download/plugin.luau)
+   - Save as `RobloxStudioMCP.luau` 
 
-### Method 1: Local Plugin Installation (Recommended for Development)
+2. **Install to plugins folder:**
+   - **Windows**: Save to `%LOCALAPPDATA%/Roblox/Plugins/`
+   - **macOS**: Save to `~/Documents/Roblox/Plugins/`
+   - **Or use Studio**: Plugins tab → Plugins Folder → drop the file
 
-1. **Save the plugin file:**
-   - Copy the `plugin.lua` file content
-   - In Roblox Studio, create a new Script in any location
-   - Paste the plugin code into the script
-   - Save the script locally (File > Save to File) as `MCPPlugin.lua`
+3. **Restart Roblox Studio** - Plugin appears automatically!
 
-2. **Install as local plugin:**
-   - In Studio, go to the "Plugins" tab
-   - Click "Plugins Folder" to open your local plugins directory
-   - Copy your saved `MCPPlugin.lua` file into this folder
-   - Restart Roblox Studio
+### **Method 2: Save as Local Plugin**
+1. **Copy the plugin code:**
+   - Open [plugin.luau](https://github.com/boshyxd/robloxstudio-mcp/blob/main/studio-plugin/plugin.luau) on GitHub
+   - Copy all the code (Ctrl+A, Ctrl+C)
 
-3. **Verify installation:**
-   - After restart, you should see "MCP Integration" in your plugins toolbar
-   - Click the "MCP Server" button to activate the plugin
-
-### Method 2: Plugin Script Installation
-
-1. **Create plugin script:**
-   - In Roblox Studio, open any place
-   - In the Explorer, navigate to `ServerScriptService`
-   - Right-click and select "Insert Object" > "Script"
-   - Name it "MCPPlugin"
+2. **Create in Studio:**
+   - Open Roblox Studio with any place
+   - Create a new Script in ServerScriptService  
    - Paste the plugin code
-
-2. **Convert to plugin:**
-   - Right-click the script
-   - Select "Save as Local Plugin..."
-   - Give it a name like "MCP Integration"
-   - Click Save
-
-3. **The plugin will be immediately available in your toolbar**
-
-## Configuration
-
-1. **Enable HTTP Requests:**
-   - Open Game Settings (Home tab > Game Settings)
-   - Navigate to Security
-   - Enable "Allow HTTP Requests"
-   - Save settings
-
-2. **Start MCP Server:**
-   - In your terminal, navigate to the MCP server directory
-   - Run: `npm start`
-   - The server should start on port 3002
-
-3. **Activate Plugin:**
-   - Click the "MCP Server" button in the toolbar
-   - The status window should show "MCP Server: Active" in green
-   - The plugin will now poll for requests from the MCP server
-
-## Usage
-
-Once activated, the plugin will:
-- Poll the MCP server every 500ms for incoming requests
-- Process requests for Studio data (scripts, instances, properties, etc.)
-- Send responses back to the MCP server
-- Display connection status in the dock widget
-
-## Troubleshooting
-
-### Plugin doesn't appear in toolbar
-- Ensure the plugin file was saved in the correct plugins folder
-- Try restarting Roblox Studio
-- Check Output window for any error messages
-
-### "HTTP 403 Forbidden" errors
-- Make sure "Allow HTTP Requests" is enabled in Game Settings
-- Verify the MCP server is running on the correct port (3002)
-
-### Connection timeout errors
-- Check that the MCP server is running (`npm start`)
-- Ensure no firewall is blocking localhost connections
-- Verify the server URLs in the plugin match your setup
-
-### Plugin shows "Disconnected"
-- Click the MCP Server button to activate
-- Check the Output window for error messages
-- Ensure the MCP server is accessible at http://localhost:3002
-
-## Security Notes
-
-- The plugin only works with local servers (localhost)
-- No external connections are made
-- All data stays on your local machine
-- The plugin only reads data, it doesn't modify your place
-
-## Development Tips
-
-- Use the Output window to see debug messages
-- The status widget shows real-time connection status
-- You can modify polling interval in the plugin code if needed
-- For debugging, add print statements to track request/response flow
+   - **Right-click script** → **"Save as Local Plugin..."**
+   - Name it "Roblox Studio MCP"
+
+3. **Plugin appears immediately** in your toolbar!
+
+## ⚙️ Setup & Configuration
+
+### **1. Enable HTTP Requests (Required)**
+🔐 **Game Settings** → **Security** → ✅ **"Allow HTTP Requests"**
+
+### **2. Activate the Plugin**
+🔘 **Plugins toolbar** → Click **"MCP Server"** button
+- 🟢 **Green status** = Connected and ready
+- 🔴 **Red status** = Disconnected (normal until MCP server runs)
+
+### **3. Install MCP Server** 
+Choose your AI assistant:
+
+**For Claude Code:**
+```bash
+claude mcp add robloxstudio-mcp
+```
+
+**For Claude Desktop/Others:**
+```json
+{
+  "mcpServers": {
+    "robloxstudio-mcp": {
+      "command": "npx",
+      "args": ["-y", "robloxstudio-mcp"]
+    }
+  }
+}
+```
+
+## 🎯 How It Works
+
+1. **🤖 AI calls tool** → MCP server queues request
+2. **🔄 Plugin polls** every 500ms for work
+3. **⚙️ Plugin executes** Studio API calls  
+4. **📤 Plugin responds** with extracted data
+5. **✅ AI receives** comprehensive Studio information
+
+**Available Tools:** 15 specialized tools for file trees, dependencies, properties, project structure, and more!
+
+## 🔧 Troubleshooting
+
+### **Plugin Missing from Toolbar**
+- ✅ Verify file saved to correct plugins folder
+- 🔄 Restart Roblox Studio completely
+- 📝 Check Output window for error messages
+
+### **"HTTP 403 Forbidden" Errors**  
+- ✅ Enable "Allow HTTP Requests" in Game Settings → Security
+- 🔍 Verify MCP server is running (status should show connected)
+
+### **Plugin Shows "Disconnected"**
+- ✅ **Normal behavior** when MCP server isn't running
+- 🔘 Click "MCP Server" button to activate
+- 📡 Install MCP server using commands above
+
+### **Connection Issues**
+- 🔥 Check Windows Firewall isn't blocking localhost:3002
+- 🖥️ Restart both Studio and your AI assistant
+- 📝 Check Studio Output window for detailed error messages
+
+## 🔒 Security & Privacy
+
+- 🏠 **Local-only**: All communication stays on your machine
+- 🚫 **No external servers**: Plugin only talks to localhost
+- 👁️ **Read-only access**: Plugin extracts data but never modifies your place
+- 🔐 **No data collection**: Your projects remain private
+
+## 🛠️ Advanced Usage
+
+### **Plugin Features**
+- **Real-time status**: Visual connection indicators
+- **Smart polling**: Exponential backoff for failed connections  
+- **Error recovery**: Automatic retry with timeout handling
+- **Debug friendly**: Comprehensive logging in Output window
+
+### **Customization**
+- 📝 **Server URL**: Modify in plugin UI (default: http://localhost:3002)
+- ⏱️ **Poll interval**: 500ms default (editable in code)
+- 🔧 **Timeout settings**: 30-second request timeouts
+
+### **Development Mode**
+```lua
+-- Enable debug logging in plugin code:
+local DEBUG_MODE = true
+```
+
+## 💡 Pro Tips
+
+- 🖥️ **Keep Studio open** while using AI assistants
+- 🔄 **Plugin auto-connects** when MCP server starts
+- 📊 **Monitor status** via the dock widget
+- 🎯 **Use AI tools** to explore game architecture, find bugs, analyze dependencies
+- 🚀 **Perfect for** code reviews, debugging, and understanding complex projects!