conduit-mcp 2.0.3 → 2.1.0

package/dist/{chunk-HI6KFLGA.js → chunk-VTWABOF4.js}

@@ -224,7 +224,21 @@ var Bridge = class extends EventEmitter {
       }, REQUEST_TIMEOUT_MS);
       this.pendingRequests.set(id, { resolve, reject, timer });
       if (studio) {
-        studio.ws.send(json);
+        studio.ws.send(json, (err) => {
+          if (err) {
+            clearTimeout(timer);
+            this.pendingRequests.delete(id);
+            log.warn(
+              `WebSocket send failed for studio "${this.activeStudioId}": ${err.message}`
+            );
+            this.evictStaleStudio(this.activeStudioId);
+            reject(
+              new Error(
+                `Failed to send to Roblox Studio: ${err.message}. The plugin connection may have dropped \u2014 it should auto-reconnect shortly. Please retry.`
+              )
+            );
+          }
+        });
       } else {
         const studioId = this.activeStudioId ?? "_default";
         const queue = this.httpPendingCommands.get(studioId) ?? [];
@@ -241,13 +255,51 @@ var Bridge = class extends EventEmitter {
     }
     return void 0;
   }
+  isStudioAlive(studioId, studio) {
+    if (studio.ws.readyState !== WebSocket.OPEN) return false;
+    const lastBeat = this.lastHeartbeats.get(studioId);
+    if (lastBeat !== void 0 && Date.now() - lastBeat > HEARTBEAT_TIMEOUT_MS) {
+      log.warn(
+        `Studio "${studioId}" has stale heartbeat (${Math.round((Date.now() - lastBeat) / 1e3)}s ago) \u2014 evicting`
+      );
+      this.evictStaleStudio(studioId);
+      return false;
+    }
+    return true;
+  }
+  evictStaleStudio(studioId) {
+    const studio = this.studios.get(studioId);
+    if (studio) {
+      studio.ws.terminate();
+      this.studios.delete(studioId);
+      this.lastHeartbeats.delete(studioId);
+      this.emit("studio-disconnected", studio.info);
+      log.info(`Evicted stale studio: ${studioId}`);
+    }
+    if (this.activeStudioId === studioId) {
+      for (const [id, s] of this.studios) {
+        if (s.ws.readyState === WebSocket.OPEN) {
+          this.activeStudioId = id;
+          log.info(`Auto-switched active studio to: ${id}`);
+          return;
+        }
+      }
+      this.activeStudioId = null;
+    }
+    if (this.studios.size === 0) {
+      this.stopHeartbeatMonitor();
+      this.stopPingInterval();
+    }
+  }
   resolveTargetStudio() {
-    const active = this.getActiveStudio();
-    if (active && active.ws.readyState === WebSocket.OPEN) {
-      return active;
+    if (this.activeStudioId) {
+      const active = this.studios.get(this.activeStudioId);
+      if (active && this.isStudioAlive(this.activeStudioId, active)) {
+        return active;
+      }
     }
     for (const [studioId, studio] of this.studios) {
-      if (studio.ws.readyState === WebSocket.OPEN) {
+      if (this.isStudioAlive(studioId, studio)) {
         this.activeStudioId = studioId;
         log.info(`Auto-selected active studio: ${studioId}`);
         return studio;
@@ -325,7 +377,7 @@ var Bridge = class extends EventEmitter {
     ws.on("pong", () => {
       ws.isAlive = true;
     });
-    if (this.activeStudioId === null) {
+    if (this.activeStudioId === null || this.activeStudioId === studioId) {
       this.activeStudioId = studioId;
     }
     this.emit("studio-connected", info);
@@ -792,10 +844,13 @@ function register(server, bridge) {
     "get_info",
     {
       title: "Get Instance Info",
-      description: "Get detailed information about a single instance: class, parent, children count, properties, attributes, tags, and optionally a typed property list \u2014 all in one call.",
+      description: "Get detailed information about a single instance: class, parent, children count, properties, attributes, tags, and optionally a typed property list \u2014 all in one call.\n\nUse this to inspect runtime UI layout (Size, Position, Transparency, Visible, Text, etc.), part properties, lighting, sounds, and more. Reads ~60 common properties automatically. Use `propertyNames` to request only specific properties for a leaner response.\n\nFor UI debugging: check BackgroundTransparency, Visible, Size, Position, AnchorPoint, ZIndex, LayoutOrder on GuiObjects.",
       inputSchema: z.object({
         path: z.string().describe("Path to the instance, e.g. 'game.Workspace.Part'"),
-        includeProperties: z.boolean().default(true).describe("Include property values"),
+        includeProperties: z.boolean().default(true).describe("Include property values (reads ~60 common properties)"),
+        propertyNames: z.array(z.string()).optional().describe(
+          "Request only these specific properties by name, e.g. ['Size', 'Position', 'Transparency']. When set, only these properties are returned (much leaner than the full property dump)."
+        ),
         includeAttributes: z.boolean().default(true).describe("Include custom attributes"),
         includeTags: z.boolean().default(true).describe("Include CollectionService tags"),
         includePropertyList: z.boolean().default(false).describe("Include a typed list of all discoverable properties with types and values"),
@@ -813,6 +868,7 @@ function register(server, bridge) {
       const result = await bridge.send("get_info", {
         path: params.path,
         includeProperties: params.includeProperties,
+        propertyNames: params.propertyNames,
         includeAttributes: params.includeAttributes,
         includeTags: params.includeTags,
         includePropertyList: params.includePropertyList,
@@ -1135,13 +1191,16 @@ function registerReadScript(server, bridge) {
     "read_script",
     {
       title: "Read Script Source",
-      description: "Read the Lua source code of a script instance. Optionally restrict to a line range.",
+      description: "Read the Lua source code of a script instance. Optionally restrict to a line range. Use outline=true to get just function signatures and top-level declarations with line numbers \u2014 much cheaper than reading the full source for large scripts.",
       inputSchema: z3.object({
         path: z3.string().describe("Path to the script instance"),
+        outline: z3.boolean().default(false).describe(
+          "If true, return only a structural outline (function signatures, top-level locals, types, return) with line numbers instead of full source. Ideal for navigating large scripts."
+        ),
         lineRange: z3.object({
           start: z3.number().int().min(1).describe("Start line (1-based)"),
           end: z3.number().int().min(1).describe("End line (1-based, inclusive)")
-        }).optional().describe("Optional line range to read"),
+        }).optional().describe("Optional line range to read (ignored when outline=true)"),
         maxTokens: z3.number().optional().describe("Maximum token budget for the response")
       }),
       annotations: {
@@ -1152,6 +1211,28 @@ function registerReadScript(server, bridge) {
       }
     },
     async (params) => {
+      if (params.outline) {
+        const result2 = await bridge.send("outline_script", {
+          path: params.path
+        });
+        const lines = [
+          `### Outline: \`${result2.path}\` (${result2.totalLines} lines)`,
+          ""
+        ];
+        for (const entry of result2.outline) {
+          const pad = " ".repeat(entry.indent);
+          lines.push(`${entry.line}: ${pad}${entry.text}`);
+        }
+        if (result2.outline.length === 0) {
+          lines.push("*No functions, type definitions, or top-level declarations found.*");
+        }
+        const text2 = lines.join("\n");
+        return {
+          content: [
+            { type: "text", text: applyTokenBudget(text2, params.maxTokens) }
+          ]
+        };
+      }
       if (params.lineRange && params.lineRange.end < params.lineRange.start) {
         return {
           content: [{ type: "text", text: "lineRange.end must be >= lineRange.start." }],
@@ -1176,10 +1257,10 @@ function registerWriteTools(server, bridge) {
     "edit_script",
     {
       title: "Edit Script Source",
-      description: "Edit the Lua source code of a script. Supports four modes: 'full' replaces the entire source, 'range' replaces specific line/column ranges, 'find_replace' does text find-and-replace on one script, and 'multi_replace' does find-and-replace across multiple scripts in one undoable operation.",
+      description: "Edit the Lua source code of a script. Supports five modes:\n- 'full': Replace entire source.\n- 'range': Replace specific line/column ranges.\n- 'find_replace': Text find-and-replace on one script.\n- 'multi_replace': Same find-and-replace across multiple scripts.\n- 'batch': Different find-and-replace edits across different scripts in one atomic operation. Use this when you need different changes in different scripts.\n\nTip: Wrap multiple edits in a transaction (begin/commit) to group them into a single Ctrl+Z undo point.",
       inputSchema: z3.object({
-        path: z3.string().describe("Path to the script instance"),
-        mode: z3.enum(["full", "range", "find_replace", "multi_replace"]).describe("Edit mode: full, range, find_replace, or multi_replace"),
+        path: z3.string().optional().describe("Path to the script instance (not needed for 'multi_replace' or 'batch' modes)"),
+        mode: z3.enum(["full", "range", "find_replace", "multi_replace", "batch"]).describe("Edit mode"),
         source: z3.string().optional().describe("Complete new source (for 'full' mode)"),
         edits: z3.array(
           z3.object({
@@ -1193,7 +1274,17 @@ function registerWriteTools(server, bridge) {
         find: z3.string().optional().describe("Text or pattern to find (for 'find_replace' mode)"),
         replace: z3.string().optional().describe("Replacement text (for 'find_replace' mode)"),
         regex: z3.boolean().optional().describe("Treat 'find' as a Lua pattern (for 'find_replace' and 'multi_replace' modes)"),
-        scripts: z3.array(z3.string()).optional().describe("Array of script paths to apply find/replace across (for 'multi_replace' mode)")
+        scripts: z3.array(z3.string()).optional().describe("Array of script paths to apply find/replace across (for 'multi_replace' mode)"),
+        batch: z3.array(
+          z3.object({
+            path: z3.string().describe("Script path"),
+            find: z3.string().describe("Text or pattern to find"),
+            replace: z3.string().default("").describe("Replacement text"),
+            regex: z3.boolean().default(false).describe("Treat find as a Lua pattern")
+          })
+        ).optional().describe(
+          "Array of per-script find/replace operations (for 'batch' mode). Each entry targets a different script with its own find/replace pair."
+        )
       }),
       annotations: {
         readOnlyHint: false,
@@ -1255,6 +1346,33 @@ function registerWriteTools(server, bridge) {
         }
         return { content: [{ type: "text", text: lines.join("\n") }] };
       }
+      if (params.mode === "batch") {
+        if (!params.batch || params.batch.length === 0) {
+          return {
+            content: [{ type: "text", text: "batch mode requires a non-empty `batch` array." }],
+            isError: true
+          };
+        }
+        const result2 = await bridge.send("batch_edit_scripts", {
+          edits: params.batch
+        });
+        const lines = [
+          `**Batch edit** \u2014 ${result2.scriptsModified} script(s) modified`,
+          ""
+        ];
+        for (const r of result2.results) {
+          if (r.success) {
+            lines.push(`- \`${r.path}\`: ${r.replacements ?? 0} replacement(s)`);
+          }
+        }
+        if (result2.errors && result2.errors.length > 0) {
+          lines.push("", "**Errors:**");
+          for (const e of result2.errors) {
+            lines.push(`- \`${e.path}\`: ${e.error}`);
+          }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      }
       const result = await bridge.send("edit_script", {
         path: params.path,
         mode: params.mode,
@@ -1327,9 +1445,9 @@ function register4(server, bridge) {
     "playtest",
     {
       title: "Playtest Control & Virtual Input",
-      description: "Control Roblox Studio playtesting and simulate user input.\n\nActions:\n- `start`: Begin a playtest session. Defaults to Play mode (F5, full client with player character). Set mode='run' for Run mode (F8, server-only, no player).\n- `stop`: End the current playtest.\n- `execute`: Run Lua code in the running game context.\n- `get_output`: Get console/log output from Studio (works in edit mode and during playtest).\n- `inspect`: Evaluate a Luau expression and return the typed result (requires active playtest).\n- `navigate`: Walk the player character to a position using PathfindingService (requires client playtest).\n- `mouse_click`: Simulate a mouse click at screen coordinates.\n- `mouse_move`: Move the virtual mouse to screen coordinates.\n- `key_press`: Press and release a key.\n- `key_down`: Hold a key down.\n- `key_up`: Release a held key.",
+      description: "Control Roblox Studio playtesting and simulate user input.\n\nActions:\n- `start`: Begin a playtest session. Defaults to Play mode (F5, full client with player character). Set mode='run' for Run mode (F8, server-only, no player).\n- `stop`: End the current playtest.\n- `execute`: Run Lua code in the running game context.\n- `get_output`: Get console/log output from Studio (works in edit mode and during playtest).\n- `inspect`: Evaluate a Luau expression and return the typed result (requires active playtest).\n- `navigate`: Walk the player character to a position using PathfindingService (requires client playtest).\n- `mouse_click`: Simulate a mouse click at screen coordinates.\n- `mouse_move`: Move the virtual mouse to screen coordinates.\n- `key_press`: Press and release a key.\n- `key_down`: Hold a key down.\n- `key_up`: Release a held key.\n- `screenshot`: Capture the viewport during playtest. Useful for seeing the game state visually.",
       inputSchema: z4.object({
-        action: z4.enum(["start", "stop", "execute", "get_output", "inspect", "navigate", "mouse_click", "mouse_move", "key_press", "key_down", "key_up"]).describe("Playtest action"),
+        action: z4.enum(["start", "stop", "execute", "get_output", "inspect", "navigate", "mouse_click", "mouse_move", "key_press", "key_down", "key_up", "screenshot"]).describe("Playtest action"),
         mode: z4.enum(["play", "run"]).default("play").describe("Playtest mode: 'play' (F5, full client with player) or 'run' (F8, server-only). Default: play"),
         code: z4.string().optional().describe("Lua code to execute (for 'execute' action)"),
         // get_output params
@@ -1413,6 +1531,25 @@ ${logText}
 ${result2.message}` : ""}`;
         return { content: [{ type: "text", text: text2 }] };
       }
+      if (params.action === "screenshot") {
+        const result2 = await bridge.send("screenshot", {});
+        if (result2.imageBase64 && result2.mimeType) {
+          return {
+            content: [
+              {
+                type: "image",
+                data: result2.imageBase64,
+                mimeType: result2.mimeType
+              }
+            ]
+          };
+        }
+        return {
+          content: [
+            { type: "text", text: `Playtest screenshot: ${result2.message ?? result2.status}` }
+          ]
+        };
+      }
       if (params.action === "mouse_click" || params.action === "mouse_move" || params.action === "key_press" || params.action === "key_down" || params.action === "key_up") {
         if ((params.action === "mouse_click" || params.action === "mouse_move") && (params.x === void 0 || params.y === void 0)) {
           return {
@@ -1903,7 +2040,7 @@ function register7(server, bridge) {
     "screenshot",
     {
       title: "Take Screenshot",
-      description: "Capture a screenshot of the current Roblox Studio viewport. Returns base64 image data when available for vision model consumption.",
+      description: "Capture a screenshot of the current Roblox Studio viewport. Works in both edit mode and during playtest.\n\nThe screenshot is saved to the user's Roblox screenshots folder. Base64 image data is returned when the EditableImage API is available (Roblox platform limitation).\n\nTip: During playtest, use this to capture the game viewport. Combine with `playtest start` + a short delay via `playtest execute` (e.g. `task.wait(2)`) to capture after the game loads.",
       inputSchema: z7.object({}),
       annotations: {
         readOnlyHint: true,
@@ -1962,7 +2099,7 @@ function register7(server, bridge) {
     "transaction",
     {
       title: "Transaction Control",
-      description: "Group multiple mutating tool calls into a single Ctrl+Z undo point.\n\nUsage: ALWAYS call `begin` first, then make your changes, then call `commit` or `rollback`. Calling `commit` or `rollback` without a prior `begin` will error.\n\nActions:\n- `begin`: Start a transaction. All subsequent writes share one undo recording.\n- `commit`: Finish an open transaction and commit all changes as one undo point. Requires a prior `begin`.\n- `rollback`: Cancel an open transaction and undo all changes made since begin. Requires a prior `begin`.\n\nTransactions auto-rollback after 60 seconds if not committed.",
+      description: "Group multiple tool calls into a single Ctrl+Z undo point \u2014 essential when making several related edits that the user should be able to revert together.\n\n**When to use:** Before starting a multi-edit session (e.g. refactoring across scripts, creating multiple instances, UI changes). Call `begin`, make all your changes, then `commit`. The user can undo everything in one Ctrl+Z.\n\nActions:\n- `begin`: Start a transaction. All subsequent writes share one undo recording.\n- `commit`: Finish and commit all changes as one undo point.\n- `rollback`: Cancel and revert all changes since begin.\n\nTransactions auto-rollback after 60 seconds if not committed.",
       inputSchema: z7.object({
         action: z7.enum(["begin", "commit", "rollback"]).describe("Transaction action"),
         name: z7.string().optional().describe("Transaction name for the undo history (for 'begin' action)")
@@ -2376,4 +2513,4 @@ async function startServer(port = 3200, options = {}) {
 export {
   startServer
 };
-//# sourceMappingURL=chunk-HI6KFLGA.js.map
+//# sourceMappingURL=chunk-VTWABOF4.js.map