@el4cteo/rbx-studio-mcp 0.8.3 → 0.8.6

package/plugin/src/init.server.luau

@@ -44,6 +44,7 @@ local Device = require(script.handlers.Device)
 local Data = require(script.handlers.Data)
 local Api = require(script.handlers.Api)
 local Scripts = require(script.handlers.Scripts)
+local Sync = require(script.handlers.Sync)
 local Session = require(script.handlers.Session)
 
 local SETTING_PORT = "port"
@@ -65,6 +66,9 @@ local SETTING_WIDGET_OPEN = "widgetOpen"
 ]]
 local SETTING_AUTO_OPEN = "autoOpen"
 local SETTING_PLAYTESTS = "playtestsEnabled"
+-- Whether sentences typed at the prompt are sent to an agent. Absent means off:
+-- it only turns on when the user runs `chat on`.
+local SETTING_CHAT = "chatEnabled"
 local SETTING_WIDGET_SIZE = "widgetSize"
 local SETTING_WIDGET_TRACE = "widgetTrace"
 
@@ -193,6 +197,7 @@ Audio.register()
 Exec.register()
 Viewport.register()
 Scripts.register()
+Sync.register()
 Input.register()
 Device.register()
 Data.register()
@@ -261,6 +266,8 @@ local wantOpen = if typeof(storedOpen) == "boolean" then storedOpen else true
 	left exactly as it was, so turning this back on restores the panel to however
 	it was last left rather than to a default.
 ]]
+local chat = plugin:GetSetting(SETTING_CHAT) == true
+
 local storedAutoOpen = plugin:GetSetting(SETTING_AUTO_OPEN)
 local autoOpen = if typeof(storedAutoOpen) == "boolean" then storedAutoOpen else true
 if not autoOpen then
@@ -560,12 +567,27 @@ Commands.setup({
 		autoOpen = value
 		plugin:SetSetting(SETTING_AUTO_OPEN, value)
 	end,
+	chat = function()
+		return chat
+	end,
+	saveChat = function(value)
+		chat = value
+		plugin:SetSetting(SETTING_CHAT, value)
+	end,
 	status = function()
 		return currentStatus
 	end,
 	studioId = studioId,
 })
 
+Console.setPromptChat(chat)
+
+-- Sync reports what it changed in the log; handed a function rather than the
+-- console itself, for the same reason `Commands` is.
+Sync.setup(function(level, message, detail)
+	Console.log(level :: any, message, detail)
+end)
+
 -- The saved preset, now that there is something to paint. Done immediately
 -- after mounting and before the first line is logged, so nothing is ever drawn
 -- in the wrong palette.
@@ -741,7 +763,30 @@ end
 	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 }?)
