Script Debugger
MCP tools for connecting to the B2C Commerce Script Debugger API (SDAPI), setting breakpoints, inspecting variables, and stepping through server-side code. Part of the DIAGNOSTICS toolset (always enabled), and also available in the CARTRIDGES and SCAPI toolsets.
Authentication
Requires Basic Auth credentials only. OAuth is not supported by the SDAPI.
Required:
- Basic Auth -
hostname,username, andpassword— either the account password or aWebDAV File Access and UX Studioaccess key — for a user with theWebDAV_Manage_Customizationpermission.
Configuration priority: Flags → Environment variables → dw.json config file
See Configuration for complete credential setup details including flags and environment variables. See Authentication Setup for access key configuration instructions.
Recovery from broken or orphaned sessions
Debug sessions are stateful and live in the MCP server process. If the agent loses track of an active session (context flush, crash, restart), or breakpoints stop firing as expected:
- List active sessions — call
debug_list_sessions(no args). It returns all sessions known to the server with theirsession_id,hostname, halted threads, and currently armed breakpoints. - End orphaned sessions — call
debug_end_sessionwith thesession_idto free the debugger slot on the instance. - MCP-owned debugger identity — the MCP server assigns the debugger client identity internally; callers do not configure or track it.
- Idle cleanup — sessions inactive for 30 minutes are automatically cleaned up by the server.
- Restart the MCP server — as a last resort, restarting the MCP server destroys all local session state. Any orphaned debugger slot on the instance is freed by SDAPI's own timeout.
Session Lifecycle
debug_start_session
Start a new script debugger session. Connects to the SDAPI, discovers cartridge mappings, and begins polling for halted threads.
Warning: Debug sessions can halt remote request threads on the instance. Use
debug_end_sessionto cleanly disconnect when done.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
projectDirectory | string | No | Server project directory/cwd | Project root used to load .env/dw.json and resolve relative paths. Overrides the server-level directory; run config_inspect to see the resolved paths. |
configPath | string | No | Resolved from project context | Primary dw.json-format configuration file. Relative paths resolve from projectDirectory; the shared default remains available. |
instanceName | string | No | Active/default instance | Named instance selected from the primary configuration first, then the shared default dw.json. |
cartridgeDirectory | string | No | projectDirectory | Cartridge discovery and source-mapping root only. Use when cartridges are outside the project root; relative paths resolve from project root. |
Returns: session_id, hostname, discovered cartridges, resolution, and warnings. The session retains its resolution context; debug_list_sessions returns it for later follow-up calls.
debug_end_session
End a script debugger session. Disconnects from the SDAPI, stops polling, and cleans up resources.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id | string | Yes | Session ID from debug_start_session | |
clear_breakpoints | boolean | No | false | Delete all breakpoints before disconnecting |
debug_list_sessions
List all active debug sessions. Returns session IDs, connected hostnames, any currently halted threads, and armed breakpoints.
No parameters.
Breakpoints
debug_set_breakpoints
Set breakpoints in a debug session. Replaces all previously set breakpoints.
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 /.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID from debug_start_session |
breakpoints | array | Yes | Array of {file, line, condition?} objects |
Each breakpoint object:
| Field | Type | Required | Description |
|---|---|---|---|
file | string | Yes | Local file path, cartridge-prefixed path, or server script path |
line | number | Yes | Line number |
condition | string | No | Conditional expression — breakpoint only triggers when true |
Execution Control
debug_wait_for_stop
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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id | string | Yes | Session ID | |
timeout_ms | number | No | 30000 | Timeout in milliseconds (max 120000) |
Returns: {halted, thread_id, location} or {halted: false, timed_out: true}.
debug_continue
Resume execution of a halted thread.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID |
thread_id | number | Yes | Thread ID of the halted thread |
debug_step_over
Step to the next line in the current function. Follow with debug_wait_for_stop.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID |
thread_id | number | Yes | Thread ID |
debug_step_into
Step into the function call on the current line. Follow with debug_wait_for_stop.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID |
thread_id | number | Yes | Thread ID |
debug_step_out
Step out of the current function, returning to the caller. Follow with debug_wait_for_stop.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID |
thread_id | number | Yes | Thread ID |
Inspection
debug_get_stack
Get the call stack for a halted thread. Returns stack frames with mapped local file paths and server script paths.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session ID |
thread_id | number | Yes | Thread ID |
debug_get_variables
Get variables for a stack frame in a halted thread.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id | string | Yes | Session ID | |
thread_id | number | Yes | Thread ID | |
frame_index | number | No | 0 | Stack frame index (0 = top frame) |
scope | string | No | All scopes | Filter by local, closure, or global |
object_path | string | No | Dot-delimited path to drill into an object (e.g. request.httpParameters) |
debug_evaluate
Evaluate an expression in the context of a halted thread and stack frame.
Warning: Expressions can have side effects (modify variables, call functions). Use with care.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id | string | Yes | Session ID | |
thread_id | number | Yes | Thread ID | |
frame_index | number | No | 0 | Stack frame index |
expression | string | Yes | JavaScript expression to evaluate |
Higher-Level Tools
debug_capture_at_breakpoint
Set a breakpoint, wait for it to be hit, and capture a diagnostic snapshot — stack, variables, and optional expression results in a single call. Optionally resumes the thread after capture.
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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id | string | Yes | Session ID | |
file | string | Yes | File path for the breakpoint | |
line | number | Yes | Line number | |
condition | string | No | Conditional expression | |
expressions | string[] | No | Expressions to evaluate when hit | |
timeout_ms | number | No | 30000 | Timeout waiting for the breakpoint (max 120000) |
auto_continue | boolean | No | false | Resume the thread after capturing |
See Also
- Debug CLI Commands — Interactive REPL and RPC mode for the CLI
- Configuration — Setting up instance credentials