idontlikecode-roblox-mcp

v0.1.9

Published

19 days ago

A local-first, typed, observable bridge between MCP-compatible AI clients and Roblox Studio

0High
0Medium
0Low

mshbljrngoding

mcp roblox roblox-studio model-context-protocol

iDONTLikeCODE 🎮

A local-first, typed, observable Model Context Protocol (MCP) bridge for Roblox Studio.

iDONTLikeCODE connects MCP-compatible AI clients (such as Antigravity CLI, Claude Desktop, Cursor, Gemini, and Cline) directly to Roblox Studio.

It enables AI agents to inspect your DataModel hierarchy, plan structured changes, construct 3D environments, edit Luau scripts with syntax verification, frame camera angles, capture viewport screenshots for visual evaluation, and execute playtest assertions—all recorded safely in Studio’s native ChangeHistoryService undo history.

🚀 Quick Start (60 Seconds)

You don't need to clone this repository to use it! All you need is Node.js (>= 20) and Roblox Studio.

1. Install the Studio Plugin

Run this one command in your terminal to automatically install the prebuilt plugin to your local Roblox Studio plugins folder:

npx -y idontlikecode-roblox-mcp install-plugin

(Supports macOS and Windows automatically).

2. Configure Roblox Studio

Open your place in Roblox Studio.
Go to Home ➔ Game Settings ➔ Security:
- Toggle Allow HTTP Requests to ON (required for the bridge connection).
- Toggle Allow Mesh / Image APIs to ON (required for camera_screenshot).
Save settings.
Under the Plugins tab ribbon, click the iDONTLikeCODE button to open the widget and click Connect Bridge.

3. Add to Your AI Client

Add idontlikecode-roblox-mcp to your client configuration:

Antigravity CLI (`~/.gemini/config/mcp_config.json` or `.agents/mcp_config.json`)

{
  "mcpServers": {
    "idontlikecode": {
      "command": "npx",
      "args": ["-y", "idontlikecode-roblox-mcp@latest"],
      "env": {
        "ENABLE_LUAU_EXECUTE": "true"
      }
    }
  }
}

Claude Desktop (`claude_desktop_config.json`)

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "idontlikecode": {
      "command": "npx",
      "args": ["-y", "idontlikecode-roblox-mcp@latest"]
    }
  }
}

Cursor (`mcp.json`)

{
  "mcpServers": {
    "idontlikecode": {
      "command": "npx",
      "args": ["-y", "idontlikecode-roblox-mcp@latest"]
    }
  }
}

🌟 Core Features

Inspect-Before-Write: Stable ancestry fingerprints (dataModelFingerprint and instance fingerprints). Writes against deleted or moved instances fail safely with STALE_FINGERPRINT.
ChangeHistoryService Native: Every mutation wraps inside ChangeHistoryService:TryBeginRecording() and commits via FinishRecording(). Full Ctrl+Z / Cmd+Z support in Studio.
Vision-Driven Loop: The AI can frame targets (camera_focus) and capture high-resolution Edit-mode screenshots (camera_screenshot) to evaluate 3D aesthetics and adjust misalignments.
Diff-First Plans: Preview, validate, and approve changes before mutating your game (change_plan, change_validate, change_diff).
Multi-Session Safety: Automatically protects against accidental cross-place changes when multiple Studio windows are open (AMBIGUOUS_TARGET gate).
Self-Healing Bridge: Automatic port conflict resolution (EADDRINUSE) and graceful fallback between WebSocket and HTTP long-polling.

🛠️ Canonical Tools Reference

🔒 Security & Safety Controls

| Threat | Mitigation | | :--- | :--- | | Accidental cross-place mutation | Each Studio window receives a unique session key. Multi-session requires explicit targetSessionId. | | Mutating moved or stale instances | Target fingerprint validation. Changes fail with STALE_FINGERPRINT if modified externally. | | Secret leaks via tool responses | Recursive pattern redaction masks API keys, bearer tokens, passwords, and .ROBLOSECURITY cookies. | | Destructive actions | Deletions and rollbacks require an explicit approvalToken: "user_approved". | | Stdio corruption | All diagnostics and bridge logs strictly stream to process.stderr (never stdout). |

💻 Local Development & Contributing

If you want to contribute to iDONTLikeCODE:

Prerequisites

Node.js: >= 20.0.0
pnpm: >= 10.0.0
Rojo: >= 7.4.0 (brew install rojo or via Aftman)
Luau CLI: luau / luau-compile (brew install luau)

Build & Test Commands

# 1. Install dependencies
pnpm install --frozen-lockfile

# 2. Typecheck & Lint
pnpm typecheck
pnpm lint

# 3. Run full Vitest test suite (51 tests)
pnpm test

# 4. Check Luau plugin files & compile with Rojo
pnpm plugin:check
pnpm plugin:build

# 5. Build TypeScript server
pnpm build

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme