@weppy/roblox-mcp 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,39 @@
+{
+  "name": "hope1026-roblox-mcp",
+  "owner": {
+    "name": "hope1026",
+    "email": "hope841026@gmail.com"
+  },
+  "metadata": {
+    "description": "Roblox MCP server and tools for AI-powered game development",
+    "version": "0.1.0",
+    "pluginRoot": "./plugins"
+  },
+  "plugins": [
+    {
+      "name": "weppy-roblox-mcp",
+      "source": "./weppy-roblox-mcp",
+      "description": "MCP server for Roblox Studio integration - 118 tools for AI-powered game development with specialized agents and skills",
+      "version": "0.1.0",
+      "author": {
+        "name": "hope1026"
+      },
+      "homepage": "https://github.com/hope1026/roblox-mcp",
+      "repository": "https://github.com/hope1026/roblox-mcp",
+      "license": "SEE LICENSE IN LICENSE",
+      "keywords": [
+        "mcp",
+        "roblox",
+        "roblox-studio",
+        "game-development",
+        "ai",
+        "claude",
+        "codex",
+        "gemini",
+        "cursor"
+      ],
+      "category": "game-development",
+      "tags": ["roblox", "mcp", "game-dev", "ai-tools"]
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-01-31
+
+### Initial Release
+
+First public release of Roblox MCP - AI-powered Roblox Studio integration.
+
+#### 140 Tools Available
+
+**Free (68 tools)**
+- Create, delete, clone, and move parts and models
+- Write and edit scripts with AI assistance
+- Change properties like color, size, and position
+- Work with selected items in Studio
+- Add and manage tags for organization
+- Control camera view and focus
+- View output logs and debug errors
+
+**Pro (72 tools)**
+- Bulk operations - create or modify hundreds of objects at once
+- Search and insert models from Creator Store
+- Environment controls - lighting, weather, time of day
+- Terrain generation and modification
+- Find spawn positions and empty spaces with raycasting
+- Visual debugging with area markers and highlights
+
+#### Highlights
+
+- **Real-time Studio control** - AI commands execute instantly in Roblox Studio
+- **Works with popular AI apps** - Claude, Cursor, Codex CLI, Gemini CLI, and more
+- **Secure by design** - Localhost only, no external network access
+- **Free tier included** - 68 essential tools free forever
+
+[0.1.0]: https://github.com/hope1026/roblox-mcp/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,53 @@
+Weppy Roblox MCP License
+
+Copyright (c) 2025 hope1026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use
+the Software for personal, educational, and commercial purposes, including
+the right to:
+
+- Use the Software to develop games, applications, or other projects
+- Distribute games or applications created using the Software
+- Modify the Software for personal use
+
+The following restrictions apply:
+
+1. RESALE PROHIBITION: You may not sell, resell, license, sublicense, or
+   distribute the Software itself, whether in original or modified form,
+   as a standalone product or as part of a competing product/service.
+
+2. REDISTRIBUTION: You may not redistribute the source code or compiled
+   binaries of the Software except as part of a larger work that adds
+   substantial value beyond the Software itself.
+
+3. COMPETING SERVICES: You may not use the Software to create a product
+   or service that directly competes with the Software or offers similar
+   functionality as a primary feature.
+
+4. ATTRIBUTION: You must retain this license notice in all copies or
+   substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Summary (not legally binding):
+
+✅ ALLOWED:
+- Use for game development (personal or commercial)
+- Use in commercial games/apps
+- Modify for your own projects
+- Learn from the code
+
+❌ NOT ALLOWED:
+- Sell or resell the Software itself
+- Create competing MCP servers using this code
+- Redistribute as a standalone product
+- Remove license/attribution

package/README.md

@@ -0,0 +1,162 @@
+# Roblox MCP
+
+> Control Roblox Studio with AI. 140 tools to make game development easier.
+
+## What can you do?
+
+Tell AI what you want, and it executes directly in Roblox Studio:
+
+```
+"Create a red brick"                      → Part creation
+"Change all parts to neon"                → Bulk modification
+"Script that increases jump power on touch" → Auto-generate scripts
+"Make it night and add stars"             → Environment settings
+"Create mountain terrain"                 → Terrain generation
+```
+
+## Quick Start
+
+### Step 1: Install Roblox Plugin
+
+Search for **"W-MCP"** in the **Roblox Creator Store** and install.
+
+Or download directly:
+- [Install from Creator Store](https://create.roblox.com/store/asset/YOUR_ASSET_ID)
+
+### Step 2: Configure MCP Server
+
+Choose your AI app:
+
+| AI App | Installation Guide |
+|--------|-------------------|
+| Claude Desktop | [Setup Guide](docs/en/installation/claude-desktop.md) |
+| Claude Code | [Setup Guide](docs/en/installation/claude-code.md) |
+| Cursor | [Setup Guide](docs/en/installation/cursor.md) |
+| Codex CLI | [Setup Guide](docs/en/installation/codex-cli.md) |
+| Gemini CLI | [Setup Guide](docs/en/installation/gemini-cli.md) |
+| Other MCP Apps | [Setup Guide](docs/en/installation/other-clients.md) |
+
+### Step 3: Connect
+
+1. Launch Roblox Studio
+2. Go to Plugins tab → Click **W-MCP**
+3. Click **Connect** button
+4. Confirm "Connected" status
+5. Start developing with AI!
+
+## 140 Tools
+
+### Free Tools (68)
+
+| Category | What you can do | Example Prompt |
+|----------|-----------------|----------------|
+| **Instance** | Create/delete/clone parts, models | "Create a red sphere" |
+| **Script** | Write/edit/search code | "Script that disappears on touch" |
+| **Property** | Change color, size, position | "Double this part's size" |
+| **Selection** | Control selected items in Studio | "Duplicate selected items" |
+| **Tag** | Manage CollectionService tags | "Add 'Enemy' tag to this part" |
+| **Camera** | Move view, focus | "Move camera to this model" |
+| **Log** | Check errors, debugging | "Show recent errors" |
+
+### Pro Tools (72)
+
+| Category | What you can do | Example Prompt |
+|----------|-----------------|----------------|
+| **Bulk Ops** | Create/modify hundreds at once | "Plant 100 trees" |
+| **Asset** | Search/insert models | "Find and insert a free car model" |
+| **Environment** | Lighting, weather, time | "Make it night and add fog" |
+| **Terrain** | Create/modify Terrain | "Create mountain terrain" |
+| **Raycast** | Collision detection, find positions | "Find 5 player spawn positions" |
+| **Visualization** | Show areas, create markers | "Highlight this area in red" |
+
+## Free vs Pro
+
+| Feature | Free | Pro |
+|---------|:----:|:---:|
+| Basic Tools (68) | ✅ | ✅ |
+| Pro Tools (72) | Daily quota | ✅ Unlimited |
+| Bulk Operations | 10 limit | Unlimited |
+| Asset Search/Insert | 5/day | Unlimited |
+| Terrain Generation | 3/day | Unlimited |
+
+## Example Prompts
+
+### Beginner
+```
+"Create a red part at position (0, 5, 0)"
+"Rename this part to 'Floor'"
+"Delete selected parts"
+"What's currently selected?"
+```
+
+### Intermediate
+```
+"Add a script that changes color on touch"
+"Find all parts with 'Platform' tag"
+"Duplicate this model 5 times in a row"
+"Change lighting to evening mood"
+```
+
+### Advanced
+```
+"Create 100 tiles in a 10x10 grid"
+"Find empty spaces in Workspace and suggest NPC spawn positions"
+"Replace all 'player' with 'character' in this script"
+"Generate mountain terrain and place 50 trees"
+```
+
+## Troubleshooting
+
+### "Not Connected" displayed
+
+1. Check if MCP server is running in your AI app
+2. Allow port 3002 in firewall
+3. Restart Studio plugin (Plugins → W-MCP → Reconnect)
+
+### AI doesn't see changes
+
+1. Ask AI to "sync current state"
+2. Request `sync_workspace_state` tool usage
+
+### Commands not executing
+
+1. Verify plugin shows "Connected" status in Studio
+2. Break complex commands into smaller steps
+
+## Security
+
+- Server runs on **localhost only** (127.0.0.1:3002)
+- No external network access
+- Protected paths blocked (CoreGui, CorePackages, etc.)
+- 450 requests per minute limit
+
+## Supported AI Apps
+
+| App | Supported | Localhost |
+|-----|:---------:|:---------:|
+| Claude Desktop | ✅ | ✅ |
+| Claude Code | ✅ | ✅ |
+| Cursor | ✅ | ✅ |
+| Codex CLI | ✅ | ✅ |
+| Gemini CLI | ✅ | ✅ |
+| Windsurf | ✅ | ✅ |
+| Continue | ✅ | ✅ |
+| Cline | ✅ | ✅ |
+| ChatGPT Desktop | ✅ | ❌ (ngrok required) |
+
+## Links
+
+- [GitHub](https://github.com/hope1026/roblox-mcp)
+- [Issue Report](https://github.com/hope1026/roblox-mcp/issues)
+- [Creator Store](https://create.roblox.com/store/asset/YOUR_ASSET_ID)
+
+## License
+
+Free to use for game development.
+
+✅ **Allowed**: Game development, commercial games, personal projects
+❌ **Not Allowed**: Software resale, creating competing products
+
+---
+
+Made for the Roblox community ❤️

package/assets/screenshots/connection_guide.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9d9d39892ab99a2250e967e468034d3de1b52c9de7f3780bbae9ecdde5c8cd09
+size 405514

package/assets/screenshots/connection_popup.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d8bae9ae267a690caefd6779a8de2c2d0e497bd24af70c55d6e715336a1a6bfe
+size 399154

package/assets/screenshots/plugin_main.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4d4836dd358105aa63777e2976a56641f95f7d26ddc550b0278369a23af3689b
+size 426185

package/assets/screenshots/settings.png

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b851a1515124546910737d9657a023eacf713e07e2ca522c7a6a454d264f2bdb
+size 370233

package/dist/http-bridge.d.ts

@@ -0,0 +1,65 @@
+import type { ServerConfig, Result, ConnectionStatus } from './types/index.js';
+export declare class HTTPBridge {
+    private app;
+    private server;
+    private config;
+    private commandQueue;
+    private pendingCommands;
+    private globalPendingCommands;
+    private sseClients;
+    private startTime;
+    private requestCounts;
+    private cachedSelection;
+    private isClientMode;
+    private baseUrl;
+    private instanceId;
+    private sessionId;
+    private pluginClients;
+    private mcpInstances;
+    private totalCommandsProcessed;
+    constructor(config: ServerConfig);
+    private generateSessionId;
+    getSessionId(): string;
+    private setupMiddleware;
+    private checkRateLimit;
+    private setupRoutes;
+    private handleSSEConnection;
+    private sendSSEEvent;
+    private handleCommandsPoll;
+    private broadcastCommand;
+    private handleResult;
+    private handleSelectionUpdate;
+    private handleRegisterPlugin;
+    private handleRegisterMCP;
+    private handleConnectionInfo;
+    private handleUnregisterPlugin;
+    private handleUnregisterMCP;
+    private handleExecute;
+    private executeCommandLocally;
+    private handleCachedSelectionRequest;
+    private getActivePollingClients;
+    private handleStatus;
+    private getLogsDirectory;
+    private handleLogs;
+    private handleQuotaStatus;
+    private handleShutdown;
+    getCachedSelection(maxAge?: number): {
+        selection: Array<{
+            name: string;
+            className: string;
+            path: string;
+        }>;
+        count: number;
+        timestamp: number;
+    } | null;
+    getConnectionInfo(): Promise<ConnectionStatus>;
+    private executeCommandViaHttp;
+    executeCommand(action: string, params: Record<string, unknown>): Promise<Result>;
+    private checkExistingServer;
+    private registerWithServer;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    getIsClientMode(): boolean;
+}
+export default HTTPBridge;
+//# sourceMappingURL=http-bridge.d.ts.map

package/dist/http-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-bridge.d.ts","sourceRoot":"","sources":["../src/http-bridge.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,YAAY,EAEZ,MAAM,EAKN,gBAAgB,EACjB,MAAM,kBAAkB,CAAC;AAI1B,qBAAa,UAAU;IACrB,OAAO,CAAC,GAAG,CAAsB;IACjC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,qBAAqB,CAAsB;IAEnD,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,eAAe,CAKP;IAGhB,OAAO,CAAC,YAAY,CAAkB;IACtC,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,SAAS,CAAc;IAG/B,OAAO,CAAC,aAAa,CAA4C;IACjE,OAAO,CAAC,YAAY,CAA2C;IAC/D,OAAO,CAAC,sBAAsB,CAAa;gBAE/B,MAAM,EAAE,YAAY;IAgBhC,OAAO,CAAC,iBAAiB;IAQlB,YAAY,IAAI,MAAM;IAO7B,OAAO,CAAC,eAAe;IAkCvB,OAAO,CAAC,cAAc;IAyBtB,OAAO,CAAC,WAAW;IAuDnB,OAAO,CAAC,mBAAmB;IAiD3B,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,gBAAgB;IA+CxB,OAAO,CAAC,YAAY;IAgDpB,OAAO,CAAC,qBAAqB;IAiD7B,OAAO,CAAC,oBAAoB;IA0D5B,OAAO,CAAC,iBAAiB;IA4CzB,OAAO,CAAC,oBAAoB;IA4C5B,OAAO,CAAC,sBAAsB;IAoB9B,OAAO,CAAC,mBAAmB;YAoBb,aAAa;YAkCb,qBAAqB;IAkDnC,OAAO,CAAC,4BAA4B;IAoBpC,OAAO,CAAC,uBAAuB;IAU/B,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,gBAAgB;YAQV,UAAU;IAqFxB,OAAO,CAAC,iBAAiB;IAqDzB,OAAO,CAAC,cAAc;IA0Cf,kBAAkB,CAAC,MAAM,GAAE,MAAc,GAAG;QACjD,SAAS,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QACpE,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,IAAI;IAkBK,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC;YAoD7C,qBAAqB;IA8CtB,cAAc,CACzB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,MAAM,CAAC;YAwDJ,mBAAmB;YA+BnB,kBAAkB;IAoCnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6EtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA8C3B,eAAe,IAAI,OAAO;CAGlC;AAED,eAAe,UAAU,CAAC"}