@el4cteo/rbx-studio-mcp 0.1.0

package/plugin/src/init.server.luau

@@ -0,0 +1,317 @@
+--!strict
+--[[
+	Studio MCP -- plugin entry point.
+
+	Owns the toolbar UI, this window's Studio identity, and the command loop.
+	Handlers do the actual work; this file only wires them to the transport and
+	reports what is happening to the console widget.
+]]
+
+local HttpService = game:GetService("HttpService")
+local RunService = game:GetService("RunService")
+
+local Config = require(script.Config)
+local Console = require(script.Console)
+local Dispatch = require(script.Dispatch)
+local LogBuffer = require(script.LogBuffer)
+local Phrase = require(script.Phrase)
+local Transport = require(script.Transport)
+local Debug = require(script.handlers.Debug)
+local Assets = require(script.handlers.Assets)
+local Capture = require(script.handlers.Capture)
+local Character = require(script.handlers.Character)
+local Geometry = require(script.handlers.Geometry)
+local World = require(script.handlers.World)
+local Discover = require(script.handlers.Discover)
+local Exec = require(script.handlers.Exec)
+local Instances = require(script.handlers.Instances)
+local Perf = require(script.handlers.Perf)
+local Playtest = require(script.handlers.Playtest)
+local Viewport = require(script.handlers.Viewport)
+local Input = require(script.handlers.Input)
+local Device = require(script.handlers.Device)
+local Api = require(script.handlers.Api)
+local Scripts = require(script.handlers.Scripts)
+local Session = require(script.handlers.Session)
+
+local SETTING_PORT = "port"
+local SETTING_AUTOCONNECT = "autoConnect"
+local SETTING_FORCE_POLL = "forcePoll"
+
+--[[
+	A fresh id per plugin load, which in practice means one per Studio window.
+
+	This was originally persisted with `plugin:SetSetting`, on the reasoning that a
+	stable id keeps reconnects mapping to the same session. That is wrong as soon
+	as the user opens a second window: plugin settings live in one file shared by
+	every Studio process, so both windows announce the same id, and the server
+	treats the second connection as the first one reconnecting -- closing the
+	original stream and making it impossible to address the two places separately.
+
+	Held in memory instead. A reconnect within one load (the SSE stream hits its
+	30-minute cap) reuses this id, and `plugin.Unloading` detaches cleanly on
+	reload, so ghost entries do not accumulate.
+]]
+local SESSION_ID = HttpService:GenerateGUID(false)
+
+local function studioId(): string
+	return SESSION_ID
+end
+
+--[[
+	Whether this copy of the plugin can reach the bridge at all.
+
+	Pressing Play loads the plugin into the playtest's DataModels as well as the
+	editor's, and HttpService refuses every request from a client one: "Http
+	requests can only be executed by game server". The transport read that as a
+	dropped connection and retried forever, filling the console with red while
+	nothing was actually wrong.
+
+	The editor session and the play session's server can both connect and are
+	worth connecting -- addressing a running server is useful. The client half
+	simply says so once and stops.
+]]
+local function canConnect(): (boolean, string?)
+	if RunService:IsEdit() or RunService:IsServer() then
+		return true, nil
+	end
+	--[[
+		The wording names the fix, because the symptom is indistinguishable
+		from a broken server: a user watching this window during a playtest
+		sees a console that logs nothing while tools plainly work, and has no
+		way to guess that the activity is in a different view of the same
+		Studio. Reported once here and again as the strip's caption, since
+		one line scrolled off the top is easy to miss.
+	]]
+	return false,
+		"client view of a playtest -- Studio forbids client sessions from making HTTP "
+			.. "requests. The playtest's server session is connected and handling this "
+			.. "place; switch Studio to the Server view (Test tab, Current: Server) to "
+			.. "watch it work."
+end
+
+-- First thing, before any handler or the transport can log: the buffer only
+-- holds what was printed after it subscribed, so every line ahead of this call
+-- is unrecoverable. This runs even in a client session that will never connect,
+-- since the console tool reads it and connectivity is a separate question.
+LogBuffer.start()
+
+local storedPort = plugin:GetSetting(SETTING_PORT)
+if typeof(storedPort) == "number" then
+	Config.setPort(storedPort)
+end
+
+Transport.setForcePoll(plugin:GetSetting(SETTING_FORCE_POLL) == true)
+
+Session.register()
+Discover.register()
+Debug.register()
+Instances.register()
+Perf.register(plugin)
+Playtest.register()
+Capture.register()
+Assets.register()
+Character.register()
+Geometry.register()
+World.register()
+Exec.register()
+Viewport.register()
+Scripts.register()
+Input.register()
+Device.register()
+Api.register()
+
+local toolbar = plugin:CreateToolbar("Studio MCP")
+local button = toolbar:CreateButton(
+	"Studio MCP",
+	"Show the Studio MCP console",
+	"rbxasset://textures/ui/common/robux.png"
+)
+button.ClickableWhenViewportHidden = true
+
+-- Enabled by default: the whole point is that opening a place shows you it
+-- connected without touching anything. Studio remembers the user's choice after
+-- the first time they close it.
+local widget = plugin:CreateDockWidgetPluginGuiAsync(
+	"StudioMCP_Console",
+	DockWidgetPluginGuiInfo.new(Enum.InitialDockState.Float, true, false, 560, 320, 360, 200)
+)
+widget.Title = "Studio MCP"
+
+local currentStatus: Transport.Status = "disconnected"
+
+local function refreshMeta()
+	Console.setStatus(
+		currentStatus,
+		string.format(
+			"127.0.0.1:%d  %s  build %s",
+			Config.getPort(),
+			Transport.getMode(),
+			Config.BUILD_ID
+		)
+	)
+	button:SetActive(currentStatus == "connected")
+end
+
+local connect: () -> ()
+
+Console.mount(widget, {
+	onReconnect = function()
+		Console.log("info", "reconnect requested")
+		Transport.stop()
+		task.wait(0.2)
+		connect()
+	end,
+	onClear = function()
+		Console.clear()
+	end,
+})
+
+Console.log("info", string.format("Studio MCP v%s", Config.PLUGIN_VERSION), "build " .. Config.BUILD_ID)
+Console.log("dim", string.format("place: %s (%d)", game.Name, game.PlaceId))
+
+local function onStatus(status: Transport.Status, detail: string?)
+	local previous = currentStatus
+	currentStatus = status
+	refreshMeta()
+
+	-- Only narrate transitions. The transport re-reports its state on every
+	-- reconnect attempt, and echoing an unchanged status would bury real events.
+	if status == previous and detail == nil then
+		return
+	end
+
+	if status == "connected" then
+		Console.log(
+			"ok",
+			string.format("connected to 127.0.0.1:%d", Config.getPort()),
+			if detail then "(" .. detail .. ")" else nil
+		)
+	elseif status == "connecting" then
+		Console.log("dim", string.format("connecting to 127.0.0.1:%d...", Config.getPort()))
+	else
+		Console.log("error", "disconnected", detail)
+	end
+end
+
+--[[
+	Runs each command on its own task. Handlers may yield -- `UpdateSourceAsync`
+	and any `*Async` call does -- and serialising them would let one slow edit
+	stall every other request on the stream.
+]]
+local function onCommand(id: string, op: string, params: { [string]: any }?)
+	task.spawn(function()
+		local startedAt = os.clock()
+		--[[
+			Named for what it does, not for how it travels. `script.edit` on
+			ServerScriptService.Systems.KillBrick reads as "Edit KillBrick",
+			which is the thing someone watching actually wants to know; the wire
+			name is kept alongside so the log still maps onto the protocol when
+			something needs debugging.
+		]]
+		local title = Phrase.of(op, params)
+		Console.beginCall(title, Phrase.kindOf(op))
+
+		local result = Dispatch.invoke(id, op, params)
+		local elapsed = string.format("%.0fms", (os.clock() - startedAt) * 1000)
+
+		Console.recordCall(result.ok, (os.clock() - startedAt) * 1000)
+
+		if result.ok then
+			Console.log("reply", title, elapsed)
+		else
+			local err = result.error
+			Console.log(
+				"error",
+				string.format("%s failed: %s", title, if err then err.code else "unknown"),
+				elapsed
+			)
+			if err and err.message then
+				Console.log("dim", "   " .. err.message)
+			end
+		end
+
+		Transport.sendResult(result)
+	end)
+end
+
+function connect()
+	local allowed, reason = canConnect()
+	if not allowed then
+		-- Reported as standby rather than an error: nothing failed, and this
+		-- session was never going to connect.
+		currentStatus = "disconnected"
+		Console.log("dim", "standby", reason)
+		Console.setStatus(
+			"standby",
+			string.format("%s  build %s", "client view", Config.BUILD_ID)
+		)
+		Console.setCaption("switch to the Server view to watch this playtest")
+		return
+	end
+	Transport.start(studioId(), { onCommand = onCommand, onStatus = onStatus })
+	plugin:SetSetting(SETTING_AUTOCONNECT, true)
+end
+
+button.Click:Connect(function()
+	widget.Enabled = not widget.Enabled
+end)
+
+plugin.Unloading:Connect(function()
+	Transport.stop()
+end)
+
+--[[
+	Switches this session between the push and long-poll transports.
+
+	Registered here rather than in a handler module because it is the only
+	command that has to reach back into the plugin object and the connection
+	loop, both of which live in this file -- and registered THIS far down the
+	file on purpose: `connect` is a forward-declared local, so a closure written
+	above its declaration captures the global of that name instead, which is nil.
+	That cost a session. The plugin loaded and connected perfectly, and then died
+	the first time somebody asked it to switch transport.
+
+	The reply is sent before the reconnect, and the reconnect is deferred:
+	tearing the stream down inside the handler would strand the answer to the
+	very call that asked for the switch, which is a confusing way to succeed.
+]]
+Dispatch.registerAll("studio", {
+	transport = function(params: { [string]: any }): { [string]: any }
+		local requested = params.mode
+		if requested ~= nil and requested ~= "sse" and requested ~= "poll" then
+			Dispatch.fail("BAD_PARAMS", 'transport mode must be "sse" or "poll".')
+		end
+		if requested == nil then
+			return { mode = Transport.getMode(), forcePoll = Transport.getForcePoll(), changed = false }
+		end
+
+		local wantPoll = requested == "poll"
+		if Transport.getMode() == requested and Transport.getForcePoll() == wantPoll then
+			return { mode = Transport.getMode(), forcePoll = wantPoll, changed = false }
+		end
+
+		Transport.setForcePoll(wantPoll)
+		plugin:SetSetting(SETTING_FORCE_POLL, wantPoll)
+		task.defer(function()
+			Transport.stop()
+			task.wait(0.1)
+			connect()
+		end)
+		return {
+			mode = requested,
+			forcePoll = wantPoll,
+			changed = true,
+			note = "Reconnecting on the new transport; the next call will use it.",
+		}
+	end,
+})
+
+refreshMeta()
+
+-- Connect on load unless the user explicitly disconnected last session.
+if plugin:GetSetting(SETTING_AUTOCONNECT) ~= false then
+	connect()
+else
+	Console.log("warn", "auto-connect disabled — press reconnect to start")
+end

