jetbrains-debugger

name: jetbrains-debugger description: >- Guide for using JetBrains IDE Debugger MCP tools to programmatically debug applications. TRIGGER when ANY of these MCP tools are available: list_run_configurations, execute_run_configuration, start_debug_session, stop_debug_session, get_debug_session_status, list_debug_sessions, set_breakpoint, remove_breakpoint, list_breakpoints, resume_execution, pause_execution, step_over, step_into, step_out, run_to_line, wait_for_pause, get_stack_trace, select_stack_frame, list_threads, get_variables, set_variable, get_source_context, evaluate_expression. Use when debugging any application, investigating bugs, tracing execution flow, inspecting runtime state, or when the user says "debug", "breakpoint", "step through", "inspect variable", "why is this returning X", "trace execution", or similar debugging-related requests. PREFER the debugger over reading code and guessing when runtime behavior is unclear.

JetBrains Debugger MCP

Use these tools to actually debug applications in a JetBrains IDE rather than guessing from static code.

Complete parameter reference: See references/tool-reference.md for all tool parameters, types, defaults, and return schemas.

When to Use the Debugger

USE the debugger when:

• A bug involves runtime state (wrong values, unexpected nulls, incorrect flow)
• Reading code alone doesn't explain the behavior
• The user asks "why does X happen" or "what value does Y have"
• A test fails and the cause isn't obvious from the assertion message
• You need to verify a hypothesis about execution flow
• The user explicitly asks to debug

DON'T use the debugger when:

• The bug is a clear syntax error, typo, or missing import
• The fix is obvious from reading the code (e.g., off-by-one, wrong operator)
• There's no run configuration available to debug

Core Workflow

Standard Debugging Sequence

1. list_run_configurations          -- Find a config with can_debug: true
2. set_breakpoint                   -- Set breakpoint(s) BEFORE starting
3. start_debug_session              -- Launch the debugger
4. wait_for_pause(timeout=60)       -- Block until breakpoint hit (returns full status)
5. evaluate_expression              -- Test hypotheses about values
6. step_over / step_into / step_out -- Navigate through code
7. wait_for_pause(timeout=10)       -- Wait for step to complete, get state
8. resume_execution                 -- Continue to next breakpoint
9. wait_for_pause(timeout=60)       -- Block until next breakpoint hit
10. stop_debug_session              -- Clean up when done

Critical Rules

1. Set breakpoints BEFORE starting the session. Breakpoints can be set without an active session. Setting them first ensures the program pauses where you need it.

2. After resume_execution or any step command, use wait_for_pause to block until the session pauses. It returns the full session status (variables, stack, source, location) when the pause occurs — no polling needed. Step/resume commands return immediately with newState: "running" and do NOT wait for the program to pause.

3. Use get_debug_session_status to re-inspect state without waiting. It returns variables, stack trace, source context, and current location in ONE call. Do NOT call get_variables, get_stack_trace, and get_source_context separately unless you need specific parameters (e.g., a different frame index or more context lines).

4. Line numbers are 1-based. When setting breakpoints or using run_to_line, use the line numbers as they appear in the editor (starting from 1).

5. File paths must be absolute. For set_breakpoint, run_to_line, and get_source_context, always use absolute file paths (e.g., /Users/dev/project/src/Main.java). Files inside JARs are supported via the !/ separator (e.g. /path/to/lib-sources.jar!/com/example/Foo.kt).

6. session_id is optional for single-session debugging. When only one debug session exists, all tools auto-select it. Only specify session_id when multiple sessions are active.

7. project_path is required when multiple projects are open. If omitted with multiple projects, tools return an error listing available projects.

8. evaluate_expression may be safety-filtered by IDE settings. If a call is blocked, prefer get_variables, simple field/arithmetic expressions, or a narrower expression that avoids method calls and risky APIs. Do not retry blocked process, filesystem, network, reflection, native-loading, or environment/system-property operations unless the user explicitly changes the IDE setting.

Debugging Patterns

Pattern: Find Why a Value is Wrong

1. set_breakpoint at the line where the wrong value is used
2. start_debug_session with the appropriate run configuration
3. wait_for_pause(timeout=60) -- blocks until breakpoint hit, returns full status
4. Inspect variables in the response -- the wrong value and its inputs are visible
5. evaluate_expression to test alternative calculations
6. If the value was already wrong here, set_breakpoint earlier in the call chain
7. resume_execution, then wait_for_pause(timeout=60) -- repeat

Pattern: Debug a Specific Loop Iteration

1. set_breakpoint with condition (e.g., condition: "i == 50")
2. start_debug_session
3. wait_for_pause(timeout=120) -- debugger runs at full speed until condition is true
4. Inspect variables in the response -- state at exactly iteration 50

Pattern: Trace Execution Without Stopping

1. set_breakpoint with log_message and suspend_policy: "none"
   Example: log_message: "Entering process() with id={id}, count={items.size()}"
2. start_debug_session
3. resume_execution
4. Check IDE console output for trace log -- execution never pauses

Pattern: Inspect a Different Stack Frame

1. get_debug_session_status -- see the stack summary
2. select_stack_frame with the frame_index of interest (0 = current, 1 = caller, etc.)
3. get_variables -- now shows variables from the selected frame
4. evaluate_expression -- expressions evaluated in the selected frame's context

Pattern: Test a Fix Without Restarting

1. Pause at the point of interest
2. evaluate_expression with the corrected logic to verify it produces the right result
3. set_variable to inject the correct value
4. resume_execution to see if the fix resolves the downstream issue

Common Mistakes to Avoid

Language-Specific Notes

Full Support (Java, Kotlin, Python, JavaScript, TypeScript, PHP, Ruby)

• All tools work as documented
• evaluate_expression supports method calls, field access, arithmetic
• set_variable works for all types including objects and strings

Limited Support (Rust, C++, C, Go, Swift)

These use native debuggers (LLDB/GDB) with restrictions:

• evaluate_expression: Variable inspection works, but method calls (e.g., s.len(), vec.size()) may fail
• set_variable: Works for primitives (int, float, bool). Complex types (String, Vec, structs) may fail
• Workaround: Use get_variables to inspect values instead of evaluate_expression with method calls

Tool Quick Reference