livedbg-mcp
by Lagooneng
README.md
# livedbg-mcp
**English** | [한국어](README.ko.md)
An MCP server that reads and debugs a running C++ process (a development build with PDBs).
It drives execution and shows values through cdb (with natvis), and looks up symbols and types quickly through DIA.
- The core is generic C++. For Unreal processes it loads `Unreal.natvis` automatically.
- Several sessions can read the same process at once. Only one session owns the debugger (breakpoints, stepping, writes).
- It never locks the original PDB, so you can keep building while attached.
## Requirements
| Tool | Default location | If missing |
|---|---|---|
| cdb | `%LOCALAPPDATA%\Microsoft\WindowsApps\cdbX64.exe` | `winget install Microsoft.WinDbg` |
| msdia140.dll | `DIA SDK\bin\amd64\msdia140.dll` of the VS instance found by vswhere | Install the VS "Desktop development with C++" workload |
| uv | PATH | `winget install astral-sh.uv` |
**This repository does not include cdb.exe or msdia140.dll.** Both are Microsoft software: install them yourself
and use them under their own licenses (WinDbg terms of use, Visual Studio license). livedbg-mcp only calls the installed tools.
cdb may not be redistributed, so it is not shipped in this repository or the plugin.
If a tool is not in its default location, point to it with an environment variable. Environment variables take precedence.
| Environment variable | Meaning |
|---|---|
| `LIVEDBG_CDB_PATH` | Path to cdb.exe |
| `LIVEDBG_MSDIA_PATH` | Path to msdia140.dll |
| `LIVEDBG_CACHE_DIR` | Location of the PDB shadow cache and lock files (default `%LOCALAPPDATA%\livedbg-mcp`) |
| `LIVEDBG_SYMBOL_DIRS` | PDB folders that are never rebuilt (`;`-separated). Opened in place without copying. Example: `Engine\Binaries\Win64` of an installed (non-source) engine |
| `LIVEDBG_MS_SYMBOLS` | `1` downloads and caches OS symbols from the Microsoft symbol server (off by default; uses the network) |
The `status` tool reports the paths it found and which tools are missing.
The target must be built with **`/DEBUG:FULL`**. A `/DEBUG:FASTLINK` PDB leaves type information in the `.obj` files, so a copy of the PDB alone cannot be read.
## Installation (Claude Code plugin)
```bash
claude plugin marketplace add <path to this repository or owner/repo>
```
```bash
claude plugin install livedbg-mcp@livedbg-marketplace
```
The plugin starts the server with `uv run --directory ${CLAUDE_PLUGIN_ROOT} livedbg-mcp`. On first run uv installs the dependencies.
To use it without the plugin, put the same command in your MCP configuration.
## Tools
| Category | Tools |
|---|---|
| Session | `status` `list_processes` `attach` `detach` `modules` `prepare_symbols` |
| Symbols (DIA) | `find_symbols` `type_layout` `symbol_at` `dynamic_type` |
| Read | `evaluate` (cdb `dx` + natvis) `read_memory` `debugger_command` (for inspection, see below) |
| Execution control | `set_breakpoint` `list_breakpoints` `clear_breakpoint` `wait` `break_in` `resume` `step` `stack` `locals` |
| Write | `write_memory` `undo_write` `write_history` |
| Unreal | `ue_inspect` `ue_find_objects` `ue_worlds` |
Qualify symbols as `module!name` (`target!g_State`, `UnrealEditor-ChronoSpace!...`).
Unqualified names are only looked up in modules whose symbols are already loaded.
`debugger_command` and `evaluate` pass cdb commands and expressions through as-is, but refuse the following. The dedicated tools handle these with the proper safety steps.
| Refused | Use instead |
|---|---|
| Execution commands (`g`, `p`, `t` families, including thread-prefixed forms like `~0 g`) | `resume` `step` |
| Session lifetime commands (`q` `qd` `.kill` `.detach` ...), freezing or suspending threads | `detach` |
| Memory and register writes (`eb` `ed` `f` `m`, `dx x = 1`, `++` `--`, breakpoint conditions containing an assignment) | `write_memory` |
| Constructs that run other commands indirectly (`.if` blocks, scripts, aliases, `!for_each_*`, dx `ExecuteCommand`) | — |
This check **guards against accidentally breaking state; it is not a security boundary.** It can be bypassed on purpose.
## Architecture
Each session (MCP client) runs its own server process. There is no daemon.
```
MCP session A ── livedbg-mcp ─┬─ reader cdb -pvr (noninvasive, never stops the target, any number)
├─ controller cdb -pd (debugger, one per process — enforced by the OS)
└─ DIA (dedicated thread)
MCP session B ── livedbg-mcp ─── reader cdb -pvr (can read while A owns the debugger)
```
- **Reads**: when the target is stopped, the controller reads a consistent snapshot; while it runs, the reader reads live values.
A struct read while running may have fields from different moments (shown in the response's `read`).
- **Debugger ownership**: ownership is a byte-range lock on `%LOCALAPPDATA%\livedbg-mcp\locks\<pid>.json`.
Another session's debug attach is refused, and the owner info written in the file (server pid, start time) tells who holds it.
The lock is tied to a handle, so the OS releases it however the owning server dies; a dead owner never leaves a stale lock.
- **PDBs**: it reads the RSDS record (GUID/Age) from the loaded module **in memory**, briefly copies the build output's PDB
with all share flags, verifies GUID/Age with DIA, and stores it as `<cache>\<name>.pdb\<GUID><Age>\<name>.pdb`.
cdb opens only this copy, through `srv*<cache>` and `-sicv` (ignore the original path embedded in the PE).
Why memory and not the DLL on disk: if you rebuild while it runs, the file on disk is already the new build.
A PDB judged mismatched is remembered and not copied again. If it is rebuilt and the file changes (size, modification time), it is checked again.
- **Lookup speed**: symbol and type lookups go through DIA, memory reads go directly through `ReadProcessMemory`.
cdb is used only for expression evaluation and execution control. Measured in an Unreal editor (1,138 modules):
| Lookup | DIA | cdb |
|---|---|---|
| Type layout (`AActor`) | 1.7 ms | 8.0 ms (`dt`) |
| Wildcard function search (`*Tick*`) | 1.6 ms | 83 ms (`x`) |
A tool response (including the module lookup) takes around 15 ms.
## Safety rules and their basis
Based on direct measurements against a test target on 2026-09-30.
| Measurement | Result | Therefore |
|---|---|---|
| Opening a PDB for writing (as the linker does) while dbghelp or DIA has it open | Sharing violation for both | Never open the original, only a copy |
| Killing cdb while running, without `-pd` | Target terminates | The controller always uses `-pd` |
| `-pd`, running, no breakpoints, kill cdb | Target survives | — |
| `-pd`, kill cdb while stopped at a breakpoint | **Target frozen permanently** (RIP = bp+1, unrecoverable) | Detach must always go (stop if running) → `bc *` → `qd` |
| `-pd`, kill cdb while running with breakpoints inserted | `0xCC` left behind → crash when hit | Same as above |
| `cdb -pvr` while an invasive cdb is attached | Read succeeds, no effect on the target | Multiple read sessions coexist |
| `bc *` → `qd` while stopped | Target keeps running | Normal shutdown path |
MCP clients close the server's stdin and force-kill the process tree **2 seconds** later (Python SDK behavior).
On stdin EOF, signals, or console close events, the server immediately detaches all targets in parallel. This shutdown path has little time, so:
- Even if another operation (PDB copy, Unreal initialization, a long command) holds the target, it waits only 0.2 seconds and proceeds.
- If the target is running, it waits 1.5 seconds for the break-in. `bc *` and `qd` are sent without waiting for a reply; cdb processes
input in order, so they run as soon as the command in progress finishes.
- It also closes a controller that is still being set up (loading symbols) and not yet registered.
In tests, disconnecting while stopped finished in 0.11 seconds, and disconnecting during attach setup in 1.03 seconds.
A normal `detach` has no time limit, so if cdb is still processing a timed-out command, it waits for that to finish before shutting down
(killing cdb while stopped guarantees a freeze). After a command times out, the next command first `.echo`es a marker to resynchronize with cdb.
Without that, a late prompt would be mistaken for a stop, and the target would appear "stopped" while actually running.
**Remaining risks**
- If the server is killed without a chance to clean up (Task Manager, etc.), a stopped target freezes,
and a target with breakpoints inserted crashes at the next hit.
- If, at the moment of shutdown, cdb is processing a command that takes more than 2 seconds (loading a large PDB, etc.) or attach is
waiting for its first prompt, cleanup may not finish before the client's forced kill.
- Detach when you are done debugging.
## Memory writes
- Only allowed while owning the debugger and stopped, and only through `write_memory` (read sessions can also write memory,
so writes through `debugger_command` or `evaluate` are refused).
- Type and size are checked against the PDB, every page in the written range is checked to be writable and non-executable, and the value is read back to verify.
- Value formats: integers (decimal or `0x`), floats, `true`/`false`, `hex:0a0b...` (exactly that many bytes). Structs (even of size 1, 2, 4 or 8,
e.g. `TObjectPtr`) do not accept integers, only `hex:`.
- A bitfield write changes only its own bits and leaves neighboring bits in the same storage unit untouched. dx returns a bitfield's address
as the address of its containing byte, indistinguishable from a normal field, so bitfields are detected with the C++ expression evaluator (`??`)
and the bit position is read from the parent's raw layout.
- Every write is recorded and can be reverted with `undo_write`. If the value changed in the meantime, it is not overwritten.
- A target stopped at an arbitrary point may be in the middle of another thread updating that object, and optimized code may
hold the value in a register. When possible, set a breakpoint where the object is quiet (start of a frame, etc.) and write there.
## Unreal
> **Built and verified on the UE 5.8 editor (Development, Win64).** Other engine versions and game builds are untested.
> Struct offsets are read from the PDB, and unknown structures raise errors instead of guessing, but correct behavior is not guaranteed.
> Run `tests\test_unreal_live.py` before using it with another version.
### natvis only partly works in cdb
`Unreal.natvis` (FString, TArray, FName ...) is not embedded in the PDB (only per-module natvis files are).
The server automatically `.nvload`s `Engine\Extras\VisualStudioDebugging\Unreal.natvis` from the engine installation.
That file is written for the Visual Studio debugger, and cdb's `dx` has its own natvis implementation,
so some parts break (confirmed on 5.8).
| Cause | Broken types |
|---|---|
| dx interprets the reference cast `(T&)x` differently | FName → UObject names, soft paths, gameplay tags |
| Format specifiers dx does not know (`X` `Xb` `xb` `na` ...) | FGuid, hash and ID types |
| TSet display rule fails (cause not determined) | TSet, TMap |
TArray, FString and math types display correctly with dx. The VS debugger engine (vsdbg) may not be used by other tools under its license.
### Unreal decoders (`ue_*`)
Frequently used types are decoded directly from memory instead of through natvis. All struct offsets come from the PDB (DIA),
and each decoder validates what it reads, so a changed structure produces an error rather than a silently wrong value.
| Type | Validation |
|---|---|
| FName | ComparisonId of the name pool entry matches, block range. Builds without ComparisonId reject control characters and invalid UTF-16 |
| Enums | Size and signedness from the underlying type in the PDB (200 in `enum class E : uint8` is 200). Error instead of guessing if the definition is missing |
| UObject references (TObjectPtr, TSubclassOf, pointers) → name, class, full path | Global object array[InternalIndex] == this address |
| TWeakObjectPtr | SerialNumber of the object array item matches (stale otherwise) |
| TArray / TSet / TMap | Number of allocated bits == ArrayNum − NumFreeIndices |
| TCompactSet (the new TSet implementation in 5.8, `UE_USE_COMPACT_SET_AS_DEFAULT`) | 0 ≤ NumElements ≤ MaxElements |
| TSoftObjectPtr / TSoftClassPtr, FString | Go through the FName and array validation |
| Dynamic delegates | Binding = (weak object, function FName) |
| Sparse delegates (`OnComponentBeginOverlap`, etc.) | Looked up in the global `FSparseDelegateStorage`. Given only the field, the owner object is derived from the registered offset map and validated as a UObject |
| Native delegates | Kind determined from the binding instance's vtable symbol → target object and function symbol. Bindings in modules without a PDB (engine) show as `unknown` |
- The entry points are debug symbols UE plants in every module (`GNameBlocksDebug`, `GObjectArrayForDebugVisualizers`),
so it works **with only the game module's PDB, no engine PDBs**. The base module is chosen automatically: game module → plugins → engine.
If the game module's PDB cannot be used (built differently from the running DLL, etc.), another module is used and the reason is shown
in the `ue_*` results and `status`. Common engine types (FName, objects, containers) are still visible, but game class fields are not.
This happens when a committed DLL is pulled and not relinked. Rebuild the game module, or get the PDB together with the DLL.
- `type_module` in the `ue_worlds` / `ue_find_objects` results is the module qualifier to use when casting in expressions.
Example: `ue_inspect(pid, "*(UnrealEditor_ChronoSpace!ACSCharacterPlayer*)0x1e1d3c6e600", depth=1)`
- Structs are expanded through their PDB fields down to `depth`; base classes are shown by name only (the UObject hierarchy has hundreds of fields).
- For **engine-internal TMaps whose instance layout is not in the PDB**, such as the sparse delegate storage, element positions are computed
from another TMap instance's container layout plus key/value sizes and alignment (the allocated-bit validation catches computation mistakes).
- Not supported: FText. Blueprint variables (reflection) are the next step.
### Other notes
- UE modules are `/GR-` (RTTI off) by default regardless of build configuration (`CppCompileEnvironment.bUseRTTI = false`).
`dynamic_type` determines the actual class from the vftable symbol (`??_7Class@@6B@`), so RTTI is not needed.
- For a launcher engine, the "Editor symbols for debugging" option must be enabled to install engine PDBs. If installed,
add `Engine\Binaries\Win64` to `LIVEDBG_SYMBOL_DIRS` to use them in place without copying (safe, since they are never rebuilt).
- Blueprint variables are not in the PDB (they only exist in reflection). Not supported yet.
- On a listen server, stopping one side for long makes the other side drop on a network timeout.
- The Development editor is an optimized build, so local variables may be missing from `locals`.
- cdb handles pipe I/O in the system ANSI code page (CP949 on Korean Windows), so the server uses that encoding too.
Korean text in `FString` (UTF-16) shows correctly in `evaluate`. UTF-8 `char*` strings in memory and line display of UTF-8 source files
(`lsa`) come out already garbled from cdb. `ue_inspect` decodes directly without going through cdb, so it is unaffected.
## Development
The tests run in five steps, in order from the top.
| Step | Test | Needs | Checks |
|---|---|---|---|
| 1 | `tests\fixtures\build.ps1` | VS C++ workload | Builds the integration test target (`/GR-`, no RTTI) into `tests\fixtures\bin` |
| 2 | `tests\test_units.py` | Nothing (no cdb or target) | Command blocking, address parsing, value and bitfield encoding, owner lock, PDB cache races, late break-in detection |
| 3 | `tests\test_mcp_e2e.py` | Target from step 1, cdb, msdia | Starts the server through a real MCP client (stdio) and attaches to the target. Scenarios below |
| 4 | `tests\test_unreal_decoders.py` | Nothing | Container decoding on synthetic memory (TCompactSet is checked here because a live instance is hard to catch) |
| 5 | `tests\test_unreal_live.py [pid]` | A running Unreal editor | Attaches read-only to the editor and cross-checks decoder results against values dx displays correctly (TArray counts, etc.). Does not stop the editor. Run after upgrading the engine |
```bash
powershell -NoProfile -ExecutionPolicy Bypass -File tests\fixtures\build.ps1
```
```bash
uv run python tests\test_units.py
```
```bash
uv run python tests\test_mcp_e2e.py
```
```bash
uv run python tests\test_unreal_decoders.py
```
```bash
uv run python tests\test_unreal_live.py
```
The build script runs with `-ExecutionPolicy Bypass` for machines where the execution policy blocks it (applies to that process only).
`test_unreal_live.py` finds `UnrealEditor.exe` if the pid is omitted.
e2e scenarios (G takes about 35 seconds, so the whole run takes a few minutes):
| Scenario | Checks |
|---|---|
| A | Core flow: debug attach, live reads, type layout, dynamic type without RTTI, breakpoints, writes while stopped. A second session's debug attach is refused, read allowed, writes refused. The target survives and keeps running when the client disconnects while it is stopped |
| B | All remaining tools: conditional and source-line breakpoints, step, locals, break_in, symbol_at, read_memory, write and undo, bitfield writes, refusing code and struct writes, command blocking |
| C | A real linker rebuild that overwrites the same PDB succeeds while attached, and a new session detects the PDB mismatch |
| D | If debug attach fails during setup, the target is not left stopped, the lock is released, and attaching works again |
| E | After a command times out, the running/stopped state still matches reality |
| F | If the server shuts down during debug attach setup, the not-yet-registered controller is closed and the target survives |
| G | Detaching while cdb is still processing a timed-out command does not kill it with the target stopped |
When done, check that no cdb processes are left behind.
## License
MIT (`LICENSE`). The dependencies mcp and comtypes are MIT as well.
cdb.exe and msdia140.dll are not included in this repository and are not covered by this license (see Requirements).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues