@chrrxs/robloxstudio-mcp-inspector 2.19.1 → 2.20.0

package/dist/index.js

@@ -196,6 +196,9 @@ var init_bridge_service = __esm({
         }
         return removed;
       }
+      async unregisterInstanceIdEverywhere(instanceId) {
+        return this.unregisterInstanceId(instanceId);
+      }
       getInstances() {
         return Array.from(this.instances.values());
       }
@@ -451,23 +454,202 @@ var init_bridge_service = __esm({
   }
 });
 
+// ../core/dist/roblox-docs.js
+function isDocCategory(value) {
+  return DOC_CATEGORIES.includes(value);
+}
+function cacheGet(key) {
+  const entry = cache.get(key);
+  if (!entry)
+    return void 0;
+  const ttl = entry.notFound ? NEGATIVE_CACHE_TTL_MS : CACHE_TTL_MS;
+  if (Date.now() - entry.fetchedAt > ttl) {
+    cache.delete(key);
+    return void 0;
+  }
+  return entry;
+}
+function cacheSet(key, entry) {
+  if (cache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== void 0)
+      cache.delete(oldest);
+  }
+  cache.set(key, entry);
+}
+function docUrl(category, name) {
+  return `${DOCS_BASE_URL}/${category}/${encodeURIComponent(name)}.md`;
+}
+async function fetchRobloxDoc(category, name) {
+  const key = `${category}/${name}`;
+  const cached = cacheGet(key);
+  if (cached) {
+    if (cached.notFound)
+      throw new DocNotFoundError(category, name);
+    return cached.content;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  let response;
+  try {
+    response = await fetch(docUrl(category, name), {
+      signal: controller.signal,
+      headers: { Accept: "text/markdown, text/plain" }
+    });
+  } catch (error) {
+    throw new Error(`Failed to fetch Roblox docs for ${key}: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    clearTimeout(timer);
+  }
+  if (response.status === 404) {
+    cacheSet(key, { fetchedAt: Date.now(), notFound: true });
+    throw new DocNotFoundError(category, name);
+  }
+  if (!response.ok) {
+    throw new Error(`Failed to fetch Roblox docs for ${key}: HTTP ${response.status}`);
+  }
+  const content = await response.text();
+  cacheSet(key, { fetchedAt: Date.now(), content });
+  return content;
+}
+function listSections(markdown) {
+  const sections = [];
+  for (const line of markdown.split("\n")) {
+    const match = line.match(/^##\s+(.+?)\s*$/);
+    if (match)
+      sections.push(match[1]);
+  }
+  return sections;
+}
+function extractSection(markdown, section) {
+  const lines = markdown.split("\n");
+  const wanted = section.trim().toLowerCase();
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^##\s+(.+?)\s*$/);
+    if (match && match[1].toLowerCase() === wanted) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1)
+    return void 0;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##?\s+/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n").trimEnd();
+}
+async function getRobloxDoc(category, name, section) {
+  const markdown = await fetchRobloxDoc(category, name);
+  const sections = listSections(markdown);
+  if (section) {
+    const extracted = extractSection(markdown, section);
+    if (extracted === void 0) {
+      throw new Error(`Section "${section}" not found in ${category}/${name}. Available sections: ${sections.join(", ") || "(none)"}`);
+    }
+    return { content: extracted, truncated: false, sections };
+  }
+  if (markdown.length > MAX_DOC_CHARS) {
+    const head = markdown.slice(0, MAX_DOC_CHARS);
+    const note = `
+
+---
+[Truncated at ${MAX_DOC_CHARS} of ${markdown.length} characters. Re-request with the "section" parameter to read one section in full. Available sections: ${sections.join(", ")}]`;
+    return { content: head + note, truncated: true, sections };
+  }
+  return { content: markdown, truncated: false, sections };
+}
+var DOC_CATEGORIES, DOCS_BASE_URL, FETCH_TIMEOUT_MS, CACHE_TTL_MS, NEGATIVE_CACHE_TTL_MS, MAX_CACHE_ENTRIES, MAX_DOC_CHARS, cache, DocNotFoundError;
+var init_roblox_docs = __esm({
+  "../core/dist/roblox-docs.js"() {
+    "use strict";
+    DOC_CATEGORIES = ["classes", "enums", "datatypes", "libraries", "globals"];
+    DOCS_BASE_URL = "https://create.roblox.com/docs/reference/engine";
+    FETCH_TIMEOUT_MS = 15e3;
+    CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+    NEGATIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
+    MAX_CACHE_ENTRIES = 200;
+    MAX_DOC_CHARS = 5e4;
+    cache = /* @__PURE__ */ new Map();
+    DocNotFoundError = class extends Error {
+      constructor(category, name) {
+        super(`No Roblox documentation found for ${category}/${name}. Names are case-sensitive PascalCase (e.g. "ProximityPrompt", "TweenService"). Valid categories: ${DOC_CATEGORIES.join(", ")}.`);
+        this.name = "DocNotFoundError";
+      }
+    };
+  }
+});
+
 // ../core/dist/mcp-compat.js
 import { ErrorCode, ListResourceTemplatesRequestSchema, ListResourcesRequestSchema, McpError, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
-function registerEmptyResourceShim(server) {
+function registerResourceHandlers(server) {
   server.registerCapabilities({ resources: {} });
   server.setRequestHandler(ListResourcesRequestSchema, async () => ({
     resources: []
   }));
   server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
-    resourceTemplates: []
+    resourceTemplates: [
+      {
+        uriTemplate: "robloxdocs://classes/{className}",
+        name: "Roblox class documentation",
+        description: "Official engine reference for a class (e.g. robloxdocs://classes/ProximityPrompt) \u2014 properties, methods, events, and usage guidance as markdown.",
+        mimeType: "text/markdown"
+      },
+      {
+        uriTemplate: "robloxdocs://enums/{enumName}",
+        name: "Roblox enum documentation",
+        description: "Official engine reference for an enum (e.g. robloxdocs://enums/KeyCode).",
+        mimeType: "text/markdown"
+      },
+      {
+        uriTemplate: "robloxdocs://datatypes/{dataTypeName}",
+        name: "Roblox datatype documentation",
+        description: "Official engine reference for a datatype (e.g. robloxdocs://datatypes/CFrame).",
+        mimeType: "text/markdown"
+      },
+      {
+        uriTemplate: "robloxdocs://libraries/{libraryName}",
+        name: "Roblox library documentation",
+        description: "Official engine reference for a Luau library (e.g. robloxdocs://libraries/table).",
+        mimeType: "text/markdown"
+      },
+      {
+        uriTemplate: "robloxdocs://globals/{globalsPage}",
+        name: "Roblox globals documentation",
+        description: "Official engine reference for global functions and variables (e.g. robloxdocs://globals/LuaGlobals, robloxdocs://globals/RobloxGlobals).",
+        mimeType: "text/markdown"
+      }
+    ]
   }));
   server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    throw new McpError(ErrorCode.InvalidParams, `Resource ${request.params.uri} not found`);
+    const uri = request.params.uri;
+    const match = uri.match(/^robloxdocs:\/\/([^/]+)\/([^/]+)$/);
+    if (!match || !isDocCategory(match[1])) {
+      throw new McpError(ErrorCode.InvalidParams, `Resource ${uri} not found`);
+    }
+    const [, category, rawName] = match;
+    const name = decodeURIComponent(rawName);
+    try {
+      const content = await fetchRobloxDoc(category, name);
+      return {
+        contents: [{ uri, mimeType: "text/markdown", text: content }]
+      };
+    } catch (error) {
+      if (error instanceof DocNotFoundError) {
+        throw new McpError(ErrorCode.InvalidParams, `Resource ${uri} not found. Names are case-sensitive PascalCase; valid categories: ${DOC_CATEGORIES.join(", ")}.`);
+      }
+      throw new McpError(ErrorCode.InternalError, `Failed to read ${uri}: ${error instanceof Error ? error.message : String(error)}`);
+    }
   });
 }
 var init_mcp_compat = __esm({
   "../core/dist/mcp-compat.js"() {
     "use strict";
+    init_roblox_docs();
   }
 });
 
@@ -658,6 +840,15 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
     }
     res.json({ success: true });
   });
+  app.post("/unregister-instance-id", (req, res) => {
+    const { instanceId } = req.body;
+    if (typeof instanceId !== "string" || instanceId.length === 0) {
+      res.status(400).json({ error: "instanceId is required" });
+      return;
+    }
+    const removed = bridge.unregisterInstanceId(instanceId);
+    res.json({ success: true, removed });
+  });
   app.get("/status", (req, res) => {
     const instances = bridge.getInstances();
     const publicInstances = instances.map(toPublic);
@@ -775,7 +966,7 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig) {
       try {
         trackMCPActivity();
         const server = new Server({ name: serverConfig.name, version: serverConfig.version }, { capabilities: { tools: {} } });
-        registerEmptyResourceShim(server);
+        registerResourceHandlers(server);
         server.setRequestHandler(ListToolsRequestSchema, async () => ({
           tools: filteredTools.map((t) => ({
             name: t.name,
@@ -918,6 +1109,7 @@ var init_http_server = __esm({
     init_bridge_service();
     init_mcp_compat();
     TOOL_HANDLERS = {
+      get_roblox_docs: (tools, body) => tools.getRobloxDocs(body.name, body.doc_type, body.section),
       get_file_tree: (tools, body) => tools.getFileTree(body.path, body.instance_id),
       search_files: (tools, body) => tools.searchFiles(body.query, body.searchType, body.instance_id),
       get_place_info: (tools, body) => tools.getPlaceInfo(body.instance_id),
@@ -4388,6 +4580,7 @@ var init_tools = __esm({
     init_roblox_cookie_client();
     init_studio_instance_manager();
     init_image_decode();
+    init_roblox_docs();
     init_jpeg_encoder();
     init_png_encoder();
     MAX_INLINE_IMAGE_BYTES = 6e6;
@@ -4459,6 +4652,17 @@ var init_tools = __esm({
       _textResult(body) {
         return { content: [{ type: "text", text: JSON.stringify(body) }] };
       }
+      async getRobloxDocs(name, docType, section) {
+        if (!name || typeof name !== "string") {
+          throw new Error('get_roblox_docs requires a name (e.g. "ProximityPrompt")');
+        }
+        const category = docType ?? "classes";
+        if (!isDocCategory(category)) {
+          throw new Error(`Invalid doc_type "${category}". Valid categories: ${DOC_CATEGORIES.join(", ")}`);
+        }
+        const result = await getRobloxDoc(category, name.trim(), section);
+        return { content: [{ type: "text", text: result.content }] };
+      }
       _parseTextResult(result) {
         const text = result?.content?.[0]?.text;
         if (typeof text !== "string")
@@ -6094,9 +6298,9 @@ ${code}`
           if (instance_id) {
             const managedClose = this.instanceManager.closeByInstanceId(instance_id);
             if (managedClose.status !== "not_found") {
-              this.bridge.unregisterInstanceId(instance_id);
+              await this.bridge.unregisterInstanceIdEverywhere(instance_id);
               await sleep(500);
-              this.bridge.unregisterInstanceId(instance_id);
+              await this.bridge.unregisterInstanceIdEverywhere(instance_id);
               return this._textResult({
                 instance_id,
                 message: managedClose.status === "already_closed" ? "Studio instance was already closed." : "Studio instance closed."
@@ -6119,7 +6323,7 @@ ${code}`
                 instance_id
               });
             }
-            this.bridge.unregisterInstanceId(instance_id);
+            await this.bridge.unregisterInstanceIdEverywhere(instance_id);
             return this._textResult({
               instance_id,
               message: "Studio instance closed."
@@ -6138,11 +6342,11 @@ ${code}`
             record2 = active[0];
           }
           if (record2.instanceId)
-            this.bridge.unregisterInstanceId(record2.instanceId);
+            await this.bridge.unregisterInstanceIdEverywhere(record2.instanceId);
           const closeResult = this.instanceManager.close(record2);
           if (record2.instanceId) {
             await sleep(500);
-            this.bridge.unregisterInstanceId(record2.instanceId);
+            await this.bridge.unregisterInstanceIdEverywhere(record2.instanceId);
           }
           return this._textResult({
             instance_id: record2.instanceId,
@@ -7930,6 +8134,24 @@ var init_proxy_bridge_service = __esm({
       getInstances() {
         return this.cachedInstances;
       }
+      async unregisterInstanceIdEverywhere(instanceId) {
+        const response = await fetch(`${this.primaryBaseUrl}/unregister-instance-id`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ instanceId })
+        });
+        if (!response.ok) {
+          const body = await response.text().catch(() => "");
+          throw new Error(`Proxy unregister failed (${response.status}): ${body || response.statusText}`);
+        }
+        const result = await response.json();
+        const removed = Array.isArray(result.removed) ? result.removed : [];
+        const removedKeys = new Set(removed.map((inst) => `${inst.instanceId}\0${inst.role}`));
+        if (removedKeys.size > 0) {
+          this.cachedInstances = this.cachedInstances.filter((inst) => !removedKeys.has(`${inst.instanceId}\0${inst.role}`));
+        }
+        return removed;
+      }
       /** Called when this proxy is being discarded (e.g. promotion to primary
           replaced it). Stops the background refresh so it doesn't leak. */
       stop() {
@@ -8012,7 +8234,7 @@ var init_server = __esm({
         });
         this.bridge = new BridgeService();
         this.tools = new RobloxStudioTools(this.bridge);
-        registerEmptyResourceShim(this.server);
+        registerResourceHandlers(this.server);
         this.setupToolHandlers();
       }
       setupToolHandlers() {
@@ -10758,6 +10980,31 @@ part(0,2,0,2,1,1,"b")`,
           },
           required: ["pattern", "replacement"]
         }
+      },
+      // === Documentation ===
+      {
+        name: "get_roblox_docs",
+        category: "read",
+        description: 'Fetch official Roblox engine API documentation as markdown from create.roblox.com. Call this BEFORE writing or editing code that uses an engine class, enum, datatype, or Luau library you are not fully certain about (e.g. ProximityPrompt, Enum.KeyCode, CFrame, TweenService) \u2014 the page includes the description, properties, methods, events, and code samples. Results are cached, so repeat lookups are cheap. Very large pages are truncated with a section index; pass section (e.g. "Properties", "Methods", "Events") to read one section in full.',
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: 'Exact PascalCase name of the class, enum, datatype, or library (e.g. "ProximityPrompt", "KeyCode", "CFrame", "table")'
+            },
+            doc_type: {
+              type: "string",
+              enum: ["classes", "enums", "datatypes", "libraries", "globals"],
+              description: "Documentation category (default: classes)"
+            },
+            section: {
+              type: "string",
+              description: 'Optional "##"-level section to return instead of the whole page (e.g. "Description", "Properties", "Methods", "Events", "Code Samples")'
+            }
+          },
+          required: ["name"]
+        }
       }
     ];
     DEPRECATED_TOOL_DEFINITIONS = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrrxs/robloxstudio-mcp-inspector",
-  "version": "2.19.1",
+  "version": "2.20.0",
   "description": "Read-only MCP server for inspecting and debugging Roblox Studio from AI coding tools",
   "main": "dist/index.js",
   "type": "module",

package/studio-plugin/MCPInspectorPlugin.rbxmx

@@ -1413,9 +1413,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.19.1" is replaced with the package version at package time
+	-- "2.20.0" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.19.1`
+	return `{tostring(h)}-2.20.0`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10745,7 +10745,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.19.1"
+local CURRENT_VERSION = "2.20.0"
 local PLUGIN_VARIANT = "inspector"
 local BASE_PORT = 58741
 local function createConnection(port)

package/studio-plugin/MCPPlugin.rbxmx

@@ -1413,9 +1413,9 @@ local function computeBridgeStamp()
 	for i = 1, #combined do
 		h = (h * 33 + (string.byte(combined, i))) % 2147483647
 	end
-	-- "2.19.1" is replaced with the package version at package time
+	-- "2.20.0" is replaced with the package version at package time
 	-- (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
-	return `{tostring(h)}-2.19.1`
+	return `{tostring(h)}-2.20.0`
 end
 local BRIDGE_STAMP = computeBridgeStamp()
 local function setSource(scriptInst, source)
@@ -10745,7 +10745,7 @@ return {
         <Properties>
           <string name="Name">State</string>
           <string name="Source"><![CDATA[-- Compiled with roblox-ts v3.0.0
-local CURRENT_VERSION = "2.19.1"
+local CURRENT_VERSION = "2.20.0"
 local PLUGIN_VARIANT = "main"
 local BASE_PORT = 58741
 local function createConnection(port)