@el4cteo/rbx-studio-mcp 0.6.5 → 0.6.7

package/dist/lib/credentials.js

@@ -0,0 +1,180 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Where the Open Cloud key lives, and the rules about handling it.
+ *
+ * A Roblox API key with `assets:write` can publish assets under the user's own
+ * name, and Roblox counts those against a real monthly quota. So it is treated
+ * as a password everywhere in this file: it is never returned to a caller, never
+ * logged, never put in a tool result, and never written anywhere that travels.
+ *
+ * Not `plugin:SetSetting`, which was the obvious place to put it. Plugin
+ * settings are stored per place and move with the .rbxl: into version control,
+ * into a Team Create session, to whoever the place is shared with. A file under
+ * the user's own home directory does not move at all.
+ *
+ * The environment still wins over the file. Someone running this in CI, or
+ * sharing one machine, wants the key to come from the process they started and
+ * to leave nothing behind — so `ROBLOX_API_KEY` is checked first and the file is
+ * only consulted when it is unset.
+ */
+const DIRECTORY = join(homedir(), ".rbx-studio-mcp");
+const FILE = join(DIRECTORY, "credentials.json");
+async function readStored() {
+    try {
+        return JSON.parse(await readFile(FILE, "utf8"));
+    }
+    catch {
+        // Absent, unreadable or corrupt all mean the same thing to every caller:
+        // nothing is stored. A parse error is not worth failing a tool over.
+        return {};
+    }
+}
+async function writeStored(next) {
+    await mkdir(DIRECTORY, { recursive: true, mode: 0o700 });
+    /**
+     * Written, then narrowed.
+     *
+     * `mode` on writeFile is masked by the process umask, so it is not on its own
+     * a guarantee; chmod after the fact is. On Windows this is close to a no-op —
+     * Node maps it to the read-only flag — and the protection there comes from
+     * the file sitting inside the user's profile, which is ACL'd to that user.
+     * Worth doing anyway: this server runs on macOS and Linux too, where a
+     * world-readable key in a home directory is a real exposure.
+     */
+    await writeFile(FILE, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    await chmod(FILE, 0o600).catch(() => {
+        // Best effort: a filesystem that does not do permissions is not a reason to
+        // refuse to save.
+    });
+}
+/**
+ * The credentials to upload with, or null when the setup is incomplete.
+ *
+ * A key with no creator is incomplete, not usable: Roblox rejects the upload
+ * with a permissions error that names neither, which is a much worse thing to
+ * debug than being told up front.
+ */
+export async function loadCredentials() {
+    const stored = await readStored();
+    const envKey = process.env["ROBLOX_API_KEY"]?.trim();
+    const envUser = process.env["ROBLOX_USER_ID"]?.trim();
+    const envGroup = process.env["ROBLOX_GROUP_ID"]?.trim();
+    /**
+     * The universe and place fall back to the file even when the key comes from
+     * the environment.
+     *
+     * They are not secrets and they are not part of the credential: someone who
+     * exports a key in CI has still told the panel which game they are working
+     * on, and making them re-export two public ids to keep that would be a
+     * papercut with nothing behind it.
+     */
+    const universeId = process.env["ROBLOX_UNIVERSE_ID"]?.trim() || stored.universeId;
+    const placeId = process.env["ROBLOX_PLACE_ID"]?.trim() || stored.placeId;
+    const apiKey = envKey || stored.apiKey;
+    if (!apiKey)
+        return null;
+    const source = envKey ? "environment" : "file";
+    const groupId = envKey ? envGroup : stored.groupId;
+    const userId = envKey ? envUser : stored.userId;
+    if (!groupId && !userId)
+        return null;
+    return {
+        apiKey,
+        creatorId: (groupId || userId),
+        creatorField: groupId ? "groupId" : "userId",
+        universeId,
+        placeId,
+        source,
+    };
+}
+/** What is configured, without the key itself. */
+export async function credentialStatus() {
+    const envKey = process.env["ROBLOX_API_KEY"]?.trim();
+    const envUser = process.env["ROBLOX_USER_ID"]?.trim();
+    const envGroup = process.env["ROBLOX_GROUP_ID"]?.trim();
+    const stored = await readStored();
+    const apiKey = envKey || stored.apiKey;
+    const source = envKey ? "environment" : stored.apiKey ? "file" : null;
+    const groupId = envKey ? envGroup : stored.groupId;
+    const userId = envKey ? envUser : stored.userId;
+    return {
+        hasKey: Boolean(apiKey),
+        keyHint: apiKey ? apiKey.slice(-4) : null,
+        creatorId: groupId || userId || null,
+        creatorField: groupId ? "groupId" : userId ? "userId" : null,
+        universeId: process.env["ROBLOX_UNIVERSE_ID"]?.trim() || stored.universeId || null,
+        placeId: process.env["ROBLOX_PLACE_ID"]?.trim() || stored.placeId || null,
+        source,
+        path: FILE,
+    };
+}
+/** Remembers which game the universe-scoped calls act on. */
+export async function saveTarget(field, id) {
+    const stored = await readStored();
+    stored[field] = id;
+    await writeStored(stored);
+}
+export async function saveApiKey(apiKey) {
+    const stored = await readStored();
+    stored.apiKey = apiKey;
+    await writeStored(stored);
+}
+/**
+ * Sets the creator, clearing the other kind.
+ *
+ * Both at once is not a state worth allowing: Roblox takes one creator per
+ * upload, and a leftover userId sitting under a groupId is the kind of thing
+ * that silently publishes to the wrong account months later.
+ */
+export async function saveCreator(field, id) {
+    const stored = await readStored();
+    delete stored.userId;
+    delete stored.groupId;
+    stored[field] = id;
+    await writeStored(stored);
+}
+/** Deletes the file outright. Nothing is left behind to un-delete. */
+export async function forgetCredentials() {
+    try {
+        await rm(FILE);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Asks Roblox whether the key works, without uploading anything.
+ *
+ * There is no "who am I" endpoint for an API key, so this calls the operations
+ * endpoint with an id that cannot exist. A working key gets 404 (or 400); a bad
+ * one gets 401 or 403 before Roblox ever looks at the id. That distinction is
+ * the whole test, and it costs no quota.
+ */
+export async function testCredentials(apiKey) {
+    let response;
+    try {
+        response = await fetch("https://apis.roblox.com/assets/v1/operations/0", {
+            headers: { "x-api-key": apiKey },
+        });
+    }
+    catch (cause) {
+        return { ok: false, detail: `could not reach Roblox: ${cause.message}` };
+    }
+    if (response.status === 401)
+        return { ok: false, detail: "Roblox rejected the key (401)" };
+    if (response.status === 403) {
+        return {
+            ok: false,
+            detail: "Roblox refused the key (403) — usually a missing `assets` permission, " +
+                "or your IP is not in the key's allowed list",
+        };
+    }
+    if (response.status === 429)
+        return { ok: true, detail: "the key works (rate limited right now)" };
+    return { ok: true, detail: "the key works" };
+}
+export { FILE as CREDENTIALS_PATH };
+//# sourceMappingURL=credentials.js.map

package/dist/lib/credentials.js.map

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

package/dist/lib/livedata.js

@@ -0,0 +1,325 @@
+import { ToolError } from "./errors.js";
+import { call, paged } from "./opencloud.js";
+/**
+ * Data stores of the PUBLISHED game, over Open Cloud.
+ *
+ * The `datastore` tool already reads data stores — through Studio, which reads
+ * whatever the open place is connected to. That is the right thing while
+ * building and the wrong thing when a player reports lost progress, because
+ * Studio's view depends on which place is open and on "Enable Studio Access to
+ * API Services" being ticked. This path talks to Roblox directly and always
+ * sees exactly what the live servers see.
+ *
+ * Kept behind the same tool and the same five verbs rather than a new one. The
+ * question "what did this player save" does not change because the answer comes
+ * over HTTP, and a second tool would mean an agent picking between two spellings
+ * of one idea.
+ *
+ * Two differences from the engine API are load-bearing and are surfaced rather
+ * than hidden:
+ *
+ * 1. Creating and updating are separate permissions. `SetAsync` creates or
+ *    overwrites; here a write to a missing key is refused unless it is asked
+ *    for, which is what makes a support tool safe to hand out.
+ * 2. Values are JSON, not Luau. Roblox does no serialising for us, and a value
+ *    that was a Luau table arrives as a JSON object.
+ */
+/** Percent-encodes one path segment. Key names routinely contain slashes. */
+function segment(value) {
+    return encodeURIComponent(value);
+}
+/**
+ * Builds the entries path, with or without a scope.
+ *
+ * Open Cloud has two shapes rather than a scope parameter: omitting the scope
+ * is not "the default scope", it means "all scopes". A game that uses scopes
+ * and a game that does not therefore need genuinely different URLs, and getting
+ * this wrong reads as the store being empty.
+ */
+function entriesPath(universe, store, scope) {
+    const base = `/cloud/v2/universes/${segment(universe)}/data-stores/${segment(store)}`;
+    return scope && scope !== ""
+        ? `${base}/scopes/${segment(scope)}/entries`
+        : `${base}/entries`;
+}
+function orderedPath(universe, store, scope) {
+    return (`/cloud/v2/universes/${segment(universe)}` +
+        `/ordered-data-stores/${segment(store)}/scopes/${segment(scope)}/entries`);
+}
+/** The trailing id of a resource path, which is the only part a human wants. */
+function idOf(path) {
+    if (!path)
+        return "";
+    const parts = path.split("/");
+    return decodeURIComponent(parts[parts.length - 1] ?? "");
+}
+function parseValue(raw) {
+    if (raw === undefined) {
+        throw new ToolError("BAD_PARAMS", "set needs a `value`.");
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        /**
+         * A bare string is valid JSON only when quoted, and people write
+         * `value: "hello"` meaning the string. Accepting it is friendlier than a
+         * parse error — but only after real JSON has been tried, so `{"a":1}` is
+         * never stored as the eleven characters that spell it.
+         */
+        return raw;
+    }
+}
+export async function liveDataStore(credentials, args) {
+    const { universe, op, kind } = args;
+    if (kind === "ordered")
+        return orderedStore(credentials, args);
+    if (op === "list" && !args.store) {
+        const { items, truncated } = await paged(credentials, {
+            path: `/cloud/v2/universes/${segment(universe)}/data-stores`,
+            scope: "universe-datastores.control:list",
+            field: "dataStores",
+            limit: args.limit,
+            query: { pageToken: args.cursor },
+        });
+        return {
+            target: "live",
+            universe,
+            items: items.map((store) => ({
+                store: idOf(store.path),
+                created: store.createTime,
+                state: store.state,
+            })),
+            count: items.length,
+            truncated,
+        };
+    }
+    if (!args.store) {
+        throw new ToolError("BAD_PARAMS", `live ${op} needs a \`store\`.`);
+    }
+    const base = entriesPath(universe, args.store, args.scope);
+    if (op === "list") {
+        const { items, truncated } = await paged(credentials, {
+            path: base,
+            scope: "universe-datastores.objects:list",
+            field: "dataStoreEntries",
+            limit: args.limit,
+            query: { pageToken: args.cursor },
+        });
+        return {
+            target: "live",
+            store: args.store,
+            items: items.map((entry) => ({ key: idOf(entry.path), state: entry.state })),
+            count: items.length,
+            truncated,
+        };
+    }
+    if (!args.key)
+        throw new ToolError("BAD_PARAMS", `live ${op} needs a \`key\`.`);
+    const entry = `${base}/${segment(args.key)}`;
+    if (op === "versions") {
+        const { items, truncated } = await paged(credentials, {
+            path: `${entry}:listRevisions`,
+            scope: "universe-datastores.versions:list",
+            field: "dataStoreEntries",
+            limit: args.limit,
+            query: { pageToken: args.cursor },
+        });
+        return {
+            target: "live",
+            store: args.store,
+            key: args.key,
+            items: items.map((revision) => ({
+                version: revision.revisionId,
+                created: revision.revisionCreateTime,
+                deleted: revision.state === "DELETED",
+            })),
+            count: items.length,
+            truncated,
+        };
+    }
+    if (op === "get") {
+        const found = await call(credentials, {
+            path: entry,
+            scope: "universe-datastores.objects:read",
+        });
+        return {
+            target: "live",
+            store: args.store,
+            key: args.key,
+            exists: true,
+            value: found.value,
+            version: found.revisionId,
+            updated: found.revisionCreateTime,
+            etag: found.etag,
+        };
+    }
+    if (op === "remove") {
+        await call(credentials, {
+            method: "DELETE",
+            path: entry,
+            scope: "universe-datastores.objects:delete",
+        });
+        return { target: "live", store: args.store, key: args.key, removed: true };
+    }
+    if (op === "increment") {
+        if (typeof args.amount !== "number") {
+            throw new ToolError("BAD_PARAMS", "increment needs an `amount`.");
+        }
+        const result = await call(credentials, {
+            method: "POST",
+            path: `${entry}:increment`,
+            body: { amount: args.amount },
+            scope: "universe-datastores.objects:update",
+        });
+        return {
+            target: "live",
+            store: args.store,
+            key: args.key,
+            value: result.value,
+            version: result.revisionId,
+        };
+    }
+    /**
+     * `allowMissing` is the create/update split made visible.
+     *
+     * Off by default so a typo in a key name fails instead of quietly creating a
+     * second, empty save beside the real one — the failure mode that makes people
+     * think a player's data "reset".
+     */
+    const written = await call(credentials, {
+        method: "PATCH",
+        path: entry,
+        query: { allowMissing: args.create ? "true" : undefined },
+        body: { value: parseValue(args.value) },
+        scope: "universe-datastores.objects:update",
+    });
+    return {
+        target: "live",
+        store: args.store,
+        key: args.key,
+        written: true,
+        version: written.revisionId,
+    };
+}
+/**
+ * Ordered data stores: the leaderboard backend.
+ *
+ * A separate service with a separate scope, not a flavour of the one above —
+ * values are numbers only, entries are always sorted, and there is no version
+ * history. It lives here rather than in its own file because from the caller's
+ * side it is the same five verbs against the same game.
+ */
+async function orderedStore(credentials, args) {
+    if (!args.store)
+        throw new ToolError("BAD_PARAMS", "ordered stores need a `store`.");
+    // Roblox requires a scope in the URL and every SDK defaults it to "global";
+    // an ordered store written by an engine script with no scope lands there.
+    const scope = args.scope && args.scope !== "" ? args.scope : "global";
+    const base = orderedPath(args.universe, args.store, scope);
+    if (args.op === "list") {
+        const { items, truncated } = await paged(credentials, {
+            path: base,
+            scope: "universe.ordered-data-store.scope.entry:read",
+            field: "orderedDataStoreEntries",
+            limit: args.limit,
+            // Descending: a leaderboard is read from the top, and asking for the
+            // bottom of one is the rarer case.
+            query: { orderBy: "value desc", pageToken: args.cursor },
+        });
+        return {
+            target: "live",
+            kind: "ordered",
+            store: args.store,
+            scope,
+            items: items.map((entry, index) => ({
+                rank: index + 1,
+                key: entry.id ?? idOf(entry.path),
+                value: entry.value,
+            })),
+            count: items.length,
+            truncated,
+        };
+    }
+    if (!args.key)
+        throw new ToolError("BAD_PARAMS", `ordered ${args.op} needs a \`key\`.`);
+    const entry = `${base}/${segment(args.key)}`;
+    if (args.op === "get") {
+        const found = await call(credentials, {
+            path: entry,
+            scope: "universe.ordered-data-store.scope.entry:read",
+        });
+        return { target: "live", kind: "ordered", store: args.store, scope, key: args.key, value: found.value };
+    }
+    if (args.op === "remove") {
+        await call(credentials, {
+            method: "DELETE",
+            path: entry,
+            scope: "universe.ordered-data-store.scope.entry:write",
+        });
+        return { target: "live", kind: "ordered", store: args.store, key: args.key, removed: true };
+    }
+    if (args.op === "increment") {
+        if (typeof args.amount !== "number") {
+            throw new ToolError("BAD_PARAMS", "increment needs an `amount`.");
+        }
+        const result = await call(credentials, {
+            method: "POST",
+            path: `${entry}:increment`,
+            body: { amount: args.amount },
+            scope: "universe.ordered-data-store.scope.entry:write",
+        });
+        return { target: "live", kind: "ordered", store: args.store, key: args.key, value: result.value };
+    }
+    if (args.op === "versions") {
+        throw new ToolError("UNSUPPORTED", "Ordered data stores keep no version history.", 'Use kind="data" for anything that needs to be recoverable.');
+    }
+    const numeric = Number(args.value);
+    if (!Number.isFinite(numeric)) {
+        throw new ToolError("BAD_PARAMS", `An ordered data store holds numbers; "${args.value}" is not one.`);
+    }
+    /**
+     * Update first, create on 404.
+     *
+     * Open Cloud splits the two and the caller usually does not know which they
+     * need — setting a player's score works the same whether or not they have one
+     * yet. Trying the safer verb first keeps the create path from being the
+     * default, which is what stops a typo'd key becoming a new leaderboard row.
+     */
+    try {
+        const patched = await call(credentials, {
+            method: "PATCH",
+            path: entry,
+            body: { value: numeric },
+            scope: "universe.ordered-data-store.scope.entry:write",
+        });
+        return {
+            target: "live",
+            kind: "ordered",
+            store: args.store,
+            key: args.key,
+            value: patched.value,
+            created: false,
+        };
+    }
+    catch (cause) {
+        if (!(cause instanceof ToolError) || cause.code !== "NOT_FOUND")
+            throw cause;
+        const made = await call(credentials, {
+            method: "POST",
+            path: base,
+            query: { id: args.key },
+            body: { value: numeric },
+            scope: "universe.ordered-data-store.scope.entry:write",
+        });
+        return {
+            target: "live",
+            kind: "ordered",
+            store: args.store,
+            key: args.key,
+            value: made.value,
+            created: true,
+        };
+    }
+}
+//# sourceMappingURL=livedata.js.map

package/dist/lib/livedata.js.map

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

package/dist/lib/liveluau.js

@@ -0,0 +1,83 @@
+import { ToolError } from "./errors.js";
+import { call } from "./opencloud.js";
+/**
+ * Running Luau against the PUBLISHED game, over Open Cloud.
+ *
+ * `execute_luau` already runs code — inside Studio, against the place someone
+ * has open. This runs it on Roblox's own servers against the published place,
+ * with no Studio involved at all. That is a different question with the same
+ * shape: "what does this code do here" versus "what does this code do in
+ * production", and it is the only way to answer the second one.
+ *
+ * Roblox models it as a task rather than a request: you create one, it queues,
+ * a server picks it up, and the result appears later. So this submits and then
+ * polls, and reports the state it ended in rather than pretending it was
+ * synchronous.
+ *
+ * It is genuinely dangerous in a way the Studio path is not. Studio has an undo
+ * stack and a place file nobody is playing; this touches live data stores and
+ * live players, and nothing here can put any of it back. The tool gates it.
+ */
+const POLL_INTERVAL_MS = 2_000;
+export async function runLiveLuau(credentials, args) {
+    const started = await call(credentials, {
+        method: "POST",
+        path: `/cloud/v2/universes/${encodeURIComponent(args.universeId)}` +
+            `/places/${encodeURIComponent(args.placeId)}/luau-execution-session-tasks`,
+        body: { script: args.source, timeout: `${args.timeoutSeconds}s` },
+        scope: "universe.place.luau-execution-session:write",
+    });
+    if (!started.path) {
+        throw new ToolError("NO_TASK", "Roblox accepted the script but did not say where to track it.");
+    }
+    /**
+     * Waited on for the script's own timeout plus a margin.
+     *
+     * The margin is for the queue: a task is not running the moment it is
+     * created, and giving up at exactly the script timeout would report a
+     * failure for a script that had not started yet.
+     */
+    const deadline = Date.now() + (args.timeoutSeconds + 30) * 1000;
+    let task = started;
+    while (task.state === "QUEUED" || task.state === "PROCESSING" || task.state === undefined) {
+        if (Date.now() >= deadline) {
+            return {
+                target: "live",
+                state: task.state ?? "UNKNOWN",
+                task: started.path,
+                note: "Gave up waiting. The task may still be running on Roblox's side — " +
+                    "it was not cancelled.",
+            };
+        }
+        await new Promise((done) => setTimeout(done, POLL_INTERVAL_MS));
+        task = await call(credentials, {
+            path: `/cloud/v2/${started.path}`,
+            query: { view: "FULL" },
+            scope: "universe.place.luau-execution-session:write",
+        });
+    }
+    // Logs are a separate resource from the result, and they hold everything the
+    // script printed — which for a diagnostic script is the whole point.
+    let logs = [];
+    try {
+        const page = await call(credentials, {
+            path: `/cloud/v2/${started.path}/logs`,
+            query: { maxPageSize: 100 },
+            scope: "universe.place.luau-execution-session:write",
+        });
+        logs = (page.luauExecutionSessionTaskLogs ?? []).flatMap((entry) => entry.messages ?? []);
+    }
+    catch {
+        // A missing log page is not worth failing a successful run over.
+    }
+    return {
+        target: "live",
+        universeId: args.universeId,
+        placeId: args.placeId,
+        state: task.state,
+        results: task.output?.results,
+        logs,
+        error: task.error ? `${task.error.code ?? "error"}: ${task.error.message ?? ""}` : undefined,
+    };
+}
+//# sourceMappingURL=liveluau.js.map

package/dist/lib/liveluau.js.map

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