+--[[
+	Commands that run without a line in the log.
+
+	`sync watch` asks what changed twice a second for as long as it runs, and
+	`sync.log` exists to print a line of its own. Logging either call would bury
+	everything else the panel shows under a heartbeat nobody needs to see.
+]]
+local QUIET: { [string]: boolean } = {
+	["sync.changes"] = true,
+	["sync.log"] = true,
+	["sync.shape"] = true,
+	["sync.revisions"] = true,
+}
+
+local function onCommand(id: string, op: string, params: { [string]: any }?, deadlineMs: number?)
+	-- A sync op can also ask to be quiet: `watch` runs the same scans a manual
+	-- sync does, and logging each would print a heartbeat. What a watch
+	-- actually changes is still logged, by `sync.apply` and `sync.log`.
+	if QUIET[op] or (string.sub(op, 1, 5) == "sync." and params ~= nil and params.quiet == true) then
+		task.spawn(function()
+			Transport.sendResult(Dispatch.invoke(id, op, params, deadlineMs))
+		end)
+		return
+	end
 	task.spawn(function()
 		local startedAt = os.clock()
 		--[[
@@ -764,7 +809,7 @@ local function onCommand(id: string, op: string, params: { [string]: any }?)
 		]]
 		Console.beginCall(title, Phrase.kindOf(op))
 
-		local result = Dispatch.invoke(id, op, params)
+		local result = Dispatch.invoke(id, op, params, deadlineMs)
 		local milliseconds = (os.clock() - startedAt) * 1000
 
 		--[[

package/scripts/build.mjs

@@ -0,0 +1,14 @@
+/** Build from a clean output directory so removed tools cannot enter npm packs. */
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = realpathSync(resolve(dirname(fileURLToPath(import.meta.url)), ".."));
+const output = join(root, "dist");
+if (existsSync(output)) {
+  // Refuse junctions/symlinks outside the exact generated-output directory.
+  if (realpathSync(output) !== output) throw new Error("dist resolves outside the expected build directory");
+  rmSync(output, { recursive: true, force: true });
+}
+execFileSync(process.execPath, [join(root, "node_modules", "typescript", "bin", "tsc")], { cwd: root, stdio: "inherit" });

package/scripts/sync-fake.mjs

@@ -0,0 +1,191 @@
+/**
+ * An in-memory Studio answering the plugin's `sync.*` ops, for the offline
+ * sync tests. It keeps the plugin's contracts -- revisions, writes and moves
+ * conditional on them, per-item results, change tracking that also reports
+ * the echo of sync's own writes -- without any of its Roblox.
+ */
+import { createHash } from "node:crypto";
+import { ToolError } from "../dist/lib/errors.js";
+
+export const fingerprint = (source) => createHash("sha1").update(source).digest("hex").slice(0, 12);
+
+/** A scan from a flat map of script paths, the way the plugin reports one. */
+export function scanOf(scripts, folders = {}) {
+  const nodes = [];
+  const index = new Map();
+  const nodeOf = (segments, className) => {
+    const key = segments.join(".");
+    if (index.has(key)) return index.get(key);
+    const parent = segments.length > 1 ? nodeOf(segments.slice(0, -1), folders[segments.slice(0, -1).join(".")] ?? "Folder") : 0;
+    nodes.push({ path: key, name: segments.at(-1), className, parent });
+    index.set(key, nodes.length);
+    return nodes.length;
+  };
+  const items = [];
+  for (const [scriptPath, info] of Object.entries(scripts)) {
+    const node = nodeOf(scriptPath.split("."), info.className);
+    nodes[node - 1].className = info.className;
+    items.push({ node, revision: info.revision, fileSynced: info.fileSynced });
+  }
+  return { nodes, items, roots: [...new Set(Object.keys(scripts).map((key) => key.split(".")[0]))] };
+}
+
+/** `{value, type}` property specs back to plain values, as Studio would store them. */
+function untype(spec) {
+  const out = { className: spec.className, name: spec.name };
+  if (spec.properties) {
+    out.properties = Object.fromEntries(
+      Object.entries(spec.properties).map(([key, value]) => [key, value && typeof value === "object" && "value" in value ? value.value : value]),
+    );
+  }
+  if (spec.attributes) out.attributes = spec.attributes;
+  if (spec.tags) out.tags = spec.tags;
+  if (spec.children) out.children = spec.children.map(untype);
+  for (const key of Object.keys(out)) if (out[key] === undefined) delete out[key];
+  return out;
+}
+
+const classesIn = (spec, into = new Set()) => {
+  into.add(spec.className);
+  for (const child of spec.children ?? []) classesIn(child, into);
+  return into;
+};
+
+export function fakeStudio(placeId = 1) {
+  const scripts = new Map(); // path -> { className, source }
+  const trees = new Map(); // path -> build spec (plain values)
+  const dirty = new Set();
+  const logged = [];
+  const session = { studioId: "edit", placeId, placeName: "Test", context: "edit" };
+  const chain = (item) => [item.parentPath, ...(item.parents ?? []).map((link) => link.name)].filter(Boolean).join(".");
+  const calls = [];
+
+  const bridge = {
+    scripts,
+    trees,
+    logged,
+    calls,
+    /** Studio restarted: same place, new session id. */
+    restart() {
+      session.studioId = `${session.studioId}+`;
+    },
+    /** An edit made in Studio: tracked, as the plugin's events would. */
+    edit(path, source) {
+      scripts.get(path).source = source;
+      dirty.add(path);
+    },
+    async sessions() {
+      return { list: [session], activeId: null, activeIsChosen: false };
+    },
+    async call(op, params = {}, options = {}) {
+      calls.push(op);
+      if (options.studioId !== undefined && options.studioId !== session.studioId) {
+        throw new ToolError("UNKNOWN_STUDIO", `No connected Studio has id "${options.studioId}".`);
+      }
+      switch (op) {
+        case "sync.scan": {
+          const byPath = {};
+          for (const [key, value] of scripts) {
+            byPath[key] = { className: value.className, revision: params.revisions === false ? undefined : fingerprint(value.source) };
+          }
+          const scan = scanOf(byPath);
+          scan.roots = ["ServerScriptService", "ReplicatedStorage", "StarterGui"];
+          return scan;
+        }
+        case "sync.shape":
+          return { shape: [...scripts.keys()].sort().join("\n") };
+        case "sync.read":
+          return {
+            items: params.paths.map((key) =>
+              scripts.has(key)
+                ? { path: key, source: scripts.get(key).source, revision: fingerprint(scripts.get(key).source), className: scripts.get(key).className }
+                : { path: key, code: "NOT_FOUND", message: "gone" },
+            ),
+          };
+        case "sync.revisions":
+          return {
+            items: params.paths.map((key) =>
+              scripts.has(key) ? { path: key, revision: fingerprint(scripts.get(key).source) } : { path: key, missing: true },
+            ),
+          };
+        case "sync.changes": {
+          const out = { token: "tracking", reset: params.token !== "tracking", dirty: [...dirty], structural: false };
+          dirty.clear();
+          return out;
+        }
+        case "sync.apply": {
+          const out = { writes: [], creates: [], deletes: [], moves: [], undoStep: "MCP sync" };
+          for (const item of params.creates ?? []) {
+            const target = `${chain(item)}.${item.name}`;
+            if (scripts.has(target)) out.creates.push({ ok: false, code: "EXISTS", message: "exists" });
+            else {
+              scripts.set(target, { className: item.className, source: item.source });
+              out.creates.push({ ok: true, path: target, revision: fingerprint(item.source) });
+            }
+          }
+          for (const item of params.deletes ?? []) {
+            const current = scripts.get(item.path);
+            if (!current || fingerprint(current.source) !== item.revision) out.deletes.push({ ok: false, path: item.path, code: "STALE_SCRIPT", message: "changed" });
+            else {
+              scripts.delete(item.path);
+              out.deletes.push({ ok: true, path: item.path });
+            }
+          }
+          for (const item of params.moves ?? []) {
+            const current = scripts.get(item.path);
+            if (!current || fingerprint(current.source) !== item.revision) out.moves.push({ ok: false, from: item.path, code: "STALE_SCRIPT", message: "changed" });
+            else {
+              const target = `${chain(item)}.${item.name}`;
+              scripts.delete(item.path);
+              scripts.set(target, current);
+              out.moves.push({ ok: true, from: item.path, path: target });
+            }
+          }
+          for (const item of params.writes ?? []) {
+            const current = scripts.get(item.path);
+            if (!current || fingerprint(current.source) !== item.revision) out.writes.push({ ok: false, path: item.path, code: "STALE_SCRIPT", message: "changed" });
+            else {
+              current.source = item.source;
+              // The plugin's editor event fires for sync's own write too.
+              dirty.add(item.path);
+              out.writes.push({ ok: true, path: item.path, revision: fingerprint(item.source) });
+            }
+          }
+          return out;
+        }
+        case "sync.classes": {
+          const spec = trees.get(params.path);
+          if (!spec) throw new ToolError("NOT_FOUND", `nothing at ${params.path}`);
+          const segments = params.path.split(".");
+          return {
+            path: params.path,
+            classes: [...classesIn(spec)].sort(),
+            chain: segments.map((name, index) => ({
+              name,
+              className: index === segments.length - 1 ? spec.className : index === 0 ? name : "Folder",
+              path: segments.slice(0, index + 1).join("."),
+            })),
+          };
+        }
+        case "sync.export": {
+          const spec = trees.get(params.path);
+          return { path: params.path, spec: structuredClone(spec), instances: classesIn(spec).size, scripts: 0, skipped: [] };
+        }
+        case "sync.build": {
+          const target = `${params.parent}.${params.spec.name ?? params.spec.className}`;
+          if (params.replaces && params.replaces !== target) trees.delete(params.replaces);
+          trees.set(target, untype(params.spec));
+          return { path: target, carried: [] };
+        }
+        case "sync.log":
+          logged.push(...params.lines);
+          return { logged: true };
+        case "sync.stop":
+          return { stopped: true };
+        default:
+          throw new Error(`fake Studio has no ${op}`);
+      }
+    },
+  };
+  return bridge;
+}

package/scripts/test-live-sync-scale.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * `sync` at scale, against a real Studio: thousands of scripts, same-named
+ * siblings, a source past the `.Source` limit -- timed, so a slowdown shows up
+ * as a number rather than as a watch that "feels laggy".
+ *
+ * Builds ServerStorage.__mcp_sync_scale and a temp folder, and removes both.
+ *
+ * Usage: node scripts/test-live-sync-scale.mjs [--scripts 2000] [--port 44755] [--studio-id ID]
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const at = args.indexOf(`--${name}`);
+  return at === -1 ? fallback : args[at + 1];
+};
+const COUNT = Number(flag("scripts", "2000"));
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const FIXTURE = "ServerStorage.__mcp_sync_scale";
+const dir = mkdtempSync(join(tmpdir(), "rbx-sync-scale-"));
+const file = (relative) => join(dir, "ServerStorage", "__mcp_sync_scale", ...relative.split("/"));
+const studioId = flag("studio-id");
+
+const client = new Client({ name: "test-live-sync-scale", version: "0" });
+await client.connect(
+  new StdioClientTransport({
+    command: process.execPath,
+    args: [join(root, "dist", "index.js"), ...(flag("port") ? ["--port", flag("port")] : [])],
+    stderr: "inherit",
+  }),
+);
+
+let failures = 0;
+const timings = [];
+async function call(name, params = {}) {
+  const started = performance.now();
+  const result = await client.callTool({ name, arguments: { ...(studioId ? { studioId } : {}), ...params } }, undefined, { timeout: 600_000 });
+  const text = (result.content ?? []).filter((part) => part.type === "text").map((part) => part.text).join("\n");
+  return { text, isError: result.isError === true, ms: Math.round(performance.now() - started) };
+}
+function report(label, good, detail = "") {
+  if (!good) failures += 1;
+  process.stdout.write(`${good ? "ok  " : "FAIL"}  ${label.padEnd(48)} ${detail.replace(/\s+/g, " ").slice(0, good ? 100 : 400)}\n`);
+}
+async function timed(label, name, params, expect = /./) {
+  const reply = await call(name, params);
+  timings.push([label, reply.ms]);
+  report(label, !reply.isError && expect.test(reply.text), `${reply.ms}ms  ${reply.text}`);
+  return reply;
+}
+const luau = async (source) => {
+  const reply = await call("execute_luau", { source });
+  if (reply.isError) throw new Error(reply.text);
+  return reply.text;
+};
+const sync = (op, extra = {}) => ({ op, dir, roots: [FIXTURE], ...extra });
+const until = async (probe, seconds = 10) => {
+  const started = Date.now();
+  for (;;) {
+    if (await probe()) return Date.now() - started;
+    if (Date.now() - started > seconds * 1000) return -1;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+};
+
+try {
+  // A place-shaped tree: 40 folders of modules with realistic bodies, two
+  // same-named siblings, and one script too long for `.Source`.
+  await luau(`
+    local old = game.ServerStorage:FindFirstChild("__mcp_sync_scale")
+    if old then old:Destroy() end
+    local fixture = Instance.new("Folder"); fixture.Name = "__mcp_sync_scale"
+    local body = string.rep("local value = math.random() * 100 -- padding to look like real code\\n", 30)
+    for f = 1, 40 do
+      local folder = Instance.new("Folder"); folder.Name = "Feature" .. f; folder.Parent = fixture
+      for s = 1, math.floor(${COUNT} / 40) do
+        local module = Instance.new("ModuleScript"); module.Name = "Module" .. s
+        module.Source = "-- " .. f .. "/" .. s .. "\\n" .. body .. "return {}\\n"
+        module.Parent = folder
+      end
+    end
+    local a = Instance.new("ModuleScript"); a.Name = "Dup"; a.Source = "return 'first'\\n"; a:SetAttribute("Which", "first"); a.Parent = fixture
+    local b = Instance.new("ModuleScript"); b.Name = "Dup"; b.Source = "return 'second'\\n"; b:SetAttribute("Which", "second"); b.Parent = fixture
+    fixture.Parent = game.ServerStorage
+    local big = Instance.new("ModuleScript"); big.Name = "Big"; big.Parent = fixture
+    game:GetService("ScriptEditorService"):UpdateSourceAsync(big, function() return string.rep("-- a long generated table row\\n", 12000) .. "return {}\\n" end)
+    return "ok"`);
+
+  await timed(`pull ${COUNT + 3} scripts`, "sync", sync("pull"), new RegExp(`${COUNT + 3} created on disk`));
+  await timed("no-op sync (nothing changed)", "sync", sync("sync"), /nothing to do/);
+  await timed("no-op sync again (revision cache warm)", "sync", sync("sync"), /nothing to do/);
+
+  writeFileSync(file("Feature7/Module3.luau"), "return 'edited'\n");
+  await timed("one file edited", "sync", sync("sync"), /1 written to Studio/);
+  const edited = await luau(`return game.ServerStorage.__mcp_sync_scale.Feature7.Module3.Source`);
+  report("the right script took it", edited.includes("edited"), edited);
+
+  // Same-named siblings: two files, each bound to its own script.
+  report("duplicate names get two files", existsSync(file("Dup.luau")) && existsSync(file("Dup~2.luau")));
+  const second = readFileSync(file("Dup~2.luau"), "utf8").includes("second") ? "Dup~2.luau" : "Dup.luau";
+  writeFileSync(file(second), "return 'second, edited'\n");
+  await timed("edit one of two same-named scripts", "sync", sync("sync"), /1 written to Studio/);
+  const which = await luau(`
+    for _, s in game.ServerStorage.__mcp_sync_scale:GetChildren() do
+      if s.Name == "Dup" and string.find(s.Source, "edited") then return s:GetAttribute("Which") end
+    end
+    return "none"`);
+  report("edit landed on the matching duplicate", which.includes("second"), which);
+
+  // Past the .Source limit: round trip through the editor path.
+  const big = readFileSync(file("Big.luau"), "utf8");
+  report("large script pulled whole", big.length > 300_000, `${big.length} chars`);
+  writeFileSync(file("Big.luau"), `${big}-- appended\n`);
+  await timed("push a 360KB script", "sync", sync("sync"), /1 written to Studio/);
+  const tail = await luau(`local s = game.ServerStorage.__mcp_sync_scale.Big.Source return string.sub(s, -12)`);
+  report("large script edit landed", tail.includes("appended"), tail);
+
+  // Watch latency at this size.
+  await timed("watch start", "sync", sync("watch"), /Watching|Already/);
+  writeFileSync(file("Feature20/Module5.luau"), "return 'watched'\n");
+  const toStudio = await until(async () => (await luau(`return game.ServerStorage.__mcp_sync_scale.Feature20.Module5.Source`)).includes("watched"));
+  timings.push(["watch: file -> Studio", toStudio]);
+  report("watch: file edit reached Studio", toStudio >= 0, `${toStudio}ms`);
+  await luau(`game:GetService("ScriptEditorService"):UpdateSourceAsync(game.ServerStorage.__mcp_sync_scale.Feature21.Module6, function() return "return 'from studio'\\n" end) return 1`);
+  const toDisk = await until(() => readFileSync(file("Feature21/Module6.luau"), "utf8").includes("from studio"));
+  timings.push(["watch: Studio -> file", toDisk]);
+  report("watch: Studio edit reached the file", toDisk >= 0, `${toDisk}ms`);
+  await new Promise((resolve) => setTimeout(resolve, 3_000));
+  const status = await call("sync", sync("status"));
+  report("watch settles: echoes skipped, not re-synced", /echo/.test(status.text), status.text.split("\n").slice(-1)[0]);
+  await call("sync", sync("stop"));
+} catch (cause) {
+  report("run", false, String(cause?.stack ?? cause));
+} finally {
+  await call("sync", { op: "stop", dir }).catch(() => undefined);
+  await luau(`local f = game.ServerStorage:FindFirstChild("__mcp_sync_scale") if f then f:Destroy() end return 1`).catch(() => undefined);
+  rmSync(dir, { recursive: true, force: true });
+  await client.close();
+}
+
+process.stdout.write("\ntimings\n");
+for (const [label, ms] of timings) process.stdout.write(`  ${label.padEnd(44)} ${ms}ms\n`);
+process.stdout.write(failures === 0 ? "\nlive sync scale: ok\n" : `\nlive sync scale: ${failures} failure(s)\n`);
+process.exit(failures === 0 ? 0 : 1);