@el4cteo/rbx-studio-mcp 0.1.0

package/dist/tools/session.js

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { json, text } from "../lib/format.js";
+import { pluginStalenessWarning } from "../lib/pluginbuild.js";
+import { defineTool } from "../lib/tool.js";
+export function registerSessionTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "studio_status",
+        title: "Studio status",
+        description: "One-call snapshot of the connected Roblox Studio: place name and id, " +
+            "whether it is in edit / run / play mode, the current selection, which " +
+            "scripts are open in the editor, and how big the data model is.\n\n" +
+            "Call this FIRST in any Studio session, and again whenever a tool reports " +
+            "NO_STUDIO or TIMEOUT — it is the cheapest way to tell a disconnected " +
+            "plugin apart from a genuinely failing request. Also call it before and " +
+            "after `playtest`, because most tools behave differently in run mode.\n\n" +
+            "`openScripts` is what the user is actually working on: for each open tab " +
+            "it gives the script's path, the cursor line, any selected text, and which " +
+            "lines are on screen. Use it whenever a request is deictic — 'this " +
+            "function', 'the script I'm in', 'fix this' — instead of searching the " +
+            "place or asking which file they mean. Studio exposes no focused-tab API, " +
+            "so with several open, prefer the one holding a selection and otherwise " +
+            "ask.\n\n" +
+            "Returns JSON. Selection is capped at 50 entries and selected text at 400 " +
+            "characters; use `find` or `script_read` for more.",
+        inputSchema: {
+            studioId: z
+                .string()
+                .optional()
+                .describe("Target a specific Studio instance. Omit to use the active one " +
+                "(see list_studios / set_active_studio)."),
+        },
+        readOnly: true,
+    }, async ({ studioId }) => {
+        const status = await bridge.call("studio.status", {}, { studioId });
+        const targetId = studioId ?? bridge.activeId;
+        if (targetId)
+            bridge.notePlaceName(targetId, status.placeName, status.context);
+        // A stale plugin answers with older handlers and no other symptom, so the
+        // warning rides along with the one call agents are told to make first.
+        const session = bridge.list().find((entry) => entry.studioId === targetId);
+        const warning = pluginStalenessWarning(session?.buildId);
+        return json(status, warning ? `WARNING: ${warning}` : undefined);
+    });
+    defineTool(context, {
+        name: "list_studios",
+        title: "List connected Studios",
+        description: "Lists every Roblox Studio window currently connected to this server, " +
+            "with its studioId, place name, transport (sse or poll), when it " +
+            "connected, and which one is active.\n\n" +
+            "Call this whenever a tool reports AMBIGUOUS_STUDIO, and whenever the " +
+            "user refers to 'the other place' or 'my other window'. With a single " +
+            "Studio open every other tool targets it automatically, so you can skip " +
+            "it then.\n\n" +
+            "Nothing is targeted by default when several are connected: pick one with " +
+            "`set_active_studio`, or pass `studioId` to a single tool call to act on " +
+            "one place without changing the default.\n\n" +
+            "Each Studio is queried live, so `placeName` is the published name the " +
+            "user would recognise. A place never saved to Roblox has no published " +
+            "name and falls back to its data model name ('Place1').\n\n" +
+            "`context` matters more than it looks. Pressing Play adds a second entry " +
+            "for the playtest's server — same place, same name, same id as the editor " +
+            "session. Instances created or changed in a 'playtest' context are thrown " +
+            "away the moment the user stops, so building there looks like it worked " +
+            "and then vanishes. Target 'edit' unless the user specifically wants to " +
+            "inspect or affect the running game.",
+        inputSchema: {},
+        readOnly: true,
+    }, async () => {
+        const sessions = bridge.list();
+        if (sessions.length === 0) {
+            return text("No Studio instances are connected.\n" +
+                "Open Roblox Studio and enable the Studio MCP plugin (Plugins tab -> " +
+                "Studio MCP -> Connect), then call this again.");
+        }
+        // A defaulted target is not reported as active: tools refuse to use it
+        // while several are connected, so showing it as active would explain
+        // neither the AMBIGUOUS_STUDIO that follows nor how to clear it.
+        const active = bridge.activeIsChosen || sessions.length === 1 ? bridge.activeId : null;
+        // The identity captured at connect only knows the data model's name. Each
+        // Studio is asked live for the name the user would actually recognise,
+        // plus what it has open — which is usually how someone identifies a window
+        // ("the one with the intro script"). A Studio that does not answer still
+        // gets listed, from the identity it announced.
+        const detail = await Promise.all(sessions.map(async (session) => {
+            try {
+                const status = await bridge.call("studio.status", {}, { studioId: session.studioId, timeoutMs: 3_000 });
+                bridge.notePlaceName(session.studioId, status.placeName, status.context);
+                return {
+                    placeName: status.placeName,
+                    context: status.context,
+                    openScripts: (status.openScripts ?? []).map((script) => script.path),
+                };
+            }
+            catch {
+                return { placeName: session.placeName, unreachable: true };
+            }
+        }));
+        return json({
+            studios: sessions.map((session, index) => ({
+                studioId: session.studioId,
+                ...detail[index],
+                placeId: session.placeId,
+                connectedAt: new Date(session.connectedAt).toISOString(),
+                transport: session.transport,
+                pluginVersion: session.pluginVersion,
+                buildId: session.buildId,
+                stale: pluginStalenessWarning(session.buildId) ?? false,
+                active: session.studioId === active,
+            })),
+            activeStudioId: active,
+        }, active === null && sessions.length > 1
+            ? "No place is selected. Ask the user which one they mean, then call " +
+                "set_active_studio."
+            : undefined);
+    });
+    defineTool(context, {
+        name: "set_active_studio",
+        title: "Set active Studio",
+        description: "Chooses which connected Studio window every other tool targets by " +
+            "default. Use it after list_studios when several places are open, and " +
+            "again whenever the user says to switch to another place.\n\n" +
+            "The choice persists until it is changed or that Studio disconnects. " +
+            "While several Studios are connected and none has been chosen, tools " +
+            "refuse with AMBIGUOUS_STUDIO rather than guessing.",
+        inputSchema: {
+            studioId: z
+                .string()
+                .min(1)
+                .describe("A studioId from list_studios."),
+        },
+        readOnly: false,
+        destructive: false,
+        idempotent: true,
+    }, async ({ studioId }) => {
+        bridge.setActive(studioId);
+        const session = bridge.list().find((s) => s.studioId === studioId);
+        // Confirmed with the session's context because two entries can share a
+        // place name, and picking the playtest one means work that disappears
+        // when the user presses stop.
+        const status = await bridge
+            .call("studio.status", {}, { studioId, timeoutMs: 3_000 })
+            .catch(() => null);
+        const where = status?.context && status.context !== "edit" ? ` (${status.context})` : "";
+        return text(`Active Studio is now "${status?.placeName ?? session?.placeName ?? studioId}"${where}.` +
+            (where
+                ? "\nThis is a running playtest, not the editor. Changes made here are " +
+                    "discarded when the user stops it."
+                : ""));
+    });
+}
+//# sourceMappingURL=session.js.map

