robloxstudio-mcp 2.4.0 → 2.5.0

package/dist/index.js

@@ -74,7 +74,8 @@ var TOOL_HANDLERS = {
   get_asset_details: (tools, body) => tools.getAssetDetails(body.assetId),
   get_asset_thumbnail: (tools, body) => tools.getAssetThumbnail(body.assetId, body.size),
   insert_asset: (tools, body) => tools.insertAsset(body.assetId, body.parentPath, body.position),
-  preview_asset: (tools, body) => tools.previewAsset(body.assetId, body.includeProperties, body.maxDepth)
+  preview_asset: (tools, body) => tools.previewAsset(body.assetId, body.includeProperties, body.maxDepth),
+  capture_screenshot: (tools) => tools.captureScreenshot()
 };
 function createHttpServer(tools, bridge, allowedTools) {
   const app = express();
@@ -805,6 +806,41 @@ var OpenCloudClient = class {
   }
 };
 
+// ../../node_modules/@robloxstudio-mcp/core/dist/png-encoder.js
+import { deflateSync, crc32 } from "zlib";
+var PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+function writeChunk(type, data) {
+  const typeBytes = Buffer.from(type, "ascii");
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length);
+  const crcInput = Buffer.concat([typeBytes, data]);
+  const checksum = Buffer.alloc(4);
+  checksum.writeUInt32BE(crc32(crcInput) >>> 0);
+  return Buffer.concat([length, typeBytes, data, checksum]);
+}
+function rgbaToPng(rgba, width, height) {
+  const stride = width * 4;
+  const filtered = Buffer.alloc(height * (1 + stride));
+  for (let y = 0; y < height; y++) {
+    filtered[y * (1 + stride)] = 0;
+    rgba.copy(filtered, y * (1 + stride) + 1, y * stride, (y + 1) * stride);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  ihdr[10] = 0;
+  ihdr[11] = 0;
+  ihdr[12] = 0;
+  return Buffer.concat([
+    PNG_SIGNATURE,
+    writeChunk("IHDR", ihdr),
+    writeChunk("IDAT", deflateSync(filtered)),
+    writeChunk("IEND", Buffer.alloc(0))
+  ]);
+}
+
 // ../../node_modules/@robloxstudio-mcp/core/dist/tools/index.js
 import * as fs from "fs";
 import * as path from "path";
@@ -1404,7 +1440,7 @@ var RobloxStudioTools = class _RobloxStudioTools {
     };
   }
   static findLibraryPath() {
-    let dir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, "$1"));
+    let dir = path.dirname(decodeURIComponent(new URL(import.meta.url).pathname).replace(/^\/([A-Z]:)/, "$1"));
     for (let i = 0; i < 6; i++) {
       const candidate = path.join(dir, "build-library");
       if (fs.existsSync(candidate))
@@ -1656,11 +1692,59 @@ var RobloxStudioTools = class _RobloxStudioTools {
     const expandedBuilds = [];
     const modelMap = sceneData.models || {};
     const placements = sceneData.place || [];
-    for (const placement of placements) {
-      const [modelKey, position, rotation] = placement;
+    const isVec3Tuple = (value) => {
+      return Array.isArray(value) && value.length === 3 && value.every((component) => typeof component === "number" && Number.isFinite(component));
+    };
+    for (const [placementIndex, placement] of placements.entries()) {
+      let modelKey;
+      let position;
+      let rotation;
+      let validatedKeyPath;
+      if (Array.isArray(placement)) {
+        if (placement.length < 2 || placement.length > 3) {
+          throw new Error(`Invalid sceneData.place[${placementIndex}]: expected [modelKey, [x,y,z], [rotX?,rotY?,rotZ?]]`);
+        }
+        const [tupleModelKey, tuplePosition, tupleRotation] = placement;
+        if (typeof tupleModelKey !== "string" || tupleModelKey.trim() === "") {
+          throw new Error(`Invalid sceneData.place[${placementIndex}][0]: model key must be a non-empty string`);
+        }
+        modelKey = tupleModelKey.trim();
+        validatedKeyPath = `sceneData.place[${placementIndex}][0]`;
+        if (!isVec3Tuple(tuplePosition)) {
+          throw new Error(`Invalid sceneData.place[${placementIndex}][1]: position must be a numeric [x,y,z] tuple`);
+        }
+        position = tuplePosition;
+        if (tupleRotation !== void 0) {
+          if (!isVec3Tuple(tupleRotation)) {
+            throw new Error(`Invalid sceneData.place[${placementIndex}][2]: rotation must be a numeric [x,y,z] tuple when provided`);
+          }
+          rotation = tupleRotation;
+        }
+      } else if (placement && typeof placement === "object") {
+        const placementRecord = placement;
+        const objectModelKey = placementRecord.modelKey;
+        const objectPosition = placementRecord.position;
+        const objectRotation = placementRecord.rotation;
+        if (typeof objectModelKey !== "string" || objectModelKey.trim() === "") {
+          throw new Error(`Invalid sceneData.place[${placementIndex}].modelKey: model key must be a non-empty string`);
+        }
+        if (!isVec3Tuple(objectPosition)) {
+          throw new Error(`Invalid sceneData.place[${placementIndex}].position: must be a numeric [x,y,z] tuple`);
+        }
+        if (objectRotation !== void 0 && !isVec3Tuple(objectRotation)) {
+          throw new Error(`Invalid sceneData.place[${placementIndex}].rotation: must be a numeric [x,y,z] tuple when provided`);
+        }
+        modelKey = objectModelKey.trim();
+        validatedKeyPath = `sceneData.place[${placementIndex}].modelKey`;
+        position = objectPosition;
+        rotation = objectRotation;
+      } else {
+        throw new Error(`Invalid sceneData.place[${placementIndex}]: expected an object placement or [modelKey, [x,y,z], [rotX?,rotY?,rotZ?]] tuple`);
+      }
       const buildId = modelMap[modelKey];
-      if (!buildId)
-        continue;
+      if (!buildId) {
+        throw new Error(`Invalid ${validatedKeyPath}: model key "${modelKey}" is not defined in sceneData.models`);
+      }
       const filePath = path.join(libraryPath, `${buildId}.json`);
       if (!fs.existsSync(filePath)) {
         throw new Error(`Build not found in library: ${buildId}`);
@@ -1670,7 +1754,7 @@ var RobloxStudioTools = class _RobloxStudioTools {
       const buildName = buildId.split("/").pop() || buildId;
       expandedBuilds.push({
         buildData,
-        position: position || [0, 0, 0],
+        position,
         rotation: rotation || [0, 0, 0],
         name: buildName
       });
@@ -1808,6 +1892,26 @@ var RobloxStudioTools = class _RobloxStudioTools {
       }]
     };
   }
+  async captureScreenshot() {
+    const response = await this.client.request("/api/capture-screenshot", {});
+    if (response.error) {
+      return {
+        content: [{
+          type: "text",
+          text: response.error
+        }]
+      };
+    }
+    const rgbaBuffer = Buffer.from(response.data, "base64");
+    const pngBuffer = rgbaToPng(rgbaBuffer, response.width, response.height);
+    return {
+      content: [{
+        type: "image",
+        data: pngBuffer.toString("base64"),
+        mimeType: "image/png"
+      }]
+    };
+  }
 };
 
 // ../../node_modules/@robloxstudio-mcp/core/dist/bridge-service.js
@@ -2092,6 +2196,8 @@ var RobloxStudioMCPServer = class {
             return await this.tools.insertAsset(args?.assetId, args?.parentPath, args?.position);
           case "preview_asset":
             return await this.tools.previewAsset(args?.assetId, args?.includeProperties, args?.maxDepth);
+          case "capture_screenshot":
+            return await this.tools.captureScreenshot();
           default:
             throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
         }
@@ -3177,7 +3283,10 @@ var TOOL_DEFINITIONS = [
           description: "Array of part arrays. Each: [posX, posY, posZ, sizeX, sizeY, sizeZ, rotX, rotY, rotZ, paletteKey, shape?, transparency?]. Shapes: Block (default), Wedge, Cylinder, Ball, CornerWedge.",
           items: {
             type: "array",
-            minItems: 10
+            minItems: 10,
+            items: {
+              anyOf: [{ type: "number" }, { type: "string" }]
+            }
           }
         },
         bounds: {
@@ -3353,8 +3462,53 @@ part(0,2,0,2,1,1,"b")`,
             },
             place: {
               type: "array",
-              description: "Array of placements: [modelKey, [x,y,z], [rotX?,rotY?,rotZ?]]",
-              items: { type: "array" }
+              description: "Array of placements. Preferred format: {modelKey, position:[x,y,z], rotation?:[x,y,z]}. Legacy tuple format [modelKey, [x,y,z], [rotX?,rotY?,rotZ?]] is also accepted.",
+              items: {
+                anyOf: [
+                  {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["modelKey", "position"],
+                    properties: {
+                      modelKey: {
+                        type: "string",
+                        minLength: 1
+                      },
+                      position: {
+                        type: "array",
+                        items: { type: "number" },
+                        minItems: 3,
+                        maxItems: 3
+                      },
+                      rotation: {
+                        type: "array",
+                        items: { type: "number" },
+                        minItems: 3,
+                        maxItems: 3
+                      }
+                    }
+                  },
+                  {
+                    type: "array",
+                    minItems: 2,
+                    maxItems: 3,
+                    items: {
+                      anyOf: [
+                        {
+                          type: "string",
+                          minLength: 1
+                        },
+                        {
+                          type: "array",
+                          items: { type: "number" },
+                          minItems: 3,
+                          maxItems: 3
+                        }
+                      ]
+                    }
+                  }
+                ]
+              }
             },
             custom: {
               type: "array",
@@ -3498,6 +3652,15 @@ part(0,2,0,2,1,1,"b")`,
       },
       required: ["assetId"]
     }
+  },
+  {
+    name: "capture_screenshot",
+    category: "read",
+    description: 'Capture a screenshot of the Roblox Studio viewport and return it as a PNG image. Requires EditableImage API to be enabled: Game Settings > Security > "Allow Mesh / Image APIs". Only works in Edit mode with the viewport visible.',
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
   }
 ];
 var getAllTools = () => [...TOOL_DEFINITIONS];

