@el4cteo/rbx-studio-mcp 0.1.0

package/plugin/src/TextEdit.luau

@@ -0,0 +1,296 @@
+--!strict
+--[[
+	The edit engine: pure text in, pure text out.
+
+	Kept free of Roblox APIs on purpose. Getting a line splice or a find/replace
+	subtly wrong is the one bug class here that produces no error at all -- it
+	just writes the wrong code into the user's game -- so this logic is unit
+	tested outside Studio (see tests/textedit.luau). Everything that actually
+	touches the DataModel lives in handlers/Scripts.luau.
+]]
+
+local Dispatch = require(script.Parent.Dispatch)
+
+local TextEdit = {}
+
+export type Edit = {
+	path: string,
+	find: string?,
+	replace: string?,
+	replaceAll: boolean?,
+	startLine: number?,
+	endLine: number?,
+	replacement: string?,
+	source: string?,
+}
+
+type LineEdit = {
+	startLine: number,
+	endLine: number,
+	replacement: string,
+}
+
+--[[
+	Splits source into lines. A trailing newline does not produce a final empty
+	line, so a round trip through `toLines`/`concat` leaves the text unchanged.
+]]
+function TextEdit.toLines(source: string): { string }
+	local lines: { string } = {}
+	for line in string.gmatch(source .. "\n", "([^\n]*)\n") do
+		table.insert(lines, line)
+	end
+	-- gmatch on the sentinel newline yields one trailing empty entry.
+	if #lines > 0 and lines[#lines] == "" then
+		table.remove(lines)
+	end
+	return lines
+end
+
+--[[
+	Literal (non-pattern) find and replace.
+
+	`string.gsub` would be shorter but treats `%` as an escape in both the needle
+	and the replacement, so a single `%d` in the user's code silently changes
+	meaning. Agent-supplied text has to be taken exactly as given.
+]]
+function TextEdit.replaceLiteral(text: string, needle: string, replacement: string, all: boolean): string
+	local out: { string } = {}
+	local index = 1
+
+	while true do
+		local from, to = string.find(text, needle, index, true)
+		if not from or not to then
+			break
+		end
+		table.insert(out, string.sub(text, index, from - 1))
+		table.insert(out, replacement)
+		index = to + 1
+		if not all then
+			break
+		end
+	end
+
+	table.insert(out, string.sub(text, index))
+	return table.concat(out)
+end
+
+function TextEdit.countLiteral(text: string, needle: string): number
+	local index = 1
+	local count = 0
+	while true do
+		local from, to = string.find(text, needle, index, true)
+		if not from or not to then
+			return count
+		end
+		count += 1
+		index = to + 1
+	end
+end
+
+--[[
+	Rejects a malformed edit before anything is written.
+
+	Validation is a separate pass on purpose: a batch that turns out to be
+	nonsense should fail with nothing touched and no undo entry, rather than
+	applying three scripts' worth of changes and then rolling them back.
+]]
+function TextEdit.validate(edit: Edit, position: number)
+	if typeof(edit.path) ~= "string" or edit.path == "" then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("edits[%d] has no `path`.", position),
+			'Every edit needs the path of the script to change, e.g. "ServerScriptService.Main".'
+		)
+	end
+
+	local modes = 0
+	if edit.source ~= nil then
+		modes += 1
+	end
+	if edit.startLine ~= nil then
+		modes += 1
+	end
+	if edit.find ~= nil then
+		modes += 1
+	end
+
+	if modes == 0 then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("edits[%d] (%s) says what to edit but not how.", position, edit.path),
+			"Give exactly one of: `find` + `replace`, `startLine` (+ `endLine`) + "
+				.. "`replacement`, or `source` to replace the whole script."
+		)
+	end
+	if modes > 1 then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("edits[%d] (%s) combines more than one edit mode.", position, edit.path),
+			"Use `find`, `startLine` or `source` -- one per edit. Send several entries "
+				.. "in the array if you need several changes."
+		)
+	end
+
+	if edit.find ~= nil then
+		if edit.find == "" then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				string.format("edits[%d] (%s) has an empty `find`.", position, edit.path)
+			)
+		end
+		if typeof(edit.replace) ~= "string" then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				string.format("edits[%d] (%s) has `find` but no `replace`.", position, edit.path),
+				"Pass an empty `replace` to delete the matched text."
+			)
+		end
+	elseif edit.startLine ~= nil then
+		if typeof(edit.replacement) ~= "string" then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				string.format("edits[%d] (%s) has `startLine` but no `replacement`.", position, edit.path),
+				"Pass an empty `replacement` to delete those lines."
+			)
+		end
+	end
+end
+
+--[[
+	Applies every edit destined for one script to its source text. `path` is used
+	only for error messages.
+
+	Order is fixed rather than left to the caller: line edits run first, bottom
+	up, so all their numbers refer to the file as the agent read it instead of
+	drifting as earlier edits resize it. Find/replace edits then run in the given
+	order against the result, which is safe because they address text, not
+	positions.
+]]
+function TextEdit.apply(path: string, source: string, edits: { Edit }): string
+	for _, edit in edits do
+		if edit.source ~= nil then
+			if #edits > 1 then
+				Dispatch.fail(
+					"CONFLICTING_EDITS",
+					string.format("%s gets a whole-script `source` edit plus %d other edit(s).", path, #edits - 1),
+					"A `source` edit replaces the entire script, so any other edit to the "
+						.. "same script would be discarded. Send it on its own."
+				)
+			end
+			return edit.source :: string
+		end
+	end
+
+	local lineEdits: { LineEdit } = {}
+	local findEdits: { Edit } = {}
+	for _, edit in edits do
+		local start = edit.startLine
+		if start ~= nil then
+			table.insert(lineEdits, {
+				startLine = start,
+				endLine = tonumber(edit.endLine) or start,
+				replacement = edit.replacement :: string,
+			})
+		else
+			table.insert(findEdits, edit)
+		end
+	end
+
+	local lines = TextEdit.toLines(source)
+
+	if #lineEdits > 0 then
+		table.sort(lineEdits, function(a, b)
+			return a.startLine > b.startLine
+		end)
+
+		-- Every range is checked against the file as the agent read it, before any
+		-- of them is applied. Validating inside the apply loop instead would test
+		-- later edits against a file the earlier ones had already resized, which
+		-- reports an invented line count and hides genuine overlaps behind a
+		-- spurious BAD_RANGE.
+		local lineCount = #lines
+		for index, edit in lineEdits do
+			if edit.startLine < 1 or edit.startLine > lineCount + 1 then
+				Dispatch.fail(
+					"BAD_RANGE",
+					string.format("startLine %d is outside %s, which has %d lines.", edit.startLine, path, lineCount),
+					"Call script_read on this script first. Line numbers shift after every edit."
+				)
+			end
+			if edit.endLine < edit.startLine - 1 or edit.endLine > lineCount then
+				Dispatch.fail(
+					"BAD_RANGE",
+					string.format(
+						"endLine %d is invalid for %s (%d lines): it must be at least startLine - 1 and at most the line count.",
+						edit.endLine,
+						path,
+						lineCount
+					),
+					"Set endLine one below startLine to insert without replacing anything."
+				)
+			end
+
+			-- Sorted descending, so the previous entry is the next range up the
+			-- file. Overlapping ranges would make the result depend on apply order.
+			local previous = lineEdits[index - 1]
+			if previous and edit.endLine >= previous.startLine then
+				Dispatch.fail(
+					"CONFLICTING_EDITS",
+					string.format(
+						"Two edits to %s cover overlapping lines (%d-%d and %d-%d).",
+						path,
+						edit.startLine,
+						edit.endLine,
+						previous.startLine,
+						previous.endLine
+					),
+					"Merge them into one edit spanning the whole range."
+				)
+			end
+		end
+
+		for _, edit in lineEdits do
+			local result: { string } = {}
+			table.move(lines, 1, edit.startLine - 1, 1, result)
+			for _, line in TextEdit.toLines(edit.replacement) do
+				table.insert(result, line)
+			end
+			if edit.endLine < #lines then
+				table.move(lines, edit.endLine + 1, #lines, #result + 1, result)
+			end
+			lines = result
+		end
+	end
+
+	local text = table.concat(lines, "\n")
+
+	for _, edit in findEdits do
+		local needle = edit.find :: string
+		local occurrences = TextEdit.countLiteral(text, needle)
+
+		if occurrences == 0 then
+			Dispatch.fail(
+				"NO_MATCH",
+				string.format("The `find` text does not appear in %s.", path),
+				"Call script_read on the script and copy the text exactly, including "
+					.. "indentation -- the match is literal and whitespace-sensitive."
+			)
+		end
+		-- Refusing an ambiguous match is the point: silently taking the first of
+		-- five identical lines is how an agent edits the wrong function.
+		if occurrences > 1 and edit.replaceAll ~= true then
+			Dispatch.fail(
+				"AMBIGUOUS_EDIT",
+				string.format("The `find` text appears %d times in %s.", occurrences, path),
+				"Include surrounding lines so the text is unique, or set "
+					.. "`replaceAll` to change every occurrence."
+			)
+		end
+
+		text = TextEdit.replaceLiteral(text, needle, edit.replace :: string, edit.replaceAll == true)
+	end
+
+	return text
+end
+
+return TextEdit

package/plugin/src/Transport.luau

@@ -0,0 +1,328 @@
+--!strict
+--[[
+	Command channel between the bridge and this Studio instance.
+
+	Preferred path is a single Server-Sent Events stream opened with
+	`HttpService:CreateWebStreamClient`, which pushes commands the moment they are
+	issued. Every other Roblox Studio MCP server long-polls on a fixed interval,
+	which adds half the poll period to every single call and keeps a request in
+	flight forever; a stream costs nothing while idle.
+
+	Studio allows only 4 concurrent web stream connections and closes them after
+	30 minutes, so exactly one stream is held and reconnects are treated as
+	routine. Where web streams are unavailable (older Studio builds, or the 4
+	slots being taken by other plugins) the same command loop runs over long-poll
+	instead, and neither the server nor the handlers can tell the difference.
+]]
+
+local HttpService = game:GetService("HttpService")
+
+local Config = require(script.Parent.Config)
+local Context = require(script.Parent.Context)
+local Net = require(script.Parent.Net)
+
+local Transport = {}
+
+export type Status = "disconnected" | "connecting" | "connected"
+
+type Callbacks = {
+	onCommand: (id: string, op: string, params: { [string]: any }?) -> (),
+	onStatus: (status: Status, detail: string?) -> (),
+}
+
+local running = false
+local studioId: string = ""
+local activeStream: any = nil
+local mode: "sse" | "poll" = "sse"
+
+--[[
+	Forces the long-poll path even where streaming is available.
+
+	Two reasons it is worth being able to ask for the slower transport. Studio
+	caps SSE at four concurrent connections for the whole process, shared with
+	every other plugin the user has installed, so a session can find itself
+	unable to open a stream through no fault of its own -- and being able to say
+	"just poll" beats discovering that as an intermittent failure to connect.
+
+	The other is honesty: this project's headline claim is that pushing beats
+	polling, and a claim like that should be checkable by whoever doubts it, on
+	their own machine, without patching the source to see the other number.
+]]
+local forcePoll = false
+
+--[[
+	True when this Studio build exposes web streams. Guarded rather than assumed:
+	the API shipped in August 2025 and users on older builds must still work.
+]]
+local function supportsWebStream(): boolean
+	if typeof((HttpService :: any).CreateWebStreamClient) ~= "function" then
+		return false
+	end
+	local ok, enumItem = pcall(function()
+		return (Enum :: any).WebStreamClientType.SSE
+	end)
+	return ok and enumItem ~= nil
+end
+
+local function identity(transport: string): { [string]: any }
+	return {
+		studioId = studioId,
+		placeName = if game.Name ~= "" then game.Name else "Untitled place",
+		placeId = game.PlaceId,
+		pluginVersion = Config.PLUGIN_VERSION,
+		buildId = Config.BUILD_ID,
+		transport = transport,
+		-- Announced at the handshake rather than left for a later status call.
+		-- The ambiguity error that forces someone to choose between two rows
+		-- with the same place name is raised before any such call could have
+		-- run, so without this it lists them with nothing to choose between.
+		context = Context.of(),
+	}
+end
+
+--[[
+	Parses one SSE payload. `MessageReceived` hands over the event data, but the
+	exact framing is not contractual, so a stray `data:` prefix is tolerated and
+	comment/keepalive lines are dropped.
+]]
+local function parseFrame(message: string): { [string]: any }?
+	local text = (string.gsub(message, "^%s+", ""))
+	if text == "" or string.sub(text, 1, 1) == ":" then
+		return nil
+	end
+	if string.sub(text, 1, 5) == "data:" then
+		text = (string.gsub(string.sub(text, 6), "^%s+", ""))
+	end
+	local decoded = Net.decode(text)
+	if typeof(decoded) ~= "table" then
+		return nil
+	end
+	return decoded
+end
+
+local function handleFrame(callbacks: Callbacks, frame: { [string]: any })
+	local id = frame.id
+	local op = frame.op
+	if typeof(id) == "string" and typeof(op) == "string" then
+		callbacks.onCommand(id, op, frame.params)
+	end
+end
+
+--[[
+	Opens the stream and blocks until it closes. Returns false when the stream
+	could not be opened at all, which is the signal to fall back to long-poll.
+]]
+local function runStream(callbacks: Callbacks): boolean
+	local opened = false
+
+	local ok, client = pcall(function()
+		return (HttpService :: any):CreateWebStreamClient((Enum :: any).WebStreamClientType.SSE, {
+			Url = Config.baseUrl() .. "/events",
+			Method = "POST",
+			Headers = Config.headers(),
+			Body = HttpService:JSONEncode(identity("sse")),
+		})
+	end)
+
+	if not ok or client == nil then
+		return false
+	end
+
+	activeStream = client
+	local connections: { RBXScriptConnection } = {}
+
+	table.insert(
+		connections,
+		client.Opened:Connect(function(statusCode: number)
+			if statusCode == 200 then
+				opened = true
+				mode = "sse"
+				callbacks.onStatus("connected", "streaming")
+			end
+		end)
+	)
+
+	table.insert(
+		connections,
+		client.MessageReceived:Connect(function(message: string)
+			local frame = parseFrame(message)
+			if frame then
+				handleFrame(callbacks, frame)
+			end
+		end)
+	)
+
+	local streamError: string? = nil
+	table.insert(
+		connections,
+		client.Error:Connect(function(statusCode: number, errorMessage: string)
+			streamError = string.format("stream error %d: %s", statusCode, tostring(errorMessage))
+		end)
+	)
+
+	client.Closed:Wait()
+	for _, connection in connections do
+		connection:Disconnect()
+	end
+	activeStream = nil
+
+	if not opened then
+		callbacks.onStatus("disconnected", streamError or Net.explain("could not connect"))
+		return false
+	end
+	callbacks.onStatus("disconnected", "stream closed")
+	return true
+end
+
+--[[
+	Long-poll fallback. The bridge parks each request for ~25s and answers with a
+	command or an idle marker, so this is a blocking wait rather than a busy loop.
+
+	Returns true when it is giving way so streaming can be tried again.
+
+	That return exists because this loop used to have no exit while it was
+	succeeding, which quietly made the fallback permanent: streaming is only
+	attempted when a connection is being established, so a single failed attempt
+	-- Studio's four-stream cap being momentarily full, or the bridge restarting
+	at the wrong instant -- dropped the session onto long-poll for as long as it
+	stayed connected. Nothing reported it, because polling works; it is just
+	slower, which is precisely the thing this project claims to fix. Both windows
+	of this session were found sitting on poll with no error anywhere.
+]]
+local function runPolling(callbacks: Callbacks): boolean
+	mode = "poll"
+	local handshake = Net.postJson("/connect", identity("poll"))
+	if not handshake.ok then
+		callbacks.onStatus("disconnected", handshake.error or "handshake failed")
+		return false
+	end
+	callbacks.onStatus("connected", "polling")
+
+	local retryStreamAt = os.clock() + Config.RESTREAM_INTERVAL
+
+	while running do
+		local response = Net.request("GET", "/poll?studioId=" .. studioId)
+		if not running then
+			return false
+		end
+
+		if response.statusCode == 409 then
+			-- The server restarted and no longer knows us; re-handshake.
+			local retry = Net.postJson("/connect", identity("poll"))
+			if not retry.ok then
+				callbacks.onStatus("disconnected", retry.error or "reconnect failed")
+				return false
+			end
+		elseif not response.ok then
+			callbacks.onStatus("disconnected", response.error or "poll failed")
+			return false
+		else
+			local payload = Net.decode(response.body)
+			if typeof(payload) == "table" and typeof(payload.command) == "table" then
+				handleFrame(callbacks, payload.command)
+			end
+		end
+
+		-- Checked after handling rather than before waiting, so the handover
+		-- happens between commands instead of while one is outstanding.
+		if os.clock() >= retryStreamAt then
+			return true
+		end
+	end
+	return false
+end
+
+--[[
+	Posts a command result. Fire-and-forget: if it fails the server's own timeout
+	will surface an actionable error to the agent, and retrying here would risk
+	answering a request that has already been abandoned.
+]]
+function Transport.sendResult(result: { [string]: any })
+	task.spawn(function()
+		Net.postJson("/result?studioId=" .. studioId, result)
+	end)
+end
+
+function Transport.getMode(): string
+	return mode
+end
+
+function Transport.getForcePoll(): boolean
+	return forcePoll
+end
+
+--[[
+	Takes effect on the next connection, not this one: the change has to happen
+	between commands, and tearing the stream down from inside a handler would
+	strand the reply to the very call that asked for it.
+]]
+function Transport.setForcePoll(value: boolean)
+	forcePoll = value
+end
+
+function Transport.isRunning(): boolean
+	return running
+end
+
+--[[
+	Connects and keeps reconnecting until `stop` is called. Backs off on repeated
+	failure so a server that is simply not running does not spin the CPU.
+]]
+function Transport.start(id: string, callbacks: Callbacks)
+	if running then
+		return
+	end
+	running = true
+	studioId = id
+
+	task.spawn(function()
+		local delay = Config.RECONNECT_DELAY
+		while running do
+			callbacks.onStatus("connecting")
+
+			local streamed = not forcePoll and supportsWebStream() and runStream(callbacks)
+			local upgrading = false
+			if running and not streamed then
+				upgrading = runPolling(callbacks)
+			end
+
+			if not running then
+				break
+			end
+
+			-- Polling was healthy and stood aside to let streaming be retried.
+			-- The backoff exists to slow down repeated failures, and this is not
+			-- one, so go straight back round.
+			if upgrading then
+				delay = Config.RECONNECT_DELAY
+				continue
+			end
+
+			task.wait(delay)
+			delay = math.min(delay * 2, Config.MAX_RECONNECT_DELAY)
+			-- A connection that lasted long enough to do real work resets the
+			-- backoff; only repeated fast failures should slow retries down.
+			if activeStream ~= nil then
+				delay = Config.RECONNECT_DELAY
+			end
+		end
+	end)
+end
+
+function Transport.stop()
+	if not running then
+		return
+	end
+	running = false
+	pcall(function()
+		Net.postJson("/bye?studioId=" .. studioId, {})
+	end)
+	if activeStream then
+		pcall(function()
+			activeStream:Close()
+		end)
+		activeStream = nil
+	end
+end
+
+return Transport

package/plugin/src/Undo.luau

@@ -0,0 +1,72 @@
+--!strict
+--[[
+	Wraps every mutation in a ChangeHistoryService recording.
+
+	Two things fall out of this that competing servers do not give you:
+
+	1. One agent action is one Ctrl+Z. A tool that creates 200 parts collapses to
+	   a single undo step named after the tool, instead of 200 separate steps or
+	   -- worse -- no undo entry at all.
+	2. A batch that fails part way through is *cancelled*, not committed. Without
+	   this, a `modify` call that sets 5 of 10 properties and then hits a bad
+	   value leaves the place in a half-edited state the user has to unpick by
+	   hand.
+
+	`SetWaypoint` is deliberately not used; it has been superseded by recordings
+	and cannot express the cancel case.
+]]
+
+local ChangeHistoryService = game:GetService("ChangeHistoryService")
+
+local Undo = {}
+
+--[[
+	Runs `body` inside a named recording. Returns its result, and whether a
+	recording was actually opened.
+
+	`TryBeginRecording` returns nil when another recording is already open (for
+	example the user is mid-drag in the viewport) or when history is unavailable.
+	The work still runs in that case -- refusing to act would be worse than a
+	slightly coarser undo stack -- it simply joins the surrounding recording.
+
+	That second return value is not decoration. Whether an operation is undoable
+	is something tools tell the agent, and therefore the user, so it has to be
+	observed rather than assumed: a claim of "one Ctrl+Z" that silently degrades
+	to no undo entry at all is worse than no claim.
+]]
+function Undo.record<T>(name: string, displayName: string, body: () -> T): (T, boolean)
+	local identifier = ChangeHistoryService:TryBeginRecording(name, displayName)
+	if not identifier then
+		return body(), false
+	end
+
+	local ok, result = pcall(body)
+	if ok then
+		ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Commit)
+		return result, true
+	end
+
+	ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Cancel)
+	error(result, 0)
+end
+
+--[[
+	Commits the recording even when `body` fails, for operations whose partial
+	effects are still wanted. Used only by handlers that report per-item results
+	and therefore tell the agent exactly what did and did not apply.
+]]
+function Undo.recordPartial<T>(name: string, displayName: string, body: () -> T): (T, boolean)
+	local identifier = ChangeHistoryService:TryBeginRecording(name, displayName)
+	if not identifier then
+		return body(), false
+	end
+
+	local ok, result = pcall(body)
+	ChangeHistoryService:FinishRecording(identifier, Enum.FinishRecordingOperation.Commit)
+	if not ok then
+		error(result, 0)
+	end
+	return result, true
+end
+
+return Undo