@lolofuk123/rbx-mcp 0.2.0

package/README.md

@@ -0,0 +1,79 @@
+# rbx-mcp (server)
+
+The Node/TS package published to npm as **`@lolofuk123/rbx-mcp`**. One process, two faces:
+
+- **MCP side** (stdio) — exposes `execute_lua`, `read_studio_state`, `get_errors`
+  to Claude.
+- **HTTP side** (`127.0.0.1:30700`) — the Studio plugin long-polls it; correlates
+  results back to the awaiting tool call.
+
+On startup it also **auto-installs** the bundled Studio plugin into the local
+Plugins folder. See the repo [`README`](../README.md) for the big picture.
+
+## Use with Claude
+
+```json
+{
+  "mcpServers": {
+    "rbx-mcp": { "command": "npx", "args": ["-y", "@lolofuk123/rbx-mcp"] }
+  }
+}
+```
+
+Claude launches the process; you never run a `start` command. Then start/restart
+Studio so it loads the auto-installed plugin.
+
+## Environment variables
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `RBXMCP_HOST` | `127.0.0.1` | Bind/connect host (loopback). |
+| `RBXMCP_PORT` | `30700` | HTTP port (must match the plugin's Port field). |
+| `RBXMCP_TOKEN` | _(unset)_ | Shared secret; if set, the plugin must send it (`X-RbxMcp-Token`). |
+| `RBXMCP_POLL_HOLD_MS` | `25000` | Long-poll hold window. |
+| `RBXMCP_CMD_TIMEOUT_MS` | `30000` | Default per-command execution budget. |
+| `RBXMCP_MAX_RESULT_BYTES` | `1048576` | Max result body size. |
+| `RBXMCP_MAX_QUEUE_DEPTH` | `16` | Reject new work past this (fail-fast "busy"). |
+| `RBXMCP_AUTOINSTALL` | `on` | Set `off` to skip writing the plugin into the Plugins folder. |
+| `RBXMCP_LOG` | `info` | `error` \| `warn` \| `info` \| `debug` (stderr only). |
+| `RBXMCP_DEV` | _(unset)_ | `1` enables the dev-only `POST /v1/_dev/enqueue` route. |
+
+## Develop
+
+```bash
+npm install
+npm test          # vitest (52 tests)
+npm run typecheck
+npm run build     # bundle plugin -> assets/, then tsc -> dist/
+```
+
+### Prove the pipeline without Studio (Milestone A)
+
+Terminal 1 — run the server with the dev route enabled:
+
+```bash
+RBXMCP_DEV=1 RBXMCP_AUTOINSTALL=off npm run dev
+```
+
+Terminal 2 — enqueue a command (a real plugin, or a fake poller, answers it):
+
+```bash
+npm run dev-enqueue -- "return 1 + 1"
+```
+
+`GET http://127.0.0.1:30700/v1/health` shows live status (`pluginConnected`,
+`queueDepth`, …).
+
+## Manual plugin install
+
+Auto-install covers Windows and macOS. To install by hand (or with
+`RBXMCP_AUTOINSTALL=off`), copy [`../plugin/src/rbx-mcp.server.luau`](../plugin/src/rbx-mcp.server.luau)
+into the local Plugins folder and restart Studio. See
+[`../plugin/README.md`](../plugin/README.md).
+
+## Troubleshooting
+
+- **Plugin not connected** — Studio open? plugin enabled + **Start**ed? HttpService
+  allowed? Host/Port/Token match the server?
+- **Port in use** — set `RBXMCP_PORT` (and the plugin's Port field) to a free port.
+- **Linux** — there's no standard Studio Plugins path; install manually.

package/assets/rbx-mcp.lua

@@ -0,0 +1,427 @@
+--!nocheck
+--[[
+	rbx-mcp — Roblox Studio plugin (single file)
+
+	Polls the local rbx-mcp server for Lua commands, runs each via loadstring(),
+	and reports back captured output, return values, and errors (with traceback).
+
+	Deliberately dumb and universal: it executes whatever Lua it's handed, so it
+	never needs updating for new tasks. All intelligence lives on the AI side.
+
+	Talks only to the local server over loopback HTTP. Requires HttpService.
+	Spec: work/02-studio-plugin.md · wire contract: work/01-wire-protocol.md
+]]
+
+local HttpService = game:GetService("HttpService")
+
+local PLUGIN_VERSION = "0.2.0"
+local HOLD_MS = 25000 -- long-poll hold; keep under HttpService's request timeout
+local MAX_RESULT_BYTES = 900 * 1024 -- stay under the server's 1 MiB default
+local SETTING_PREFIX = "rbx-mcp."
+
+-- ============================================================ [Config]
+local Config = {}
+local DEFAULTS = { host = "127.0.0.1", port = 30700, token = "", enabled = false }
+
+local function getSetting(key, default)
+	local ok, value = pcall(function()
+		return plugin:GetSetting(SETTING_PREFIX .. key)
+	end)
+	if not ok or value == nil then
+		return default
+	end
+	return value
+end
+
+local function setSetting(key, value)
+	pcall(function()
+		plugin:SetSetting(SETTING_PREFIX .. key, value)
+	end)
+end
+
+function Config.load()
+	return {
+		host = getSetting("host", DEFAULTS.host),
+		port = tonumber(getSetting("port", DEFAULTS.port)) or DEFAULTS.port,
+		token = getSetting("token", DEFAULTS.token),
+		enabled = getSetting("enabled", DEFAULTS.enabled) == true,
+	}
+end
+
+function Config.base(cfg)
+	return ("http://%s:%d"):format(cfg.host, cfg.port)
+end
+
+-- ============================================================ [Serialize]
+-- Total: never throws. Produces a JSON-safe string for any value.
+local Serialize = {}
+local MAX_KEYS, MAX_DEPTH = 50, 3
+
+function Serialize.value(v, depth, seen)
+	depth = depth or 0
+	local t = typeof(v)
+	if t == "nil" then
+		return "nil"
+	elseif t == "string" then
+		return v
+	elseif t == "number" or t == "boolean" then
+		return tostring(v)
+	elseif t == "Instance" then
+		local ok, full = pcall(function()
+			return v:GetFullName()
+		end)
+		return ("%s (%s)"):format(ok and full or v.Name, v.ClassName)
+	elseif t == "table" then
+		seen = seen or {}
+		if seen[v] then
+			return "<cycle>"
+		end
+		if depth >= MAX_DEPTH then
+			return "{…}"
+		end
+		seen[v] = true
+		local parts, count = {}, 0
+		for key, val in pairs(v) do
+			count += 1
+			if count > MAX_KEYS then
+				table.insert(parts, "… (truncated)")
+				break
+			end
+			table.insert(parts, ("%s = %s"):format(tostring(key), Serialize.value(val, depth + 1, seen)))
+		end
+		seen[v] = nil
+		return "{" .. table.concat(parts, ", ") .. "}"
+	elseif t == "function" then
+		return "<function>"
+	else
+		local ok, s = pcall(tostring, v)
+		return ok and s or ("<" .. t .. ">")
+	end
+end
+
+-- ============================================================ [Executor]
+-- loadstring + captured environment + xpcall/traceback. Verified by the spike.
+local Executor = {}
+
+function Executor.run(code)
+	local chunk, compileErr = loadstring(code, "=rbx-mcp")
+	if not chunk then
+		return {
+			ok = false,
+			output = "",
+			error = { message = tostring(compileErr), traceback = tostring(compileErr), phase = "compile" },
+			durationMs = 0,
+		}
+	end
+
+	local buffer = {}
+	local function capture(...)
+		local parts = {}
+		for i = 1, select("#", ...) do
+			parts[i] = tostring(select(i, ...))
+		end
+		table.insert(buffer, table.concat(parts, "\t"))
+	end
+
+	local env = setmetatable({
+		print = capture,
+		warn = function(...)
+			capture("[warn]", ...)
+		end,
+	}, { __index = getfenv() })
+	setfenv(chunk, env)
+
+	local t0 = os.clock()
+	local results = table.pack(xpcall(chunk, function(err)
+		return debug.traceback(tostring(err), 2)
+	end))
+	local durationMs = math.floor((os.clock() - t0) * 1000 + 0.5)
+	local output = table.concat(buffer, "\n")
+
+	if results[1] then
+		local returnValues = nil
+		if results.n >= 2 then
+			returnValues = {}
+			for i = 2, results.n do
+				returnValues[i - 1] = Serialize.value(results[i])
+			end
+		end
+		return { ok = true, output = output, returnValues = returnValues, error = nil, durationMs = durationMs }
+	else
+		local tb = tostring(results[2])
+		local message = tb:match("^[^\n]*") or tb
+		return {
+			ok = false,
+			output = output,
+			error = { message = message, traceback = tb, phase = "runtime" },
+			durationMs = durationMs,
+		}
+	end
+end
+
+-- Enforce the wire size cap: trim output (then drop return values) if too big.
+local function capResult(result)
+	if #result.output > MAX_RESULT_BYTES then
+		result.output = result.output:sub(1, MAX_RESULT_BYTES) .. "\n… (truncated)"
+		result.truncated = true
+	end
+	return result
+end
+
+-- ============================================================ [Transport]
+local Transport = {}
+
+local function headers(cfg)
+	local h = { ["Content-Type"] = "application/json", ["X-RbxMcp-Plugin"] = "plugin/" .. PLUGIN_VERSION }
+	if cfg.token and cfg.token ~= "" then
+		h["X-RbxMcp-Token"] = cfg.token
+	end
+	return h
+end
+
+function Transport.poll(cfg, clientId)
+	local url = ("%s/v1/poll?clientId=%s&wait=%d"):format(Config.base(cfg), HttpService:UrlEncode(clientId), HOLD_MS)
+	local res = HttpService:RequestAsync({ Url = url, Method = "GET", Headers = headers(cfg) })
+	if res.StatusCode == 200 then
+		return "command", HttpService:JSONDecode(res.Body).command
+	elseif res.StatusCode == 204 then
+		return "idle"
+	elseif res.StatusCode == 401 then
+		return "auth"
+	end
+	return "error", res.StatusCode
+end
+
+function Transport.postResult(cfg, result)
+	local res = HttpService:RequestAsync({
+		Url = Config.base(cfg) .. "/v1/result",
+		Method = "POST",
+		Headers = headers(cfg),
+		Body = HttpService:JSONEncode(result),
+	})
+	if res.StatusCode == 200 then
+		return "accepted"
+	elseif res.StatusCode == 404 then
+		return "unknown"
+	end
+	return "error", res.StatusCode
+end
+
+-- ============================================================ [Ui]
+local Ui = {}
+local widget, statusLabel, toggleButton, lastLabel
+local fields = {}
+
+local COLORS = {
+	ok = Color3.fromRGB(120, 220, 130),
+	warn = Color3.fromRGB(240, 200, 90),
+	error = Color3.fromRGB(240, 110, 110),
+	idle = Color3.fromRGB(200, 200, 200),
+}
+
+local function makeLabel(text, parent, order)
+	local label = Instance.new("TextLabel")
+	label.BackgroundTransparency = 1
+	label.Size = UDim2.new(1, -16, 0, 18)
+	label.Font = Enum.Font.Gotham
+	label.TextSize = 13
+	label.TextXAlignment = Enum.TextXAlignment.Left
+	label.TextColor3 = COLORS.idle
+	label.Text = text
+	label.LayoutOrder = order
+	label.Parent = parent
+	return label
+end
+
+local function makeField(labelText, settingKey, value, order, parent, onSave)
+	makeLabel(labelText, parent, order)
+	local box = Instance.new("TextBox")
+	box.Size = UDim2.new(1, -16, 0, 24)
+	box.BackgroundColor3 = Color3.fromRGB(30, 30, 30)
+	box.TextColor3 = Color3.fromRGB(230, 230, 230)
+	box.Font = Enum.Font.Code
+	box.TextSize = 13
+	box.ClearTextOnFocus = false
+	box.Text = tostring(value)
+	box.LayoutOrder = order + 1
+	box.Parent = parent
+	box.FocusLost:Connect(function()
+		setSetting(settingKey, box.Text)
+		if onSave then
+			onSave()
+		end
+	end)
+	fields[settingKey] = box
+	return box
+end
+
+function Ui.build(onToggle)
+	local info = DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, false, false, 300, 300, 260, 260)
+	widget = plugin:CreateDockWidgetPluginGui("rbxMcpWidget", info)
+	widget.Title = "rbx-mcp"
+
+	local root = Instance.new("Frame")
+	root.Size = UDim2.fromScale(1, 1)
+	root.BackgroundColor3 = Color3.fromRGB(46, 46, 46)
+	root.BorderSizePixel = 0
+	root.Parent = widget
+
+	local layout = Instance.new("UIListLayout")
+	layout.SortOrder = Enum.SortOrder.LayoutOrder
+	layout.Padding = UDim.new(0, 6)
+	layout.HorizontalAlignment = Enum.HorizontalAlignment.Center
+	layout.Parent = root
+
+	local pad = Instance.new("UIPadding")
+	pad.PaddingTop = UDim.new(0, 10)
+	pad.PaddingLeft = UDim.new(0, 8)
+	pad.Parent = root
+
+	statusLabel = makeLabel("Disconnected", root, 1)
+	statusLabel.TextSize = 14
+	statusLabel.TextWrapped = true
+	statusLabel.AutomaticSize = Enum.AutomaticSize.Y
+
+	local cfg = Config.load()
+	makeField("Host", "host", cfg.host, 10, root)
+	makeField("Port", "port", cfg.port, 20, root)
+	makeField("Token (optional)", "token", cfg.token, 30, root)
+
+	toggleButton = Instance.new("TextButton")
+	toggleButton.Size = UDim2.new(1, -16, 0, 30)
+	toggleButton.BackgroundColor3 = Color3.fromRGB(64, 110, 180)
+	toggleButton.TextColor3 = Color3.fromRGB(255, 255, 255)
+	toggleButton.Font = Enum.Font.GothamMedium
+	toggleButton.TextSize = 14
+	toggleButton.Text = "Start"
+	toggleButton.LayoutOrder = 40
+	toggleButton.Parent = root
+	toggleButton.Activated:Connect(onToggle)
+
+	lastLabel = makeLabel("", root, 50)
+	lastLabel.TextSize = 12
+	lastLabel.TextColor3 = COLORS.idle
+end
+
+function Ui.setStatus(text, kind)
+	if statusLabel then
+		statusLabel.Text = text
+		statusLabel.TextColor3 = COLORS[kind] or COLORS.idle
+	end
+end
+
+function Ui.setRunning(running)
+	if toggleButton then
+		toggleButton.Text = running and "Stop" or "Start"
+		toggleButton.BackgroundColor3 = running and Color3.fromRGB(150, 70, 70) or Color3.fromRGB(64, 110, 180)
+	end
+end
+
+function Ui.setLastCommand(commandId, ok, durationMs)
+	if lastLabel then
+		lastLabel.Text = ("last: %s  %s  %dms"):format(commandId:sub(1, 8), ok and "ok" or "ERR", durationMs)
+	end
+end
+
+function Ui.toggleVisible()
+	if widget then
+		widget.Enabled = not widget.Enabled
+	end
+end
+
+-- ============================================================ [Loop]
+local Loop = {}
+local active = false
+local clientId = HttpService:GenerateGUID(false)
+
+function Loop.isActive()
+	return active
+end
+
+function Loop.start()
+	if active then
+		return
+	end
+	active = true
+	Ui.setRunning(true)
+	Ui.setStatus("Connecting…", "warn")
+
+	task.spawn(function()
+		local backoff = 0.5
+		while active do
+			-- Plugins can't enable HttpService themselves (it needs a higher security
+			-- identity than plugin context); guide the user — it recovers automatically.
+			if not HttpService.HttpEnabled then
+				Ui.setStatus("HTTP service disabled - enable it in Experience settings → Security → Allow HTTP Requests", "error")
+				task.wait(2)
+				continue
+			end
+
+			local cfg = Config.load()
+			local ok, kind, data = pcall(Transport.poll, cfg, clientId)
+
+			if not active then
+				break
+			elseif not ok then
+				Ui.setStatus("Disconnected — is the server running?", "warn")
+				task.wait(backoff)
+				backoff = math.min(backoff * 2, 5)
+			else
+				backoff = 0.5
+				if kind == "idle" then
+					Ui.setStatus("Connected (idle)", "ok")
+				elseif kind == "auth" then
+					Ui.setStatus("Auth failed — check token", "error")
+					task.wait(2)
+				elseif kind == "error" then
+					Ui.setStatus("Server error " .. tostring(data), "warn")
+					task.wait(1)
+				elseif kind == "command" then
+					Ui.setStatus("Executing…", "ok")
+					local result = capResult(Executor.run(data.code))
+					result.commandId = data.commandId
+					local pok, outcome = pcall(Transport.postResult, cfg, result)
+					Ui.setLastCommand(data.commandId, result.ok, result.durationMs)
+					if pok and outcome == "accepted" then
+						Ui.setStatus("Connected (idle)", "ok")
+					else
+						Ui.setStatus("Result not accepted (" .. tostring(outcome) .. ")", "warn")
+					end
+				end
+			end
+		end
+	end)
+end
+
+function Loop.stop()
+	active = false
+	Ui.setRunning(false)
+	Ui.setStatus("Disconnected", "idle")
+end
+
+-- ============================================================ [main]
+local toolbar = plugin:CreateToolbar("rbx-mcp")
+local button = toolbar:CreateButton("rbx-mcp", "Show/hide the rbx-mcp panel", "")
+button.ClickableWhenViewportHidden = true
+
+local function onToggle()
+	if Loop.isActive() then
+		Loop.stop()
+		setSetting("enabled", false)
+	else
+		Loop.start()
+		setSetting("enabled", true)
+	end
+end
+
+Ui.build(onToggle)
+button.Click:Connect(Ui.toggleVisible)
+
+plugin.Unloading:Connect(function()
+	active = false
+end)
+
+-- Auto-start if it was running last session.
+if Config.load().enabled then
+	Loop.start()
+end

