gradusnikov / eclipse-debug

Debug Java Applications in Eclipse

Full interactive debugging using Eclipse's JDT debugger. Set breakpoints, step through code, inspect variables, evaluate expressions, and hot-swap changes.

Breakpoints

• toggleBreakpoint — Set or remove a line breakpoint. Provide projectName, typeName (fully qualified), and lineNumber.
• setConditionalBreakpoint — Set a breakpoint with a condition. Only triggers when the condition is true. Also supports hitCount (trigger after N hits).
• listBreakpoints — Show all breakpoints with location, enabled status, and conditions.
• removeAllBreakpoints — Clear all breakpoints.

Launch

• debugJavaApplication — Launch in debug mode. Same parameters as runJavaApplication but defaults to timeout=0 (background). The app stops at breakpoints.
• launchConfiguration — Debug an existing saved launch configuration by name with mode="debug", preserving its classpath, VM args, environment variables, working directory, and agent settings (e.g. JRebel). Use listLaunchConfigurations to find the name. Breakpoints set via toggleBreakpoint still apply.

Stepping (requires suspended thread)

• stepOver — Execute current line, don't enter method calls.
• stepInto — Enter the method call on the current line.
• stepReturn — Run until the current method returns.
• resumeDebug — Continue execution until next breakpoint or termination.

Inspection (requires suspended thread)

• getStackTrace — Show all threads with call stack. For the top frame, also shows local variables with their values and types.
• evaluateExpression — Evaluate any Java expression in the context of the suspended frame. Examples: myList.size(), x + y, this.toString(), System.getProperty("user.dir").

Hot Code Replace

• hotCodeReplace — Push code changes into the running debug session without restarting. Triggers an incremental build and the JVM reloads changed classes.

Structural Reloads

• restartMcpServers — Rebuild the HTTP MCP server registry after a 500–30,000 ms delay. The delay lets the invoking response complete; clients may need to reconnect.
• reloadWorkspaceBundle — Schedule an OSGi update for a bundle whose symbolic name maps to an open workspace project. System bundles, fragments, and installed-only bundles are rejected.
• Use hotCodeReplace for supported method-body changes. Use reloadWorkspaceBundle when structural changes (new methods, fields, or MCP tools) cannot be hot-swapped, then restartMcpServers if the HTTP registry still needs rebuilding.

Typical Debug Workflow

1. Set breakpoints where you want to pause:
   `
   toggleBreakpoint(projectName="myapp", typeName="com.example.Main", lineNumber="42")
   `

2. Launch in debug mode:
   `
   debugJavaApplication(projectName="myapp", mainClass="com.example.Main", timeout="0")
   `

3. Wait for breakpoint hit, then inspect:
   `
   getStackTrace(nameOrClass="Main")
   `

4. Evaluate expressions to understand state:
   `
   evaluateExpression(nameOrClass="Main", expression="myList.size()")
   `

5. Step through code:
   `
   stepOver(nameOrClass="Main")
   getStackTrace(nameOrClass="Main")
   `

6. Fix code and hot-swap without restarting:
   `
   # ... edit the file using eclipse-coder tools ...
   hotCodeReplace(nameOrClass="Main")
   resumeDebug(nameOrClass="Main")
   `

7. Clean up:
   `
   stopApplication(nameOrClass="Main")
   removeAllBreakpoints()
   `

Notes

• All stepping/inspection tools match debug sessions by substring against the launch name or main class (nameOrClass parameter)
• getStackTrace shows local variables only for the top frame to keep output manageable
• evaluateExpression has a 10-second timeout
• Hot code replace works on most JVMs but has limitations (can't change method signatures or add/remove fields in some cases)
• Reload tools are deliberately deferred and may disconnect MCP clients; do not use them while another critical MCP operation is in flight