# Jdbg > Agent-friendly Java debugger CLI for coding agents and humans, wrapping JDK jdb with persistent sessions, structured output, and native MCP tools. - **Type:** MCP server - **Install:** `agentstack add mcp-pieceoffall-jdbg` - **Verified:** Pending review - **Seller:** [PieceOfFall](https://agentstack.voostack.com/s/pieceoffall) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [PieceOfFall](https://github.com/PieceOfFall) - **Source:** https://github.com/PieceOfFall/jdbg ## Install ```sh agentstack add mcp-pieceoffall-jdbg ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About jdbg Agent-friendly Java debugging from a Rust CLI. Wraps the JDK jdb with prompt-aware control, persistent sessions, an optional JDI sidecar backend, structured output, and native MCP tools for Claude Code, Codex, OpenCode, Pi, and humans. Demo    Quick Start    Why jdbg    Agent Setup    Commands    Architecture Debug Java without Bash glue jdbg gives coding agents a stable debugging surface for Java: no sleeps, no temp files, no shell command injection surface, and no one-shot process that forgets the session. Prompt-aware: reads jdb until the prompt or stop event is complete. Stateful: one background daemon keeps sessions alive across calls. Agent-native: exposes the same debugger through CLI and MCP tools. JDI-capable: optional sidecar backend for structured inspect, expression eval, mutation, and force return. Built for agent workflows Claude Code MCP tools plus skill Codex MCP server config plus skill OpenCode Local MCP config plus skill Pi CLI skill ## Demo ## Quick Start ### Install The installer downloads the right release artifact for your OS and adds `jdbg` to your user-level `PATH`. Open a new terminal afterwards so the command is visible. Windows: ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/PieceOfFall/jdbg/releases/latest/download/java-agent-debugger-installer.ps1 | iex" ``` macOS / Linux: ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/PieceOfFall/jdbg/releases/latest/download/java-agent-debugger-installer.sh | sh ``` Already have Rust? Install with cargo or build from source. ```bash # Install to ~/.cargo/bin/jdbg cargo install --git https://github.com/PieceOfFall/jdbg.git # Build from source git clone https://github.com/PieceOfFall/jdbg.git cd jdbg # Source builds need JDK 17+ for the Gradle sidecar build. cargo build --release ``` ### Register With Your Agent ```bash jdbg setup ``` Use non-interactive setup when provisioning machines: ```bash jdbg setup --target claude,codex,opencode,pi --yes jdbg setup --backend jdi --target codex --yes jdbg setup --target codex --print jdbg setup --target opencode --print jdbg setup --target pi --print ``` ### Debug Something ```bash # Compile with debug info for locals and line breakpoints javac -g Main.java # Launch a debug session. The daemon starts automatically. jdbg launch Main --classpath . # Set a breakpoint and run jdbg break-at Main 9 jdbg run # Inspect the stopped program jdbg locals jdbg where jdbg print myVar # Move execution forward jdbg step jdbg cont # Clean up jdbg kill jdbg daemon stop ``` In Claude Code, Codex, or OpenCode, ask the agent to debug the Java program. It drives the same flow through `mcp__jdbg__*` tools. In Pi, the installed skill drives the `jdbg` CLI. ## Why jdbg Capability What it changes Prompt-aware reader Commands finish when jdb is actually ready, not after a guessed sleep. Persistent daemon Every CLI or MCP call can reuse live debug sessions instead of restarting state. Native MCP surface Claude Code, Codex, and OpenCode get typed tool calls instead of shell-wrapped debugging. Thread-only breakpoints suspend: "thread" stops the hit thread while heartbeat, ZK, Dubbo, and server threads keep running. Runtime discovery classes and methods help agents find CGLIB proxies, generated classes, and exact signatures. Focused inspection locals, where, inspect, watch, and thread-locks keep agent loops short. JDI runtime actions print, eval, set, and force-return let agents test hypotheses in a suspended frame when explicit side effects are intended. ## Agent Setup `jdbg setup` installs only the target-specific configuration that belongs to `jdbg`. Removal is surgical and preserves sibling servers, user settings, and unrelated skill directories. Interactive setup also asks which backend the installed skills should prefer. Use `--backend jdb|jdi` for non-interactive provisioning; the preference is written into the skill guidance, while `jdb` remains the CLI/MCP runtime default when no backend is passed on session creation. Target What gets configured Installed skill Claude Code mcpServers.jdbg in ~/.claude.json, plus mcp__jdbg__* permission in ~/.claude/settings.json ~/.claude/skills/jdbg/SKILL.md Codex [mcp_servers.jdbg] in ~/.codex/config.toml ~/.codex/skills/jdbg/SKILL.md OpenCode mcp.jdbg in ~/.config/opencode/opencode.json ~/.config/opencode/skills/jdbg/SKILL.md Pi No MCP config ~/.pi/agent/skills/jdbg/SKILL.md ```bash jdbg setup --remove jdbg setup --remove --target codex jdbg update ``` When `--sourcepath` is omitted, jdbg uses the current working directory as the source root and sends it to the daemon as an absolute path. Relative `--sourcepath` values are absolutized before session creation. `jdbg update` stops any running jdbg daemon before replacing the binary. It detects which agents already had `jdbg` configured, installs the latest release, installs the official JDI sidecar jar next to the `jdbg` binary, then re-registers the same targets. ## MCP Server `jdbg __mcp` runs an rmcp-based stdio MCP server exposing the debugger as 37 native tools. The MCP layer is a thin daemon client: it maps tool calls to the same command protocol used by the CLI, then renders the same results. Category Tools Sessions launch, attach, status, list, kill Breakpoints break_at, break_in, catch, watch, unwatch, breakpoints, clear Execution run, cont, step, next, step_out, suspend, resume Inspection where, locals, print, dump, eval, inspect, threads, thread, frame, list_source, set, force_return, lock, threadlocks, raw Discovery classes, methods Exception control ignore Manual Claude-style MCP config for a development build: ```json { "mcpServers": { "jdbg": { "command": "target/debug/jdbg", "args": ["__mcp"] } } } ``` Codex config: ```toml [mcp_servers.jdbg] command = "target/debug/jdbg" args = ["__mcp"] ``` OpenCode config: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "jdbg": { "type": "local", "command": ["target/debug/jdbg", "__mcp"], "enabled": true } } } ``` ## Command Surface Core commands ```text # Session lifecycle jdbg launch [--backend jdb|jdi] [--classpath CP] [--sourcepath SP] [--name N] [-- app-args...] jdbg attach [--backend jdb|jdi] [--host H] [--port P] [--sourcepath SP] [--name N] jdbg status | list | kill [--session ID] jdbg daemon start | stop | status # Breakpoints and watchpoints jdbg break-at [-c ] [-s thread|all] jdbg break-in [--event entry|exit|both] [--args types] [-c ] [-s thread|all] jdbg catch [--mode caught|uncaught|all] jdbg watch [--mode access|modification|all] jdbg unwatch [--mode access|modification|all] jdbg breakpoints | clear jdbg ignore [--mode caught|uncaught|all] # Runtime discovery jdbg classes [pattern] jdbg methods # Execution control jdbg run | cont | step | next | step-out # Inspection jdbg where [--all] | locals | print | dump | eval jdbg inspect [--max-elements N] jdbg threads | thread | frame [n] | list-source [line] jdbg suspend [thread-id] | resume [thread-id] jdbg set jdbg force-return jdbg lock | thread-locks [thread-id] jdbg raw # Setup and maintenance jdbg setup [--remove] [--print] [--target claude,codex,opencode,pi|auto|all|none] [--backend jdb|jdi] [--yes] jdbg update ``` Global flags: | Flag | Purpose | |---|---| | `--session ` | Target a specific debug session. Defaults to the sole live session when unambiguous. | | `--json` | Emit machine-readable JSON instead of human-readable text. | | `--timeout ` | Override per-command timeout. | | `--jdb-path ` | Use an explicit `jdb` executable. For JDI, this also selects the sidecar JDK. | Backend selection is made only when creating a session. The default `jdb` backend is the compatibility path and supports the full command surface. The `jdi` backend can `launch` or `attach` through a local Java sidecar for structured runtime data; it supports `threads`, line `break-at`, method `break-in` entry/exit events, field `watch`/`unwatch`, exception `catch`/`ignore`, breakpoint listing/clearing, `run` for launched sessions, `cont`, `step`, `next`, `step-out`, `where`, `frame`, `locals`, `thread`, `classes`, `methods`, `list-source`, thread suspend/resume, lock inspection, safe JSON `inspect`, expression `print`/`eval`/`dump`, `set`, and non-void `force-return`. JDI `raw` dispatches supported jdb-style aliases through the sidecar instead of writing to a literal jdb stdin. JDI method breakpoints accept `--event entry|exit|both`. Method exit stops include the rendered return value when the target VM provides it. The `jdb` backend keeps method-entry behavior; `--event exit` and `both` fail with an explicit unsupported-backend error. On JDI sessions, `inspect` is intentionally safe and reads fields directly without invoking getters. JDI `print`, `eval`, `dump`, `set`, and `force-return` are executable capabilities: method calls may run in the target JVM and can have side effects. `set` assigns locals, fields, or array elements by evaluating the right hand side as a Java expression. `force-return` evaluates its value expression and forces the current non-void method to return it; void force-return is reported as unsupported. These executable JDI operations require a suspended stop site; running, dead, or exited sessions fail explicitly. The daemon can hold multiple JDI sessions at once. Each session serializes its own in-flight command, while separate sessions continue independently so multiple agents can debug different Java projects concurrently. The JDI sidecar message protocol is length-prefixed JSON over platform-local byte streams: two one-way Named Pipes on Windows, or an AF_UNIX socketpair on Linux/macOS. The Unix socket is handed to the Java 8 sidecar as an inherited fd because Java 8 has no pathname UDS client API. gRPC, protobuf, and direct Rust JDWP are not part of the roadmap. ## Architecture Two clients feed one daemon. The daemon owns live backend sessions and the in-memory session map. ```mermaid flowchart LR CLI["CLI: jdbg "] MCP["MCP: jdbg __mcp"] Daemon["Daemon: session manager"] JdbA["jdb child A"] Jdi["JDI sidecar"] JvmA["JVM A"] JvmB["JVM B"] CLI --> Daemon MCP --> Daemon Daemon --> JdbA --> JvmA Daemon -->|length-prefixed JSON| Jdi --> JvmB ``` The internal dependency direction stays simple: ```text bin -> cli / output -> client / daemon -> backend -> session / jdi -> jdb / jdkpath -> error / protocol / registry ``` See [`DESIGN.md`](DESIGN.md) for the full design reference. ## Requirements | Requirement | Notes | |---|---| | Debug target JDK | JDK 8-21+ with `jdb` on `PATH` or discoverable via `JAVA_HOME`. | | Debug info | Compile Java with `javac -g` for locals and reliable line breakpoints. | | Rust | Rust 1.85+ only when installing through cargo or building from source. | | Source build JDK | JDK 17+ is required to run Gradle and build the JDI sidecar fat jar. Debug targets still support JDK 8+. | For JDWP attach on JDK 8, start the target with `address=5005` or `address=localhost:5005`. `address=*:5005` is JDK 9+ syntax. When building from source, `cargo build` runs the Gradle wrapper in `sidecar/jdi`, builds the fat jar `jdbg-jdi-sidecar.jar`, and copies it next to the `jdbg` binary. Set `JDBG_GRADLE_JAVA_HOME` when the build JDK is different from the target/debuggee JDK. Override sidecar discovery with `JDBG_JDI_SIDECAR_JAR` or the Java runtime with `JDBG_JDI_JAVA`. For JDI sessions, `--jdb-path` also selects the sidecar JDK and lets JDK 8 `tools.jar` be found next to that JDK. Set `JDBG_SKIP_JDI_SIDECAR_BUILD` only when a suitable sidecar jar is already available through `JDBG_JDI_SIDECAR_JAR` or next to the `jdbg` binary. `classes` works without a pattern, but that lists every loaded class; pass a pattern in real application servers. `watch --mode all` creates separate access and modification watchpoints on both backends, so `unwatch --mode modification` removes only the write watchpoint and leaves access watchpoints active. JDI structured inspect covers common list, deque, set, and map implementations without invoking getters. ## Building And Testing ```bash cargo build cargo build --release cargo test cargo test -- --test-threads=1 # mirrors Windows CI when investigating JDI fixture contention ``` Tests cover parser fixtures from real `jdb` transcripts, reader behavior, protocol mapping, MCP tools, sessions, watchpoints, JDI fixture flows, JDI watchpoint flows, expression eval/set/force-return, MCP JDI smoke coverage, sidecar death handling, Java sidecar self-tests, and end-to-end flows where the environment has a JDK. CI runs the matrix on Windows, Linux, and macOS across JDK 8, 11, 17, and 21; Windows runs tests serially to avoid JDWP/JDI fixture process contention. ## License Licensed under the [Apache License 2.0](LICENSE). ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [PieceOfFall](https://github.com/PieceOfFall) - **Source:** [PieceOfFall/jdbg](https://github.com/PieceOfFall/jdbg) - **License:** Apache-2.0 Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-pieceoffall-jdbg - Seller: https://agentstack.voostack.com/s/pieceoffall - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.