package/dist/bridge.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+const RECENT_MAX = 20;
+export function createBridge(config, log) {
+    const queue = [];
+    const inFlight = new Map();
+    const waiters = [];
+    const recentErrors = [];
+    let lastPollAt = null;
+    let stopped = false;
+    function pushRecent(r) {
+        recentErrors.push(r);
+        while (recentErrors.length > RECENT_MAX)
+            recentErrors.shift();
+    }
+    function clampTimeout(ms) {
+        return Math.min(config.cmdTimeoutMsMax, Math.max(config.cmdTimeoutMsMin, Math.floor(ms)));
+    }
+    function timeoutResult(command) {
+        return {
+            commandId: command.commandId,
+            ok: false,
+            output: "",
+            returnValues: null,
+            error: {
+                message: `Execution timed out after ${command.timeoutMs} ms (no result from the Studio plugin).`,
+                traceback: "",
+                phase: "timeout",
+            },
+            durationMs: command.timeoutMs,
+        };
+    }
+    function armTimeout(pending) {
+        pending.timer = setTimeout(() => {
+            if (!inFlight.has(pending.command.commandId))
+                return;
+            inFlight.delete(pending.command.commandId);
+            const r = timeoutResult(pending.command);
+            pushRecent(r);
+            log.warn("command timed out", { commandId: pending.command.commandId, timeoutMs: pending.command.timeoutMs });
+            pending.resolve(r);
+            dispatch();
+        }, pending.command.timeoutMs + 1000); // small transport grace beyond the plugin budget
+    }
+    /** Hand the head of the queue to a parked waiter — but only one command in-flight at a time. */
+    function dispatch() {
+        while (inFlight.size === 0 && queue.length > 0 && waiters.length > 0) {
+            const pending = queue.shift();
+            const waiter = waiters.shift();
+            clearTimeout(waiter.timer);
+            inFlight.set(pending.command.commandId, pending);
+            armTimeout(pending);
+            log.debug("dispatch", { commandId: pending.command.commandId });
+            waiter.resolve(pending.command);
+        }
+    }
+    function enqueueAndAwait(input) {
+        if (stopped)
+            return Promise.reject(new Error("bridge is shutting down"));
+        if (queue.length >= config.maxQueueDepth) {
+            return Promise.reject(new Error(`bridge busy: command queue is full (${config.maxQueueDepth})`));
+        }
+        const command = {
+            commandId: randomUUID(),
+            kind: "execute_lua",
+            code: input.code,
+            timeoutMs: clampTimeout(input.timeoutMs ?? config.cmdTimeoutMs),
+            meta: input.meta,
+        };
+        log.info("enqueue", { commandId: command.commandId, codeLen: input.code.length, label: input.meta?.label });
+        return new Promise((resolve) => {
+            queue.push({ command, resolve, enqueuedAt: Date.now() });
+            dispatch();
+        });
+    }
+    function waitForCommand(waitMs, clientId) {
+        markPoll(clientId);
+        if (stopped)
+            return Promise.resolve(null);
+        const hold = Math.min(Math.max(waitMs, 0), config.pollHoldMs);
+        return new Promise((resolve) => {
+            const waiter = {
+                resolve,
+                timer: setTimeout(() => {
+                    const i = waiters.indexOf(waiter);
+                    if (i >= 0)
+                        waiters.splice(i, 1);
+                    resolve(null);
+                }, hold),
+            };
+            waiters.push(waiter);
+            dispatch();
+        });
+    }
+    function submitResult(result) {
+        const pending = inFlight.get(result.commandId);
+        if (!pending)
+            return "unknown";
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        inFlight.delete(result.commandId);
+        if (!result.ok)
+            pushRecent(result);
+        log.info("result", { commandId: result.commandId, ok: result.ok, durationMs: result.durationMs });
+        pending.resolve(result);
+        dispatch();
+        return "accepted";
+    }
+    function markPoll(clientId) {
+        lastPollAt = Date.now();
+        void clientId; // reserved for future multi-client tracking
+    }
+    function getStatus() {
+        const connected = lastPollAt !== null && Date.now() - lastPollAt <= 2 * config.pollHoldMs;
+        return {
+            status: "ok",
+            bridgeVersion: config.version,
+            queueDepth: queue.length,
+            inFlight: inFlight.size,
+            pluginConnected: connected,
+            lastPollAt: lastPollAt !== null ? new Date(lastPollAt).toISOString() : null,
+        };
+    }
+    function getRecentErrors(limit = 5) {
+        const n = Math.max(0, Math.min(limit, recentErrors.length));
+        return recentErrors.slice(recentErrors.length - n).reverse();
+    }
+    function shutdown(reason = "shutting down") {
+        stopped = true;
+        for (const w of waiters.splice(0)) {
+            clearTimeout(w.timer);
+            w.resolve(null);
+        }
+        const pending = [...queue.splice(0), ...inFlight.values()];
+        inFlight.clear();
+        for (const p of pending) {
+            if (p.timer)
+                clearTimeout(p.timer);
+            p.resolve({
+                commandId: p.command.commandId,
+                ok: false,
+                output: "",
+                returnValues: null,
+                error: { message: `bridge ${reason}`, traceback: "", phase: "internal" },
+                durationMs: 0,
+            });
+        }
+    }
+    return {
+        enqueueAndAwait,
+        waitForCommand,
+        submitResult,
+        markPoll,
+        getStatus,
+        getRecentErrors,
+        shutdown,
+    };
+}