package/scripts/build-plugin.mjs

@@ -0,0 +1,157 @@
+/**
+ * Builds plugin/src into an installable StudioMCP.rbxmx.
+ *
+ * Rojo would do this too, but requiring contributors (and users building from
+ * source) to install a Luau toolchain just to get a plugin file is friction the
+ * project does not need. The .rbxmx format is plain XML, so we emit it directly
+ * and keep `plugin/default.project.json` around for people who do use Rojo.
+ *
+ * Usage: node scripts/build-plugin.mjs [outputPath]
+ */
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const sourceDir = join(root, "plugin", "src");
+const outputPath = resolve(process.argv[2] ?? join(root, "build", "StudioMCP.rbxmx"));
+
+const NEWLINE = "\n";
+
+/**
+ * Fingerprints plugin/src so the running plugin can be compared against the
+ * sources this package ships. Must stay byte-identical to
+ * `expectedPluginBuildId` in src/lib/pluginbuild.ts — line endings are
+ * normalised because git checkouts differ across platforms.
+ */
+function buildId(dir) {
+  const files = [];
+
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+      } else if (entry.name.endsWith(".luau")) {
+        files.push([
+          relative(dir, path).split("\\").join("/"),
+          readFileSync(path, "utf8"),
+        ]);
+      }
+    }
+  };
+  walk(dir);
+  files.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+
+  const hash = createHash("sha256");
+  for (const [path, contents] of files) {
+    hash.update(path);
+    hash.update(NEWLINE);
+    hash.update(contents.replace(/\r\n/g, NEWLINE));
+    hash.update(NEWLINE);
+  }
+  return hash.digest("hex").slice(0, 12);
+}
+
+const stamp = buildId(sourceDir);
+
+let nextReferent = 0;
+
+/** XML text escaping for property values (source goes in CDATA instead). */
+const escapeXml = (value) =>
+  value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+
+/**
+ * Wraps Luau source in CDATA. A literal "]]>" would close the section early, so
+ * it is split across two adjacent sections — the parser rejoins them.
+ */
+const cdata = (source) => `<![CDATA[${source.replaceAll("]]>", "]]]]><![CDATA[>")}]]>`;
+
+function renderItem(node, depth) {
+  const pad = "  ".repeat(depth);
+  const referent = `RBX${nextReferent++}`;
+  const properties = [`${pad}    <string name="Name">${escapeXml(node.name)}</string>`];
+
+  if (node.source !== undefined) {
+    properties.push(`${pad}    <ProtectedString name="Source">${cdata(node.source)}</ProtectedString>`);
+  }
+  if (node.className === "Script") {
+    // Plugin scripts must not be disabled, and RunContext 0 (Legacy) is what
+    // Studio expects for code running in the plugin's own context.
+    properties.push(`${pad}    <bool name="Disabled">false</bool>`);
+    properties.push(`${pad}    <token name="RunContext">0</token>`);
+  }
+
+  const children = node.children.map((child) => renderItem(child, depth + 1)).join(NEWLINE);
+
+  return [
+    `${pad}<Item class="${node.className}" referent="${referent}">`,
+    `${pad}  <Properties>`,
+    ...properties,
+    `${pad}  </Properties>`,
+    ...(children ? [children] : []),
+    `${pad}</Item>`,
+  ].join(NEWLINE);
+}
+
+/**
+ * Mirrors Rojo's naming rules: `init.server.luau` turns its folder into a
+ * Script, `init.luau` into a ModuleScript, and every other .luau file becomes a
+ * ModuleScript child. That keeps this builder and Rojo producing the same tree.
+ */
+function buildTree(dir, name) {
+  const node = { name, className: "Folder", children: [] };
+
+  for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const path = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      node.children.push(buildTree(path, entry.name));
+      continue;
+    }
+    if (!entry.name.endsWith(".luau")) continue;
+
+    let source = readFileSync(path, "utf8");
+    if (entry.name === "Config.luau") {
+      // Stamped with the fingerprint of the pre-injection sources, which is
+      // exactly what the server recomputes at runtime.
+      source = source.replace('Config.BUILD_ID = "dev"', `Config.BUILD_ID = "${stamp}"`);
+    }
+
+    if (entry.name === "init.server.luau") {
+      node.className = "Script";
+      node.source = source;
+    } else if (entry.name === "init.luau") {
+      node.className = "ModuleScript";
+      node.source = source;
+    } else {
+      node.children.push({
+        name: entry.name.replace(/\.luau$/, ""),
+        className: "ModuleScript",
+        source,
+        children: [],
+      });
+    }
+  }
+
+  return node;
+}
+
+const tree = buildTree(sourceDir, "StudioMCP");
+const document = [
+  '<roblox xmlns:xmime="http://www.w3.org/2005/05/xmlmime"',
+  '  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"',
+  '  xsi:noNamespaceSchemaLocation="http://www.roblox.com/roblox.xsd" version="4">',
+  renderItem(tree, 1),
+  "</roblox>",
+  "",
+].join(NEWLINE);
+
+mkdirSync(dirname(outputPath), { recursive: true });
+writeFileSync(outputPath, document, "utf8");
+writeFileSync(join(dirname(outputPath), "plugin-build-id.txt"), stamp + NEWLINE, "utf8");

