Fix high CPU usage caused by watch::Receiver clone inside loop

CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Roblox Studio MCP Server - A Model Context Protocol (MCP) server that enables Claude Desktop and Cursor to communicate with Roblox Studio. It provides two tools: `run_code` (execute Luau code in Studio) and `insert_model` (search and insert models from Roblox marketplace).
+
+## Build Commands
+
+```bash
+# Build and run (installs plugin and configures Claude Desktop/Cursor)
+cargo run
+
+# Build release binary
+cargo build --release
+
+# macOS universal binary (both architectures)
+cargo build --release --target aarch64-apple-darwin
+cargo build --release --target x86_64-apple-darwin
+```
+
+## Linting and Formatting
+
+```bash
+# Rust
+cargo clippy -- -D warnings
+cargo fmt -- --check
+
+# Luau (from plugin directory)
+cd plugin
+selene .
+stylua . --check
+```
+
+## Architecture
+
+```
+Claude Desktop/Cursor (MCP Client)
+        ↓↑ stdio transport
+MCP Server (Rust)
+        ↓↑ HTTP (localhost:44755)
+Roblox Studio Plugin (Luau)
+        ↓↑ Long polling
+Studio Workspace/Datamodel
+```
+
+### Core Components
+
+- **`src/main.rs`**: CLI entry point, sets up Tokio runtime, spawns HTTP server (port 44755) and MCP server concurrently
+- **`src/rbx_studio_server.rs`**: MCP handler implementing `ServerHandler` trait from rmcp crate; defines `run_code` and `insert_model` tools; manages state with `AppState` (process_queue, output_map, watch channel)
+- **`src/install.rs`**: Installation logic - detects Roblox Studio, embeds plugin, updates Claude Desktop/Cursor config files
+- **`src/error.rs`**: Custom error handling with color-eyre
+
+### Plugin Components (Luau)
+
+- **`plugin/src/Main.server.luau`**: Plugin entry point, runs HTTP long polling loop
+- **`plugin/src/MockWebSocketService.luau`**: Simulates WebSocket via HTTP for Studio plugin
+- **`plugin/src/Tools/RunCode.luau`**: Executes arbitrary Luau code, captures output
+- **`plugin/src/Tools/InsertModel.luau`**: Searches marketplace and inserts models
+
+### Communication Flow
+
+1. Plugin long polls `/request` endpoint (15s timeout, HTTP 423 if no tasks)
+2. MCP server queues tool requests with UUIDs
+3. Plugin executes tools and POSTs results to `/response`
+4. Response sent through channel to waiting MCP handler
+
+### Watch Channel Pattern
+
+The `request_handler` uses a `tokio::sync::watch` channel to efficiently wait for new tasks. **Critical**: When cloning a `watch::Receiver`, the clone inherits the "seen version" from the source. If you clone inside a loop and the source receiver never updates its version, each clone will immediately see stale values as "new", causing a hot loop. Always clone the receiver once before the loop, not inside it.
+
+### Build Process
+
+The `build.rs` script automatically compiles the Luau plugin using Rojo, embedding `MCPStudioPlugin.rbxm` into the binary.
+
+## Testing
+
+No automated tests. Manual verification:
+1. Verify MCP plugin appears in Roblox Studio Plugins tab
+2. Check console for "The MCP Studio plugin is ready for prompts."
+3. Verify Claude Desktop shows available tools (insert_model, run_code)
+
+## Profiling
+
+```bash
+# Install samply profiler (macOS)
+brew install samply
+
+# Profile the MCP server (requires signing or SIP disabled)
+samply record ./target/release/rbx-studio-mcp --stdio
+```
+
+## Configuration Paths
+
+- Claude Desktop (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Claude Desktop (Windows): `%APPDATA%\Claude\claude_desktop_config.json`
+- Cursor: `~/.cursor/mcp.json`

INSTALL.md

@@ -0,0 +1,159 @@
+# Installation Guide
+
+Install the Roblox Studio MCP Server from source. This fork fixes a critical CPU bug (150%+ idle usage) in the official Roblox release.
+
+## Prerequisites
+
+- [Rust](https://rustup.rs/) (latest stable)
+- [Roblox Studio](https://create.roblox.com/docs/studio/setting-up-roblox-studio)
+- Claude Code, Claude Desktop, or Cursor
+
+## Remove Official Roblox Release (if installed)
+
+If you previously installed the official Roblox MCP server, remove it first to avoid conflicts and CPU issues.
+
+### 1. Kill running processes
+
+```bash
+# Check for running processes (look for high CPU usage!)
+ps aux | grep rbx-studio-mcp | grep -v grep
+
+# Kill any running instances
+pkill -f rbx-studio-mcp
+```
+
+### 2. Remove old binaries
+
+```bash
+# macOS - check common locations and remove
+rm -f /Applications/RobloxStudioMCP.app/Contents/MacOS/rbx-studio-mcp
+rm -f ~/bin/rbx-studio-mcp
+rm -f ~/.local/bin/rbx-studio-mcp
+
+# Windows - remove from common locations
+# del "%LOCALAPPDATA%\Programs\rbx-studio-mcp\rbx-studio-mcp.exe"
+```
+
+### 3. Remove old MCP configurations
+
+```bash
+# Claude Code - list and remove old entries
+claude mcp list
+claude mcp remove Roblox-Studio --scope user 2>/dev/null
+claude mcp remove roblox-studio --scope user 2>/dev/null
+
+# Claude Desktop - edit config file
+# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
+# Windows: %APPDATA%\Claude\claude_desktop_config.json
+# Remove any "Roblox Studio" entries pointing to old binaries
+
+# Cursor - edit ~/.cursor/mcp.json
+# Remove any entries pointing to old binaries
+```
+
+## Clone or Update
+
+```bash
+# First time: clone the repo
+git clone git@github.com:splash-screen-studio/studio-rust-mcp-server.git
+cd studio-rust-mcp-server
+
+# Or if already cloned: pull latest
+cd studio-rust-mcp-server
+git pull origin main
+```
+
+## Build
+
+```bash
+cargo build --release
+```
+
+## Install Plugin
+
+Copy the compiled plugin to your Roblox Studio plugins folder:
+
+```bash
+# macOS
+cp target/release/build/rbx-studio-mcp-*/out/MCPStudioPlugin.rbxm ~/Documents/Roblox/Plugins/
+
+# Windows
+copy target\release\build\rbx-studio-mcp-*\out\MCPStudioPlugin.rbxm "%LOCALAPPDATA%\Roblox\Plugins\"
+```
+
+## Configure MCP Clients
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add --transport stdio roblox-studio --scope user -- /path/to/studio-rust-mcp-server/target/release/rbx-studio-mcp --stdio
+```
+
+Verify with:
+```bash
+claude mcp list
+```
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "Roblox Studio": {
+      "command": "/path/to/studio-rust-mcp-server/target/release/rbx-studio-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Edit `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "Roblox Studio": {
+      "command": "/path/to/studio-rust-mcp-server/target/release/rbx-studio-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+## Verify Installation
+
+1. Restart Roblox Studio
+2. Check the Plugins tab for "MCP" button
+3. Open Studio console - should see: `The MCP Studio plugin is ready for prompts.`
+4. Restart your MCP client (Claude Code, Claude Desktop, or Cursor)
+5. Verify tools are available: `run_code` and `insert_model`
+
+### Verify CPU Fix
+
+```bash
+# Check CPU usage - should be near 0% at idle, NOT 150%+
+ps aux | grep rbx-studio-mcp | grep -v grep
+
+# Example of GOOD output (low CPU):
+# bedwards  12345  0.1  0.0 ... rbx-studio-mcp --stdio
+
+# Example of BAD output (old buggy version):
+# bedwards  12345  163.0  0.0 ... rbx-studio-mcp --stdio
+```
+
+If you see high CPU usage, you're still running the old binary. Re-check the removal steps above.
+
+## Updating
+
+```bash
+cd studio-rust-mcp-server
+git pull origin main
+cargo build --release
+cp target/release/build/rbx-studio-mcp-*/out/MCPStudioPlugin.rbxm ~/Documents/Roblox/Plugins/
+```
+
+Then restart Studio and your MCP client.

README.md

@@ -1,4 +1,27 @@
-# Roblox Studio MCP Server
+# Roblox Studio MCP Server (Fork)
+
+This is a fork of [Roblox/studio-rust-mcp-server](https://github.com/Roblox/studio-rust-mcp-server) with performance improvements.
+
+## Fork Maintainer
+
+**Brian Edwards**
+brian.mabry.edwards@gmail.com
+512-584-6841
+Waco, Texas, USA
+
+## Changes from Upstream
+
+- **Fixed high CPU usage** (150%+ idle) caused by `watch::Receiver` clone inside loop in `request_handler`
+- **Fixed busy-wait in `dud_proxy_loop`** - replaced `exit.is_empty()` polling with `tokio::select!`
+- **Replaced unbounded channels** with bounded channels (capacity 1) for backpressure
+- **Replaced panic unwraps** with proper error handling to prevent server crashes
+- **Reduced lock contention** by releasing locks before async channel sends
+
+See [INSTALL.md](INSTALL.md) for installation instructions.
+
+---
+
+## Original README
 
 This repository contains a reference implementation of the Model Context Protocol (MCP) that enables
 communication between Roblox Studio via a plugin and [Claude Desktop](https://claude.ai/download) or [Cursor](https://www.cursor.com/).