package/dist/config.js

@@ -0,0 +1,32 @@
+export const VERSION = "0.1.0";
+const LOG_LEVELS = ["error", "warn", "info", "debug"];
+function clampInt(raw, def, min, max) {
+    if (raw === undefined || raw.trim() === "")
+        return def;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return def;
+    return Math.min(max, Math.max(min, Math.floor(n)));
+}
+/** Read, validate, and clamp configuration from the environment. */
+export function loadConfig(env = process.env, version = VERSION) {
+    const logRaw = (env.RBXMCP_LOG ?? "info").toLowerCase();
+    const logLevel = LOG_LEVELS.includes(logRaw) ? logRaw : "info";
+    const token = env.RBXMCP_TOKEN && env.RBXMCP_TOKEN.length > 0 ? env.RBXMCP_TOKEN : null;
+    const cfg = {
+        host: env.RBXMCP_HOST && env.RBXMCP_HOST.length > 0 ? env.RBXMCP_HOST : "127.0.0.1",
+        port: clampInt(env.RBXMCP_PORT, 30700, 0, 65535),
+        pollHoldMs: clampInt(env.RBXMCP_POLL_HOLD_MS, 25000, 0, 60000),
+        cmdTimeoutMs: clampInt(env.RBXMCP_CMD_TIMEOUT_MS, 30000, 1000, 600000),
+        cmdTimeoutMsMin: 1000,
+        cmdTimeoutMsMax: 600000,
+        maxResultBytes: clampInt(env.RBXMCP_MAX_RESULT_BYTES, 1024 * 1024, 1024, 64 * 1024 * 1024),
+        maxQueueDepth: clampInt(env.RBXMCP_MAX_QUEUE_DEPTH, 16, 1, 1024),
+        token,
+        logLevel,
+        dev: env.RBXMCP_DEV === "1" || env.RBXMCP_DEV === "true",
+        autoInstall: env.RBXMCP_AUTOINSTALL !== "off",
+        version,
+    };
+    return cfg;
+}

