Skip to main content
Glama
livedbg-mcp

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).