ROALL - Roblox MCP Proxy Server

ROALL is a production-minded proxy that sits between your AI coding assistant and Roblox Studio MCP server.

It keeps official tools pass-through compatible while adding practical reliability layers:

• DataModel and script caching for token and latency savings
• Timeout protection for stuck Studio calls
• Auto-restart behavior when MCP child process crashes
• Safe mode guard for destructive operations
• Snapshot and patch workflows for fast iterative coding

What ROALL is for

Use ROALL if you want an AI + Roblox workflow that is:

• cheaper to run (fewer redundant context calls)
• safer to run (confirmation on risky changes)
• easier to debug (log reader + status + metrics)
• more automation-friendly (scaffold, patch, snapshot tools)

If you only need raw Roblox MCP pass-through with zero extras, you may not need this proxy.

Community vs Commercial

ROALL now follows an open-core model:

| Edition | License | Intended use | Notes | | --- | --- | --- | --- | | Community Edition | AGPL-3.0-or-later | Open source usage, research, and public collaboration | If you run modified versions as a network service, provide corresponding source to users under AGPL terms | | Commercial Edition | Commercial license | Private enterprise deployment and closed-source integration | Contact project owner for terms and support scope |

License transition details are documented in NOTICE-LICENSE-TRANSITION.md.

Quick Start

Requirements

• Node.js 18+
• Roblox Studio running
• Roblox MCP enabled in Studio: Assistant -> Manage MCP Servers -> Enable

Fastest way (recommended)

Run directly from npm without cloning:

npx -y roblox-mcp-proxy

Optional global install:

npm i -g roblox-mcp-proxy
roblox-proxy

Local development

Clone repo, then install and build:

npm install
npm run build

Run local build:

npm start

For development:

npm run dev

Recommended Workflow

1. Start Roblox Studio and confirm MCP is enabled.
2. Start ROALL with npx -y roblox-mcp-proxy (or npm start if using local clone).
3. Connect your AI client to dist/index.js over stdio.
4. Use search_game_tree once, then use proxy_get_cached_tree with path_filter for cheap context refreshes.
5. Use proxy_script_patch for small targeted edits instead of full script rewrites.
6. Use proxy_commit_snapshot after major patch cycles.

AI Client Setup

Generic MCP config

{
  "mcpServers": {
    "roblox-proxy": {
      "command": "npx",
      "args": ["-y", "roblox-mcp-proxy"],
      "env": {}
    }
  }
}

Generic MCP config (local clone)

{
  "mcpServers": {
    "roblox-proxy": {
      "command": "node",
      "args": ["<absolute-path>/dist/index.js"],
      "env": {}
    }
  }
}

Claude Code (CLI)

claude mcp add roblox-proxy npx -y roblox-mcp-proxy

Local clone option:

claude mcp add roblox-proxy node <absolute-path>/dist/index.js

Proxy Tooling

ROALL keeps all official Roblox MCP tools and adds proxy-native tools:

| Tool | Purpose | | --- | --- | | proxy_get_cached_tree | Return cached DataModel tree (or one subtree with path_filter) | | proxy_invalidate_cache | Flush both tree and script caches | | proxy_status | Runtime health, cache stats, restart attempts, uptime | | proxy_scaffold_hierarchy | Scaffold deep Roblox instance hierarchy in one call | | proxy_script_patch | Patch specific code blocks without full-file rewrites | | proxy_get_logs | Read recent Roblox Studio log lines | | proxy_search_codebase | Search script content and return normalized match output | | proxy_eval_state | Evaluate lightweight live state expression | | proxy_commit_snapshot | Dump script cache to local backups Git repo | | proxy_get_assets | Query local asset-id dictionary from assets.json | | proxy_generate_ui | Generate responsive UI hierarchy with scale-first defaults and optional UICorner/UIAspectRatioConstraint | | proxy_generate_terrain | Procedurally fill or clear terrain using block/cylinder/ball volumes | | proxy_insert_asset | Load Roblox catalog assets via InsertService and place them in the DataModel | | proxy_audit_code | Fetch script source and return security/bad-practice warnings with raw source | | proxy_static_analyzer | Produce context-aware static-analysis findings with approximate line numbers while reducing common false positives | | proxy_fuzz_remote | Fuzz a RemoteEvent with malformed payloads, with optional auto-start Play mode support | | proxy_fuzz_remote_function | Fuzz a RemoteFunction in sync or async mode and capture invocation failures/timeouts | | proxy_memory_profiler | Compare before/after descendant counts with auto, loadstring, or path execution modes (path avoids loadstring) |

Configuration

ROALL reads roblox-proxy.json from the project root.

{
  "maxPayloadSizeMB": 1,
  "cacheTtlSeconds": 120,
  "safeModeEnabled": true,
  "maxRollingBackups": 10
}

Environment variables:

| Variable | Default | Description | | --- | --- | --- | | ROBLOX_MCP_COMMAND | cmd.exe | Command that launches official Roblox MCP | | ROBLOX_MCP_ARGS | /c,%LOCALAPPDATA%\\Roblox\\mcp.bat | Launch args (comma separated) | | LOG_LEVEL | debug | Logging level |

Project Structure

src/
  index.ts                  # boot sequence
  proxy/
    proxy-server.ts         # AI-facing MCP server + proxy tools
    roblox-client.ts        # resilient stdio client for Studio MCP
  cache/
    datamodel-cache.ts      # TTL cache + subtree filtering
    script-cache.ts         # read-behind script source cache
  utils/
    logger.ts               # structured logging
    metrics.ts              # runtime telemetry counters
    prompt.ts               # safe-mode terminal confirmation
    log-reader.ts           # Roblox log tail reader

Documentation

• README
• Proxy config
• Main source entry
• License transition notice
• AGPL compliance checklist

Contributors

| Role | Name | GitHub | | --- | --- | --- | | Owner | Viet Nguyen | @VietNguyen3095 |

License

• Current: AGPL-3.0-or-later (see LICENSE)
• Legacy: versions released before the transition remain MIT (see LICENSE-MIT-LEGACY)