package/dist/dev-enqueue.js

@@ -0,0 +1,43 @@
+/**
+ * Dev CLI: enqueue one Lua command against a running server and print the result.
+ *
+ *   RBXMCP_DEV=1 npm run dev               # in one terminal (starts the server)
+ *   npm run dev-enqueue -- "return 1 + 1"  # in another
+ *
+ * Talks to the dev-only POST /v1/_dev/enqueue route (only present when RBXMCP_DEV is set).
+ * This is a standalone process, not the MCP server, so writing to stdout is fine here.
+ */
+const code = process.argv[2];
+if (!code) {
+    console.error('usage: dev-enqueue "<lua code>"');
+    process.exit(1);
+}
+const host = process.env.RBXMCP_HOST ?? "127.0.0.1";
+const port = process.env.RBXMCP_PORT ?? "30700";
+const token = process.env.RBXMCP_TOKEN;
+const headers = { "content-type": "application/json" };
+if (token)
+    headers["x-rbxmcp-token"] = token;
+try {
+    const res = await fetch(`http://${host}:${port}/v1/_dev/enqueue`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ code }),
+    });
+    const text = await res.text();
+    let pretty = text;
+    try {
+        pretty = JSON.stringify(JSON.parse(text), null, 2);
+    }
+    catch {
+        /* leave as-is */
+    }
+    console.log(`HTTP ${res.status}\n${pretty}`);
+    process.exit(res.ok ? 0 : 1);
+}
+catch (err) {
+    console.error(`Failed to reach the server at http://${host}:${port}. ` +
+        `Is it running with RBXMCP_DEV=1?\n${err.message}`);
+    process.exit(1);
+}
+export {};

