@chrrxs/robloxstudio-mcp-inspector 3.0.3 → 3.0.4

package/dist/index.js

@@ -1971,6 +1971,8 @@ var DUPLICATE_TAKEOVER_MS = 3e3;
 var INSTANCE_ALIAS_TTL_MS = 5 * 60 * 1e3;
 var ACCEPTED_REQUEST_TOMBSTONE_TTL_MS = 6e4;
 var MAX_ACCEPTED_REQUEST_TOMBSTONES = 4096;
+var CANCELLATION_TOMBSTONE_TTL_MS = 6e4;
+var MAX_CANCELLATION_TOMBSTONES = 4096;
 function publishedInstanceId(placeId) {
   if (placeId === void 0 || !Number.isFinite(placeId) || placeId <= 0)
     return void 0;
@@ -1979,6 +1981,7 @@ function publishedInstanceId(placeId) {
 var BridgeService = class {
   pendingRequests = /* @__PURE__ */ new Map();
   acceptedRequestIds = /* @__PURE__ */ new Map();
+  pendingCancellations = /* @__PURE__ */ new Map();
   // Keyed by pluginSessionId (the per-plugin GUID).
   instances = /* @__PURE__ */ new Map();
   instanceAliases = /* @__PURE__ */ new Map();
@@ -2037,6 +2040,21 @@ var BridgeService = class {
       }
     }
   }
+  notifyRequestCancelled(request, reason) {
+    const physicalSessionId = request.lastDeliveryPhysicalSessionId;
+    if (!physicalSessionId || this.pendingCancellations.has(request.id))
+      return;
+    const now = Date.now();
+    this.prunePendingCancellations(now);
+    this.pendingCancellations.set(request.id, {
+      requestId: request.id,
+      reason,
+      physicalSessionId,
+      createdAt: now
+    });
+    this.prunePendingCancellations(now);
+    this.notifyRequestAvailable(physicalSessionId);
+  }
   physicalSessionsForTarget(targetInstanceId, targetRole) {
     const physicalSessionIds = /* @__PURE__ */ new Set();
     for (const instance of this.instances.values()) {
@@ -2196,11 +2214,10 @@ var BridgeService = class {
     }
     for (const child of logicalChildren)
       this.unregisterInstance(child.pluginSessionId);
-    for (const [id, req] of this.pendingRequests.entries()) {
+    for (const req of Array.from(this.pendingRequests.values())) {
       const stillHasHandler = Array.from(this.instances.values()).some((i) => i.instanceId === req.targetInstanceId && i.role === req.targetRole);
       if (!stillHasHandler) {
-        clearTimeout(req.timeoutId);
-        this.pendingRequests.delete(id);
+        this.removePendingRequest(req);
         req.reject(new Error(`Target (${req.targetInstanceId}, ${req.targetRole}) disconnected`));
       }
     }
@@ -2390,16 +2407,21 @@ var BridgeService = class {
     const onlyInstanceId = distinctInstanceIds.values().next().value;
     return this.resolveTarget({ instance_id: onlyInstanceId, target });
   }
-  async sendRequest(endpoint, data, targetInstanceId, targetRole, timeoutMs = this.requestTimeout) {
+  async sendRequest(endpoint, data, targetInstanceId, targetRole, timeoutMs = this.requestTimeout, signal) {
     const requestId = randomUUID();
     const effectiveTimeoutMs = Math.max(1, timeoutMs);
+    if (signal?.aborted)
+      throw new Error("Request aborted");
     return new Promise((resolve5, reject) => {
-      const timeoutId = setTimeout(() => {
-        if (this.pendingRequests.has(requestId)) {
-          this.pendingRequests.delete(requestId);
-          reject(new Error("Request timeout"));
-        }
-      }, effectiveTimeoutMs);
+      const cancelPending = (reason, error) => {
+        const pending = this.pendingRequests.get(requestId);
+        if (!pending || !this.removePendingRequest(pending))
+          return;
+        this.notifyRequestCancelled(pending, reason);
+        pending.reject(error);
+      };
+      const timeoutId = setTimeout(() => cancelPending("timeout", new Error("Request timeout")), effectiveTimeoutMs);
+      const abortListener = () => cancelPending("aborted", new Error("Request aborted"));
       const request = {
         id: requestId,
         endpoint,
@@ -2410,14 +2432,31 @@ var BridgeService = class {
         resolve: resolve5,
         reject,
         timeoutId,
-        timeoutMs: effectiveTimeoutMs
+        timeoutMs: effectiveTimeoutMs,
+        abortSignal: signal,
+        abortListener
       };
       this.pendingRequests.set(requestId, request);
-      for (const physicalSessionId of this.physicalSessionsForTarget(targetInstanceId, targetRole)) {
-        this.notifyRequestAvailable(physicalSessionId);
+      signal?.addEventListener("abort", abortListener, { once: true });
+      if (signal?.aborted)
+        abortListener();
+      if (this.pendingRequests.has(requestId)) {
+        for (const physicalSessionId of this.physicalSessionsForTarget(targetInstanceId, targetRole)) {
+          this.notifyRequestAvailable(physicalSessionId);
+        }
       }
     });
   }
+  removePendingRequest(request) {
+    if (this.pendingRequests.get(request.id) !== request)
+      return false;
+    clearTimeout(request.timeoutId);
+    if (request.abortSignal && request.abortListener) {
+      request.abortSignal.removeEventListener("abort", request.abortListener);
+    }
+    this.pendingRequests.delete(request.id);
+    return true;
+  }
   claimNextRequestForPhysical(physicalSessionId, claimOwner) {
     let oldestRequest;
     let logicalSessionId = "";
@@ -2441,14 +2480,27 @@ var BridgeService = class {
     if (!oldestRequest)
       return null;
     oldestRequest.claimOwner = claimOwner;
+    oldestRequest.lastDeliveryPhysicalSessionId = physicalSessionId;
     return {
       requestId: oldestRequest.id,
       logicalSessionId,
       target: oldestRequest.targetRole,
       endpoint: oldestRequest.endpoint,
-      data: oldestRequest.data
+      data: oldestRequest.data,
+      remainingMs: Math.max(1, oldestRequest.timeoutMs - (Date.now() - oldestRequest.timestamp))
     };
   }
+  claimNextCancellationForPhysical(physicalSessionId, claimOwner) {
+    this.prunePendingCancellations(Date.now());
+    for (const cancellation of this.pendingCancellations.values()) {
+      if (cancellation.physicalSessionId !== physicalSessionId || cancellation.claimOwner !== void 0) {
+        continue;
+      }
+      cancellation.claimOwner = claimOwner;
+      return { requestId: cancellation.requestId, reason: cancellation.reason };
+    }
+    return null;
+  }
   releaseDeliveryClaims(claimOwner) {
     const physicalSessionIds = /* @__PURE__ */ new Set();
     for (const request of this.pendingRequests.values()) {
@@ -2459,6 +2511,12 @@ var BridgeService = class {
         physicalSessionIds.add(physicalSessionId);
       }
     }
+    for (const cancellation of this.pendingCancellations.values()) {
+      if (cancellation.claimOwner !== claimOwner)
+        continue;
+      cancellation.claimOwner = void 0;
+      physicalSessionIds.add(cancellation.physicalSessionId);
+    }
     for (const physicalSessionId of physicalSessionIds) {
       this.notifyRequestAvailable(physicalSessionId);
     }
@@ -2476,8 +2534,7 @@ var BridgeService = class {
     if (!request) {
       return this.acceptedRequestIds.has(requestId) ? "already_settled" : "unknown";
     }
-    clearTimeout(request.timeoutId);
-    this.pendingRequests.delete(requestId);
+    this.removePendingRequest(request);
     this.acceptedRequestIds.set(requestId, now);
     this.pruneAcceptedRequestIds(now);
     settle(request);
@@ -2496,22 +2553,34 @@ var BridgeService = class {
       this.acceptedRequestIds.delete(oldestRequestId);
     }
   }
+  prunePendingCancellations(now) {
+    for (const [requestId, cancellation] of this.pendingCancellations) {
+      if (now - cancellation.createdAt < CANCELLATION_TOMBSTONE_TTL_MS)
+        break;
+      this.pendingCancellations.delete(requestId);
+    }
+    while (this.pendingCancellations.size > MAX_CANCELLATION_TOMBSTONES) {
+      const oldestRequestId = this.pendingCancellations.keys().next().value;
+      if (oldestRequestId === void 0)
+        break;
+      this.pendingCancellations.delete(oldestRequestId);
+    }
+  }
   cleanupOldRequests() {
     const now = Date.now();
-    for (const [id, request] of this.pendingRequests.entries()) {
-      if (now - request.timestamp > request.timeoutMs) {
-        clearTimeout(request.timeoutId);
-        this.pendingRequests.delete(id);
+    for (const request of this.pendingRequests.values()) {
+      if (now - request.timestamp > request.timeoutMs && this.removePendingRequest(request)) {
+        this.notifyRequestCancelled(request, "timeout");
         request.reject(new Error("Request timeout"));
       }
     }
   }
   clearAllPendingRequests() {
-    for (const [, request] of this.pendingRequests.entries()) {
-      clearTimeout(request.timeoutId);
+    for (const request of Array.from(this.pendingRequests.values())) {
+      this.removePendingRequest(request);
       request.reject(new Error("Connection closed"));
     }
-    this.pendingRequests.clear();
+    this.pendingCancellations.clear();
   }
 };
 
@@ -5536,9 +5605,9 @@ function createToolServer(options) {
       inputSchema: fromJsonSchema(publicDefinition.inputSchema),
       ...publicDefinition.outputSchema ? { outputSchema: fromJsonSchema(publicDefinition.outputSchema) } : {},
       annotations: publicDefinition.annotations
-    }, async (args) => {
+    }, async (args, context) => {
       try {
-        const raw = await options.invoke(options.getTools(), definition.name, args);
+        const raw = await options.invoke(options.getTools(), definition.name, args, { signal: context.mcpReq.signal });
         return normalizeToolResult(raw, options.era);
       } catch (error) {
         return normalizeToolResult({
@@ -5723,6 +5792,13 @@ var SseStudioTransport = class {
           return;
       }
     }
+    while (!stream.closed && !stream.blocked) {
+      const cancellation = this.queue.claimNextCancellationForPhysical(stream.physicalSessionId, stream.claimOwner);
+      if (!cancellation)
+        break;
+      if (!this.write(stream, { kind: "cancel", ...cancellation }))
+        return;
+    }
     while (!stream.closed && !stream.blocked) {
       const request = this.queue.claimNextRequestForPhysical(stream.physicalSessionId, stream.claimOwner);
       if (!request)
@@ -5733,7 +5809,8 @@ var SseStudioTransport = class {
         logicalSessionId: request.logicalSessionId,
         target: request.target,
         endpoint: request.endpoint,
-        data: request.data === void 0 ? null : request.data
+        data: request.data === void 0 ? null : request.data,
+        remainingMs: request.remainingMs
       };
       if (!this.write(stream, event))
         return;
@@ -5834,7 +5911,7 @@ var TOOL_HANDLERS = {
   get_instance_properties: (tools, body) => tools.getInstanceProperties(body.instancePath, body.excludeSource, body.instance_id),
   get_project_structure: (tools, body) => tools.getProjectStructure(body.path, body.maxDepth, body.scriptsOnly, body.instance_id),
   set_properties: (tools, body) => tools.setProperties(body.instancePath, body.properties, body.instance_id),
-  grep_scripts: (tools, body) => tools.grepScripts(body.pattern, {
+  grep_scripts: (tools, body, context) => tools.grepScripts(body.pattern, {
     caseSensitive: body.caseSensitive,
     usePattern: body.usePattern,
     contextLines: body.contextLines,
@@ -5843,7 +5920,7 @@ var TOOL_HANDLERS = {
     filesOnly: body.filesOnly,
     path: body.path,
     classFilter: body.classFilter
-  }, body.instance_id),
+  }, body.instance_id, context?.signal),
   get_script_source: (tools, body) => {
     const { startLine, endLine } = optionalLineRange(body, "get_script_source");
     return tools.getScriptSource(body.instancePath, startLine, endLine, body.instance_id);
@@ -6273,30 +6350,45 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, security) {
     res.json({ success: true, disposition });
   });
   app.post("/proxy", async (req, res) => {
-    const { endpoint, data, targetInstanceId, targetRole, proxyInstanceId } = req.body;
+    const { endpoint, data, targetInstanceId, targetRole, proxyInstanceId, timeoutMs } = req.body;
     if (!endpoint || !targetInstanceId || !targetRole) {
       res.status(400).json({ error: "endpoint, targetInstanceId, and targetRole are required" });
       return;
     }
+    if (timeoutMs !== void 0 && (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 3e5)) {
+      res.status(400).json({ error: "timeoutMs must be an integer between 1 and 300000" });
+      return;
+    }
     if (proxyInstanceId) {
       proxyInstances.add(proxyInstanceId);
     }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    req.once("aborted", abort);
+    res.once("close", abort);
     try {
-      const response = await bridge.sendRequest(endpoint, data, targetInstanceId, targetRole);
+      const response = await bridge.sendRequest(endpoint, data, targetInstanceId, targetRole, timeoutMs, controller.signal);
       res.json({ response });
-    } catch (err2) {
-      res.status(500).json({ error: err2.message || "Proxy request failed" });
+    } catch (error) {
+      if (!res.headersSent && !res.destroyed) {
+        res.status(500).json({
+          error: error instanceof Error ? error.message : "Proxy request failed"
+        });
+      }
+    } finally {
+      req.removeListener("aborted", abort);
+      res.removeListener("close", abort);
     }
   });
   const mcpHandler = serverConfig ? createToolHttpHandler({
     config: serverConfig,
     getTools: () => tools,
     allowedTools,
-    invoke: async (currentTools, name, args) => {
+    invoke: async (currentTools, name, args, context) => {
       const handler = TOOL_HANDLERS[name];
       if (!handler)
         throw new Error(`Unknown tool: ${name}`);
-      return handler(currentTools, args);
+      return handler(currentTools, args, context);
     }
   }) : void 0;
   const nodeMcpHandler = mcpHandler ? toNodeHandler(mcpHandler) : void 0;
@@ -6341,25 +6433,21 @@ function createHttpServer(tools, bridge, allowedTools, serverConfig, security) {
   };
   return app;
 }
-function listenWithRetry(app, host, startPort, maxAttempts = 5) {
-  return new Promise(async (resolve5, reject) => {
-    for (let i = 0; i < maxAttempts; i++) {
-      const port = startPort + i;
-      try {
-        const server = await bindPort(app, host, port);
-        resolve5({ server, port });
-        return;
-      } catch (err2) {
-        if (err2.code === "EADDRINUSE") {
-          console.error(`Port ${port} in use, trying next...`);
-          continue;
-        }
-        reject(err2);
-        return;
+async function listenWithRetry(app, host, startPort, maxAttempts = 5) {
+  for (let i = 0; i < maxAttempts; i++) {
+    const port = startPort + i;
+    try {
+      const server = await bindPort(app, host, port);
+      return { server, port };
+    } catch (error) {
+      if (error !== null && typeof error === "object" && "code" in error && error.code === "EADDRINUSE") {
+        console.error(`Port ${port} in use, trying next...`);
+        continue;
       }
+      throw error;
     }
-    reject(new Error(`All ports ${startPort}-${startPort + maxAttempts - 1} are in use. Stop some MCP server instances and retry.`));
-  });
+  }
+  throw new Error(`All ports ${startPort}-${startPort + maxAttempts - 1} are in use. Stop some MCP server instances and retry.`);
 }
 function bindPort(app, host, port) {
   return new Promise((resolve5, reject) => {
@@ -6382,9 +6470,9 @@ var StudioHttpClient = class {
   constructor(bridge) {
     this.bridge = bridge;
   }
-  async request(endpoint, data, targetInstanceId, targetRole, timeoutMs) {
+  async request(endpoint, data, targetInstanceId, targetRole, timeoutMs, signal) {
     try {
-      const response = await this.bridge.sendRequest(endpoint, data, targetInstanceId, targetRole, timeoutMs);
+      const response = await this.bridge.sendRequest(endpoint, data, targetInstanceId, targetRole, timeoutMs, signal);
       return response;
     } catch (error) {
       if (error instanceof Error && error.message === "Request timeout") {
@@ -9199,6 +9287,8 @@ var MAX_SEARCH_ASSET_DESCRIPTION_LENGTH = 240;
 var ROBLOX_CREATOR_USER_ID = 1;
 var MAX_DEVICE_MATRIX_ENTRIES = 6;
 var MAX_NETWORK_PACKET_LOSS_PERCENT = 0.5;
+var GREP_SCRIPTS_TIMEOUT_MS = 12e4;
+var MAX_GREP_PATTERN_UTF8_BYTES = 4096;
 var STUDIO_ASSISTANT_SOURCE_IMAGE_LABEL = "Studio Assistant Source Image";
 var CREATOR_STORE_SEARCH_TYPES = /* @__PURE__ */ new Set([
   "Audio",
@@ -10025,7 +10115,7 @@ var RobloxStudioTools = class {
   // ambiguous, missing, or asks for fanout on a non-fanout-capable tool —
   // the MCP transport layer surfaces it as a structured error result so
   // the LLM can recover via the embedded data.instances list.
-  async _callSingle(endpoint, data, target, instance_id, timeoutMs) {
+  async _callSingle(endpoint, data, target, instance_id, timeoutMs, signal) {
     const r = this.bridge.resolveTarget({ instance_id, target });
     if (!r.ok)
       throw new RoutingFailure(r.error);
@@ -10039,7 +10129,10 @@ var RobloxStudioTools = class {
         }
       });
     }
-    return this.client.request(endpoint, data, r.targetInstanceId, r.targetRole, timeoutMs);
+    if (signal === void 0) {
+      return this.client.request(endpoint, data, r.targetInstanceId, r.targetRole, timeoutMs);
+    }
+    return this.client.request(endpoint, data, r.targetInstanceId, r.targetRole, timeoutMs, signal);
   }
   // Resolves which connected place a tool should target and whether a playtest
   // CLIENT peer is present on it. Used by capture/input to auto-route to the
@@ -10539,14 +10632,17 @@ var RobloxStudioTools = class {
       ]
     };
   }
-  async grepScripts(pattern, options, instance_id) {
+  async grepScripts(pattern, options, instance_id, signal) {
     if (!pattern) {
       throw new Error("Pattern is required for grep_scripts");
     }
+    if (Buffer.byteLength(pattern, "utf8") > MAX_GREP_PATTERN_UTF8_BYTES) {
+      throw new Error(`Pattern must not exceed ${MAX_GREP_PATTERN_UTF8_BYTES} UTF-8 bytes`);
+    }
     const response = await this._callSingle("/api/grep-scripts", {
       pattern,
       ...options ?? {}
-    }, void 0, instance_id);
+    }, void 0, instance_id, GREP_SCRIPTS_TIMEOUT_MS, signal);
     return {
       content: [
         {
@@ -12988,6 +13084,7 @@ var RobloxStudioTools = class {
 
 // ../core/dist/proxy-bridge-service.js
 import { randomUUID as randomUUID4 } from "crypto";
+var PROXY_RESPONSE_GRACE_MS = 5e3;
 var ProxyBridgeService = class _ProxyBridgeService extends BridgeService {
   primaryBaseUrl;
   authToken;
@@ -13063,9 +13160,20 @@ var ProxyBridgeService = class _ProxyBridgeService extends BridgeService {
       this.refreshTimer = void 0;
     }
   }
-  async sendRequest(endpoint, data, targetInstanceId, targetRole) {
+  async sendRequest(endpoint, data, targetInstanceId, targetRole, timeoutMs = this.proxyRequestTimeout, signal) {
+    if (signal?.aborted)
+      throw new Error("Request aborted");
     const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.proxyRequestTimeout);
+    const effectiveTimeoutMs = Math.max(1, timeoutMs);
+    let timedOut = false;
+    const abortFromCaller = () => controller.abort();
+    signal?.addEventListener("abort", abortFromCaller, { once: true });
+    if (signal?.aborted)
+      controller.abort();
+    const timeoutId = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, effectiveTimeoutMs + PROXY_RESPONSE_GRACE_MS);
     try {
       const response = await fetch(`${this.primaryBaseUrl}/proxy`, {
         method: "POST",
@@ -13075,26 +13183,34 @@ var ProxyBridgeService = class _ProxyBridgeService extends BridgeService {
           data,
           targetInstanceId,
           targetRole,
-          proxyInstanceId: this.proxyInstanceId
+          proxyInstanceId: this.proxyInstanceId,
+          timeoutMs: effectiveTimeoutMs
         }),
         signal: controller.signal
       });
-      clearTimeout(timeoutId);
       if (!response.ok) {
         const body = await response.text();
         throw new Error(`Proxy request failed (${response.status}): ${body}`);
       }
       const result = await response.json();
-      if (result.error) {
+      if (!result || typeof result !== "object" || Array.isArray(result)) {
+        throw new Error("Proxy returned an invalid response");
+      }
+      if ("error" in result && typeof result.error === "string" && result.error.length > 0) {
         throw new Error(result.error);
       }
-      return result.response;
-    } catch (err2) {
-      clearTimeout(timeoutId);
-      if (err2.name === "AbortError") {
+      return "response" in result ? result.response : void 0;
+    } catch (error) {
+      const isAbortError = error instanceof Error ? error.name === "AbortError" : !!error && typeof error === "object" && "name" in error && error.name === "AbortError";
+      if (isAbortError) {
+        if (!timedOut && signal?.aborted)
+          throw new Error("Request aborted");
         throw new Error("Proxy request timeout");
       }
-      throw err2;
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener("abort", abortFromCaller);
     }
   }
   cleanupOldRequests() {
@@ -13190,11 +13306,11 @@ var RobloxStudioMCPServer = class {
       getTools: () => this.tools,
       allowedTools: this.allowedToolNames,
       era: context.era,
-      invoke: async (tools, name, args) => {
+      invoke: async (tools, name, args, invocation) => {
         const handler = TOOL_HANDLERS[name];
         if (!handler)
           throw new Error(`Unknown tool: ${name}`);
-        return handler(tools, args);
+        return handler(tools, args, invocation);
       }
     }), { onerror: (error) => console.error("[mcp:stdio]", error) });
     console.error(`${this.config.name} v${this.config.version} running on stdio`);
@@ -13641,37 +13757,44 @@ var TOOL_DEFINITIONS = [
   {
     name: "grep_scripts",
     category: "read",
-    description: "Use to locate text or Lua pattern matches across script sources.",
+    description: "Use to search script sources.",
     inputSchema: {
       type: "object",
       properties: {
         pattern: {
           type: "string",
-          description: "Literal text, or a Lua pattern when usePattern is true."
+          maxLength: 4096,
+          description: "Literal or Lua pattern; max 4096 UTF-8 bytes."
         },
         caseSensitive: {
           type: "boolean",
-          description: "Literal match casing; patterns are always case-sensitive."
+          description: "Lua patterns are always case-sensitive."
         },
         usePattern: {
           type: "boolean",
-          description: "Use Lua patterns with top-level | alternation; not PCRE."
+          description: "Enable Lua pattern with top-level | (not PCRE)."
         },
         contextLines: {
-          type: "number",
-          description: "Lines before and after each match; defaults to 0."
+          type: "integer",
+          minimum: 0,
+          maximum: 100,
+          description: "Surrounding lines (0-100; default 0)."
         },
         maxResults: {
-          type: "number",
-          description: "Total match limit; defaults to 100."
+          type: "integer",
+          minimum: 1,
+          maximum: 1e4,
+          description: "Default 100."
         },
         maxResultsPerScript: {
-          type: "number",
-          description: "Match limit per script."
+          type: "integer",
+          minimum: 0,
+          maximum: 1e4,
+          description: "Per-script cap; 0 is unlimited."
         },
         filesOnly: {
           type: "boolean",
-          description: "Return only script paths; defaults to false."
+          description: "Paths only; default false."
         },
         path: {
           type: "string",

package/package.json

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