package/dist/install-plugin-cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+// src/install-plugin.ts
+import { createWriteStream, existsSync, mkdirSync, unlinkSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { get } from "https";
+var REPO = "boshyxd/robloxstudio-mcp";
+var ASSET_NAME = "MCPPlugin.rbxmx";
+var TIMEOUT_MS = 3e4;
+var MAX_REDIRECTS = 5;
+function getPluginsFolder() {
+  if (process.platform === "win32") {
+    return join(process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "Roblox", "Plugins");
+  }
+  return join(homedir(), "Documents", "Roblox", "Plugins");
+}
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const req = get(url, { headers: { "User-Agent": "robloxstudio-mcp" } }, resolve);
+    req.on("error", reject);
+    req.setTimeout(TIMEOUT_MS, () => {
+      req.destroy(new Error(`Request timed out after ${TIMEOUT_MS}ms`));
+    });
+  });
+}
+async function download(url, dest, redirects = 0) {
+  const res = await httpsGet(url);
+  if (res.statusCode === 301 || res.statusCode === 302) {
+    if (redirects >= MAX_REDIRECTS) throw new Error(`Too many redirects (max ${MAX_REDIRECTS})`);
+    const location = res.headers.location;
+    if (!location) throw new Error("Redirect with no location header");
+    return download(location, dest, redirects + 1);
+  }
+  if (res.statusCode !== 200) {
+    throw new Error(`Download failed: HTTP ${res.statusCode}`);
+  }
+  return new Promise((resolve, reject) => {
+    const file = createWriteStream(dest);
+    const cleanup = (err) => {
+      file.close(() => {
+        try {
+          unlinkSync(dest);
+        } catch {
+        }
+        reject(err);
+      });
+    };
+    res.pipe(file);
+    file.on("finish", () => {
+      file.close();
+      resolve();
+    });
+    file.on("error", cleanup);
+    res.on("error", cleanup);
+  });
+}
+async function installPlugin() {
+  const pluginsFolder = getPluginsFolder();
+  if (!existsSync(pluginsFolder)) {
+    mkdirSync(pluginsFolder, { recursive: true });
+  }
+  console.log("Fetching latest release...");
+  const res = await httpsGet(`https://api.github.com/repos/${REPO}/releases/latest`);
+  if (res.statusCode !== 200) {
+    throw new Error(`GitHub API returned HTTP ${res.statusCode}`);
+  }
+  const chunks = [];
+  for await (const chunk of res) {
+    chunks.push(chunk);
+  }
+  const release = JSON.parse(Buffer.concat(chunks).toString());
+  const asset = release.assets?.find((a) => a.name === ASSET_NAME);
+  if (!asset) {
+    throw new Error(`${ASSET_NAME} not found in release ${release.tag_name}`);
+  }
+  const dest = join(pluginsFolder, ASSET_NAME);
+  console.log(`Downloading ${ASSET_NAME} from ${release.tag_name}...`);
+  await download(asset.browser_download_url, dest);
+  console.log(`Installed to ${dest}`);
+}
+
+// src/install-plugin-cli.ts
+installPlugin().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "robloxstudio-mcp",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "MCP Server for Roblox Studio Integration - Access Studio data, scripts, and objects through AI tools",
   "main": "dist/index.js",
   "type": "module",
   "bin": {
-    "robloxstudio-mcp": "dist/index.js"
+    "robloxstudio-mcp": "dist/index.js",
+    "robloxstudio-mcp-install-plugin": "dist/install-plugin-cli.js"
   },
   "files": [
     "dist/**/*",