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>"}
4. get_stack_trace        {sessionId}                          -> frames (use frame.id, never assume 0)
5. get_scopes             {sessionId, frameId: <frame.id>}     -> scope variablesReference
6. get_variables          {sessionId, scope: <variablesReference>}
   ... or get_local_variables {sessionId} for the common case
7. evaluate_expression    {sessionId, expression: "x + y"}
8. step_over / step_into / step_out / continue_execution
9. get_output             {sessionId}                          -> captured debuggee stdout/stderr
10. close_debug_session   {sessionId}                          -> ALWAYS, even on failure

Rules that prevent 90% of failed sessions:

• Absolute paths only for file and scriptPath (relative paths are rejected in host mode).
• Use real frame IDs. Take id from get_stack_trace frames; it is adapter-assigned and is not 0-indexed.
• Expand variable containers. If a variable entry carries a variablesReference, call get_variables again with that reference to see children (Python's "special variables", object fields, array elements).
• Respect session state. Stepping, evaluation, and variable reads require PAUSED. After continue_execution the session is RUNNING; after a step or breakpoint hit it returns to PAUSED with a persisted stop reason telling you why it stopped (breakpoint, step, entry, exception, ...).
• Breakpoints may verify late. Some adapters (debugpy, JDI) report breakpoints unverified until the module/class loads; that is normal, not an error.
• <redacted:...> placeholders are masking, not program state. Credential-shaped values and values of sensitive variable names (password, api_key, ...) are masked by default in variable/evaluate/output results; a redaction field reports what was hidden. The real value is intact in the debuggee — don't "fix" it, and don't retry the read. The user can disable masking by restarting the server with DEBUG_MCP_NO_REDACT=1.
• If get_variables demands names, the server is in least-privilege mode (DEBUG_MCP_VARIABLE_ACCESS=explicit): pass the exact variable names you need (names: ["user", "total"]; case-sensitive, misses reported in notFound) instead of dumping the scope. evaluate_expression still works for targeted reads.
• Always close_debug_session when done — it tears down the debuggee process tree.