@el4cteo/rbx-studio-mcp 0.1.3 → 0.1.5

package/dist/index.js

@@ -20,7 +20,7 @@ import { registerInputTools } from "./tools/input.js";
 import { registerDeviceTools } from "./tools/device.js";
 import { registerApiTools } from "./tools/api.js";
 import { registerResources } from "./resources.js";
-const VERSION = "0.1.3";
+const VERSION = "0.1.5";
 function parsePort(argv) {
     const flag = argv.indexOf("--port");
     const raw = flag !== -1 ? argv[flag + 1] : process.env["ROBLOX_STUDIO_MCP_PORT"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@el4cteo/rbx-studio-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Free, open-source MCP server for Roblox Studio. Push-based SSE transport, editor-safe script edits, token-lean tools.",
   "type": "module",
   "license": "MIT",

package/plugin/src/Config.luau

@@ -9,7 +9,7 @@
 
 local Config = {}
 
-Config.PLUGIN_VERSION = "0.1.3"
+Config.PLUGIN_VERSION = "0.1.5"
 
 -- 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

package/plugin/src/handlers/Debug.luau

@@ -42,7 +42,28 @@
 	is why nothing in this file offers one.
 ]]
 
-local ScriptDebuggerService = game:GetService("ScriptDebuggerService")
+--[[
+	Fetched defensively, because this module is required at plugin start.
+
+	Measured with the beta off and Studio restarted: `GetService` does NOT throw
+	here, it hands back a working service object. So this guard is not fixing an
+	observed crash -- it is insurance on the one call in this file that runs
+	before any tool is invoked. init.server.luau requires this module alongside
+	every other handler, so a throw at this line would take down all 29 tools
+	rather than the three that need a debugger, and it would do it silently: a
+	plugin that never loads never connects, leaving nothing to read anywhere.
+
+	The beta is NOT detected here, because nothing detects it cheaply. See the
+	note on the wholesale-refusal branch in `Debug.set` for the two probes that
+	were tried and why neither works.
+]]
+local ScriptDebuggerService: any = nil
+do
+	local ok, service = pcall(game.GetService, game, "ScriptDebuggerService")
+	if ok then
+		ScriptDebuggerService = service
+	end
+end
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
 local Paths = require(script.Parent.Parent.Paths)
@@ -190,6 +211,11 @@ local function install(): boolean
 		return true
 	end
 
