@el4cteo/rbx-studio-mcp 0.4.5 → 0.5.0

package/dist/tools/terrain.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { json, text } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+export function registerTerrainTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "terrain",
+        title: "Build and edit terrain",
+        description: "Fills, repaints and clears Roblox terrain — hills, water, caves, roads.\n\n" +
+            "Terrain is not made of instances, so none of the instance tools reach " +
+            "it: there is nothing to `create`, no path for `find`, and no property " +
+            "for `modify`. This is the only way to shape it short of writing " +
+            "FillBall calls by hand through `execute_luau`.\n\n" +
+            "`fill` takes an ARRAY of solids and applies them as one undo step, " +
+            "which is how terrain is actually built: a hill is several overlapping " +
+            "balls, a road is a row of blocks. Shapes are `block` (needs `size`), " +
+            "`ball` (needs `radius`), `cylinder` (needs `radius` and `height`) and " +
+            "`wedge` (needs `size`).\n\n" +
+            "To CARVE, fill with material `Air`. That is not a special mode — a " +
+            "cave is a ball of Air inside a hill, and a tunnel is a row of them.\n\n" +
+            "`replace` swaps one material for another inside a region and leaves " +
+            "the shape alone, which is how you turn a grass hill to snow without " +
+            "rebuilding it. `clear` empties a region, or everything with " +
+            "confirm=true. `stats` says whether the place uses terrain at all " +
+            "-- call it first in an unfamiliar place. It cannot say WHERE the " +
+            "terrain is: Roblox exposes no bounding box for it, only the fixed " +
+            "limit. Take a `screenshot` to see the shape.\n\n" +
+            "Positions are the centre of the solid, in studs, as \"x, y, z\". " +
+            "Terrain snaps to a 4-stud voxel grid, so small features come out " +
+            "blockier than the numbers suggest; nothing thinner than about 4 studs " +
+            "survives.",
+        inputSchema: {
+            op: z
+                .enum(["fill", "replace", "clear", "stats"])
+                .default("stats")
+                .describe("'fill' adds solids (use material Air to carve), 'replace' swaps a " +
+                "material in place, 'clear' empties a region or everything, " +
+                "'stats' reports what is there."),
+            shapes: z
+                .array(z.object({
+                shape: z
+                    .enum(["block", "ball", "cylinder", "wedge"])
+                    .default("block")
+                    .describe("Which solid to fill."),
+                position: z
+                    .string()
+                    .describe('Centre of the solid in studs, e.g. "0, 20, 0".'),
+                size: z
+                    .string()
+                    .optional()
+                    .describe('block and wedge: extent in studs, e.g. "100, 20, 100".'),
+                radius: z.number().optional().describe("ball and cylinder: radius in studs."),
+                height: z.number().optional().describe("cylinder: height in studs."),
+                orientation: z
+                    .string()
+                    .optional()
+                    .describe('Rotation in degrees, e.g. "0, 45, 0". Omit for none.'),
+                material: z
+                    .string()
+                    .default("Grass")
+                    .describe('Terrain material — Grass, Rock, Sand, Water, Snow, Basalt, ' +
+                    'Mud, LeafyGrass... Use "Air" to carve out existing terrain.'),
+            }))
+                .max(100)
+                .optional()
+                .describe("fill only: the solids to apply, together, as one undo step."),
+            position: z
+                .string()
+                .optional()
+                .describe('replace and clear: centre of the region, e.g. "0, 0, 0".'),
+            size: z
+                .string()
+                .optional()
+                .describe('replace and clear: extent of the region in studs, e.g. "512, 256, 512".'),
+            from: z.string().optional().describe("replace only: the material to look for."),
+            to: z.string().optional().describe("replace only: the material to write instead."),
+            confirm: z
+                .boolean()
+                .optional()
+                .describe("clear only: required to empty ALL terrain. Omit it and give " +
+                "`position`/`size` to clear one region instead."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        readOnly: false,
+        destructive: true,
+    }, async (args) => {
+        // Terrain writes are slow in a way instance writes are not: the engine
+        // rebuilds the voxel mesh for the whole affected volume before it
+        // answers, and a large region takes real seconds.
+        const timeoutMs = 60_000;
+        if (args.op === "stats") {
+            const response = await bridge.call("terrain.stats", {}, { studioId: args.studioId, timeoutMs });
+            return json(response, response.cells === 0
+                ? "This place has no terrain yet. `fill` a block of Grass to start one."
+                : undefined);
+        }
+        if (args.op === "fill") {
+            if (args.shapes === undefined || args.shapes.length === 0) {
+                return text('fill needs `shapes`, e.g. [{ shape: "ball", position: "0, 10, 0", radius: 24, material: "Grass" }].');
+            }
+            const response = await bridge.call("terrain.fill", { shapes: args.shapes }, { studioId: args.studioId, timeoutMs });
+            return json(response, "Terrain snaps to 4-stud voxels, so take a `screenshot` before " +
+                "building on top of this — the result is blockier than the numbers.");
+        }
+        if (args.op === "replace") {
+            if (args.from === undefined || args.to === undefined) {
+                return text('replace needs `from` and `to`, e.g. from="Grass" to="Snow".');
+            }
+            const response = await bridge.call("terrain.replace", { position: args.position, size: args.size, from: args.from, to: args.to }, { studioId: args.studioId, timeoutMs });
+            return json(response);
+        }
+        const response = await bridge.call("terrain.clear", { position: args.position, size: args.size, confirm: args.confirm }, { studioId: args.studioId, timeoutMs });
+        return json(response);
+    });
+}
+//# sourceMappingURL=terrain.js.map

