Skip to content

Commit fc80ac5

Browse files
claveryclavery
committed
Add MCP diagnostics tools doc page and sidebar sub-group
Group debug tools on a single Diagnostics page instead of individual pages. Add Diagnostics sub-heading under MCP Tools in the sidebar for future tools like log tailing.
1 parent f357bf9 commit fc80ac5

2 files changed

Lines changed: 187 additions & 0 deletions

File tree

‎docs/.vitepress/config.mts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,6 +140,11 @@ const referenceSidebar = [
140140
{text: 'sfnext_match_tokens_to_theme', link: '/mcp/tools/sfnext-match-tokens-to-theme'},
141141
{text: 'sfnext_add_page_designer_decorator', link: '/mcp/tools/sfnext-add-page-designer-decorator'},
142142
{text: 'sfnext_configure_theme', link: '/mcp/tools/sfnext-configure-theme'},
143+
{
144+
text: 'Diagnostics',
145+
collapsed: false,
146+
items: [{text: 'Script Debugger', link: '/mcp/tools/diagnostics'}],
147+
},
143148
],
144149
},
145150
];

‎docs/mcp/tools/diagnostics.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
description: MCP tools for script debugging on B2C Commerce instances.
3+
---
4+
5+
# Diagnostics Tools
6+
7+
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**, **SCAPI**, and **STOREFRONTNEXT** toolsets.
8+
9+
## Authentication
10+
11+
All debug tools require **Basic Auth** credentials (username and password) for a Business Manager user with the `WebDAV_Manage_Customization` permission.
12+
13+
The script debugger must be enabled on the instance: Business Manager > Administration > Development Configuration > Script Debugger > Enable.
14+
15+
---
16+
17+
## Session Lifecycle
18+
19+
### debug_start_session
20+
21+
Start a new script debugger session. Connects to the SDAPI, discovers cartridge mappings, and begins polling for halted threads.
22+
23+
> **Warning:** Debug sessions can halt remote request threads on the instance. Use `debug_end_session` to cleanly disconnect when done.
24+
25+
| Parameter | Type | Required | Default | Description |
26+
|-----------|------|----------|---------|-------------|
27+
| `cartridge_directory` | string | No | Project directory | Path to directory containing cartridges |
28+
| `client_id` | string | No | `b2c-cli` | Client ID for the debugger API. Use a different ID for concurrent sessions on the same host. |
29+
30+
**Returns:** `session_id`, `hostname`, discovered `cartridges`, and `warnings`.
31+
32+
### debug_end_session
33+
34+
End a script debugger session. Disconnects from the SDAPI, stops polling, and cleans up resources.
35+
36+
| Parameter | Type | Required | Default | Description |
37+
|-----------|------|----------|---------|-------------|
38+
| `session_id` | string | Yes | | Session ID from `debug_start_session` |
39+
| `clear_breakpoints` | boolean | No | `false` | Delete all breakpoints before disconnecting |
40+
41+
### debug_list_sessions
42+
43+
List all active debug sessions. Returns session IDs, connected hostnames, and any currently halted threads.
44+
45+
No parameters.
46+
47+
---
48+
49+
## Breakpoints
50+
51+
### debug_set_breakpoints
52+
53+
Set breakpoints in a debug session. **Replaces** all previously set breakpoints.
54+
55+
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 `/`.
56+
57+
| Parameter | Type | Required | Description |
58+
|-----------|------|----------|-------------|
59+
| `session_id` | string | Yes | Session ID from `debug_start_session` |
60+
| `breakpoints` | array | Yes | Array of `{file, line, condition?}` objects |
61+
62+
Each breakpoint object:
63+
64+
| Field | Type | Required | Description |
65+
|-------|------|----------|-------------|
66+
| `file` | string | Yes | Local file path, cartridge-prefixed path, or server script path |
67+
| `line` | number | Yes | Line number |
68+
| `condition` | string | No | Conditional expression — breakpoint only triggers when true |
69+
70+
---
71+
72+
## Execution Control
73+
74+
### debug_wait_for_stop
75+
76+
Wait for a thread to halt at a breakpoint or step. Returns immediately if a thread is already halted.
77+
78+
| Parameter | Type | Required | Default | Description |
79+
|-----------|------|----------|---------|-------------|
80+
| `session_id` | string | Yes | | Session ID |
81+
| `timeout_ms` | number | No | 30000 | Timeout in milliseconds (max 120000) |
82+
83+
**Returns:** `{halted, thread_id, location}` or `{halted: false, timed_out: true}`.
84+
85+
### debug_continue
86+
87+
Resume execution of a halted thread.
88+
89+
| Parameter | Type | Required | Description |
90+
|-----------|------|----------|-------------|
91+
| `session_id` | string | Yes | Session ID |
92+
| `thread_id` | number | Yes | Thread ID of the halted thread |
93+
94+
### debug_step_over
95+
96+
Step to the next line in the current function. Follow with `debug_wait_for_stop`.
97+
98+
| Parameter | Type | Required | Description |
99+
|-----------|------|----------|-------------|
100+
| `session_id` | string | Yes | Session ID |
101+
| `thread_id` | number | Yes | Thread ID |
102+
103+
### debug_step_into
104+
105+
Step into the function call on the current line. Follow with `debug_wait_for_stop`.
106+
107+
| Parameter | Type | Required | Description |
108+
|-----------|------|----------|-------------|
109+
| `session_id` | string | Yes | Session ID |
110+
| `thread_id` | number | Yes | Thread ID |
111+
112+
### debug_step_out
113+
114+
Step out of the current function, returning to the caller. Follow with `debug_wait_for_stop`.
115+
116+
| Parameter | Type | Required | Description |
117+
|-----------|------|----------|-------------|
118+
| `session_id` | string | Yes | Session ID |
119+
| `thread_id` | number | Yes | Thread ID |
120+
121+
---
122+
123+
## Inspection
124+
125+
### debug_get_stack
126+
127+
Get the call stack for a halted thread. Returns stack frames with mapped local file paths and server script paths.
128+
129+
| Parameter | Type | Required | Description |
130+
|-----------|------|----------|-------------|
131+
| `session_id` | string | Yes | Session ID |
132+
| `thread_id` | number | Yes | Thread ID |
133+
134+
### debug_get_variables
135+
136+
Get variables for a stack frame in a halted thread.
137+
138+
| Parameter | Type | Required | Default | Description |
139+
|-----------|------|----------|---------|-------------|
140+
| `session_id` | string | Yes | | Session ID |
141+
| `thread_id` | number | Yes | | Thread ID |
142+
| `frame_index` | number | No | `0` | Stack frame index (0 = top frame) |
143+
| `scope` | string | No | All scopes | Filter by `local`, `closure`, or `global` |
144+
| `object_path` | string | No | | Dot-delimited path to drill into an object (e.g. `request.httpParameters`) |
145+
146+
### debug_evaluate
147+
148+
Evaluate an expression in the context of a halted thread and stack frame.
149+
150+
> **Warning:** Expressions can have side effects (modify variables, call functions). Use with care.
151+
152+
| Parameter | Type | Required | Default | Description |
153+
|-----------|------|----------|---------|-------------|
154+
| `session_id` | string | Yes | | Session ID |
155+
| `thread_id` | number | Yes | | Thread ID |
156+
| `frame_index` | number | No | `0` | Stack frame index |
157+
| `expression` | string | Yes | | JavaScript expression to evaluate |
158+
159+
---
160+
161+
## Higher-Level Tools
162+
163+
### debug_capture_at_breakpoint
164+
165+
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.
166+
167+
| Parameter | Type | Required | Default | Description |
168+
|-----------|------|----------|---------|-------------|
169+
| `session_id` | string | Yes | | Session ID |
170+
| `file` | string | Yes | | File path for the breakpoint |
171+
| `line` | number | Yes | | Line number |
172+
| `condition` | string | No | | Conditional expression |
173+
| `expressions` | string[] | No | | Expressions to evaluate when hit |
174+
| `timeout_ms` | number | No | 30000 | Timeout waiting for the breakpoint (max 120000) |
175+
| `auto_continue` | boolean | No | `false` | Resume the thread after capturing |
176+
177+
---
178+
179+
## See Also
180+
181+
- [Debug CLI Commands](/cli/debug) — Interactive REPL and RPC mode for the CLI
182+
- [Configuration](../configuration) — Setting up instance credentials

0 commit comments

Comments
 (0)