From 2075b56f6091f3aaf022ee55184d792afa671ee1 Mon Sep 17 00:00:00 2001 From: Admin Date: Tue, 31 Mar 2026 17:01:53 +0400 Subject: [PATCH] Add comprehensive README with installation guide, 20-weapon reference, and AI agent instructions - Full architecture diagram and data flow explanation - Step-by-step installation (5 minutes) - Complete MCP tool reference with parameter examples - Python injection fallback documentation - 20-weapon FPS game reference table - Troubleshooting guide - AI agent / bot integration instructions - File structure overview Co-Authored-By: Claude Opus 4.6 --- README.md | 585 ++++++++++++++++++++++++++---------------------------- 1 file changed, 277 insertions(+), 308 deletions(-) diff --git a/README.md b/README.md index 7255653..c06bc67 100644 --- a/README.md +++ b/README.md @@ -1,349 +1,318 @@ -# ClaudeCode-Roblox-Studio-MCP +# ClaudeCode Roblox Studio MCP Server -A Model Context Protocol (MCP) server that enables **Claude Code** (by Anthropic) to directly control **Roblox Studio** - create games, manipulate objects, write scripts, and build experiences through natural language commands. +> **Control Roblox Studio from Claude Code via MCP (Model Context Protocol)** -## Overview +This project allows any Claude Code agent/bot to directly control Roblox Studio - creating parts, writing scripts, building maps, spawning enemies, and running Lua code - all through natural language commands. -This project creates a bidirectional bridge between Claude Code and Roblox Studio using: -- **MCP Protocol** (stdio) for Claude Code communication -- **HTTP Polling** for Roblox Studio plugin communication -- **Express.js** server for command queuing and result handling +--- -## Architecture Diagram +## Architecture ``` -┌─────────────────┐ MCP (stdio) ┌──────────────────┐ HTTP Polling ┌─────────────────┐ -│ Claude Code │ ◄─────────────────► │ Node.js MCP │ ◄──────────────────► │ Roblox Studio │ -│ (AI Agent) │ │ Server │ (port 37423) │ Plugin │ -└─────────────────┘ └──────────────────┘ └─────────────────┘ - │ - ▼ - Express HTTP - (Health: 37423) +Claude Code <---> MCP Server (stdio) <---> HTTP/WS Bridge <---> Roblox Studio Plugin + | | | + | tool calls | HTTP polling (port 37423) | executes Lua + | (create_part, | WebSocket (port 37424) | creates objects + | create_script, | | runs game logic + | execute_code) | | ``` -### How It Works +**How it works:** +1. Claude Code communicates with the MCP server via stdin/stdout (MCP protocol) +2. The MCP server runs an HTTP + WebSocket bridge on localhost +3. The Roblox Studio plugin polls the MCP server and executes commands +4. Results flow back: Plugin -> HTTP -> MCP Server -> Claude Code -1. **Claude Code** connects to the MCP server via stdio -2. **MCP Server** exposes tools that Claude can call (create_part, create_script, etc.) -3. **Commands** are queued in the MCP server's memory -4. **Roblox Plugin** polls the HTTP endpoint for new commands -5. **Plugin executes** commands in Roblox Studio and sends results back -6. **Results** are returned to Claude Code via the MCP protocol +--- -## Features +## Quick Start (5 minutes) -- Create 3D parts, models, folders, and entire scenes -- Write and inject Lua scripts (Script, LocalScript, ModuleScript) -- Build GUI elements (ScreenGui, Frame, TextButton, etc.) -- Manipulate workspace hierarchy -- Execute arbitrary Lua code -- Playtest and save places automatically -- Python injection scripts for direct command bar automation - -## Installation - -### Prerequisites - -- **Node.js** 18+ (for MCP server) -- **Claude Code** (by Anthropic) -- **Roblox Studio** (installed) -- Windows 11 or macOS - -### Step 1: Clone and Install +### Step 1: Install Dependencies ```bash -cd ~ -git clone https://github.rommark.dev/admin/ClaudeCode-Roblox-Studio-MCP.git cd ClaudeCode-Roblox-Studio-MCP npm install ``` -### Step 2: Configure Claude Code +### Step 2: Install the Studio Plugin -Add to your Claude Code config (`~/.claude/config.json` or `.clauderc`): +Copy the plugin to your Roblox plugins folder: + +```bash +# Windows +copy roblox-plugin\RobloxMCPPlugin.lua "%LOCALAPPDATA%\Roblox\Plugins\" + +# Mac +cp roblox-plugin/RobloxMCPPlugin.lua ~/Library/Application\ Support/Roblox/Plugins/ +``` + +### Step 3: Start the MCP Server + +```bash +node src/index.js +``` + +You should see: +``` +HTTP server listening on port 37423 +WebSocket server listening on port 37424 +Roblox Studio MCP server running on stdio +``` + +### Step 4: Configure Claude Code + +Add to your `.claude.json` (project settings): ```json { "mcpServers": { "roblox-studio": { "command": "node", - "args": ["~/ClaudeCode-Roblox-Studio-MCP/src/index.js"], - "cwd": "~/ClaudeCode-Roblox-Studio-MCP" + "args": ["C:\\path\\to\\ClaudeCode-Roblox-Studio-MCP\\src\\index.js"] } } } ``` -### Step 3: Install Roblox Studio Plugin - -**Windows:** -```powershell -Copy-Item roblox-plugin\RobloxMCPPlugin.lua $env:LOCALAPPDATA\Roblox\Plugins\ -``` - -**Mac:** +Or use the auto-setup: ```bash -cp roblox-plugin/RobloxMCPPlugin.lua ~/Library/Application\ Support/Roblox/Plugins/ +AutoConnect\START-HERE.bat ``` -### Step 4: Enable HTTP Requests (Critical!) +### Step 5: Open Roblox Studio -In Roblox Studio: -1. **File** → **Game Settings** -2. **Security** tab -3. Enable **"Enable Studio Access to API Services"** -4. Enable **"Allow HTTP Requests"** +1. Open Roblox Studio +2. Create or open a place +3. Go to **Game Settings > Security > Allow HTTP Requests** and enable it +4. The plugin auto-connects (check Output window for `[RobloxMCP] Connected!`) -### Step 5: Start Using +### Step 6: Use in Claude Code -1. Start the MCP server: `npm start` -2. Open Roblox Studio -3. The plugin will auto-connect (look for "RobloxMCP" toolbar) -4. Start chatting with Claude Code to build your game! - -## Available MCP Tools - -| Tool | Description | Example | -|------|-------------|---------| -| `roblox_create_script` | Create Script/LocalScript/ModuleScript | "Create a Script in Workspace that prints hello" | -| `roblox_create_part` | Create 3D parts (Block, Ball, Cylinder, Wedge, CornerWedge) | "Create a red block at position 5, 10, 0" | -| `roblox_create_model` | Create model containers | "Create a model named Weapons in Workspace" | -| `roblox_create_folder` | Create folders for organization | "Create a folder named Scripts in Workspace" | -| `roblox_create_gui` | Create GUI elements | "Create a ScreenGui with a start button" | -| `roblox_set_property` | Set properties on objects | "Set the color of Workspace.Part1 to blue" | -| `roblox_get_hierarchy` | Explore object tree | "Show me the Workspace hierarchy" | -| `roblox_delete_object` | Delete objects by path | "Delete Workspace.OldPart" | -| `roblox_execute_code` | Run arbitrary Lua code | "Execute: print('Hello from Claude')" | -| `roblox_play` | Start playtest | "Start playtest in Client mode" | -| `roblox_stop` | Stop playtest | "Stop the playtest" | -| `roblox_save_place` | Save current place | "Save the place" | - -## Usage Examples - -### Creating a Simple Game - -Ask Claude: -``` -Create an obstacle course game with: -- A green starting platform at 0, 1, 0 -- 5 red checkpoint platforms going upward -- A spinning part at the end -- A kill brick floor called Lava -``` - -### Building a GUI +Restart your Claude Code session, then ask it to build: ``` -Create a ScreenGui with: -- A dark semi-transparent frame -- A title saying "MY GAME" -- A green start button -- Make the button print "Started!" when clicked +"Build me a military base with guard towers" +"Create a zombie survival game" +"Add 20 weapons to my FPS game" ``` -### Scripting - -``` -Create a Script in Workspace.Part that makes it spin continuously -``` - -## Python Injection Scripts - -The `examples/` folder includes Python scripts for direct injection into Roblox Studio: - -### studio-inject.py -Inject a single Lua script into the Roblox Studio command bar using Win32 API. - -```bash -python examples/studio-inject.py -``` - -### inject-all-parts.py -Inject all 5 parts of the FPS game sequentially into Roblox Studio. - -```bash -python examples/inject-all-parts.py -``` - -**Requirements:** -- Windows 11 -- Roblox Studio must be open -- Python 3.x - -## Examples Folder - -The `examples/` folder contains: -- `fps-game/` - Complete 5-part FPS game setup (CoD style) -- `demo_game.lua` - Simple obby game example -- `spinning_part.lua` - Rotating part script -- `start_button.lua` - Start button GUI - -### FPS Game Parts - -1. **Part 1**: Map + Infrastructure (buildings, cover, lighting) -2. **Part 2**: Weapon System (weapon data module, client weapon controller) -3. **Part 3**: Enemy AI + Server Handler (AI bots, game server script) -4. **Part 4**: HUD + Player Scripts (crosshair, minimap, damage effects) -5. **Part 5**: Weapon Client Script (final weapon controller) - -## Project Structure - -``` -ClaudeCode-Roblox-Studio-MCP/ -├── src/ -│ └── index.js # Main MCP server + Express/HTTP -├── roblox-plugin/ -│ └── RobloxMCPPlugin.lua # HTTP polling plugin for Studio -├── examples/ -│ ├── fps-game/ -│ │ ├── part1_map.lua # Map infrastructure -│ │ ├── part2_weapons.lua # Weapon system -│ │ ├── part3_ai.lua # Enemy AI + server -│ │ ├── part4_hud.lua # HUD + player scripts -│ │ └── part5_client.lua # Weapon client script -│ ├── studio-inject.py # Single script injection -│ └── inject-all-parts.py # Multi-part injection -├── package.json -└── README.md # This file -``` - -## Configuration - -### MCP Server Ports - -Edit `src/index.js`: - -```javascript -const HTTP_PORT = 37423; // HTTP polling endpoint -const WS_PORT = 37424; // WebSocket (optional, for future use) -``` - -### Roblox Plugin Configuration - -Edit `roblox-plugin/RobloxMCPPlugin.lua`: - -```lua -local CONFIG = { - HOST = "localhost", - PORT = 37423, - POLL_INTERVAL = 0.5, -- seconds between polls -} -``` - -## Troubleshooting - -### "MCP server not reachable" - -**Solution:** -- Make sure the MCP server is running: `npm start` -- Check port 37423 is not in use -- Verify Claude Code config is correct - -### "HTTP Requests Blocked" - -**Solution:** -- Game Settings → Security -- Enable both HTTP-related options -- Restart Roblox Studio after changing - -### Plugin Not Connecting - -**Solution:** -- Check Output window in Roblox Studio -- Verify plugin is in correct Plugins folder -- Make sure HttpService is enabled -- Try clicking the toolbar button manually - -### Commands Not Executing - -**Solution:** -- Check for Lua errors in Output window -- Verify parent paths exist -- Make sure object names don't contain special characters - -## Security Considerations - -⚠️ **Important Security Notes:** - -- This plugin allows executing arbitrary Lua code -- Only use in trusted development environments -- HTTP requests must be enabled (security trade-off) -- Consider using a reverse proxy for production -- Review all code before execution in production games - -## Development - -### Adding New Tools - -1. Add tool definition in `src/index.js` (in `ListToolsRequestSchema` handler) -2. Add handler in `CallToolRequestSchema` handler -3. Implement in `roblox-plugin/RobloxMCPPlugin.lua` (add to `handleCommand` function) - -Example: -```javascript -// src/index.js -{ - name: 'roblox_my_tool', - description: 'Does something cool', - inputSchema: { - type: 'object', - properties: { - param1: { type: 'string', description: 'Description' }, - }, - required: ['param1'], - }, -} -``` - -```lua --- roblox-plugin/RobloxMCPPlugin.lua -elseif command == "myTool" then - -- Your implementation - return { success = true, result = "something" } -``` - -## Contributing - -Contributions welcome! Please: -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Test thoroughly -5. Submit a pull request - -## License - -MIT License - feel free to use in your projects! - -## Credits - -- Built with [Model Context Protocol](https://github.com/modelcontextprotocol) by Anthropic -- Powered by [Claude Code](https://claude.ai/code) -- For Roblox Studio game development - -## Support - -For issues, questions, or suggestions: -- Open an issue on GitHub -- Check the Troubleshooting section -- Review the examples in `examples/` - -## Changelog - -### v2.0.0 (2025-03-31) -- Updated to HTTP polling architecture -- Added Python injection scripts -- Added complete FPS game example -- Improved plugin with toolbar UI -- Added comprehensive examples folder - -### v1.0.0 (2025-01-29) -- Initial release -- 12 MCP tools implemented -- WebSocket communication (deprecated) -- Full CRUD operations for Roblox objects - --- -**Made with ❤️ for Roblox developers using AI** +## Available MCP Tools + +| Tool | Description | +|------|-------------| +| `roblox_create_script` | Create Lua scripts (Script, LocalScript, ModuleScript) | +| `roblox_create_part` | Create 3D parts (Block, Ball, Cylinder, Wedge, CornerWedge) | +| `roblox_create_model` | Create model containers for grouping objects | +| `roblox_create_folder` | Create organizational folders | +| `roblox_create_gui` | Create UI elements (ScreenGui, Frame, TextLabel, TextButton, etc.) | +| `roblox_set_property` | Set properties on existing objects (Position, Size, Color, etc.) | +| `roblox_get_hierarchy` | Inspect the object tree of any path | +| `roblox_delete_object` | Delete objects by path | +| `roblox_execute_code` | Run arbitrary Lua code in the command bar | +| `roblox_play` | Start playtesting | +| `roblox_stop` | Stop playtesting | +| `roblox_save_place` | Save the current place | +| `roblox_import_glb` | Import a GLB 3D model into the workspace | + +--- + +## Tool Parameters + +### roblox_create_part +```json +{ + "parentPath": "Workspace", + "partName": "Wall1", + "partType": "Block", + "position": {"x": 10, "y": 5, "z": 20}, + "size": {"x": 10, "y": 10, "z": 1}, + "anchored": true, + "color": "Bright red" +} +``` + +### roblox_create_script +```json +{ + "path": "Workspace.Model", + "scriptName": "EnemyAI", + "scriptType": "Script", + "source": "-- Lua code here\nprint('Hello from Claude!')" +} +``` + +### roblox_execute_code +```json +{ + "code": "for i=1,10 do local p = Instance.new('Part', workspace) p.Position = Vector3.new(i*5, 1, 0) p.Anchored = true end" +} +``` + +--- + +## Python Injection (Alternative Method) + +If the MCP plugin isn't connecting, you can inject Lua code directly into Studio's command bar using the Python scripts: + +```bash +# Single script injection +python examples/studio-inject.py + +# Multi-part sequential injection (for large games) +python examples/inject-all-parts.py +``` + +This uses Win32 API to: +1. Find the Roblox Studio window +2. Focus the command bar +3. Copy Lua code to clipboard +4. Paste and execute via simulated keyboard input + +**Requirements**: Python 3.x on Windows, Roblox Studio open with a place loaded + +--- + +## Included Example: CoD-Style FPS Game + +A full Call of Duty-inspired FPS game built entirely from code: + +**Map**: Urban military combat zone with buildings, cover positions, watchtowers, crates, barrels, and boundary walls. + +**20 Weapons** (key to switch): +| Key | Weapon | Category | Key | Weapon | Category | +|-----|--------|----------|-----|--------|----------| +| 1 | M4A1 Carbine | Assault Rifle | 0 | UMP-45 | SMG | +| 2 | AK-47 | Assault Rifle | Q | AWP Sniper | Sniper | +| 3 | FN SCAR-H | Assault Rifle | E | Barrett M82 | Sniper | +| 4 | M16A4 | Assault Rifle | T | SVD Dragunov | Sniper | +| 5 | FAMAS F1 | Assault Rifle | Z | SPAS-12 | Shotgun | +| 6 | HK G36C | Assault Rifle | X | Remington 870 | Shotgun | +| 7 | MP5A4 | SMG | C | M249 SAW | LMG | +| 8 | FN P90 | SMG | V | M134 Minigun | LMG | +| 9 | HK MP7A2 | SMG | B | Desert Eagle | Pistol | +| | | | N | Glock 18C | Pistol | +| | | | G | RPG-7 | Launcher | + +**Controls**: WASD=Move, LMB=Shoot, RMB=ADS, Shift=Sprint, Ctrl=Crouch, R=Reload + +**Features**: +- First-person camera with ADS zoom + FOV transition +- Bullet trails, muzzle flash, impact sparks, explosion effects +- Recoil system with crosshair spread dynamics +- 10 enemy soldiers with AI (patrol, detect, chase, shoot) +- Health regen, damage vignette, hit markers, headshot indicators +- Kill feed, killstreak banners ("TRIPLE KILL!", "UNSTOPPABLE!") +- Minimap with enemy position dots +- Full HUD: health bar, ammo counter, weapon name, score, reload bar + +--- + +## Auto-Connect Setup + +For hands-free setup on a fresh machine: + +```bash +AutoConnect\START-HERE.bat +``` + +This will: +1. Install Node.js dependencies +2. Start the MCP server +3. Copy the plugin to Roblox's plugins folder +4. Register the MCP server with Claude Code + +--- + +## Troubleshooting + +### Plugin doesn't connect +- **Enable HttpService**: Game Settings > Security > Allow HTTP Requests = ON +- **Check MCP server is running**: Visit `http://localhost:37423/health` in browser +- **Check Output window**: Look for `[RobloxMCP]` messages in Studio's Output + +### MCP server won't start +- Ensure Node.js 18+ is installed +- Run `npm install` in the project directory +- Check ports 37423 and 37424 are not in use + +### Commands time out +- The plugin polls every 0.5 seconds - slight delay is normal +- Make sure you're not in Play mode (commands work in Edit mode) +- Check Studio isn't frozen or busy + +### Injection script fails +- Make sure Roblox Studio is open with a place loaded +- Run as Administrator if the window can't be focused +- Try manually: View > Command Bar, paste Lua code, press Enter + +--- + +## File Structure + +``` +ClaudeCode-Roblox-Studio-MCP/ + src/ + index.js # MCP server (Node.js) + roblox-plugin/ + RobloxMCPPlugin.lua # Studio plugin v2 (HTTP polling, auto-enable) + RobloxMCPServer_HTTP.lua # Alternative HTTP-only server + TestConnection.lua # Connection test script + examples/ + fps-game/ + part1_map.lua # Map building (buildings, cover, towers) + part2_weapons.lua # Weapon data module + part3_ai.lua # Server handler + enemy AI system + part4_hud.lua # HUD elements + player setup + part5_client.lua # Client weapon controller + studio-inject.py # Direct command bar injection via Win32 + inject-all-parts.py # Multi-part sequential injection + AutoConnect/ + START-HERE.bat # Main entry point + Setup-MCP.bat # MCP setup batch + Setup-MCP.ps1 # PowerShell setup script + AutoSetup.vbs # Silent launcher + package.json + README.md +``` + +--- + +## For AI Agents / Bots + +If you are an AI agent reading this README, here is how to use this tool: + +1. **Check if the MCP server is configured**: Look in `.claude.json` for `roblox-studio` in `mcpServers` +2. **Start the server if needed**: Run `node src/index.js` in the background +3. **Ensure Roblox Studio is open** with a place loaded and HttpService enabled +4. **Use the MCP tools**: Call `roblox_create_part`, `roblox_create_script`, `roblox_execute_code`, etc. +5. **For complex builds**: Use `roblox_execute_code` with large Lua scripts to build entire games at once +6. **Fallback injection**: If MCP is not working, use the Python injection scripts (`examples/studio-inject.py`) to paste Lua directly into Studio's command bar via Win32 API + +### Quick build example (via MCP tool) +``` +Tool: roblox_create_part +Params: { "partName": "Ground", "parentPath": "Workspace", "partType": "Block", + "size": {"x":100,"y":2,"z":100}, "position": {"x":0,"y":-1,"z":0}, + "anchored": true, "color": "Dark green" } +``` + +### Quick script example (via MCP tool) +``` +Tool: roblox_create_script +Params: { "path": "ServerScriptService", "scriptName": "GameController", + "scriptType": "Script", "source": "-- Game logic here" } +``` + +### Large build example (via execute_code + Python injection) +```python +# Read the Lua file, inject into Studio command bar +python examples/inject-all-parts.py +``` + +--- + +## License + +MIT