package/dist/tools/terrain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terrain.js","sourceRoot":"","sources":["../../src/tools/terrain.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@el4cteo/rbx-studio-mcp",
-  "version": "0.4.5",
-  "description": "MCP server for Roblox Studio. 29 tools, push-based SSE bridge, editor-safe script edits, one-step undo.",
+  "version": "0.5.0",
+  "description": "MCP server for Roblox Studio. 31 tools, push-based SSE bridge, editor-safe script edits, one-step undo.",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -24,7 +24,7 @@
     "start": "node dist/index.js",
     "build:plugin": "node scripts/check-plugin.mjs && node scripts/build-plugin.mjs",
     "sourcemap": "node scripts/sourcemap.mjs",
-    "test": "node scripts/test-plugin.mjs && node scripts/test-transport.mjs && node scripts/test-bridge.mjs && node scripts/test-failover.mjs",
+    "test": "node scripts/test-plugin.mjs && node scripts/test-transport.mjs && node scripts/test-bridge.mjs && node scripts/test-console.mjs && node scripts/test-failover.mjs",
     "build:all": "npm run build && npm run build:plugin",
     "install:plugin": "node scripts/install-plugin.mjs",
     "check:plugin": "node scripts/check-plugin.mjs",
@@ -50,7 +50,7 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.5.0",
     "typescript": "^7.0.2"
   },
   "author": "EL4CTEO",

package/plugin/src/Commands.luau

