Add script debugger MCP tools, CLI REPL, and RPC mode by clavery · Pull Request #395 · SalesforceCommerceCloud/b2c-developer-tooling

clavery · 2026-05-04T00:33:08Z

Summary

MCP debug tools — 13 tools added to CARTRIDGES and SCAPI toolsets for agent-native script debugging (start/end sessions, breakpoints, wait for halt, stack/variables/evaluate, step, capture-at-breakpoint)
ServerContext architecture — persistent server-scoped state across MCP tool invocations, enabling stateful debug sessions alongside the existing per-call config reloading
b2c debug cli — interactive REPL for terminal-based debugging with --rpc flag for JSONL-over-stdio headless/agent integration
resolveBreakpointPath — SDK utility that normalizes file paths for breakpoints (server paths, local paths, cartridge-name-prefixed paths)
Docs — CLI debug reference page, MCP diagnostics tools page, b2c-debug agent skill
MCP tools sidebar — reorganized by use case (Cartridges, SCAPI, PWA Kit, Storefront Next, Diagnostics)

debugger use case

debugger use case alt

sidebar refactor

Test plan

MCP tools: start session, set breakpoints, trigger request, wait for stop, get stack/variables, evaluate, continue, end session
CLI REPL: interactive breakpoint/step/inspect workflow
CLI RPC: test-rpc-debug.sh end-to-end via JSONL stdin/stdout
Existing MCP tools unaffected by ServerContext threading
MCP tools sidebar grouping renders correctly

- Add 13 MCP debug tools (debug_start_session, debug_set_breakpoints, debug_wait_for_stop, debug_get_stack, debug_get_variables, debug_evaluate, debug_continue, debug_step_over/into/out, debug_end_session, debug_list_sessions, debug_capture_at_breakpoint) to CARTRIDGES, SCAPI, and STOREFRONTNEXT toolsets - Add ServerContext for persistent server-scoped state across MCP tool invocations (debug sessions, future log watches) - Add DebugSessionRegistry with TTL cleanup and multi-session support - Add `b2c debug cli` command with interactive REPL and --rpc mode for JSONL-over-stdio headless/agent integration - Add resolveBreakpointPath utility in SDK for flexible path normalization (server paths, local paths, cartridge-prefixed paths) - Add debug command docs and b2c-debug agent skill

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.

Organize into Cartridges, SCAPI, PWA Kit, Storefront Next, and Diagnostics sub-groups.

Make it explicit in tool descriptions and docs that these tools block until a breakpoint is hit or timeout expires, and that the caller must trigger a request externally while waiting.

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.

Absolute local paths like /Users/.../app_mysite/cartridge/controllers/Loyalty.js start with / and were returned as-is (treated as server paths) before the source mapper had a chance to map them. Now the source mapper runs first — if it matches, the local path is correctly converted to a server path. The / passthrough only applies if the mapper doesn't match.

The new debug tools have no unit tests yet (they require mocking the DebugSessionManager and SDAPI). Excluding from coverage until tests are added to avoid blocking the draft PR.

Tests cover DebugSessionRegistry (register, duplicate rejection, get, destroy, halt waiter cleanup) and tool handlers (list_sessions, end_session, continue, get_stack, evaluate). Diagnostics tools excluded from coverage threshold until full coverage is added.

patricksullivansf

fun stuff

probably needs a type check before merging as it seems it has an unfinished refactor.

the docs might benefit from a round of global consistency and cross linking.

i see lots of new to me MCP patterns that are worth looking into more carefully.

patricksullivansf · 2026-05-06T01:13:06Z