package/dist/http.js

@@ -0,0 +1,171 @@
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { isValidResultBody } from "./types.js";
+const BODY_TOO_LARGE = Symbol("too-large");
+export function createHttpServer(bridge, config, log) {
+    const server = createServer((req, res) => {
+        handle(req, res).catch((err) => {
+            log.error("unhandled request error", { message: err.message });
+            if (!res.headersSent)
+                fail(res, 500, "internal error");
+        });
+    });
+    async function handle(req, res) {
+        const url = new URL(req.url ?? "/", `http://${config.host}`);
+        const path = url.pathname;
+        const method = req.method ?? "GET";
+        // Defense-in-depth: only serve loopback Host headers.
+        if (!hostAllowed(req.headers.host))
+            return fail(res, 400, "bad host");
+        // /health is always reachable (no command data, no auth) so setup debugging works.
+        if (method === "GET" && path === "/v1/health") {
+            return json(res, 200, bridge.getStatus());
+        }
+        if (config.token !== null && !checkToken(req, config.token)) {
+            return fail(res, 401, "unauthorized");
+        }
+        if (method === "GET" && path === "/v1/poll") {
+            const clientId = url.searchParams.get("clientId") ?? undefined;
+            const waitRaw = Number(url.searchParams.get("wait"));
+            const wait = Number.isFinite(waitRaw) ? waitRaw : config.pollHoldMs;
+            const command = await bridge.waitForCommand(wait, clientId);
+            if (command === null) {
+                res.writeHead(204).end();
+                return;
+            }
+            return json(res, 200, { type: "command", command });
+        }
+        if (method === "POST" && path === "/v1/result") {
+            const body = await readBody(req, config.maxResultBytes);
+            if (body === BODY_TOO_LARGE)
+                return fail(res, 413, "result too large");
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                return fail(res, 400, "invalid json");
+            }
+            if (!isValidResultBody(parsed))
+                return fail(res, 400, "invalid result body");
+            // Normalize omitted (undefined) fields to null so downstream Result objects are well-formed.
+            const outcome = bridge.submitResult({
+                commandId: parsed.commandId,
+                ok: parsed.ok,
+                output: parsed.output,
+                returnValues: parsed.returnValues ?? null,
+                error: parsed.error ?? null,
+                durationMs: parsed.durationMs,
+                truncated: parsed.truncated,
+            });
+            if (outcome === "unknown")
+                return fail(res, 404, "unknown commandId");
+            return json(res, 200, { accepted: true });
+        }
+        // Dev-only enqueue route — present solely when RBXMCP_DEV is set. Stripped from prod.
+        if (config.dev && method === "POST" && path === "/v1/_dev/enqueue") {
+            const body = await readBody(req, config.maxResultBytes);
+            if (body === BODY_TOO_LARGE)
+                return fail(res, 413, "too large");
+            let parsed;
+            try {
+                parsed = JSON.parse(body);
+            }
+            catch {
+                return fail(res, 400, "invalid json");
+            }
+            const obj = parsed;
+            if (typeof obj?.code !== "string")
+                return fail(res, 400, "missing code");
+            try {
+                const result = await bridge.enqueueAndAwait({
+                    code: obj.code,
+                    timeoutMs: typeof obj.timeoutMs === "number" ? obj.timeoutMs : undefined,
+                    meta: { label: typeof obj.label === "string" ? obj.label : "dev-enqueue" },
+                });
+                return json(res, 200, result);
+            }
+            catch (err) {
+                return fail(res, 503, err.message);
+            }
+        }
+        return fail(res, 404, "not found");
+    }
+    function start() {
+        return new Promise((resolve, reject) => {
+            const onError = (err) => {
+                if (err.code === "EADDRINUSE") {
+                    reject(new Error(`port ${config.port} on ${config.host} is already in use. ` +
+                        `Set RBXMCP_PORT to a free port (and match it in the Studio plugin).`));
+                }
+                else {
+                    reject(err);
+                }
+            };
+            server.once("error", onError);
+            server.listen(config.port, config.host, () => {
+                server.removeListener("error", onError);
+                const addr = server.address();
+                log.info("http listening", { host: config.host, port: addr.port });
+                resolve({ host: config.host, port: addr.port });
+            });
+        });
+    }
+    function stop() {
+        return new Promise((resolve) => {
+            server.close(() => resolve());
+            // Don't let lingering keep-alive sockets block close.
+            server.closeAllConnections?.();
+        });
+    }
+    return { start, stop };
+}
+function hostAllowed(host) {
+    if (!host)
+        return false;
+    const name = host.replace(/:\d+$/, "").replace(/^\[|\]$/g, "");
+    return name === "127.0.0.1" || name === "localhost" || name === "::1";
+}
+function checkToken(req, expected) {
+    const got = req.headers["x-rbxmcp-token"];
+    const value = Array.isArray(got) ? got[0] : got;
+    if (typeof value !== "string")
+        return false;
+    const a = Buffer.from(value);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+async function readBody(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let done = false;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (!done && size > maxBytes) {
+                done = true;
+                resolve(BODY_TOO_LARGE);
+            }
+            // Keep consuming (to drain the socket) but stop buffering once over the cap.
+            if (!done)
+                chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!done) {
+                done = true;
+                resolve(Buffer.concat(chunks).toString("utf8"));
+            }
+        });
+        req.on("error", reject);
+    });
+}
+function json(res, status, payload) {
+    const body = JSON.stringify(payload);
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(body);
+}
+function fail(res, status, message) {
+    json(res, status, { error: message });
+}

