jdbg

jdbg — interactive Java debugging for agents

jdbg is an MCP server that drives the JDK's jdb debugger as a stateful background session, so you can debug a Java program across many separate tool calls. Each tool call (launch, break_at, run, locals, …) sends ONE command to the session and returns a structured result. A background daemon keeps the JVM and debugger state alive between calls — set a breakpoint in one call, run in the next, inspect in the next.

The tools appear as mcp__jdbg__<tool> (e.g. mcp__jdbg__break_at). Below they are named bare (break_at) for brevity. The first tool call auto-starts the background daemon — no setup step is needed.

Core loop: react to each result. Call one tool, read its structured output, then decide the next call. Do NOT batch commands or tune timing — jdbg waits for jdb to be ready (no sleeps), and a hung program returns a non-destructive Timeout, not a freeze.

When to use

• Find the real runtime value of a variable / field / expression at a line (not by reading code).
• Diagnose why an exception or NPE is thrown — the stack and locals at the throw site.
• Inspect threads; find what a blocked or deadlocked thread is waiting on.
• Step through execution line by line to see actual control flow.
• Attach to an already-running JVM that has JDWP enabled.

When NOT: logic simple enough to read; a compile/build error (that is javac, not a debugger); no running JVM and nothing launchable.

Start a session — two ways

Launch a program under the debugger (you have the main class + classpath) — call launch with main_class (and usually classpath; pass program args via app_args):

launch { "main_class": "com.example.Main", "classpath": "out", "sourcepath": "src", "app_args": ["arg1", "arg2"] }

Returns a session id, state loaded (JVM not started yet). Set breakpoints, then call run.

Attach to a running JVM started with JDWP — call attach:

attach { "host": "localhost", "port": 5005, "sourcepath": "src" }

The default JDI backend returns state running for attach; set breakpoints, then call cont (attach has no run). If local JDI prerequisites are missing, an omitted backend automatically falls back to jdb and returns a note; explicit backend: "jdi" means JDI is required and does not fall back.