+	if ScriptDebuggerService == nil then
+		installError = "the service is not registered in this Studio"
+		return false
+	end
+
 	local ok, err = pcall(function()
 		service.OnStopped = function(stopped: any): any
 			-- Capture must never be what keeps a thread paused.
@@ -297,6 +323,35 @@ function Debug.set(params: { [string]: any }): { [string]: any }
 		end
 	end
 
+	--[[
+		A wholesale refusal names the likely cause without asserting it.
+
+		`AddBreakpoint` is where the "Debugger Luau API" beta actually bites, and
+		its own message -- "Failed to execute AddBreakpoint request" -- names
+		nothing anyone can act on. The beta cannot be detected from here to say
+		so with certainty, and two attempts to are worth recording so they are
+		not tried a third time: with the beta OFF, `GetService`, `FindService`,
+		assigning `OnStopped` and `Enum.DebuggerResumeType` all still succeed;
+		with the beta ON, `ReflectionService` still does not list the class. The
+		first is always available and the second never is, so neither varies with
+		the thing being measured.
+
+		The only reliable test is this call, which cannot be run speculatively on
+		a user's script just to answer a status question. So the hint says what
+		to check first and what else it could be, and does not claim to know.
+	]]
+	if #added == 0 and #failed > 0 then
+		Dispatch.fail(
+			"NO_BREAKPOINTS_SET",
+			string.format("No breakpoint could be set; all %d were refused.", #failed),
+			"Check that \"Debugger Luau API\" is on in File > Beta Features and that "
+				.. "Studio has been restarted since -- that is the usual cause, it is "
+				.. "off by default, and only the user can change it. Otherwise the "
+				.. "line may not be one that runs: a `return`, an `end` or a bare "
+				.. "declaration is often refused, so try the statement above it."
+		)
+	end
+
 	return { added = added, failed = failed, installed = installed }
 end
 

package/plugin/src/handlers/Session.luau

@@ -1,168 +1,169 @@
---!strict
---[[
-	Session and connectivity handlers. `studio.status` is the cheapest call in the
-	system and doubles as the liveness probe, so it must never touch anything
-	expensive -- notably it counts descendants lazily and caps the selection.
-]]
-
-local MarketplaceService = game:GetService("MarketplaceService")
-local RunService = game:GetService("RunService")
-local Selection = game:GetService("Selection")
-
-local Dispatch = require(script.Parent.Parent.Dispatch)
-local Context = require(script.Parent.Parent.Context)
-local Editor = require(script.Parent.Parent.Editor)
-local Emulation = require(script.Parent.Parent.Emulation)
-local Paths = require(script.Parent.Parent.Paths)
-
--- `version()` is marked deprecated but remains the only way to read the Studio
--- build, and the agent needs it to know which engine APIs actually exist in this
--- session. Bound indirectly so the deprecation lint stays enabled file-wide.
-local studioVersion: () -> string = (version :: any)
-
--- Selection can be tens of thousands of instances after a rubber-band drag.
--- Anything past this is noise for an agent and would blow the response budget.
-local MAX_SELECTION = 50
-
--- Counting descendants of a large place is O(n) over the whole DataModel, so it
--- is cached briefly; status is polled often enough for this to matter.
-local COUNT_CACHE_SECONDS = 5
-
-local cachedCounts: { descendants: number, scripts: number }? = nil
-local cachedAt = 0
-
---[[
-	Which device Studio is pretending to be, or nil for none.
-
-	Reported here because nothing else says it. Device emulation resizes the
-	viewport and stays on until it is switched off, so every screenshot after it
-	comes back the wrong shape with no indication why -- and a caller who did not
-	set it, or who set it twenty calls ago, has no way to find out. `status` is
-	the call agents are told to make first, which makes it the right place for a
-	piece of session state that silently changes what everything else returns.
-]]
-local function counts(): { descendants: number, scripts: number }
-	local now = os.clock()
-	local cache = cachedCounts
-	if cache and now - cachedAt < COUNT_CACHE_SECONDS then
-		return cache
-	end
-
-	local descendants = 0
-	local scripts = 0
-	for _, instance in game:GetDescendants() do
-		descendants += 1
-		if instance:IsA("LuaSourceContainer") then
-			scripts += 1
-		end
-	end
-
-	local fresh = { descendants = descendants, scripts = scripts }
-	cachedCounts = fresh
-	cachedAt = now
-	return fresh
-end
-
---[[
-	The name the user would recognise.
-
-	`game.Name` is the data model's name -- "Place1", "Place5" -- and has nothing
-	to do with what the place is called on the Studio tab or the Creator
-	Dashboard. Nothing local holds the real name: it lives on Roblox's servers, so
-	it takes a lookup. Without it, a user saying "the other place, the published
-	one" cannot be matched to any window, which is the whole point of being able
-	to drive several Studios at once.
-
-	Cached, including the failure, because an unpublished place would otherwise
-	make a doomed web request on every status call.
-]]
-local NAME_RETRY_SECONDS = 60
-
-local resolvedName: string? = nil
-local resolvedFor = -1
-local resolvedAt = 0
-
-local function publishedPlaceName(): string?
-	local placeId = game.PlaceId
-	-- A place that has never been saved to Roblox has no id and no remote name.
-	if placeId == 0 then
-		return nil
-	end
-
-	local fresh = resolvedFor == placeId
-		and (resolvedName ~= nil or os.clock() - resolvedAt < NAME_RETRY_SECONDS)
-	if fresh then
-		return resolvedName
-	end
-
-	resolvedFor = placeId
-	resolvedAt = os.clock()
-
-	local ok, info = pcall(function()
-		return MarketplaceService:GetProductInfo(placeId, Enum.InfoType.Asset)
-	end)
-	local name = if ok and typeof(info) == "table" then (info :: any).Name else nil
-	resolvedName = if typeof(name) == "string" and name ~= "" then name else nil
-	return resolvedName
-end
-
-local Session = {}
-
-function Session.status(): { [string]: any }
-	local selected: { { path: string, className: string } } = {}
-	for index, instance in Selection:Get() do
-		if index > MAX_SELECTION then
-			break
-		end
-		table.insert(selected, { path = Paths.of(instance), className = instance.ClassName })
-	end
-
-	local totals = counts()
-	-- Open tabs ride along with status rather than getting their own tool: this
-	-- is the call agents are told to make first, and "which script is the user
-	-- looking at" is orientation, not a separate question.
-	local openScripts = Editor.documents()
-
-	local published = publishedPlaceName()
-
-	return {
-		openScripts = if #openScripts > 0 then openScripts else nil,
-		placeName = published or (if game.Name ~= "" then game.Name else "Untitled place"),
-		-- Kept separate when the two differ, so a path rooted at the data model
-		-- name stays explicable next to a place called something else entirely.
-		dataModelName = if published and published ~= game.Name then game.Name else nil,
-		placeId = game.PlaceId,
-		context = Context.of(),
-		-- RunService:IsRunning() is true for both Play and Run; IsEdit()
-		-- distinguishes the authoring session from a live one.
-		isRunning = RunService:IsRunning(),
-		isEdit = RunService:IsEdit(),
-		isRunMode = RunService:IsRunning() and not RunService:IsClient(),
-		isServerView = RunService:IsServer(),
-		selection = selected,
-		selectionCount = #Selection:Get(),
-		descendantCount = totals.descendants,
-		scriptCount = totals.scripts,
-		studioVersion = studioVersion(),
-		emulatedDevice = Emulation.summary(),
-	}
-end
-
---[[
-	Round-trip probe used by the smoke test and by `studio_status` when the agent
-	only needs to know the channel is alive.
-]]
-function Session.ping(params: { [string]: any }): { [string]: any }
-	return { pong = true, echo = params.echo }
-end
-
-function Session.register()
-	Dispatch.registerAll("studio", {
-		status = function()
-			return Session.status()
-		end,
-		ping = Session.ping,
-	})
-end
-
-return Session
+--!strict
+--[[
+	Session and connectivity handlers. `studio.status` is the cheapest call in the
+	system and doubles as the liveness probe, so it must never touch anything
+	expensive -- notably it counts descendants lazily and caps the selection.
+]]
+
+local MarketplaceService = game:GetService("MarketplaceService")
+local RunService = game:GetService("RunService")
+local Selection = game:GetService("Selection")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Context = require(script.Parent.Parent.Context)
+local Editor = require(script.Parent.Parent.Editor)
+local Emulation = require(script.Parent.Parent.Emulation)
+local Paths = require(script.Parent.Parent.Paths)
+
+-- `version()` is marked deprecated but remains the only way to read the Studio
+-- build, and the agent needs it to know which engine APIs actually exist in this
+-- session. Bound indirectly so the deprecation lint stays enabled file-wide.
+local studioVersion: () -> string = (version :: any)
+
+
+-- Selection can be tens of thousands of instances after a rubber-band drag.
+-- Anything past this is noise for an agent and would blow the response budget.
+local MAX_SELECTION = 50
+
+-- Counting descendants of a large place is O(n) over the whole DataModel, so it
+-- is cached briefly; status is polled often enough for this to matter.
+local COUNT_CACHE_SECONDS = 5
+
+local cachedCounts: { descendants: number, scripts: number }? = nil
+local cachedAt = 0
+
+--[[
+	Which device Studio is pretending to be, or nil for none.
+
+	Reported here because nothing else says it. Device emulation resizes the
+	viewport and stays on until it is switched off, so every screenshot after it
+	comes back the wrong shape with no indication why -- and a caller who did not
+	set it, or who set it twenty calls ago, has no way to find out. `status` is
+	the call agents are told to make first, which makes it the right place for a
+	piece of session state that silently changes what everything else returns.
+]]
+local function counts(): { descendants: number, scripts: number }
+	local now = os.clock()
+	local cache = cachedCounts
+	if cache and now - cachedAt < COUNT_CACHE_SECONDS then
+		return cache
+	end
+
+	local descendants = 0
+	local scripts = 0
+	for _, instance in game:GetDescendants() do
+		descendants += 1
+		if instance:IsA("LuaSourceContainer") then
+			scripts += 1
+		end
+	end
+
+	local fresh = { descendants = descendants, scripts = scripts }
+	cachedCounts = fresh
+	cachedAt = now
+	return fresh
+end
+
+--[[
+	The name the user would recognise.
+
+	`game.Name` is the data model's name -- "Place1", "Place5" -- and has nothing
+	to do with what the place is called on the Studio tab or the Creator
+	Dashboard. Nothing local holds the real name: it lives on Roblox's servers, so
+	it takes a lookup. Without it, a user saying "the other place, the published
+	one" cannot be matched to any window, which is the whole point of being able
+	to drive several Studios at once.
+
+	Cached, including the failure, because an unpublished place would otherwise
+	make a doomed web request on every status call.
+]]
+local NAME_RETRY_SECONDS = 60
+
+local resolvedName: string? = nil
+local resolvedFor = -1
+local resolvedAt = 0
+
+local function publishedPlaceName(): string?
+	local placeId = game.PlaceId
+	-- A place that has never been saved to Roblox has no id and no remote name.
+	if placeId == 0 then
+		return nil
+	end
+
+	local fresh = resolvedFor == placeId
+		and (resolvedName ~= nil or os.clock() - resolvedAt < NAME_RETRY_SECONDS)
+	if fresh then
+		return resolvedName
+	end
+
+	resolvedFor = placeId
+	resolvedAt = os.clock()
+
+	local ok, info = pcall(function()
+		return MarketplaceService:GetProductInfo(placeId, Enum.InfoType.Asset)
+	end)
+	local name = if ok and typeof(info) == "table" then (info :: any).Name else nil
+	resolvedName = if typeof(name) == "string" and name ~= "" then name else nil
+	return resolvedName
+end
+
+local Session = {}
+
+function Session.status(): { [string]: any }
+	local selected: { { path: string, className: string } } = {}
+	for index, instance in Selection:Get() do
+		if index > MAX_SELECTION then
+			break
+		end
+		table.insert(selected, { path = Paths.of(instance), className = instance.ClassName })
+	end
+
+	local totals = counts()
+	-- Open tabs ride along with status rather than getting their own tool: this
+	-- is the call agents are told to make first, and "which script is the user
+	-- looking at" is orientation, not a separate question.
+	local openScripts = Editor.documents()
+
+	local published = publishedPlaceName()
+
+	return {
+		openScripts = if #openScripts > 0 then openScripts else nil,
+		placeName = published or (if game.Name ~= "" then game.Name else "Untitled place"),
+		-- Kept separate when the two differ, so a path rooted at the data model
+		-- name stays explicable next to a place called something else entirely.
+		dataModelName = if published and published ~= game.Name then game.Name else nil,
+		placeId = game.PlaceId,
+		context = Context.of(),
+		-- RunService:IsRunning() is true for both Play and Run; IsEdit()
+		-- distinguishes the authoring session from a live one.
+		isRunning = RunService:IsRunning(),
+		isEdit = RunService:IsEdit(),
+		isRunMode = RunService:IsRunning() and not RunService:IsClient(),
+		isServerView = RunService:IsServer(),
+		selection = selected,
+		selectionCount = #Selection:Get(),
+		descendantCount = totals.descendants,
+		scriptCount = totals.scripts,
+		studioVersion = studioVersion(),
+		emulatedDevice = Emulation.summary(),
+	}
+end
+
+--[[
+	Round-trip probe used by the smoke test and by `studio_status` when the agent
+	only needs to know the channel is alive.
+]]
+function Session.ping(params: { [string]: any }): { [string]: any }
+	return { pong = true, echo = params.echo }
+end
+
+function Session.register()
+	Dispatch.registerAll("studio", {
+		status = function()
+			return Session.status()
+		end,
+		ping = Session.ping,
+	})
+end
+
+return Session

package/scripts/release-notes.mjs

@@ -0,0 +1,43 @@
+/**
+ * Pulls one version's section out of CHANGELOG.md for the release body.
+ *
+ * Exists so a release cannot go out without notes. GitHub's own
+ * `generate_release_notes` lists commit subjects, which are written for whoever
+ * reads the diff and say nothing useful to someone deciding whether to upgrade.
+ * Failing the workflow on a missing section is the point: the alternative is a
+ * tag that quietly publishes with an empty body, which is what happened for
+ * 0.1.1 through 0.1.3.
+ *
+ * Usage: node scripts/release-notes.mjs <version> <outFile>
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+
+const [, , rawVersion, outFile] = process.argv;
+if (!rawVersion || !outFile) {
+  throw new Error("usage: release-notes.mjs <version> <outFile>");
+}
+
+// Tags carry a leading v; the changelog headings do not.
+const version = rawVersion.replace(/^v/, "");
+const changelog = readFileSync("CHANGELOG.md", "utf8");
+
+// Everything from this version's heading up to the next one, so adding a
+// release never means touching the extractor.
+const heading = new RegExp(`^## ${version.replace(/\./g, "\\.")}\\s*$`, "m");
+const start = changelog.search(heading);
+if (start === -1) {
+  throw new Error(
+    `CHANGELOG.md has no "## ${version}" section. Add one describing what changed ` +
+      `before tagging, or the release would publish with an empty body.`,
+  );
+}
+
+const body = changelog.slice(start).split("\n").slice(1).join("\n");
+const next = body.search(/^## /m);
+const section = (next === -1 ? body : body.slice(0, next)).trim();
+
+if (section.length === 0) {
+  throw new Error(`The "## ${version}" section in CHANGELOG.md is empty.`);
+}
+
+writeFileSync(outFile, `${section}\n`);