package/dist/tools/session.js.map

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

package/dist/tools/world.js

@@ -0,0 +1,281 @@
+import { z } from "zod";
+import { json, table, text, textOf } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+/** Roblox's toolbox search. Public, unauthenticated, and the same index Studio's own asset browser uses. */
+const TOOLBOX_SEARCH = "https://apis.roblox.com/toolbox-service/v1/marketplace";
+const TOOLBOX_DETAILS = "https://apis.roblox.com/toolbox-service/v1/items/details";
+/** Toolbox category ids. Models is the only one that inserts as instances. */
+const CATEGORIES = { model: 10, decal: 13, mesh: 40, audio: 3 };
+/**
+ * Searches the Creator Store from the server rather than the plugin.
+ *
+ * Node already has internet access and these endpoints answer unauthenticated,
+ * while a plugin making outbound HTTP needs the user to approve each domain in
+ * Plugin Management. Searching here means it works the moment the server starts.
+ */
+async function searchCreatorStore(keyword, category, limit) {
+    const categoryId = CATEGORIES[category] ?? 10;
+    const url = `${TOOLBOX_SEARCH}/${categoryId}?keyword=${encodeURIComponent(keyword)}` +
+        `&limit=${Math.min(limit, 30)}&sortType=Relevance`;
+    const found = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+    if (!found.ok) {
+        throw new Error(`Creator Store search failed (${found.status}). Roblox may be rate-limiting.`);
+    }
+    const results = (await found.json());
+    const ids = (results.data ?? []).map((entry) => entry.id).slice(0, limit);
+    if (ids.length === 0)
+        return [];
+    // Search returns bare ids; everything worth showing — name, creator, whether
+    // it carries scripts — needs the second call.
+    const detailed = await fetch(`${TOOLBOX_DETAILS}?assetIds=${ids.join(",")}`, {
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!detailed.ok) {
+        throw new Error(`Could not read asset details (${detailed.status}).`);
+    }
+    const payload = (await detailed.json());
+    return payload.data ?? [];
+}
+export function registerWorldTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "geometry",
+        title: "Solid modelling",
+        description: "Cuts, joins and shatters parts with real constructive solid geometry.\n\n" +
+            "This is how to build a shape that is not a box without importing a " +
+            "mesh: `subtract` a door out of a wall, `union` several parts into one " +
+            "solid, `intersect` to keep only the overlap, `fragment` to shatter " +
+            "something into debris.\n\n" +
+            "`subtract` and `intersect` need the parts to actually overlap, and they " +
+            "fail differently when they do not. `intersect` returns nothing, which " +
+            "comes back as an error rather than a silent no-op. `subtract` returns " +
+            "the subject UNCHANGED — a full-size copy of it, reported as a created " +
+            "part — because cutting nothing out of something legitimately leaves it " +
+            "whole. So a subtract that succeeds is not proof that anything was cut: " +
+            "check the positions overlap with `inspect` first, or compare the " +
+            "result's size against the original.\n\n" +
+            "Results keep the original's material, colour and anchoring. Roblox " +
+            "returns bare grey MeshParts, so a brick wall with a hole cut in it " +
+            "would otherwise come back as a grey slab — correct geometry that looks " +
+            "like a mistake.\n\n" +
+            "The originals are consumed unless `keepOriginals` is set. The whole " +
+            "operation is one undo step.",
+        inputSchema: {
+            op: z
+                .enum(["union", "subtract", "intersect", "fragment"])
+                .describe("'union' merges, 'subtract' cuts `with` out of `path`, 'intersect' " +
+                "keeps only the overlap, 'fragment' shatters `path` into pieces."),
+            path: z.string().describe("The part being operated on — the one cut from, for subtract."),
+            with: z
+                .array(z.string())
+                .max(50)
+                .optional()
+                .describe("The other parts. Required for union, subtract and intersect."),
+            pieces: z
+                .number()
+                .int()
+                .min(2)
+                .max(100)
+                .default(8)
+                .describe("fragment only: roughly how many pieces to break into."),
+            name: z.string().optional().describe("Name for the result. Defaults to the original's."),
+            parent: z.string().optional().describe("Where to put the result. Defaults to the original's parent."),
+            keepOriginals: z
+                .boolean()
+                .default(false)
+                .describe("Leave the input parts in place instead of consuming them."),
+            collisionFidelity: z
+                .enum(["Default", "Hull", "Box", "PreciseConvexDecomposition"])
+                .default("Default")
+                .describe("How exactly the result collides. Precise is expensive — raise it " +
+                "only for a surface players walk on."),
+            splitApart: z
+                .boolean()
+                .default(false)
+                .describe("Return disconnected chunks as separate parts rather than one."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: true,
+    }, async (args) => {
+        const isFragment = args.op === "fragment";
+        const response = await bridge.call(isFragment ? "geometry.fragment" : "geometry.combine", {
+            op: args.op,
+            path: args.path,
+            with: args.with,
+            pieces: args.pieces,
+            name: args.name,
+            parent: args.parent,
+            keepOriginals: args.keepOriginals,
+            collisionFidelity: args.collisionFidelity,
+            splitApart: args.splitApart,
+        }, 
+        // Solid modelling on a complex mesh is genuinely slow.
+        { studioId: args.studioId, timeoutMs: 120_000 });
+        const notes = [];
+        if (response.removed && response.removed.length > 0) {
+            notes.push(`Consumed: ${response.removed.join(", ")}.`);
+        }
+        if (!response.undoable) {
+            notes.push("Studio would not open an undo recording, so this is not one Ctrl+Z.");
+        }
+        return json(response.created, notes.length > 0 ? notes.join(" ") : undefined);
+    });
+    defineTool(context, {
+        name: "assets",
+        title: "Creator Store",
+        description: "Searches Roblox's Creator Store and inserts models into the place.\n\n" +
+            "`search` looks through the same public index Studio's own asset browser " +
+            "uses and returns ids with names, creators, vote ratios and — the part " +
+            "that matters — whether the model contains scripts. `insert` puts one " +
+            "into the place by id.\n\n" +
+            "ALWAYS check `hasScripts` before inserting. Free models carrying " +
+            "scripts are the oldest hazard on the platform, and a model dropped into " +
+            "someone's game can run whatever it likes. The insert reports the script " +
+            "count again, and names them, so it can still be undone.\n\n" +
+            "Only public assets can be inserted. A private or deleted id fails with " +
+            "a message saying so rather than inserting nothing quietly.",
+        inputSchema: {
+            op: z.enum(["search", "insert"]).describe("'search' finds assets, 'insert' adds one to the place."),
+            keyword: z.string().optional().describe("search only: what to look for, e.g. \"medieval door\"."),
+            category: z
+                .enum(["model", "decal", "mesh", "audio"])
+                .default("model")
+                .describe("search only: what kind of asset. Only models insert as instances."),
+            limit: z.number().int().min(1).max(20).default(8).describe("search only: how many results."),
+            assetId: z.number().int().positive().optional().describe("insert only: the asset id to insert."),
+            parent: z.string().optional().describe("insert only: where to put it. Defaults to Workspace."),
+            position: z
+                .string()
+                .optional()
+                .describe('insert only: where to place it, e.g. "0, 10, 0". Defaults to wherever it was saved.'),
+            name: z.string().optional().describe("insert only: rename it on the way in."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: false,
+    }, async (args) => {
+        if (args.op === "search") {
+            if (!args.keyword)
+                return text("search needs a `keyword`.");
+            const found = await searchCreatorStore(args.keyword, args.category, args.limit);
+            if (found.length === 0) {
+                return text(`Nothing matched "${args.keyword}" in ${args.category}s.`);
+            }
+            const rows = found.map((entry) => ({
+                assetId: entry.asset?.id ?? 0,
+                name: entry.asset?.name ?? "?",
+                creator: entry.creator?.name ?? "?",
+                approval: entry.voting?.upVotePercent ? `${entry.voting.upVotePercent}%` : "—",
+                hasScripts: entry.asset?.hasScripts ? "YES" : "no",
+                triangles: entry.asset?.modelTechnicalDetails?.objectMeshSummary?.triangles ?? "—",
+            }));
+            const risky = rows.filter((row) => row.hasScripts === "YES");
+            return text(textOf(table(["assetId", "name", "creator", "approval", "hasScripts", "triangles"], rows)) +
+                (risky.length > 0
+                    ? `\n\n${risky.length} of these contain scripts (${risky
+                        .map((r) => r.name)
+                        .join(", ")}). Inserting one runs whatever its author put in it — prefer a script-free model unless the scripts are the point.`
+                    : "\n\nNone of these contain scripts."));
+        }
+        if (!args.assetId)
+            return text("insert needs an `assetId`. Use `op: \"search\"` to find one.");
+        const response = await bridge.call("assets.insert", {
+            assetId: args.assetId,
+            parent: args.parent,
+            position: args.position,
+            name: args.name,
+        }, 
+        // Downloading an asset goes out to Roblox and back.
+        { studioId: args.studioId, timeoutMs: 90_000 });
+        const notes = [];
+        if (response.scriptCount > 0) {
+            notes.push(`WARNING: this asset contains ${response.scriptCount} script(s): ` +
+                `${(response.scripts ?? []).join(", ")}. They will run on the next playtest. ` +
+                "Read them before playing, or delete them.");
+        }
+        if (!response.undoable)
+            notes.push("Not undoable as one step.");
+        return json(response.inserted, notes.length > 0 ? notes.join("\n\n") : undefined);
+    });
+    defineTool(context, {
+        name: "undo",
+        title: "Undo and redo",
+        description: "Steps Studio's undo history backwards or forwards.\n\n" +
+            "Every write this server makes is already wrapped in an undo recording, " +
+            "so this reverses your own work as cleanly as the user pressing Ctrl+Z " +
+            "— one tool call is one step. Use it when the user says an edit was " +
+            "wrong, instead of trying to reconstruct the previous state by hand, " +
+            "which is guesswork and usually incomplete.\n\n" +
+            "It reports how many steps actually applied, which is not always what " +
+            "was asked: the stack runs out, and an undo that did nothing otherwise " +
+            "looks exactly like one that worked.\n\n" +
+            "Studio's history covers the whole session, including the user's own " +
+            "edits — undoing more steps than you made will start reverting THEIR " +
+            "work. Undo only what you just did, and only when asked.",
+        inputSchema: {
+            action: z
+                .enum(["undo", "redo", "status"])
+                .default("status")
+                .describe("'status' reports what is available without changing anything."),
+            steps: z
+                .number()
+                .int()
+                .min(1)
+                .max(25)
+                .default(1)
+                .describe("How many steps to take. Keep it to what you did yourself."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: true,
+    }, async (args) => {
+        const response = await bridge.call("world.history", { action: args.action, steps: args.steps }, { studioId: args.studioId });
+        return json(response, response.note);
+    });
+    defineTool(context, {
+        name: "collision",
+        title: "Collision groups",
+        description: "Controls which parts physically collide with which.\n\n" +
+            "This is the right answer to 'these should pass through each other'. " +
+            "The alternative — turning CanCollide off — disables collision against " +
+            "everything, so a ghost that should pass through walls also falls " +
+            "through the floor.\n\n" +
+            "The order is: `create` a group, `assign` parts to it, then set what it " +
+            "is `collidable` with. A group with nothing assigned does nothing.\n\n" +
+            "Assigning a Model assigns every part inside it, which is almost always " +
+            "what is meant.",
+        inputSchema: {
+            action: z
+                .enum(["list", "create", "assign", "collidable"])
+                .default("list")
+                .describe("'list' shows existing groups and changes nothing."),
+            group: z.string().optional().describe("The group's name. Required for everything but list."),
+            paths: z
+                .array(z.string())
+                .max(100)
+                .optional()
+                .describe("assign only: parts or models to put in the group."),
+            with: z.string().optional().describe("collidable only: the other group."),
+            collidable: z
+                .boolean()
+                .default(true)
+                .describe("collidable only: whether the two groups collide. False makes them pass through."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: false,
+    }, async (args) => {
+        const response = await bridge.call("world.collision", {
+            action: args.action,
+            group: args.group,
+            paths: args.paths,
+            with: args.with,
+            collidable: args.collidable,
+        }, { studioId: args.studioId });
+        if (args.action === "list") {
+            const groups = response.groups ?? [];
+            if (groups.length === 0)
+                return text("No collision groups are registered.");
+            return text(textOf(table(["name", "mask"], groups)));
+        }
+        return json(response);
+    });
+}
+//# sourceMappingURL=world.js.map

package/dist/tools/world.js.map

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

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@el4cteo/rbx-studio-mcp",
+  "version": "0.1.0",
+  "description": "Free, open-source MCP server for Roblox Studio. Push-based SSE transport, editor-safe script edits, token-lean tools.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "rbx-studio-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "plugin",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.15"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "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",
+    "build:all": "npm run build && npm run build:plugin",
+    "install:plugin": "node scripts/install-plugin.mjs",
+    "check:plugin": "node scripts/check-plugin.mjs",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "roblox",
+    "roblox-studio",
+    "luau",
+    "claude",
+    "ai"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
+  },
+  "author": "EL4CTEO",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EL4CTEO/roblox-studio-mcp.git"
+  },
+  "homepage": "https://github.com/EL4CTEO/roblox-studio-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/EL4CTEO/roblox-studio-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/default.project.json

@@ -0,0 +1,6 @@
+{
+  "name": "StudioMCP",
+  "tree": {
+    "$path": "src"
+  }
+}

package/plugin/src/Config.luau

@@ -0,0 +1,59 @@
+--!strict
+--[[
+	Connection settings for the Studio MCP plugin.
+
+	The port must match the one the Node server was started with (`--port`, or
+	the ROBLOX_STUDIO_MCP_PORT environment variable). It is stored as a plugin
+	setting so a user running on a non-default port only has to set it once.
+]]
+
+local Config = {}
+
+Config.PLUGIN_VERSION = "0.1.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
+-- plugin left running from an older build is reported rather than silently
+-- answering with stale handlers. Stays "dev" when the tree is loaded unbuilt.
+Config.BUILD_ID = "dev"
+Config.PROTOCOL_VERSION = 1
+Config.DEFAULT_PORT = 44755
+
+-- Header the bridge requires on every request. A web page cannot set it
+-- cross-origin without a preflight the bridge never answers, which is what
+-- keeps a malicious site from driving Studio through the loopback port.
+Config.CLIENT_HEADER = "x-roblox-studio-mcp"
+
+-- How long to wait before retrying after the stream drops. Studio closes SSE
+-- connections at the 30 minute mark, so reconnects are routine, not exceptional.
+Config.RECONNECT_DELAY = 1
+Config.MAX_RECONNECT_DELAY = 30
+
+-- How long a healthy long-poll session runs before standing aside so streaming
+-- can be tried again. Long enough that a Studio which genuinely cannot stream
+-- is not reconnecting constantly, short enough that a session downgraded by one
+-- unlucky attempt does not spend the rest of its life slower than it should be.
+Config.RESTREAM_INTERVAL = 60
+
+local port: number? = nil
+
+function Config.setPort(value: number)
+	port = value
+end
+
+function Config.getPort(): number
+	return port or Config.DEFAULT_PORT
+end
+
+function Config.baseUrl(): string
+	return string.format("http://127.0.0.1:%d", Config.getPort())
+end
+
+function Config.headers(): { [string]: string }
+	return {
+		[Config.CLIENT_HEADER] = tostring(Config.PROTOCOL_VERSION),
+		["Content-Type"] = "application/json",
+	}
+end
+
+return Config