package/dist/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createLogger } from "./log.js";
+import { createBridge } from "./bridge.js";
+import { createHttpServer } from "./http.js";
+import { createMcpServer } from "./mcp/server.js";
+import { installPlugin } from "./install.js";
+async function main() {
+    const config = loadConfig();
+    const log = createLogger(config.logLevel);
+    log.info("starting rbx-mcp", {
+        version: config.version,
+        host: config.host,
+        port: config.port,
+        dev: config.dev,
+        token: config.token ? "set" : "none",
+    });
+    const bridge = createBridge(config, log);
+    const http = createHttpServer(bridge, config, log);
+    await http.start();
+    if (config.autoInstall) {
+        const res = await installPlugin({ log });
+        log.info("plugin auto-install", res);
+    }
+    else {
+        log.info("plugin auto-install disabled (RBXMCP_AUTOINSTALL=off)");
+    }
+    const mcp = createMcpServer(bridge, config, log);
+    const transport = new StdioServerTransport();
+    await mcp.connect(transport);
+    log.info("MCP server connected over stdio");
+    let shuttingDown = false;
+    const shutdown = async (sig) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log.info("shutting down", { sig });
+        bridge.shutdown("shutting down");
+        await http.stop();
+        try {
+            await mcp.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        process.exit(0);
+    };
+    for (const sig of ["SIGINT", "SIGTERM"]) {
+        process.on(sig, () => void shutdown(sig));
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`[rbx-mcp] fatal: ${err.stack ?? String(err)}\n`);
+    process.exit(1);
+});

package/dist/install.js