@@ -0,0 +1,524 @@
+--!strict
+--[[
+	What the console's prompt row does with a line.
+
+	Split from `Console` on purpose. The console owns a log and a widget; half of
+	these answers are about the transport, the port setting, the place, or the
+	bridge, and wiring all of that into the console to answer `status` would make
+	the console the whole plugin.
+
+	Two kinds of line arrive here and they are told apart by one rule: the first
+	word is either a command in this table or it is not. If it is, it runs here
+	or on the bridge and prints in milliseconds. If it is not, the whole line is
+	a request for an agent, and goes to the bridge to be run by whichever coding
+	tool the user has installed. Nothing has to be marked, quoted or prefixed --
+	`doctor` is a command and "make the door open when I touch it" is not, and no
+	person needs that explained.
+
+	Commands answered on the bridge are listed here too, with `remote = true`, so
+	`help` and Tab-completion describe the whole surface rather than only the
+	half that happens to run in Luau.
+]]
+
+local ScriptEditorService = game:GetService("ScriptEditorService")
+local Selection = game:GetService("Selection")
+local ServerStorage = game:GetService("ServerStorage")
+
+local Config = require(script.Parent.Config)
+local Console = require(script.Parent.Console)
+local Net = require(script.Parent.Net)
+local ThemePicker = require(script.Parent.ThemePicker)
+local Themes = require(script.Parent.Themes)
+
+local Commands = {}
+
+export type Hooks = {
+	-- Drops the connection and dials again. Owned by init.server, which is the
+	-- only thing holding the transport's lifecycle.
+	reconnect: () -> (),
+	-- `plugin:SetSetting` is not reachable from a ModuleScript, so anything that
+	-- has to outlive the session is handed back to the script that can persist it.
+	savePort: (number) -> (),
+	saveTheme: (string) -> (),
+	-- The transport's own view of the connection, which the console only ever
+	-- receives second-hand as a string to display.
+	status: () -> string,
+	studioId: () -> string,
+}
+
+local hooks: Hooks? = nil
+
+function Commands.setup(value: Hooks)
+	hooks = value
+end
+
+type Entry = {
+	name: string,
+	usage: string,
+	summary: string,
+	-- Answered by the bridge rather than here. Listed all the same: a user
+	-- should not have to know which side of the wire a command lives on.
+	remote: boolean?,
+	run: ((args: { string }) -> ())?,
+}
+
+local entries: { Entry } = {}
+local byName: { [string]: Entry } = {}
+
+local function define(entry: Entry)
+	table.insert(entries, entry)
+	byName[entry.name] = entry
+end
+
+--[[
+	Sends a command to the bridge and prints whatever comes back.
+
+	Answers arrive as rows rather than as text, so the bridge decides what a
+	warning IS and this decides what a warning looks like. Both sides formatting
+	is how a diagnostic ends up rendered two different ways in one log.
+]]
+local function remote(command: string, args: { string }, line: string)
+	local current = hooks
+	local response = Net.postJson("/console", {
+		studioId = if current ~= nil then current.studioId() else "",
+		command = command,
+		args = args,
+		line = line,
+	})
+
+	if not response.ok then
+		Console.setPromptBusy(false)
+		Console.log("error", string.format("%s failed", command), response.error)
+		return
+	end
+
+	local decoded = Net.decode(response.body)
+	--[[
+		The bridge is the authority on whether an agent is running, so the caret
+		follows its answer rather than what this side assumed when it sent the
+		line. A prompt that never started -- no harness on PATH is the common one
+		-- would otherwise leave the panel looking busy for the rest of the
+		session.
+	]]
+	Console.setPromptBusy(typeof(decoded) == "table" and (decoded :: any).running == true)
+
+	local rows = if typeof(decoded) == "table" then (decoded :: any).lines else nil
+	if typeof(rows) ~= "table" then
+		Console.log("error", string.format("%s returned nothing readable", command))
+		return
+	end
+
+	for _, row in rows :: { any } do
+		if typeof(row) == "table" and typeof(row.message) == "string" then
+			local level = if typeof(row.level) == "string" then row.level else "dim"
+			Console.log(
+				level :: any,
+				row.message,
+				if typeof(row.detail) == "string" then row.detail else nil
+			)
+		end
+	end
+end
+
+-- Local commands ----------------------------------------------------------
+
+define({
+	name = "help",
+	usage = "help",
+	summary = "list every command",
+	run = function()
+		Console.log("info", "commands")
+		for _, entry in entries do
+			Console.log("dim", "   " .. entry.usage, entry.summary)
+		end
+		Console.log(
+			"dim",
+			"   anything else",
+			"sent to a coding agent -- run `agent` to see which"
+		)
+	end,
+})
+
+define({
+	name = "clear",
+	usage = "clear",
+	summary = "empty the log",
+	run = function()
+		Console.clear()
+	end,
+})
+
+define({
+	name = "reconnect",
+	usage = "reconnect",
+	summary = "drop the connection and dial the bridge again",
+	run = function()
+		local current = hooks
+		if current then
+			current.reconnect()
+		end
+	end,
+})
+
+define({
+	name = "status",
+	usage = "status",
+	summary = "connection, port and build of this plugin",
+	run = function()
+		local current = hooks
+		Console.log("info", "session")
+		Console.log(
+			"dim",
+			"   connection",
+			if current ~= nil then current.status() else "unknown"
+		)
+		Console.log("dim", "   bridge", Config.baseUrl())
+		Console.log(
+			"dim",
+			"   plugin",
+			string.format(
+				"v%s  build %s  protocol %d",
+				Config.PLUGIN_VERSION,
+				Config.BUILD_ID,
+				Config.PROTOCOL_VERSION
+			)
+		)
+		Console.log("dim", "   theme", Themes.activeId())
+	end,
+})
+
+define({
+	name = "clients",
+	usage = "clients",
+	summary = "which MCP clients share this bridge",
+	run = function()
+		Console.reportClients()
+	end,
+})
+
+define({
+	name = "theme",
+	usage = "theme [name]",
+	summary = "switch colour preset, or list them",
+	run = function(args)
+		local wanted = args[1]
+		if wanted == nil then
+			local active = Themes.activeId()
+			Console.log("info", "themes")
+			for _, theme in Themes.list() do
+				Console.log(
+					if theme.id == active then "ok" else "dim",
+					"   " .. theme.id,
+					if theme.id == active then "in use" else nil
+				)
+			end
+			return
+		end
+
+		-- `Themes.use` answers false both for an unknown id and for re-picking
+		-- the current one, so the two are separated here rather than reported as
+		-- the same shrug.
+		if wanted == Themes.activeId() then
+			Console.log("dim", string.format("already on %s", wanted))
+			return
+		end
+		if not Themes.use(wanted) then
+			Console.log("error", string.format("no theme called %q", wanted), "run `theme` to list them")
+			return
+		end
+
+		Console.applyTheme()
+		ThemePicker.applyTheme()
+		local current = hooks
+		if current then
+			current.saveTheme(wanted)
+		end
+		Console.log("ok", string.format("theme: %s", wanted))
+	end,
+})
+
+define({
+	name = "visuals",
+	usage = "visuals",
+	summary = "show or hide the activity band",
+	run = function()
+		local shown = Console.toggleVisuals()
+		Console.log("dim", if shown then "visuals on" else "visuals off")
+	end,
+})
+
+define({
+	name = "place",
+	usage = "place",
+	summary = "what this Studio window has open",
+	run = function()
+		Console.log("info", if game.Name ~= "" then game.Name else "Untitled place")
+		Console.log("dim", "   placeId", tostring(game.PlaceId))
+		Console.log("dim", "   gameId", tostring(game.GameId))
+		for _, name in { "Workspace", "ServerScriptService", "ServerStorage", "ReplicatedStorage", "StarterGui" } do
+			local service = game:FindFirstChild(name)
+			if service ~= nil then
+				Console.log("dim", "   " .. name, string.format("%d children", #service:GetChildren()))
+			end
+		end
+	end,
+})
+
+--[[
+	Every level the log can show, so `log` can be checked against a real list
+	rather than silently accepting a typo and hiding everything.
+]]
+local LEVELS = { "ok", "error", "warn", "info", "dim", "call", "reply" }
+
+define({
+	name = "log",
+	usage = "log [level|all]",
+	summary = "show only one kind of row",
+	run = function(args)
+		local wanted = args[1]
+		if wanted == nil or wanted == "all" then
+			Console.setFilter(nil)
+			Console.log("dim", "showing everything")
+			return
+		end
+		if not table.find(LEVELS, wanted) then
+			Console.log(
+				"error",
+				string.format("no level called %q", wanted),
+				table.concat(LEVELS, " ") .. " all"
+			)
+			return
+		end
+		--[[
+			An error filter shows warnings too.
+
+			Someone typing `log error` is looking for what went wrong, and a
+			warning is part of that answer. Filtering to the single level would
+			hide the row that usually explains the failure below it.
+		]]
+		local levels = if wanted == "error" then { "error", "warn" } else { wanted }
+		Console.setFilter(levels)
+		Console.log("dim", string.format("showing %s only", table.concat(levels, " and ")))
+	end,
+})
+
+define({
+	name = "copy",
+	usage = "copy",
+	summary = "put the log somewhere it can be selected and copied",
+	run = function()
+		--[[
+			Studio gives plugins no clipboard, and a TextLabel cannot be selected.
+
+			So the log goes where selection and Ctrl+C already work: a script
+			editor tab. The rows are written as comments -- see
+			`Console.plainText` -- so the tab opens as something to read rather
+			than as a wall of syntax errors, and the document is opened for the
+			user rather than merely selected, which turns a two-step
+			"find it in Explorer, double-click it" into typing one word.
+
+			Parented to ServerStorage so it can never end up in a published
+			place, and replaced rather than accumulated so running it twice does
+			not litter the tree.
+		]]
+		local existing = ServerStorage:FindFirstChild("rbx-studio log")
+		if existing then
+			existing:Destroy()
+		end
+		local holder = Instance.new("Script")
+		holder.Name = "rbx-studio log"
+		holder.Source = Console.plainText()
+		holder.Enabled = false
+		holder.Parent = ServerStorage
+		Selection:Set({ holder })
+
+		--[[
+			Opening is best effort, and deliberately not fatal.
+
+			`OpenScriptDocumentAsync` yields and can fail -- the editor may
+			refuse, and it is PluginSecurity, so a future Studio could withdraw
+			it. The script exists and is selected either way, which is the part
+			that matters; all that is lost is the convenience, so the failure is
+			reported as the extra step it costs rather than as an error.
+		]]
+		local opened = pcall(function()
+			ScriptEditorService:OpenScriptDocumentAsync(holder)
+		end)
+		if opened then
+			Console.log("ok", "log opened in a script tab", "select all and copy")
+		else
+			Console.log(
+				"ok",
+				"log written to ServerStorage",
+				"selected -- open it from Explorer and copy"
+			)
+		end
+	end,
+})
+
+define({
+	name = "port",
+	usage = "port [number]",
+	summary = "show, or move to, the bridge port",
+	run = function(args)
+		local wanted = args[1]
+		if wanted == nil then
+			Console.log("dim", string.format("port %d", Config.getPort()))
+			return
+		end
+		local value = tonumber(wanted)
+		if value == nil or value ~= math.floor(value) or value < 1 or value > 65535 then
+			Console.log("error", string.format("%q is not a port", wanted))
+			return
+		end
+		Config.setPort(value :: number)
+		local current = hooks
+		if current then
+			current.savePort(value :: number)
+			Console.log("ok", string.format("port %d -- reconnecting", value))
+			current.reconnect()
+		end
+	end,
+})
+
+define({
+	name = "version",
+	usage = "version",
+	summary = "what this plugin is",
+	run = function()
+		Console.log(
+			"info",
+			string.format("rbx-studio v%s", Config.PLUGIN_VERSION),
+			string.format("build %s  protocol %d", Config.BUILD_ID, Config.PROTOCOL_VERSION)
+		)
+		Console.log("dim", "run doctor to compare it against the installed package")
+	end,
+})
+
+-- Bridge commands ---------------------------------------------------------
+
+define({ name = "doctor", usage = "doctor", summary = "check every part of the setup", remote = true })
+define({ name = "studios", usage = "studios", summary = "Studio windows on this bridge", remote = true })
+define({ name = "use", usage = "use <number|id>", summary = "point calls at one Studio", remote = true })
+define({
+	name = "agent",
+	usage = "agent [use <id>|new]",
+	summary = "which coding agent runs your prompts",
+	remote = true,
+})
+define({ name = "stop", usage = "stop", summary = "cancel the running agent", remote = true })
+
+-- Dispatch ----------------------------------------------------------------
+
+--[[
+	Command names starting with `prefix`, for Tab and for the hint.
+
+	Sorted so the suggestion list does not reorder itself between keystrokes,
+	which is exactly the sort of movement that makes a hint unreadable.
+]]
+function Commands.complete(prefix: string): { string }
+	local matches: { string } = {}
+	for _, entry in entries do
+		if string.sub(entry.name, 1, #prefix) == prefix then
+			table.insert(matches, entry.name)
+		end
+	end
+	table.sort(matches)
+	return matches
+end
+
+--[[
+	The nearest command to something that is not one.
+
+	Only ever a hint, and only for a single edit's distance, because the whole
+	point of the free-text path is that an unrecognised word is usually a
+	sentence rather than a typo. Suggesting `doctor` for "door" would be worse
+	than saying nothing.
+]]
+local function nearest(word: string): string?
+	for _, entry in entries do
+		local name = entry.name
+		if math.abs(#name - #word) <= 1 then
+			-- Cheap and sufficient: a shared prefix of everything but the last
+			-- character or two catches the transpositions and dropped letters
+			-- that actually happen at a prompt.
+			local shared = 0
+			while shared < math.min(#name, #word) and string.sub(name, shared + 1, shared + 1) == string.sub(word, shared + 1, shared + 1) do
+				shared += 1
+			end
+			if shared >= #name - 1 and shared >= 3 then
+				return name
+			end
+		end
+	end
+	return nil
+end
+
+--[[
+	Runs one submitted line.
+
+	Everything here is already off the input's thread -- `Prompt` spawns it --
+	so a remote command is free to block on the bridge without freezing the
+	field the user is typing into.
+]]
+function Commands.run(line: string)
+	local trimmed = string.match(line, "^%s*(.-)%s*$") or ""
+	if trimmed == "" then
+		return
+	end
+
+	-- Echoed before anything runs, so the log shows what was asked as well as
+	-- what came back. Without it a command that prints one line looks like a
+	-- line that appeared on its own.
+	Console.log("call", trimmed, "you")
+
+	local words: { string } = {}
+	for word in string.gmatch(trimmed, "%S+") do
+		table.insert(words, word)
+	end
+
+	local head = string.lower(words[1])
+	-- `?` is the one alias, because it is what people type before they have
+	-- learned there is a `help`.
+	if head == "?" then
+		head = "help"
+	end
+
+	local entry = byName[head]
+	if entry == nil then
+		--[[
+			Not a command, so it is a request.
+
+			A single mistyped word is the one case worth querying: it is short,
+			it matches something closely, and sending it to an agent would spend
+			real money answering a typo.
+		]]
+		if #words == 1 then
+			local guess = nearest(head)
+			if guess ~= nil then
+				Console.log("dim", string.format("no command %q -- did you mean %s?", head, guess))
+				return
+			end
+		end
+		Console.setPromptBusy(true)
+		remote("prompt", words, trimmed)
+		return
+	end
+
+	local args = table.move(words, 2, #words, 1, {} :: { string })
+
+	if entry.remote then
+		remote(entry.name, args, trimmed)
+		return
+	end
+
+	local run = entry.run
+	if run ~= nil then
+		local ok, err = pcall(run, args)
+		if not ok then
+			Console.log("error", string.format("%s failed", entry.name), tostring(err))
+		end
+	end
+end
+
+return Commands

package/plugin/src/Config.luau

@@ -9,7 +9,7 @@
 
 local Config = {}
 
-Config.PLUGIN_VERSION = "0.4.5"
+Config.PLUGIN_VERSION = "0.5.0"
 
 -- Fingerprint of plugin/src, stamped in by scripts/build-plugin.mjs. The server
 -- computes the same hash from its own copy of the sources and compares, so a