CALL THIS FIRST whenever browser-side debugging is needed — before any other tool.

Auto-trigger when user mentions any of: debug, breakpoint, debugger, inspect, trace, step through, runtime value, variable value, why is this, implement based on API response, bug, error, unexpected behavior, not working, check this, confirm this.

Returns the complete debugging workflow and critical rules. The response contains a "_ui" field — relay it to the user verbatim.

[STEP 1] Launch a dedicated Chrome instance with remote debugging enabled (default port 9222). Uses --user-data-dir=~/.chrome-debug-profile so your normal Chrome keeps running (dual-instance). Auto-detects if the debug port is already active and skips launch (alreadyRunning=true). Use dryRun=true to preview the command — show it to the user and ask for confirmation before executing. Set openDevTools=true to automatically open DevTools panel for every new tab. If automatic launch does not succeed, relay the returned command to the user and ask them to run it manually. Relay the "_ui" field from the response to the user.

[STEP 2] List all open Chrome tabs available for debugging. MANDATORY: show the full list to the user and ask "Which URL do you want to debug?" NEVER skip this step, NEVER guess — even if only one tab is open. Wait for the user's explicit reply before proceeding to connect(). Relay the "_ui" field from the response to the user.

[STEP 3] Connect the debugger to a specific Chrome tab. MANDATORY: call listTargets first, show the list to the user, wait for their explicit URL confirmation, then call this. NEVER guess the URL. NEVER skip user confirmation — even if only one tab is visible. targetUrl must be a unique substring of the tab URL the user confirmed (e.g. "localhost:5173"). Relay the "_ui" field from the response to the user.

Disconnect the current Chrome debugging session and clear in-memory pause state. Use this to explicitly end a debug session before connecting again.

Set a breakpoint at a specific script URL and line number via CDP — no source code modification needed. Use a full URL (https://...) for exact match, or a partial filename/keyword for regex match. Alternative to inserting debugger; when you cannot modify the source file. After setting, call reloadPage() to ensure the breakpoint resolves correctly.

Remove a previously set CDP breakpoint by its ID (returned by setBreakpoint).

[STEP 5b — FALLBACK] BLOCKING call — waits until ANY debugger pause occurs (breakpoint, debugger; statement, or exception). Before blocking, sends a notification to the user to trigger the page action. Must be called IMMEDIATELY after reloadPage() in the SAME AI turn — do NOT end your turn before calling this. Prefer waitForSpecificPause when you know the exact file and line — it uses smarter two-tier matching. Use this only when the target location is unknown or when setBreakpoint is used without a specific line.

[STEP 5b — PREFERRED] BLOCKING call — waits for the next debugger pause, then checks if it matches the target location.

⚠️ NO AUTO-RESUME: execution stays paused after this returns, regardless of matched value. You decide what to do based on the "matched" field in the response: matched=true → call getScopeVariables() immediately to read variables matched=false → the wrong breakpoint fired; call resume() to continue, then call waitForSpecificPause() again if you need to wait for the next pause.

Must be called IMMEDIATELY after reloadPage() in the SAME AI turn. Before blocking, sends a notification to the user to trigger the page action. Editor line N → pass line=N-1 (CDP uses 0-based line numbers). Relay the "_ui" field from the response to the user once it returns.

[STEP 6a] Read all scope variables (local, closure, module) at the currently paused call frame. Call this immediately after waitForSpecificPause or waitForPause returns. Results are grouped by scope type; global scope is skipped. Use frameIndex=1, 2, ... to inspect variables in parent call frames up the stack.

[STEP 6b] Evaluate any JavaScript expression in the context of the currently paused call frame. Use this to inspect nested objects, call methods, compute derived values, or verify conditions at runtime. Complements getScopeVariables for values not directly visible in scope (e.g. this.state, JSON.stringify(obj)).

[STEP 8] Resume script execution after collecting all needed variable data — ends the current pause. After calling resume, remove all temporary debugger; statements added to source code during this session. Relay the "_ui" field from the response to the user.

[STEP 7] BLOCKING: step into the next function call, then wait until the debugger pauses again. Follow with getScopeVariables() to observe inner-function state.

[STEP 7] BLOCKING: step over the current statement without entering function calls, then wait until the debugger pauses again. Follow with getScopeVariables() to observe how local variables change.

[STEP 7] BLOCKING: step out of the current function and wait until the debugger pauses again in the caller. Use to observe the return value and the state of the calling context.

Non-blocking: return current connection and pause state immediately without waiting. Use this to poll for pause instead of waitForPause when the MCP client has a short request timeout (e.g. MCP Inspector ~10s). Returns: connected, paused, targetUrl, pauseReason, hitBreakpoints, callStack.

[STEP 5a] Reload the connected page via Chrome DevTools Protocol. More reliable than manual browser refresh — maintains the CDP connection and ensures debugger; statements and setBreakpoint() calls resolve correctly when scripts reload. Always call this after inserting debugger; in source code or after setBreakpoint(), before waitForSpecificPause/waitForPause.

⚠️ CRITICAL TURN RULE: After this tool returns, you MUST immediately call waitForSpecificPause (or waitForPause) in the SAME AI turn — do NOT end your turn here. waitForSpecificPause is a blocking call that will notify the user to trigger the page action and wait for the breakpoint internally. If you end your turn after reloadPage, the session will break.

Force the debugger to pause at the very next JavaScript statement. Useful when you cannot modify source code to add debugger; and setBreakpoint is not feasible.