Diagnostics Tools
MCP tools for connecting to the B2C Commerce Script Debugger API (SDAPI), setting breakpoints, inspecting variables, and stepping through server-side code. These tools are 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(WebDAV access key) for a Business Manager user with theWebDAV_Manage_Customizationpermission.
Configuration priority: Flags → Environment variables → dw.json config file
The script debugger must also be enabled on the instance: Business Manager > Administration > Development Configuration > Script Debugger > Enable.
See Configuration for complete credential setup details including flags and environment variables. See Authentication Setup for WebDAV 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. - SDAPI single-client guarantee — the script debugger only supports one client per
client_idper host. Callingdebug_start_sessionwith the sameclient_idagainst the same host implicitly takes over (replaces) any prior client. This is the safety net when a session is lost without a clean shutdown. - 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 session state. The orphaned debugger slot on the instance will be freed by SDAPI's own 60-second halt-timeout or by the next
debug_start_sessionwith the same client ID.
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 |
|---|---|---|---|---|
cartridge_directory | string | No | Project directory | Path to directory containing cartridges |
client_id | string | No | b2c-cli | Client ID for the debugger API. Use a different ID for concurrent sessions on the same host. |
Returns: session_id, hostname, discovered cartridges, and warnings.
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, and any currently halted threads.
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