Improve MCP debug tools based on real-world agent feedback

1. capture_at_breakpoint: add trigger_url parameter so the tool can
   fire the HTTP request itself after arming the breakpoint, avoiding
   the blocking coordination problem with LLM tool-calling.

2. set_breakpoints: surface warnings when a path cannot be round-trip
   mapped back to a local file. Set verified=false for unmapped paths
   instead of silently accepting them.

3. Tool descriptions: steer toward the non-blocking workflow
   (set_breakpoints → trigger → list_sessions → inspect) rather than
   leading with blocking tools.

4. list_sessions: include active breakpoints with resolved server
   paths so agents can inspect what's armed on the server.

5. start_session: return cartridge_mappings (name → local path) so
   agents can verify cartridge discovery and path mapping.

Author: clavery

packages/b2c-dx-mcp/src/tools/diagnostics/debug-capture-at-breakpoint.ts

@@ -28,6 +28,7 @@ interface CaptureInput {
   expressions?: string[];
   timeout_ms?: number;
   auto_continue?: boolean;
+  trigger_url?: string;
 }
 
 interface CaptureOutput {
@@ -58,6 +59,7 @@ interface CaptureOutput {
     result: string;
   }>;
   auto_continued: boolean;
+  trigger_status?: number;
 }
 
 export function createDebugCaptureAtBreakpointTool(
@@ -68,10 +70,10 @@ export function createDebugCaptureAtBreakpointTool(
     {
       name: 'debug_capture_at_breakpoint',
       description:
-        'Set a breakpoint, wait for it to be hit, and capture a diagnostic snapshot (stack, variables, expression results). ' +
-        'IMPORTANT: This tool BLOCKS until the breakpoint is hit or the timeout expires — the user or an external process must trigger a request on the instance while this tool is waiting. ' +
-        'Optionally resumes the thread after capture. ' +
-        'Combines debug_set_breakpoints, debug_wait_for_stop, debug_get_stack, debug_get_variables, and debug_evaluate in a single call.',
+        'Set a breakpoint, optionally trigger an HTTP request, wait for the breakpoint to be hit, and capture a diagnostic snapshot (stack, variables, expression results). ' +
+        'Use trigger_url to have the tool fire the request itself (recommended) — this avoids needing to coordinate a separate request while the tool blocks. ' +
+        'Without trigger_url, the tool BLOCKS until the breakpoint is hit or timeout expires and requires the user to trigger a request externally. ' +
+        'For more control, use the non-blocking workflow: debug_set_breakpoints → trigger request → debug_list_sessions (check halted_threads) → debug_get_variables.',
       toolsets: ['CARTRIDGES', 'SCAPI', 'STOREFRONTNEXT'],
       inputSchema: {
         session_id: z.string().describe('Session ID returned by debug_start_session.'),
@@ -92,6 +94,13 @@ export function createDebugCaptureAtBreakpointTool(
           .boolean()
           .optional()
           .describe('If true, resume the thread after capturing the snapshot. Defaults to false.'),
+        trigger_url: z
+          .string()
+          .optional()
+          .describe(
+            'URL to request after arming the breakpoint. The tool fires this HTTP GET in the background, then waits for the breakpoint to halt. ' +
+              'This is the recommended approach — it avoids needing to coordinate a separate request while the tool blocks.',
+          ),
       },
       async execute(args, context) {
         const registry = context.serverContext?.debugSessions;
@@ -104,7 +113,6 @@ export function createDebugCaptureAtBreakpointTool(
 
         const scriptPath = resolveBreakpointPath(args.file, entry.sourceMapper, entry.cartridges);
 
-        // Set breakpoint (adds to existing)
         const bpInput: BreakpointInput = {
           script_path: scriptPath,
           line_number: args.line,
@@ -126,6 +134,14 @@ export function createDebugCaptureAtBreakpointTool(
           script_path: scriptPath,
         };
 
+        // Fire trigger URL in the background (it will hang when the breakpoint halts the thread)
+        let triggerPromise: Promise<number | undefined> | undefined;
+        if (args.trigger_url) {
+          triggerPromise = fetch(args.trigger_url, {redirect: 'follow'})
+            .then((r) => r.status)
+            .catch((): undefined => undefined);
+        }
+
         // Wait for halt
         const haltedThread = entry.manager.getKnownThreads().find((t) => t.status === 'halted');
         let thread: null | SdapiScriptThread = haltedThread ?? null;
@@ -150,7 +166,6 @@ export function createDebugCaptureAtBreakpointTool(
           };
         }
 
-        // Capture stack
         const threadDetail = await entry.manager.client.getThread(thread.id);
         const stack = threadDetail.call_stack.map((frame) => ({
           index: frame.index,
@@ -160,7 +175,6 @@ export function createDebugCaptureAtBreakpointTool(
           script_path: frame.location.script_path,
         }));
 
-        // Capture variables (top frame)
         const varsResult = await entry.manager.client.getVariables(thread.id, 0);
         const variables = varsResult.object_members.map((m) => ({
           name: m.name,
@@ -170,7 +184,6 @@ export function createDebugCaptureAtBreakpointTool(
           has_children: !PRIMITIVE_TYPES.has(m.type),
         }));
 
-        // Evaluate expressions (sequential — each must complete before the next on the debugger)
         const evaluations: Array<{expression: string; result: string}> = [];
         if (args.expressions) {
           for (const expr of args.expressions) {
@@ -187,13 +200,14 @@ export function createDebugCaptureAtBreakpointTool(
           }
         }
 
-        // Optionally continue
         let autoContinued = false;
         if (args.auto_continue) {
           await entry.manager.resume(thread.id);
           autoContinued = true;
         }
 
+        const triggerStatus = triggerPromise ? await triggerPromise : undefined;
+
         return {
           breakpoint: breakpointInfo,
           halted: true,
@@ -202,6 +216,7 @@ export function createDebugCaptureAtBreakpointTool(
           variables,
           evaluations: evaluations.length > 0 ? evaluations : undefined,
           auto_continued: autoContinued,
+          trigger_status: triggerStatus,
         };
       },
       formatOutput: (output) => jsonResult(output),

packages/b2c-dx-mcp/src/tools/diagnostics/debug-list-sessions.ts

@@ -15,6 +15,12 @@ interface ListSessionsOutput {
     hostname: string;
     client_id: string;
     halted_threads: number[];
+    breakpoints: Array<{
+      id: number;
+      file: null | string;
+      line: number;
+      script_path: string;
+    }>;
     created_at: string;
     last_activity_at: string;
   }>;
@@ -28,9 +34,9 @@ export function createDebugListSessionsTool(
     {
       name: 'debug_list_sessions',
       description:
-        'List all active script debugger sessions. ' +
-        'Returns session IDs, connected hostnames, and any currently halted threads. ' +
-        'Use this to discover existing sessions before creating a new one.',
+        'List all active script debugger sessions with their breakpoints and halted threads. ' +
+        'Use this to check session state: whether breakpoints are armed, which threads are halted, and whether you need to call debug_get_variables or debug_continue. ' +
+        'This is the recommended way to poll for halted threads in the non-blocking debug workflow.',
       toolsets: ['CARTRIDGES', 'SCAPI', 'STOREFRONTNEXT'],
       inputSchema: {},
       async execute(_args, context) {
@@ -49,6 +55,12 @@ export function createDebugListSessionsTool(
               .getKnownThreads()
               .filter((t) => t.status === 'halted')
               .map((t) => t.id),
+            breakpoints: entry.breakpoints.map((bp) => ({
+              id: bp.id,
+              file: entry.sourceMapper.toLocalPath(bp.script_path) ?? null,
+              line: bp.line_number,
+              script_path: bp.script_path,
+            })),
             created_at: new Date(entry.createdAt).toISOString(),
             last_activity_at: new Date(entry.lastActivityAt).toISOString(),
           })),

packages/b2c-dx-mcp/src/tools/diagnostics/debug-set-breakpoints.ts

@@ -16,15 +16,18 @@ interface SetBreakpointsInput {
   breakpoints: Array<{file: string; line: number; condition?: string}>;
 }
 
+interface BreakpointResult {
+  id: number;
+  file: null | string;
+  line: number;
+  script_path: string;
+  verified: boolean;
+  condition?: string;
+}
+
 interface SetBreakpointsOutput {
-  breakpoints: Array<{
-    id: number;
-    file: null | string;
-    line: number;
-    script_path: string;
-    verified: boolean;
-    condition?: string;
-  }>;
+  breakpoints: BreakpointResult[];
+  warnings?: string[];
 }
 
 export function createDebugSetBreakpointsTool(
@@ -36,8 +39,8 @@ export function createDebugSetBreakpointsTool(
       name: 'debug_set_breakpoints',
       description:
         'Set breakpoints in a debug session. Replaces all previously set breakpoints. ' +
-        'Accepts local file paths which are mapped to server script paths via cartridge mappings. ' +
-        'You can also pass server paths directly (starting with /).',
+        'Accepts local file paths (mapped to server paths via cartridge discovery), cartridge-prefixed paths (e.g. app_storefront/cartridge/controllers/Cart.js), or server paths starting with /. ' +
+        'Check the "verified" field and "warnings" in the response — if a path could not be mapped to a known cartridge, it will be flagged.',
       toolsets: ['CARTRIDGES', 'SCAPI', 'STOREFRONTNEXT'],
       inputSchema: {
         session_id: z.string().describe('Session ID returned by debug_start_session.'),
@@ -65,12 +68,23 @@ export function createDebugSetBreakpointsTool(
         }
 
         const entry = registry.getSessionOrThrow(args.session_id);
+        const warnings: string[] = [];
 
-        const bpInputs: BreakpointInput[] = args.breakpoints.map((bp) => ({
-          script_path: resolveBreakpointPath(bp.file, entry.sourceMapper, entry.cartridges),
-          line_number: bp.line,
-          condition: bp.condition,
-        }));
+        const bpInputs: BreakpointInput[] = args.breakpoints.map((bp) => {
+          const scriptPath = resolveBreakpointPath(bp.file, entry.sourceMapper, entry.cartridges);
+          const roundTrip = entry.sourceMapper.toLocalPath(scriptPath);
+          if (!roundTrip) {
+            warnings.push(
+              `"${bp.file}" resolved to server path "${scriptPath}" but could not be mapped back to a local file. ` +
+                `Verify this path exists on the instance.`,
+            );
+          }
+          return {
+            script_path: scriptPath,
+            line_number: bp.line,
+            condition: bp.condition,
+          };
+        });
 
         const result = await entry.manager.setBreakpoints(bpInputs);
         entry.breakpoints = result;
@@ -81,9 +95,10 @@ export function createDebugSetBreakpointsTool(
             file: entry.sourceMapper.toLocalPath(bp.script_path) ?? null,
             line: bp.line_number,
             script_path: bp.script_path,
-            verified: true,
+            verified: entry.sourceMapper.toLocalPath(bp.script_path) !== undefined,
             condition: bp.condition,
           })),
+          warnings: warnings.length > 0 ? warnings : undefined,
         };
       },
       formatOutput: (output) => jsonResult(output),

packages/b2c-dx-mcp/src/tools/diagnostics/debug-start-session.ts

@@ -26,6 +26,7 @@ interface StartSessionOutput {
   session_id: string;
   hostname: string;
   cartridges: string[];
+  cartridge_mappings: Record<string, string>;
   warnings: string[];
 }
 
@@ -105,10 +106,16 @@ export function createDebugStartSessionTool(
 
         const entry = registry.registerSession(hostname, clientId, manager, sourceMapper, cartridges);
 
+        const cartridgeMappings: Record<string, string> = {};
+        for (const c of cartridges) {
+          cartridgeMappings[c.name] = c.src;
+        }
+
         return {
           session_id: entry.sessionId,
           hostname,
           cartridges: cartridges.map((c) => c.name),
+          cartridge_mappings: cartridgeMappings,
           warnings,
         };
       },

packages/b2c-dx-mcp/src/tools/diagnostics/debug-wait-for-stop.ts

@@ -41,7 +41,8 @@ export function createDebugWaitForStopTool(
       description:
         'Wait for a thread to halt at a breakpoint or step. ' +
         'Returns immediately if a thread is already halted. ' +
-        'Otherwise BLOCKS until a halt occurs or the timeout expires — the user or an external process must trigger a request on the instance while this tool is waiting.',
+        'Otherwise BLOCKS until a halt occurs or the timeout expires. ' +
+        'Preferred non-blocking alternative: after debug_set_breakpoints, trigger the request yourself, then use debug_list_sessions to check if halted_threads is non-empty before calling debug_get_stack/debug_get_variables.',
       toolsets: ['CARTRIDGES', 'SCAPI', 'STOREFRONTNEXT'],
       inputSchema: {
         session_id: z.string().describe('Session ID returned by debug_start_session.'),