package/scripts/check-plugin.mjs

@@ -0,0 +1,97 @@
+/**
+ * Compiles every plugin source file, so a broken one is caught here rather than
+ * in Studio.
+ *
+ * This exists because the feedback loop without it is terrible. Nothing in the
+ * Node build reads the Luau at all -- `build:plugin` packs the files into an
+ * .rbxmx as text -- so a syntax error ships, installs, and is only discovered
+ * when the user focuses Studio and the plugin fails to load. It cost two
+ * sessions in one afternoon: a literal newline written into a string where an
+ * escape was meant, and a closure that captured a nil global because it sat
+ * above the forward declaration of the local it meant to call. The first is a
+ * compile error and would have been caught instantly by this. The second is not,
+ * which is why `--!strict` analysis runs too when the analyser is available:
+ * an unknown global is exactly what it flags.
+ *
+ * Needs `luau-compile` (and ideally `luau-analyze`) on PATH, in ./tools, or
+ * named by the LUAU_COMPILE / LUAU_ANALYZE environment variables. Get them from
+ * https://github.com/luau-lang/luau/releases.
+ *
+ * Silent and exit 0 when everything compiles; prints what failed otherwise.
+ *
+ * Usage: node scripts/check-plugin.mjs
+ */
+import { spawnSync } from "node:child_process";
+import { readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { locateLuau, missingLuau } from "./locate-luau.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function luauFiles(directory) {
+  const found = [];
+  for (const entry of readdirSync(directory)) {
+    const path = join(directory, entry);
+    if (statSync(path).isDirectory()) found.push(...luauFiles(path));
+    else if (entry.endsWith(".luau")) found.push(path);
+  }
+  return found;
+}
+
+const compiler = locateLuau("LUAU_COMPILE", ["luau-compile.exe", "luau-compile"]);
+if (compiler === null) {
+  process.stderr.write(
+    "No luau-compile found. Put it on PATH or in ./tools, or set LUAU_COMPILE.\n" +
+      "Download: https://github.com/luau-lang/luau/releases\n",
+  );
+  process.exit(1);
+}
+
+const files = luauFiles(join(root, "plugin", "src"));
+const failures = [];
+
+for (const file of files) {
+  // --binary throws the bytecode away; only the exit status and diagnostics
+  // matter, and writing it anywhere would just be litter to clean up.
+  const result = spawnSync(compiler, ["--binary", file], { encoding: "utf8" });
+  const diagnostics = `${result.stderr ?? ""}${result.status === 0 ? "" : (result.stdout ?? "")}`.trim();
+  if (result.status !== 0 || diagnostics.length > 0) {
+    failures.push(`${file.slice(root.length + 1)}\n${diagnostics}`);
+  }
+}
+
+/*
+ * One diagnostic from the analyser, deliberately.
+ *
+ * `LocalShadow` is reported when a name is used as a global and a local of that
+ * same name is declared later in the file -- which is the shape of the bug this
+ * check was written for, and is unambiguous. Running the analyser without
+ * Roblox's type definitions also reports every engine global as unknown, so
+ * `script`, `task`, `Color3` and friends produce hundreds of lines of noise;
+ * filtering to this one diagnostic gets the signal without needing a
+ * definitions file that would then have to be kept current with the engine.
+ */
+const analyser = locateLuau("LUAU_ANALYZE", ["luau-analyze.exe", "luau-analyze"]);
+const shadowed = [];
+if (analyser !== null) {
+  for (const file of files) {
+    const result = spawnSync(analyser, [file], { encoding: "utf8" });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    for (const line of output.split("\n")) {
+      if (line.includes("LocalShadow:")) shadowed.push(line.trim());
+    }
+  }
+}
+
+if (failures.length > 0) {
+  process.stderr.write(`${failures.join("\n\n")}\n`);
+}
+if (shadowed.length > 0) {
+  process.stderr.write(
+    "\nA local is used before it is declared, so the call reaches a nil global " +
+      "instead:\n" +
+      `${shadowed.join("\n")}\n`,
+  );
+}
+process.exit(failures.length > 0 || shadowed.length > 0 ? 1 : 0);

