mcp-debugger

Debugging with mcp-debugger

mcp-debugger exposes real language debuggers as MCP tools. Prefer it over print-debugging whenever you would otherwise need more than one edit-run cycle to see program state: a breakpoint plus evaluate_expression answers in one run what printf answers in three.

When to reach for the debugger

• A test fails and the assertion message doesn't explain why the value is wrong.
• Control flow surprises you (a branch that "can't happen", a loop that exits early).
• State mutates somewhere between two known-good points and you need to bisect.
• The bug lives in code you can't easily edit (third-party package, compiled artifact).
• You need ground truth about runtime types/values instead of inferring them from source.

Do NOT reach for it when a single glance at the code or one log line would answer the question — session setup costs a few seconds and the target must be runnable.

The golden path (launch)

1. create_debug_session   {language: "python"}                 -> sessionId
2. set_breakpoint         {sessionId, file: "<ABSOLUTE path>", statement: "<line text or distinctive substring>"}   (or line: N + expectedContent)
3. start_debugging        {sessionId, scriptPath: "<ABSOLUTE path>"}   -> paused at the breakpoint, or pending: true -> wait_for_stop {sessionId}
4. READ THE PAUSED ANSWER: it already carries location, the source line (context), and snapshot
   {exception?, frames, locals} — the exception message, top frames, and the top frame's locals
   (redacted, capped; snapshot.truncation says when there is more). Often that is the whole inspection.
5. To go deeper: get_stack_trace {sessionId} for the full stack (use frame.id, never assume 0),
   get_scopes {sessionId, frameId: <frame.id>} -> scope variablesReference,
   get_variables {sessionId, scope: <variablesReference>} ... or get_local_variables {sessionId}
6. evaluate_expression    {sessionId, expression: "x + y"}
7. step_over / step_into / step_out / continue_execution
   wait_for_stop          {sessionId}                          -> blocks until the next stop or the exit (continue_execution does not wait)
   Each landed step's snapshot carries changedVariables {name: {before, after}} — what the executed
   line changed — instead of re-sending full locals; an empty {} means nothing visible changed.
8. get_output             {sessionId}                          -> captured debuggee stdout/stderr
9. close_debug_session    {sessionId}                          -> ALWAYS, even on failure