@@ -0,0 +1,86 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+const PLUGIN_FILE = "rbx-mcp.lua";
+/** Path to the plugin asset bundled in the package (../assets relative to this module). */
+export function bundledPluginPath() {
+    return fileURLToPath(new URL("../assets/rbx-mcp.lua", import.meta.url));
+}
+/** Local Roblox Studio Plugins folder for the current OS, or null if there's no standard one. */
+export function resolvePluginsDir(platform = process.platform, env = process.env) {
+    if (platform === "win32") {
+        const local = env.LOCALAPPDATA;
+        return local ? join(local, "Roblox", "Plugins") : null;
+    }
+    if (platform === "darwin") {
+        return join(homedir(), "Documents", "Roblox", "Plugins");
+    }
+    return null; // Linux / other: no standard Studio install path
+}
+function parseVersion(content) {
+    return content.match(/PLUGIN_VERSION\s*=\s*"([^"]+)"/)?.[1] ?? "0.0.0";
+}
+function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Install/refresh the bundled plugin into the local Plugins folder.
+ *
+ * - missing            → write
+ * - identical          → skip
+ * - bundled is newer   → overwrite (update)
+ * - same version, diff → skip (don't clobber a user-modified copy)
+ * - bundled is older   → skip (don't downgrade)
+ *
+ * Never throws: returns a structured result so the bootstrap can log and continue.
+ */
+export async function installPlugin(opts) {
+    const sourcePath = opts.sourcePath ?? bundledPluginPath();
+    const pluginsDir = opts.pluginsDir !== undefined ? opts.pluginsDir : resolvePluginsDir();
+    const fileName = opts.fileName ?? PLUGIN_FILE;
+    if (pluginsDir === null) {
+        return {
+            action: "no-plugins-dir",
+            message: "no standard Roblox Plugins folder for this OS — install the plugin manually (see plugin/README.md)",
+        };
+    }
+    let bundled;
+    try {
+        bundled = await readFile(sourcePath, "utf8");
+    }
+    catch (err) {
+        return { action: "error", message: `cannot read bundled plugin: ${err.message}` };
+    }
+    const dest = join(pluginsDir, fileName);
+    try {
+        await mkdir(pluginsDir, { recursive: true });
+        if (!existsSync(dest)) {
+            await writeFile(dest, bundled, "utf8");
+            return { action: "written", path: dest };
+        }
+        const existing = await readFile(dest, "utf8");
+        if (existing === bundled)
+            return { action: "skipped-same", path: dest };
+        const cmp = compareVersions(parseVersion(bundled), parseVersion(existing));
+        if (cmp > 0) {
+            await writeFile(dest, bundled, "utf8");
+            return { action: "updated", path: dest };
+        }
+        if (cmp === 0)
+            return { action: "skipped-usermodified", path: dest };
+        return { action: "skipped-downgrade", path: dest };
+    }
+    catch (err) {
+        return { action: "error", path: dest, message: err.message };
+    }
+}

package/dist/log.js

@@ -0,0 +1,33 @@
+const RANK = { error: 0, warn: 1, info: 2, debug: 3 };
+function fmt(v) {
+    if (typeof v === "string")
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+/**
+ * Leveled logger that writes ONLY to stderr.
+ *
+ * stdout is reserved for MCP stdio framing — writing log text there would
+ * corrupt the protocol stream. Every path here goes to process.stderr.
+ */
+export function createLogger(level) {
+    const threshold = RANK[level];
+    function emit(l, msg, args) {
+        if (RANK[l] > threshold)
+            return;
+        const head = `[rbx-mcp] ${new Date().toISOString()} ${l.toUpperCase()} ${msg}`;
+        const line = args.length > 0 ? `${head} ${args.map(fmt).join(" ")}` : head;
+        process.stderr.write(`${line}\n`);
+    }
+    return {
+        error: (m, ...a) => emit("error", m, a),
+        warn: (m, ...a) => emit("warn", m, a),
+        info: (m, ...a) => emit("info", m, a),
+        debug: (m, ...a) => emit("debug", m, a),
+    };
+}

package/dist/mcp/server.js

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+/** Build the MCP server (tools wired to the bridge). Transport is connected by the caller. */
+export function createMcpServer(bridge, config, log) {
+    const server = new McpServer({ name: "rbx-mcp", version: config.version });
+    registerTools(server, bridge, config, log);
+    return server;
+}

package/dist/mcp/snippets.js

@@ -0,0 +1,82 @@
+/** A Studio path is a dotted name like "Workspace.Model.Part" — restrict to safe chars. */
+export function isSafePath(path) {
+    return typeof path === "string" && path.trim().length > 0 && /^[A-Za-z0-9_. ]+$/.test(path);
+}
+const SELECTION = `
+local sel = game:GetService("Selection"):Get()
+if #sel == 0 then return "(nothing selected)" end
+local lines = {}
+for _, inst in ipairs(sel) do
+	table.insert(lines, inst:GetFullName() .. " (" .. inst.ClassName .. ")")
+end
+return table.concat(lines, "\\n")
+`.trim();
+const SERVICES_SUMMARY = `
+local names = {"Workspace","Lighting","ReplicatedStorage","ReplicatedFirst","ServerStorage","ServerScriptService","StarterGui","StarterPack","StarterPlayer","SoundService","Teams"}
+local out = {}
+for _, name in ipairs(names) do
+	local ok, svc = pcall(function() return game:GetService(name) end)
+	if ok and svc then
+		table.insert(out, ("%s: %d children"):format(name, #svc:GetChildren()))
+	end
+end
+return table.concat(out, "\\n")
+`.trim();
+function explorerTree(depth) {
+    return `
+local DEPTH = ${depth}
+local function walk(inst, d, prefix, out)
+	for _, child in ipairs(inst:GetChildren()) do
+		table.insert(out, prefix .. child.Name .. " (" .. child.ClassName .. ")")
+		if d < DEPTH then
+			walk(child, d + 1, prefix .. "  ", out)
+		end
+	end
+end
+local out = {}
+walk(workspace, 1, "", out)
+if #out == 0 then return "(workspace is empty)" end
+return table.concat(out, "\\n")
+`.trim();
+}
+function instanceDump(path) {
+    // `path` MUST be pre-validated by isSafePath before reaching here.
+    return `
+local parts = string.split("${path}", ".")
+local node = game
+for _, p in ipairs(parts) do
+	if p ~= "" and node then
+		node = node:FindFirstChild(p)
+	end
+end
+if not node then return "(not found: ${path})" end
+local children = {}
+for _, c in ipairs(node:GetChildren()) do
+	table.insert(children, "  " .. c.Name .. " (" .. c.ClassName .. ")")
+end
+return table.concat({
+	"Instance: " .. node:GetFullName(),
+	"ClassName: " .. node.ClassName,
+	"Children (" .. #children .. "):",
+	table.concat(children, "\\n"),
+}, "\\n")
+`.trim();
+}
+/** Build the server-owned Lua snippet for a read_studio_state query. */
+export function buildStateSnippet(query, params) {
+    switch (query) {
+        case "selection":
+            return SELECTION;
+        case "services_summary":
+            return SERVICES_SUMMARY;
+        case "explorer_tree":
+            return explorerTree(clampDepth(params.depth));
+        case "instance":
+            return instanceDump(params.path ?? "");
+    }
+}
+function clampDepth(depth) {
+    if (depth === undefined || !Number.isFinite(depth))
+        return 2;
+    return Math.min(6, Math.max(1, Math.floor(depth)));
+}

package/dist/mcp/toToolResult.js

@@ -0,0 +1,27 @@
+/**
+ * Map an execution Result into an MCP tool result.
+ *
+ * Failures set `isError: true` and lead with phase + message + traceback so
+ * Claude can read the error and fix it — that feedback is the whole point.
+ */
+export function toToolResult(r) {
+    if (r.ok) {
+        const lines = ["✅ ok"];
+        if (r.output)
+            lines.push(`output:\n${r.output}`);
+        if (r.returnValues && r.returnValues.length > 0)
+            lines.push(`returns: ${r.returnValues.join(", ")}`);
+        lines.push(`(${r.durationMs} ms${r.truncated ? ", truncated" : ""})`);
+        return { content: [{ type: "text", text: lines.join("\n") }], isError: false };
+    }
+    const e = r.error;
+    const lines = [`❌ ${e?.phase ?? "internal"} error: ${e?.message ?? "unknown error"}`];
+    if (r.output)
+        lines.push(`output before error:\n${r.output}`);
+    if (e?.traceback)
+        lines.push(`traceback:\n${e.traceback}`);
+    return { content: [{ type: "text", text: lines.join("\n") }], isError: true };
+}
+export function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError };
+}

package/dist/mcp/tools.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { toToolResult, textResult } from "./toToolResult.js";
+import { buildStateSnippet, isSafePath } from "./snippets.js";
+const NOT_CONNECTED = "The Roblox Studio plugin isn't connected. Open Studio, make sure the rbx-mcp " +
+    "plugin is enabled and Started, and that HttpService is allowed (Game Settings → Security).";
+export function registerTools(server, bridge, config, log) {
+    server.registerTool("execute_lua", {
+        title: "Execute Lua in Roblox Studio",
+        description: "Run a Luau code string inside Roblox Studio (via loadstring) and return its captured " +
+            "output, return values, and any error with traceback. Use this to build, script, inspect, " +
+            "or modify anything in Studio; iterate by reading the error and re-running.",
+        inputSchema: {
+            code: z.string().describe("Luau code to execute in Studio."),
+            timeoutMs: z.number().int().min(1000).max(600000).optional().describe("Execution budget in ms (default 30000)."),
+            label: z.string().optional().describe("Short human label for logs/UI."),
+        },
+    }, async ({ code, timeoutMs, label }) => {
+        if (!bridge.getStatus().pluginConnected)
+            return textResult(NOT_CONNECTED, true);
+        try {
+            const r = await bridge.enqueueAndAwait({ code, timeoutMs, meta: { label } });
+            return toToolResult(r);
+        }
+        catch (err) {
+            return textResult(`❌ ${err.message}`, true);
+        }
+    });
+    server.registerTool("read_studio_state", {
+        title: "Read Roblox Studio state",
+        description: "Inspect Studio state in a clean form: 'selection' (current selection), 'explorer_tree' " +
+            "(workspace tree to a depth), 'instance' (one instance by dotted path, e.g. 'Workspace.Model.Part'), " +
+            "or 'services_summary'. Runs a server-owned snippet — no arbitrary code.",
+        inputSchema: {
+            query: z.enum(["selection", "explorer_tree", "instance", "services_summary"]),
+            path: z.string().optional().describe("For query=instance: dotted path like 'Workspace.Model.Part'."),
+            depth: z.number().int().min(1).max(6).optional().describe("For query=explorer_tree: max depth (default 2)."),
+        },
+    }, async ({ query, path, depth }) => {
+        if (query === "instance" && !isSafePath(path)) {
+            return textResult("`path` is required for query=instance and must look like 'Workspace.Model.Part'.", true);
+        }
+        if (!bridge.getStatus().pluginConnected)
+            return textResult(NOT_CONNECTED, true);
+        const code = buildStateSnippet(query, { path, depth });
+        try {
+            const r = await bridge.enqueueAndAwait({ code, meta: { label: `read_studio_state:${query}` } });
+            return toToolResult(r);
+        }
+        catch (err) {
+            return textResult(`❌ ${err.message}`, true);
+        }
+    });
+    server.registerTool("get_errors", {
+        title: "Recent execution errors",
+        description: "Return the most recent failed executions (message + traceback). Useful for recovering context.",
+        inputSchema: {
+            limit: z.number().int().min(1).max(20).optional().describe("How many recent errors (default 5)."),
+        },
+    }, async ({ limit }) => {
+        const errs = bridge.getRecentErrors(limit ?? 5);
+        if (errs.length === 0)
+            return textResult("No recent errors.");
+        const text = errs
+            .map((e, i) => `#${i + 1} [${e.error?.phase ?? "?"}] ${e.error?.message ?? ""}\n${e.error?.traceback ?? ""}`.trimEnd())
+            .join("\n\n");
+        return textResult(text);
+    });
+    log.debug("registered tools", { tools: ["execute_lua", "read_studio_state", "get_errors"] });
+}

package/dist/types.js

@@ -0,0 +1,25 @@
+/** Structural validation of a result body posted by the plugin (defensive — the wire is untyped). */
+export function isValidResultBody(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const r = v;
+    if (typeof r.commandId !== "string")
+        return false;
+    if (typeof r.ok !== "boolean")
+        return false;
+    if (typeof r.output !== "string")
+        return false;
+    // Be liberal: the plugin omits nil fields, so `error`/`returnValues` may be absent (undefined).
+    if (r.returnValues !== null && r.returnValues !== undefined && !Array.isArray(r.returnValues))
+        return false;
+    if (typeof r.durationMs !== "number")
+        return false;
+    if (r.error !== null && r.error !== undefined) {
+        if (typeof r.error !== "object")
+            return false;
+        const e = r.error;
+        if (typeof e.message !== "string")
+            return false;
+    }
+    return true;
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@lolofuk123/rbx-mcp",
+  "version": "0.2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Bridge that lets an AI agent execute Lua live inside Roblox Studio over MCP.",
+  "type": "module",
+  "bin": {
+    "rbx-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "bundle:plugin": "node scripts/bundle-plugin.mjs",
+    "build": "npm run bundle:plugin && tsc",
+    "dev": "tsx src/index.ts",
+    "dev-enqueue": "tsx src/dev-enqueue.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "roblox",
+    "roblox-studio",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "lua",
+    "luau"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}