{"_id":"@dariusa/robloxstudio-mcp","name":"@dariusa/robloxstudio-mcp","dist-tags":{"latest":"1.6.0"},"versions":{"1.6.0":{"name":"@dariusa/robloxstudio-mcp","version":"1.6.0","description":"MCP Server for Roblox Studio Integration - Access Studio data, scripts, and objects through AI tools","main":"dist/index.js","type":"module","bin":{"robloxstudio-mcp":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx src/index.ts","start":"node dist/index.js","lint":"eslint src/**/*.ts","typecheck":"tsc --noEmit","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"keywords":["mcp","roblox","studio","ai","model-context-protocol","game-development"],"author":{"name":"dariusa"},"engines":{"node":">=16.0.0"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/boshyxd/robloxstudio-mcp.git"},"homepage":"https://github.com/boshyxd/robloxstudio-mcp#readme","bugs":{"url":"https://github.com/boshyxd/robloxstudio-mcp/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^0.6.0","cors":"^2.8.5","express":"^4.18.2","node-fetch":"^3.3.2","uuid":"^9.0.1","ws":"^8.14.2"},"devDependencies":{"@types/cors":"^2.8.17","@types/express":"^4.17.21","@types/jest":"^29.5.11","@types/node":"^20.10.0","@types/supertest":"^6.0.2","@types/uuid":"^9.0.7","@types/ws":"^8.5.10","@typescript-eslint/eslint-plugin":"^7.0.0","@typescript-eslint/parser":"^7.0.0","eslint":"^8.57.0","jest":"^29.7.0","supertest":"^6.3.3","ts-jest":"^29.1.1","tsx":"^4.6.0","typescript":"^5.3.2"},"_id":"@dariusa/robloxstudio-mcp@1.6.0","types":"./dist/index.d.ts","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-wU71Bi0ipg2qVfdiDV3R0RQuyuK3Cc3H/3PldMN1Tb8pFKPVrUW9aZxj/dv5FzwgEidvtVoH2ANZAAvFKC81aQ==","shasum":"c02a7f3f3a077cbaf16c33439716c002c9b2e8fa","tarball":"https://registry.npmjs.org/@dariusa/robloxstudio-mcp/-/robloxstudio-mcp-1.6.0.tgz","fileCount":43,"unpackedSize":333162,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBvqK3RZGEOT6wEJpQ96NGhy3x+mIGeXJJWwN0oHpKGGAiBLLenWu5BHomWBQtlgUcBqwGleTBgIDngMI4O5TOkFqw=="}]},"_npmUser":{"name":"dariusa","email":"dariuxandrei@gmail.com"},"directories":{},"maintainers":[{"name":"dariusa","email":"dariuxandrei@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/robloxstudio-mcp_1.6.0_1758995714203_0.7038499819050841"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-27T17:55:14.132Z","1.6.0":"2025-09-27T17:55:14.437Z","modified":"2025-09-27T17:55:14.724Z"},"maintainers":[{"name":"dariusa","email":"dariuxandrei@gmail.com"}],"description":"MCP Server for Roblox Studio Integration - Access Studio data, scripts, and objects through AI tools","homepage":"https://github.com/boshyxd/robloxstudio-mcp#readme","keywords":["mcp","roblox","studio","ai","model-context-protocol","game-development"],"repository":{"type":"git","url":"git+https://github.com/boshyxd/robloxstudio-mcp.git"},"author":{"name":"dariusa"},"bugs":{"url":"https://github.com/boshyxd/robloxstudio-mcp/issues"},"license":"MIT","readme":"# Roblox Studio MCP Server\n\nMCP server for AI-powered Roblox Studio integration. 18 specialized tools for exploring projects, analyzing scripts, and performing bulk operations.\n\n<a href=\"https://glama.ai/mcp/servers/@boshyxd/robloxstudio-mcp\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@boshyxd/robloxstudio-mcp/badge\" alt=\"Roblox Studio Server MCP server\" />\n</a>\n\n## Quick Start\n\n**For Claude Code users:**\n```bash\nclaude mcp add robloxstudio -- npx -y robloxstudio-mcp\n```\n\n**For other MCP clients (Claude Desktop, etc.):**\n```json\n{\n  \"mcpServers\": {\n    \"robloxstudio-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"robloxstudio-mcp\"],\n      \"description\": \"Advanced Roblox Studio integration for AI assistants\"\n    }\n  }\n}\n```\n\n<details>\n<summary>Note for native Windows users</summary>\nIf you encounter issues, you may need to run it through `cmd`. Update your configuration like this:\n\n```json\n{\n  \"mcpServers\": {\n    \"robloxstudio-mcp\": {\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"-y\", \"robloxstudio-mcp@latest\"]\n    }\n  }\n}\n```\n</details>\n\n## Studio Plugin Setup (Required)\n\nThe MCP server requires a companion Roblox Studio plugin:\n\n1. **Roblox Creator Store**:\n   - Install from: https://create.roblox.com/store/asset/75577477776988\n   - Click \"Install\" - Opens in Studio automatically\n\n2. **Manual download**:\n   - Download [MCPPlugin.rbxmx](https://github.com/boshyxd/robloxstudio-mcp/releases/latest/download/MCPPlugin.rbxmx)\n   - Save to your `%LOCALAPPDATA%/Roblox/Plugins` folder\n\n3. **Advanced setup**:\n   - See [studio-plugin/INSTALLATION.md](studio-plugin/INSTALLATION.md) for other methods\n\n**After installation:**\n- Enable \"Allow HTTP Requests\" in Game Settings > Security\n- Click the \"MCP Server\" button in the Plugins toolbar\n- Status should show \"Connected\" when working\n\n## Architecture Overview\n\nDual-component system bridging Roblox Studio with AI assistants:\n\n```mermaid\n%%{init: {'theme':'dark', 'themeVariables': {'primaryColor':'#2d3748', 'primaryTextColor':'#ffffff', 'primaryBorderColor':'#4a5568', 'lineColor':'#718096', 'sectionBkgColor':'#1a202c', 'altSectionBkgColor':'#2d3748', 'gridColor':'#4a5568', 'secondaryColor':'#2b6cb0', 'tertiaryColor':'#319795'}}}%%\ngraph TB\n    subgraph AI_ENV [\"AI Environment\"]\n        AI[\"AI Assistant<br/>Claude Code/Desktop\"]\n        MCP[\"MCP Server<br/>Node.js + TypeScript\"]\n    end\n    \n    subgraph COMM_LAYER [\"Communication Layer\"]\n        HTTP[\"HTTP Bridge<br/>localhost:3002\"]\n        QUEUE[\"Request Queue<br/>UUID tracking\"]\n    end\n    \n    subgraph STUDIO_ENV [\"Roblox Studio Environment\"]\n        PLUGIN[\"Studio Plugin<br/>Luau Script\"]\n        STUDIO[\"Roblox Studio<br/>APIs & Data\"]\n    end\n    \n    subgraph TOOLS [\"18 AI Tools\"]\n        FILE[\"File System<br/>Trees, Search\"]\n        CONTEXT[\"Studio Context<br/>Services, Objects\"]\n        PROPS[\"Properties<br/>Get, Set, Mass Ops\"]\n        CREATE[\"Object Creation<br/>Single, Mass, Properties\"]\n        PROJECT[\"Project Analysis<br/>Smart Structure\"]\n    end\n    \n    AI -->|stdio| MCP\n    MCP -->|HTTP POST| HTTP\n    HTTP -->|Queue Request| QUEUE\n    PLUGIN -->|Poll every 500ms| HTTP\n    HTTP -->|Pending Work| PLUGIN\n    PLUGIN -->|Execute APIs| STUDIO\n    STUDIO -->|Return Data| PLUGIN\n    PLUGIN -->|HTTP Response| HTTP\n    HTTP -->|Resolve Promise| MCP\n    MCP -->|Tool Result| AI\n    \n    MCP -.->|Exposes| FILE\n    MCP -.->|Exposes| CONTEXT  \n    MCP -.->|Exposes| PROPS\n    MCP -.->|Exposes| CREATE\n    MCP -.->|Exposes| PROJECT\n    \n    classDef aiStyle fill:#1e40af,stroke:#3b82f6,stroke-width:2px,color:#ffffff\n    classDef mcpStyle fill:#7c3aed,stroke:#8b5cf6,stroke-width:2px,color:#ffffff\n    classDef httpStyle fill:#ea580c,stroke:#f97316,stroke-width:2px,color:#ffffff\n    classDef pluginStyle fill:#059669,stroke:#10b981,stroke-width:2px,color:#ffffff\n    classDef studioStyle fill:#dc2626,stroke:#ef4444,stroke-width:2px,color:#ffffff\n    classDef toolStyle fill:#0891b2,stroke:#06b6d4,stroke-width:2px,color:#ffffff\n    \n    class AI aiStyle\n    class MCP mcpStyle\n    class HTTP,QUEUE httpStyle\n    class PLUGIN pluginStyle\n    class STUDIO studioStyle\n    class FILE,CONTEXT,PROPS,CREATE,PROJECT toolStyle\n```\n\n### Key Components:\n- MCP Server (Node.js/TypeScript) - Exposes 18 tools via stdio\n- HTTP Bridge - Request/response queue on localhost:3002\n- Studio Plugin (Luau) - Polls server and executes API calls\n- Smart Caching - Efficient data transfer\n\n## 18 AI Tools\n\n### File System Tools\n- `get_file_tree` - Complete project hierarchy with scripts, models, folders\n- `search_files` - Find files by name, type, or content patterns  \n\n### Studio Context Tools  \n- `get_place_info` - Place ID, name, game settings, workspace info\n- `get_services` - All Roblox services and their child counts\n- `search_objects` - Find instances by name, class, or properties\n\n### Instance & Property Tools\n- `get_instance_properties` - Complete property dump for any object\n- `get_instance_children` - Child objects with metadata\n- `search_by_property` - Find objects with specific property values\n- `get_class_info` - Available properties/methods for Roblox classes\n\n### Property Modification Tools \n- `set_property` - Set a property on any Roblox instance\n- `mass_set_property` - Set the same property on multiple instances\n- `mass_get_property` - Get the same property from multiple instances\n\n### Object Creation Tools\n- `create_object` - Create a new Roblox object instance\n- `create_object_with_properties` - Create objects with initial properties\n- `mass_create_objects` - Create multiple objects at once\n- `mass_create_objects_with_properties` - Create multiple objects with properties\n- `delete_object` - Delete a Roblox object instance\n\n### Project Analysis Tools\n- `get_project_structure` - Smart hierarchy with depth control (recommended: 5-10)\n\n> Note: Previous tools removed: `get_file_content`, `get_file_properties`, `get_selection`, `get_dependencies`, `validate_references`. Use Rojo/Argon workflows instead.\n\n## AI-Optimized Features\n\n### Mass Operations (v1.3.0)\n- Bulk property editing\n- Mass object creation\n- Batch property reading\n- Atomic undo/redo operations\n\n```typescript\n// Example: Set multiple parts to red\nmass_set_property([\"game.Workspace.Part1\", \"game.Workspace.Part2\"], \"BrickColor\", \"Really red\")\n```\n\n### Smart Project Structure\n- Service overview with child counts\n- Path-based exploration: `get_project_structure(\"game.ServerStorage\", maxDepth=5)`\n- Script-only filtering for code analysis\n- Intelligent grouping for large folders\n- Recommended maxDepth=5-10\n\n### Rich Metadata\n- Script status tracking\n- GUI intelligence\n- Performance optimized\n\n## Development & Testing\n\n### Commands\n```bash\nnpm run dev         # Development server with hot reload  \nnpm run build       # Production build\nnpm start           # Run built server\nnpm run lint        # ESLint code quality\nnpm run typecheck   # TypeScript validation\n```\n\n### Plugin Development\n- Live reload\n- Robust error handling\n- Debug logging\n- Visual status indicators\n\n## Communication Protocol\n\n```mermaid\n%%{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'}}}%%\nsequenceDiagram\n    participant AI as AI Assistant\n    participant MCP as MCP Server  \n    participant HTTP as HTTP Bridge\n    participant PLUGIN as Studio Plugin\n    participant STUDIO as Roblox Studio\n    \n    Note over AI,STUDIO: Tool Request Flow\n    \n    AI->>+MCP: Call tool (e.g., get_file_tree)\n    MCP->>+HTTP: Queue request with UUID\n    HTTP->>HTTP: Store in pending requests map\n    HTTP-->>-MCP: Request queued\n    \n    Note over PLUGIN: Polling every 500ms\n    PLUGIN->>+HTTP: GET /poll\n    HTTP->>-PLUGIN: Return pending request + UUID\n    \n    PLUGIN->>+STUDIO: Execute Studio APIs\n    Note over STUDIO: game.ServerStorage<br/>Selection:Get()<br/>Instance properties\n    STUDIO->>-PLUGIN: Return Studio data\n    \n    PLUGIN->>+HTTP: POST /response with UUID + data\n    HTTP->>-MCP: Resolve promise with data\n    MCP->>-AI: Return tool result\n    \n    Note over AI,STUDIO: Error Handling\n    \n    alt Request Timeout (30s)\n        HTTP->>MCP: Reject promise with timeout\n        MCP->>AI: Return error message\n    end\n    \n    alt Plugin Disconnected\n        PLUGIN->>HTTP: Connection lost\n        HTTP->>HTTP: Exponential backoff retry\n        Note over PLUGIN: Status: \"Waiting for server...\"\n    end\n```\n\n**Features:**\n- 30-second timeouts with exponential backoff\n- Automatic retries\n- Response limiting\n- Request deduplication\n\n## Example Usage\n\n```javascript\n// Get service overview\nget_project_structure()\n\n// Explore weapons folder\nget_project_structure(\"game.ServerStorage.Weapons\", maxDepth=2)\n\n// Find all Sound objects  \nsearch_by_property(\"ClassName\", \"Sound\")\n\n// Check script dependencies\nget_dependencies(\"game.ServerScriptService.MainScript\")\n\n// Find broken references\nvalidate_references()\n\n// Get UI component details\nget_instance_properties(\"game.StarterGui.MainMenu.SettingsFrame\")\n```\n\n## Configuration\n\n**Environment Variables:**\n- `MCP_SERVER_PORT` - MCP server port (default: stdio)\n- `HTTP_SERVER_PORT` - HTTP bridge port (default: 3002)\n- `PLUGIN_POLL_INTERVAL` - Plugin poll frequency (default: 500ms)\n- `REQUEST_TIMEOUT` - Request timeout (default: 30000ms)\n\n**Studio Settings:**\n- **Allow HTTP Requests** (Game Settings > Security)\n- **HttpService.HttpEnabled = true**\n- **Plugin activated** via toolbar button\n\n## License\n\nMIT License - Feel free to use in commercial and personal projects!","readmeFilename":"README.md","_rev":"1-ef1a05e3da03c2e48e0befa635b59285"}