-      {text: 'sfnext_add_page_designer_decorator', link: '/mcp/tools/sfnext-add-page-designer-decorator'},
-      {text: 'sfnext_configure_theme', link: '/mcp/tools/sfnext-configure-theme'},
+      {
+        text: 'Cartridges',


no strong opinion, but given that the same tool shows up in different auto-detected configurations will this grouping by names that mirror toolset names cause more confusion?

maybe. I was going for the primary toolset of the tools for the tertiary organization here. I do think we will need more doc refactor here

patricksullivansf · 2026-05-06T01:20:14Z

given this is a stateful mcp tool we should probably include explicit how to stop and recover from a broken debugging session (which i assume is kill and restart your MCP server?). For example, if the agent context gets flushed it won't remember anything about the active debug session and maybe that's an issue?

It is an issue but that's the point of the list_sessions tool. We also have the benefit that the SDAPI only supports 1 connection so a new debug session WILL overwrite the older.

Covers all 13 debug tool handlers including set_breakpoints (path mapping + warnings), get_variables (scope filtering, object_path, truncation), wait_for_stop (immediate halt, timeout, waiter resolution), capture_at_breakpoint (full orchestration, trigger_url, eval errors, timeout), start_session (real fixture cartridge + stubbed manager), and all step_* variants. Registry tests cover idle cleanup and disconnect error swallowing. Coverage is now 99.81% statements/lines, 94.65% branches, 98.94% functions — meeting all thresholds without excluding diagnostics.

…pdates Tier 1 cleanup based on PR review feedback (patricksullivansf, yhsieh1) and self-review. DRY: - Extract shared projection helpers to SDK (projections.ts): truncateValue, isPrimitiveType, projectFrame, projectVariable, projectBreakpoint, projectThreadLocation, plus exported types MappedFrame/MappedVariable/MappedBreakpoint/MappedLocation. Used by both MCP debug tools and CLI RPC mode — eliminates 5+ copies of the same projection code and the MAX_VALUE_LENGTH/PRIMITIVE_TYPES constants. - Add getSessionEntry/getRegistry helpers to session-registry. Replace the 4-line "registry not available" + getSessionOrThrow boilerplate in 11 tools. - Move halt-waiter promise pattern into DebugSessionRegistry.waitForHalt. Used by debug_wait_for_stop and debug_capture_at_breakpoint instead of duplicating the promise/timer/cleanup logic. - Replace step-action switch with a lookup map. API: - DebugSessionRegistry.registerSession now takes an options object (yhsieh1 nit) instead of 5 positional parameters. Docs: - Add "Recovery from broken or orphaned sessions" section to docs/mcp/tools/diagnostics.md (patricksullivansf concern). - Link to main authentication and configuration guides. - Add JSDoc to ServerContext explaining stdio-per-client isolation vs shared transport caveats (patricksullivansf concern). Tool descriptions (yhsieh1 audit): - Drop user-facing prose, sharpen for agent consumption. - debug_start_session: explicitly mention SFRA controllers, custom API scripts, hooks, jobs as use cases. - debug_end_session: IMPORTANT call-out to always end sessions. Coverage stays at 99.81% statements/lines, 94.81% branches, 98.93% functions — all above thresholds.

Match the cartridge-deploy.md pattern: structured Required block, Configuration priority line, link to ../configuration (MCP config) and ../../guide/authentication#webdav-access (main auth guide with WebDAV anchor).

# Conflicts: # docs/cli/debug.md

clavery · 2026-05-07T17:55:26Z

@patricksullivansf @yhsieh1 thanks for the review. got to most things and coverage should be at mains baseline

clavery added 10 commits May 3, 2026 20:32

Add MCP diagnostics tools doc page and sidebar sub-group

fc80ac5

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.

Group MCP tools sidebar by use case

09c18c5

Organize into Cartridges, SCAPI, PWA Kit, Storefront Next, and Diagnostics sub-groups.

Collapse MCP tools sidebar groups by default

9247381

Clarify that debug_wait_for_stop and debug_capture_at_breakpoint block

d10d760

Make it explicit in tool descriptions and docs that these tools block until a breakpoint is hit or timeout expires, and that the caller must trigger a request externally while waiting.

Exclude diagnostics tools from MCP coverage threshold

8da16e3

The new debug tools have no unit tests yet (they require mocking the DebugSessionManager and SDAPI). Excluding from coverage until tests are added to avoid blocking the draft PR.

Fix lint errors in diagnostics test files

a2028bd

clavery marked this pull request as ready for review May 6, 2026 00:00

clavery requested review from patricksullivansf, wei-liu-sf and yhsieh1 as code owners May 6, 2026 00:00

Remove debugger tools from STOREFRONTNEXT toolset

9d72bf0

patricksullivansf approved these changes May 6, 2026

View reviewed changes

yhsieh1 reviewed May 6, 2026

View reviewed changes

Comment thread docs/mcp/tools/diagnostics.md

yhsieh1 reviewed May 6, 2026

View reviewed changes

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

yhsieh1 reviewed May 6, 2026

View reviewed changes

Comment thread packages/b2c-dx-mcp/src/tools/diagnostics/session-registry.ts Outdated

yhsieh1 reviewed May 6, 2026

View reviewed changes

Comment thread packages/b2c-dx-mcp/.c8rc.json Outdated

clavery added 4 commits May 5, 2026 23:19

Align diagnostics auth section with other MCP tool docs

3860c39

Match the cartridge-deploy.md pattern: structured Required block, Configuration priority line, link to ../configuration (MCP config) and ../../guide/authentication#webdav-access (main auth guide with WebDAV anchor).

Merge remote-tracking branch 'origin/main' into feature/debug-mcp

ece6c23

# Conflicts: # docs/cli/debug.md

clavery merged commit b947888 into main May 7, 2026
6 checks passed

clavery deleted the feature/debug-mcp branch May 7, 2026 21:04

github-actions Bot mentioned this pull request May 7, 2026

Next Release: changelog and version packages #393

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add script debugger MCP tools, CLI REPL, and RPC mode#395

Add script debugger MCP tools, CLI REPL, and RPC mode#395
clavery merged 15 commits intomainfrom
feature/debug-mcp

clavery commented May 4, 2026 •

edited

Loading

Uh oh!

patricksullivansf left a comment

Uh oh!

patricksullivansf May 6, 2026

Uh oh!

clavery May 6, 2026

Uh oh!

Uh oh!

patricksullivansf May 6, 2026

Uh oh!

clavery May 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clavery commented May 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

clavery commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

patricksullivansf left a comment

Choose a reason for hiding this comment

Uh oh!

patricksullivansf May 6, 2026

Choose a reason for hiding this comment

Uh oh!

clavery May 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

patricksullivansf May 6, 2026

Choose a reason for hiding this comment

Uh oh!

clavery May 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

clavery commented May 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

clavery commented May 4, 2026 •

edited

Loading