package/scripts/install-plugin.mjs

@@ -0,0 +1,39 @@
+/**
+ * Builds the plugin and drops it into the local Roblox Studio plugins folder.
+ *
+ * Studio watches that directory and hot-reloads, so re-running this while Studio
+ * is open picks up the new build without a restart.
+ *
+ * Usage: node scripts/install-plugin.mjs
+ */
+import { execFileSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const built = join(root, "build", "StudioMCP.rbxmx");
+
+/** Studio's per-user plugin directory, which differs per platform. */
+function pluginsDir() {
+  if (process.platform === "win32") {
+    const local = process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+    return join(local, "Roblox", "Plugins");
+  }
+  if (process.platform === "darwin") {
+    return join(homedir(), "Documents", "Roblox", "Plugins");
+  }
+  // Studio only ships for Windows and macOS; anything else is a Wine/Proton
+  // layout we cannot guess, so make the user point us at it.
+  throw new Error(
+    "Roblox Studio does not run natively on this platform. Build with " +
+      "`npm run build:plugin` and copy build/StudioMCP.rbxmx into your plugins folder.",
+  );
+}
+
+execFileSync(process.execPath, [join(root, "scripts", "build-plugin.mjs")], { stdio: "inherit" });
+
+const target = pluginsDir();
+if (!existsSync(target)) mkdirSync(target, { recursive: true });
+copyFileSync(built, join(target, "StudioMCP.rbxmx"));