@el4cteo/rbx-studio-mcp 0.1.0

package/dist/bridge/server.js

@@ -0,0 +1,281 @@
+import { createServer } from "node:http";
+import { CLIENT_HEADER, PROTOCOL_VERSION } from "../lib/protocol.js";
+import { Bridge } from "./rpc.js";
+/** Default loopback port. Deliberately not 58741 — that is drgost1's server. */
+export const DEFAULT_PORT = 44755;
+/** SSE comment cadence. Keeps intermediaries and Studio from reaping an idle stream. */
+const HEARTBEAT_MS = 15_000;
+/** Largest body we accept from the plugin (script sources and screenshots are big). */
+const MAX_BODY_BYTES = 32 * 1024 * 1024;
+/**
+ * Starts the loopback HTTP endpoint the Studio plugin talks to.
+ *
+ * Routes:
+ *   POST /connect  handshake; body is a StudioIdentity, answers with server info
+ *   POST /events   SSE stream, server -> plugin commands (preferred path)
+ *   GET  /poll     long-poll fallback for Studio builds without web streams
+ *   POST /result   plugin -> server command results
+ *   POST /bye      clean disconnect on plugin unload
+ *   GET  /latency  times N round trips to a connected plugin; measurement only
+ */
+export function startBridgeServer(options = {}) {
+    const bridge = options.bridge ?? new Bridge();
+    const port = options.port ?? DEFAULT_PORT;
+    const server = createServer((req, res) => {
+        void handle(bridge, req, res);
+    });
+    // Long-poll requests park for POLL_HOLD_MS; Node's 2-minute default would be
+    // fine, but SSE streams must never be reaped by the server itself.
+    server.headersTimeout = 0;
+    server.requestTimeout = 0;
+    server.keepAliveTimeout = 0;
+    const reaper = setInterval(() => bridge.reapStale(), 30_000);
+    reaper.unref();
+    return new Promise((resolve, reject) => {
+        server.once("error", (cause) => {
+            // Overwhelmingly the cause is a second copy of this server (a stale
+            // process, or the same server configured in two MCP clients). Both would
+            // fight over the plugin's connection, so say so plainly instead of
+            // surfacing a bare EADDRINUSE.
+            if (cause.code === "EADDRINUSE") {
+                reject(new Error(`Port ${port} is already in use — another roblox-studio-mcp is probably ` +
+                    `running. Stop it, or start this one with --port <other> and set the ` +
+                    `matching port in the Studio plugin widget.`));
+                return;
+            }
+            reject(cause);
+        });
+        // Loopback only: nothing on the network should be able to drive Studio.
+        server.listen(port, "127.0.0.1", () => {
+            server.removeListener("error", reject);
+            resolve({
+                bridge,
+                port,
+                close: () => closeServer(server, reaper),
+            });
+        });
+    });
+}
+function closeServer(server, reaper) {
+    clearInterval(reaper);
+    return new Promise((resolve) => {
+        server.closeAllConnections();
+        server.close(() => resolve());
+    });
+}
+async function handle(bridge, req, res) {
+    // A browser cannot set CLIENT_HEADER cross-origin without a preflight we never
+    // answer, and same-origin means it is already local. Together with the Origin
+    // rejection below this is what blocks DNS-rebinding attacks on the bridge.
+    if (req.headers.origin !== undefined)
+        return send(res, 403, { error: "origin not allowed" });
+    if (req.headers[CLIENT_HEADER] === undefined) {
+        return send(res, 403, { error: `missing ${CLIENT_HEADER} header` });
+    }
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    try {
+        switch (`${req.method} ${url.pathname}`) {
+            case "POST /connect":
+                return await handleConnect(bridge, req, res);
+            case "POST /events":
+                return await handleEvents(bridge, req, res);
+            case "GET /poll":
+                return await handlePoll(bridge, url, res);
+            case "POST /result":
+                return await handleResult(bridge, url, req, res);
+            case "GET /latency":
+                return await handleLatency(bridge, url, res);
+            case "POST /transport":
+                return await handleTransport(bridge, url, res);
+            case "POST /bye":
+                bridge.detach(url.searchParams.get("studioId") ?? "");
+                return send(res, 200, { ok: true });
+            default:
+                return send(res, 404, { error: "unknown route" });
+        }
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        if (!res.headersSent)
+            send(res, 400, { error: message });
+        else
+            res.end();
+    }
+}
+/**
+ * Times sequential round trips to a connected Studio and returns the spread.
+ *
+ * This exists so the project's central performance claim -- that pushing over
+ * SSE beats the long-polling every other Studio MCP server uses -- can be
+ * checked by whoever doubts it, without them having to take the number on
+ * trust. It lives on the bridge rather than only in a script because the bridge
+ * owns the port: a standalone measurement tool has to bind 44755 itself, which
+ * means shutting down the editor's own connection first, and a measurement that
+ * costs you your session is one nobody runs twice.
+ *
+ * `studio.ping` is the payload because it is the smallest command the plugin
+ * answers, so what is left is the transport. Sequential rather than concurrent
+ * on purpose: an agent waits for each answer before choosing what to ask next,
+ * so serial round trips are the figure that matters, and running them in
+ * parallel would measure throughput instead.
+ */
+async function handleLatency(bridge, url, res) {
+    const count = Math.min(Math.max(Number(url.searchParams.get("count") ?? 50), 1), 500);
+    const requested = url.searchParams.get("studioId") ?? undefined;
+    const studios = bridge.list();
+    const target = requested
+        ? studios.find((entry) => entry.studioId === requested)
+        : studios[0];
+    if (target === undefined) {
+        // Reporting zero for a run that never happened would be worse than failing.
+        return send(res, 409, {
+            error: studios.length === 0
+                ? "No Studio is connected. Open Studio with the plugin installed."
+                : `No connected Studio has id ${requested}.`,
+        });
+    }
+    // One warm-up that is not recorded: the first call after an idle period pays
+    // for stream wake-up, which is real but is not what the tenth call costs.
+    await bridge.call("studio.ping", {}, { studioId: target.studioId });
+    const samples = [];
+    for (let index = 0; index < count; index += 1) {
+        const started = process.hrtime.bigint();
+        await bridge.call("studio.ping", {}, { studioId: target.studioId });
+        samples.push(Number(process.hrtime.bigint() - started) / 1e6);
+    }
+    const sorted = [...samples].sort((a, b) => a - b);
+    const at = (fraction) => sorted[Math.max(0, Math.ceil(fraction * sorted.length) - 1)] ?? 0;
+    const round = (value) => Number(value.toFixed(2));
+    send(res, 200, {
+        transport: target.transport,
+        place: target.placeName,
+        samples: samples.length,
+        meanMs: round(samples.reduce((sum, value) => sum + value, 0) / samples.length),
+        medianMs: round(at(0.5)),
+        p95Ms: round(at(0.95)),
+        minMs: round(sorted[0] ?? 0),
+        maxMs: round(sorted[sorted.length - 1] ?? 0),
+    });
+}
+/**
+ * Moves a connected plugin between the push and long-poll transports.
+ *
+ * Paired with /latency so one command can measure both sides of the comparison
+ * the README rests on, rather than only the side this project prefers.
+ */
+async function handleTransport(bridge, url, res) {
+    const mode = url.searchParams.get("mode");
+    if (mode !== "sse" && mode !== "poll") {
+        return send(res, 400, { error: 'mode must be "sse" or "poll"' });
+    }
+    const requested = url.searchParams.get("studioId") ?? undefined;
+    const target = requested
+        ? bridge.list().find((entry) => entry.studioId === requested)
+        : bridge.list()[0];
+    if (target === undefined) {
+        return send(res, 409, { error: "No Studio is connected." });
+    }
+    const result = await bridge.call("studio.transport", { mode }, { studioId: target.studioId });
+    send(res, 200, result);
+}
+async function handleConnect(bridge, req, res) {
+    const identity = parseIdentity(await readBody(req));
+    bridge.attach(identity, null);
+    send(res, 200, {
+        ok: true,
+        protocolVersion: PROTOCOL_VERSION,
+        pollHoldMs: 25_000,
+        heartbeatMs: HEARTBEAT_MS,
+    });
+}
+/**
+ * Opens the push channel. The plugin reaches this through
+ * `HttpService:CreateWebStreamClient`, which issues a normal POST and then
+ * keeps the response body open, so identity rides in the request body.
+ */
+async function handleEvents(bridge, req, res) {
+    const identity = parseIdentity(await readBody(req), "sse");
+    res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive",
+        "X-Accel-Buffering": "no",
+    });
+    // Flush headers immediately so the plugin's Closed signal is meaningful.
+    res.write(`: connected ${PROTOCOL_VERSION}\n\n`);
+    const studioId = bridge.attach(identity, res);
+    const heartbeat = setInterval(() => {
+        if (res.writableEnded)
+            return;
+        res.write(": ping\n\n");
+        bridge.touch(studioId);
+    }, HEARTBEAT_MS);
+    const teardown = () => {
+        clearInterval(heartbeat);
+        bridge.detach(studioId);
+    };
+    req.on("close", teardown);
+    req.on("error", teardown);
+}
+async function handlePoll(bridge, url, res) {
+    const studioId = url.searchParams.get("studioId");
+    if (!studioId || !bridge.has(studioId)) {
+        // The plugin restarted the server, or we restarted under it. Either way it
+        // must hand us its identity again before we can route commands to it.
+        return send(res, 409, { error: "unknown studioId", reconnect: true });
+    }
+    const command = await bridge.waitForCommand(studioId);
+    send(res, 200, command ? { command } : { idle: true });
+}
+async function handleResult(bridge, url, req, res) {
+    const studioId = url.searchParams.get("studioId") ?? "";
+    const body = await readBody(req);
+    const parsed = JSON.parse(body);
+    if (typeof parsed?.id !== "string")
+        throw new Error("result is missing an id");
+    bridge.settle(studioId, parsed);
+    send(res, 200, { ok: true });
+}
+function parseIdentity(body, transport = "poll") {
+    const raw = JSON.parse(body);
+    if (typeof raw.studioId !== "string" || raw.studioId.length === 0) {
+        throw new Error("handshake is missing studioId");
+    }
+    return {
+        studioId: raw.studioId,
+        placeName: raw.placeName ?? "Unnamed place",
+        placeId: raw.placeId ?? 0,
+        pluginVersion: raw.pluginVersion ?? "unknown",
+        buildId: raw.buildId ?? "unknown",
+        transport: raw.transport ?? transport,
+        // Optional, because a plugin older than this field still connects fine —
+        // it simply lists without a context, as every session did before.
+        context: raw.context,
+    };
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function send(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+//# sourceMappingURL=server.js.map

package/dist/bridge/server.js.map

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

package/dist/index.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { DEFAULT_PORT, startBridgeServer } from "./bridge/server.js";
+import { registerDiscoverTools } from "./tools/discover.js";
+import { registerInstanceTools } from "./tools/instances.js";
+import { registerDebugTools } from "./tools/debug.js";
+import { registerExecTools } from "./tools/exec.js";
+import { registerPerfTools } from "./tools/perf.js";
+import { registerPlaytestTools } from "./tools/playtest.js";
+import { registerScreenshotTools } from "./tools/screenshot.js";
+import { registerWorldTools } from "./tools/world.js";
+import { registerCharacterTools } from "./tools/character.js";
+import { registerScriptTools } from "./tools/scripts.js";
+import { registerSessionTools } from "./tools/session.js";
+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.0";
+function parsePort(argv) {
+    const flag = argv.indexOf("--port");
+    const raw = flag !== -1 ? argv[flag + 1] : process.env["ROBLOX_STUDIO_MCP_PORT"];
+    const port = raw ? Number.parseInt(raw, 10) : DEFAULT_PORT;
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid port: ${raw}`);
+    }
+    return port;
+}
+/**
+ * Builds the Studio plugin and copies it into the local plugins folder.
+ *
+ * Without this the npm package is only half of what someone needs: the server
+ * installs with `npx` and the plugin is only reachable by cloning the repo,
+ * which is a strange thing to ask of someone who just installed a package.
+ *
+ * The work is delegated to `scripts/install-plugin.mjs` rather than reimplemented
+ * here, because Studio's plugins directory differs per platform and two copies of
+ * that knowledge is one too many. That script is shipped in the package.
+ */
+function installPlugin() {
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    execFileSync(process.execPath, [join(root, "scripts", "install-plugin.mjs")], {
+        stdio: "inherit",
+    });
+    process.stderr.write("Studio plugin installed. Open Studio and look for the Studio MCP button.\n");
+}
+async function main() {
+    if (process.argv.includes("--install-plugin")) {
+        installPlugin();
+        return;
+    }
+    const bridgeServer = await startBridgeServer({ port: parsePort(process.argv) });
+    const server = new McpServer({ name: "roblox-studio-mcp", version: VERSION }, {
+        instructions: "Drives a live Roblox Studio session through a companion plugin.\n\n" +
+            "Start with `studio_status` to confirm Studio is connected. Instances are " +
+            "addressed by dot-notation path from the DataModel root, e.g. " +
+            '"Workspace.Map.Spawn" or "ServerScriptService.Systems.Combat". Paths are ' +
+            "case-sensitive.\n\n" +
+            "The user may have several Studio windows open on different places. When " +
+            "more than one is connected, no place is targeted by default and tools " +
+            "refuse with AMBIGUOUS_STUDIO: call `list_studios`, ask the user which " +
+            "place they mean, then `set_active_studio`. Do the same whenever they " +
+            "mention their other place — never assume a switch.\n\n" +
+            "Prefer the batch tools: `create`, `modify`, `delete`, `move` and " +
+            "`script_edit` all take arrays and apply as a single undo step, so one " +
+            "call beats a loop of calls both in latency and in how cleanly the user " +
+            "can revert your work. Reach for `execute_luau` only when no dedicated " +
+            "tool fits — it is the escape hatch, not the default.",
+    });
+    const context = { server, bridge: bridgeServer.bridge };
+    registerSessionTools(context);
+    registerDiscoverTools(context);
+    registerScriptTools(context);
+    registerInstanceTools(context);
+    registerPerfTools(context);
+    registerPlaytestTools(context);
+    registerExecTools(context);
+    registerDebugTools(context);
+    registerScreenshotTools(context);
+    registerInputTools(context);
+    registerDeviceTools(context);
+    registerApiTools(context);
+    registerWorldTools(context);
+    registerCharacterTools(context);
+    registerResources(context);
+    const shutdown = async () => {
+        await bridgeServer.close();
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown());
+    process.on("SIGTERM", () => void shutdown());
+    // stdout belongs to the MCP transport from here on; nothing else may write to it.
+    await server.connect(new StdioServerTransport());
+}
+main().catch((cause) => {
+    process.stderr.write(`roblox-studio-mcp failed to start: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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