livedbg-mcp

실행 중인 C++ 프로세스(PDB 가 있는 개발 빌드)를 읽고 디버깅하는 MCP 서버. cdb 로 실행을 제어하고 값을 보여주며(natvis 적용), DIA 로 심볼·타입을 빠르게 찾는다.

• 코어는 범용 C++ 이고, 언리얼 프로세스면 Unreal.natvis 를 자동으로 로드한다.

• 여러 세션이 같은 프로세스를 동시에 읽을 수 있다. 디버거(bp·스텝·쓰기)는 한 세션만 갖는다.

• 원본 PDB 를 잠그지 않는다. 붙어 있는 동안에도 빌드가 된다.

요구 사항

이 저장소는 cdb.exe 와 msdia140.dll 을 포함하지 않는다. 두 도구는 Microsoft 소프트웨어라서 각자 설치하고, 각 라이선스(WinDbg 사용 약관, Visual Studio 라이선스)에 따라 사용한다. livedbg-mcp 는 설치된 도구를 호출만 한다. cdb 는 재배포가 허용되지 않으므로 이 저장소나 플러그인에 넣어 배포하지 않는다.

기본 위치가 아니면 환경 변수로 지정한다. 환경 변수가 있으면 그것이 우선이다.

status 도구가 찾은 경로와 없는 도구를 알려준다.

타깃 빌드는 /DEBUG:FULL 이어야 한다. /DEBUG:FASTLINK PDB 는 타입 정보가 .obj 에 남아 있어 사본만으로 읽을 수 없다.

Related MCP server: gdbmcp

설치 (Claude Code 플러그인)

claude plugin marketplace add <이 저장소 경로 또는 owner/repo>

claude plugin install livedbg-mcp@livedbg-marketplace

플러그인은 uv run --directory ${CLAUDE_PLUGIN_ROOT} livedbg-mcp 로 서버를 띄운다. 첫 실행 때 uv 가 의존성을 설치한다.

플러그인 없이 쓰려면 MCP 설정에 같은 명령을 넣는다.

도구

심볼은 module!name 으로 한정해서 쓴다 (target!g_State, UnrealEditor-ChronoSpace!...). 비한정 이름은 심볼이 이미 로드된 모듈에서만 찾는다.

debugger_command 와 evaluate 는 cdb 명령·식을 그대로 보내되, 다음은 거부한다. 전용 도구가 안전 절차를 거쳐 처리한다.

이 검사는 실수로 상태를 깨는 것을 막는 장치이지 보안 경계가 아니다. 일부러 우회하려면 할 수 있다.

구조

세션(MCP 클라이언트)마다 서버 프로세스 하나가 뜬다. 데몬은 없다.

MCP 세션 A ── livedbg-mcp ─┬─ reader     cdb -pvr  (비침투·무정지, 몇 개든 가능)
                           ├─ controller cdb -pd   (디버거, 프로세스당 1개 — OS 가 강제)
                           └─ DIA (전용 스레드)
MCP 세션 B ── livedbg-mcp ─── reader     cdb -pvr  (A 가 디버거를 가진 동안에도 읽기 가능)

• 읽기: 멈춰 있으면 controller 가 일관된 스냅숏을, 실행 중이면 reader 가 라이브 값을 읽는다. 실행 중에 읽은 구조체는 필드끼리 시점이 다를 수 있다 (응답의 read 에 표시).

• 디버거 소유권: %LOCALAPPDATA%\livedbg-mcp\locks\<pid>.json 파일의 바이트 범위 잠금이 소유권이다. 다른 세션의 debug attach 는 거절되고, 파일에 적힌 소유 정보(서버 pid, 시작 시각)로 누가 갖고 있는지 알려준다. 잠금은 핸들에 묶여 있어 소유 서버가 어떻게 죽든 OS 가 풀므로, 죽은 소유자의 lock 이 남지 않는다.

• PDB: 로드된 모듈의 메모리 에서 RSDS(GUID/Age)를 읽고, 빌드 출력의 PDB 를 모든 공유 플래그로 짧게 복사한 뒤 DIA 로 GUID/Age 를 검증해 <cache>\<name>.pdb\<GUID><Age>\<name>.pdb 에 넣는다. cdb 는 srv*<cache> 와 -sicv(PE 에 박힌 원본 경로 무시)로 이 사본만 연다. 디스크 DLL 이 아니라 메모리를 보는 이유: 실행 중에 재빌드되면 디스크 쪽은 이미 새 빌드다. 불일치로 판정한 PDB 는 기억해 두고 다시 복사하지 않는다. 다시 빌드해 파일이 바뀌면(크기·수정 시각) 다시 확인한다.

• 조회 속도: 심볼·타입 조회는 DIA, 메모리 읽기는 ReadProcessMemory 로 직접 한다. cdb 는 식 평가와 실행 제어에만 쓴다. 언리얼 에디터(모듈 1,138개)에서 잰 값:

  조회	DIA	cdb
  타입 레이아웃 (AActor)	1.7 ms	8.0 ms (dt)
  와일드카드 함수 검색 (*Tick*)	1.6 ms	83 ms (x)

  도구 응답(모듈 조회 포함)은 15 ms 안팎이다.

안전 규칙과 근거

2026-09-30 에 테스트 타깃으로 직접 측정한 결과에 기반한다.

MCP 클라이언트는 서버의 stdin 을 닫은 뒤 2초 후 프로세스 트리를 강제 종료한다 (Python SDK 기준). 서버는 stdin EOF·시그널·콘솔 종료 이벤트에서 즉시 모든 타깃을 병렬로 detach 한다. 이 종료 경로는 시간이 없으므로:

• 다른 작업(PDB 복사, 언리얼 초기화, 긴 명령)이 타깃을 잡고 있어도 0.2초만 기다리고 진행한다.

• 실행 중이면 break-in 을 1.5초 기다린다. bc * · qd 는 응답을 기다리지 않고 보낸다. cdb 는 입력을 순서대로 처리하므로 진행 중인 명령이 끝나면 바로 실행된다.

• attach 가 설정(심볼 로드) 중이라 아직 등록 전인 controller 도 닫는다.

테스트에서 멈춘 상태로 연결을 끊었을 때 0.11초, attach 설정 도중 끊었을 때 1.03초에 끝났다.

평소의 detach 는 시간 제약이 없으므로, cdb 가 시간 초과된 명령을 아직 처리 중이면 끝날 때까지 기다린 뒤 종료한다 (멈춘 채 cdb 를 죽이면 동결이 확정이기 때문). 명령이 시간 초과되면 다음 명령 전에 표식을 .echo 해서 cdb 와 다시 맞춘다. 맞추지 않으면 늦게 도착한 프롬프트를 정지로 오인해, 타깃은 도는데 '멈춤' 으로 보인다.

남은 위험

• 서버가 정리할 틈 없이 강제 종료되면 (작업 관리자 등) 멈춰 있던 타깃은 동결되고, bp 가 박혀 있던 타깃은 다음 적중 때 크래시한다.

• 서버 종료 순간 cdb 가 2초 넘게 걸리는 명령(큰 PDB 로드 등)을 처리 중이거나, attach 가 첫 프롬프트를 기다리는 중이면 클라이언트의 강제 종료 전에 정리를 끝내지 못할 수 있다.

• 디버깅이 끝나면 detach 한다.

메모리 쓰기

• debug 소유 + 정지 상태에서만 되고, write_memory 한 경로로만 한다 (읽기 세션도 메모리를 쓸 수 있으므로 debugger_command·evaluate 의 쓰기는 거부한다).

• 타입·크기는 PDB 로 확인하고, 쓰는 범위의 모든 페이지가 쓰기 가능한 비실행 페이지인지 검사하고, 쓴 뒤 되읽어 검증한다.

• 값 형식: 정수(10진·0x), 실수, true/false, hex:0a0b...(정확히 그 크기의 바이트). 구조체(크기가 1·2·4·8 이어도, 예: TObjectPtr)에는 정수를 받지 않고 hex: 만 받는다.

• 비트필드는 해당 비트만 바꾸고 같은 저장 단위의 이웃 비트는 그대로 둔다. dx 는 비트필드의 주소를 소속 바이트 주소로 돌려줘 일반 필드와 구분되지 않으므로, C++ 식 평가기(??)로 판별하고 비트 위치는 부모의 원시 레이아웃에서 읽는다.

• 모든 쓰기는 기록되고 undo_write 로 되돌린다. 그 사이 값이 바뀌었으면 덮어쓰지 않는다.

• 아무 데서나 멈춘 상태는 다른 스레드가 그 객체를 갱신하던 도중일 수 있고, 최적화 코드는 값을 레지스터에 들고 있을 수 있다. 가능하면 객체가 조용한 지점(프레임 시작 등)에 bp 를 걸고 쓴다.

언리얼

UE 5.8 에디터(Development, Win64)에서 만들고 검증했다. 다른 엔진 버전·게임 빌드에서는 테스트하지 않았다. 구조체 오프셋은 PDB 에서 읽고 모르는 구조는 추정 대신 오류를 내도록 했지만, 동작은 보장하지 않는다. 다른 버전에서 쓰기 전에 tests\test_unreal_live.py 를 돌려 본다.

natvis 는 cdb 에서 일부만 동작한다

Unreal.natvis(FString, TArray, FName ...)는 PDB 에 임베드되지 않는다 (모듈별 natvis 만 들어감). 엔진 설치본의 Engine\Extras\VisualStudioDebugging\Unreal.natvis 를 자동으로 .nvload 한다.

하지만 이 파일은 Visual Studio 디버거 기준으로 작성돼 있고, cdb 의 dx 는 natvis 를 따로 구현한 것이라 일부가 깨진다 (5.8 에서 확인).

TArray, FString, 수학 타입은 dx 로 정상 표시된다. VS 디버거 엔진(vsdbg)은 라이선스상 다른 도구에서 쓸 수 없다.

언리얼 해석기 (ue_*)

자주 쓰는 타입은 natvis 대신 메모리에서 직접 해석한다. 구조체 오프셋은 전부 PDB(DIA)에서 가져오고, 해석마다 검증을 넣어 구조가 바뀌면 조용히 틀린 값 대신 오류를 낸다.

• 진입점은 UE 가 모든 모듈에 심어 두는 디버그 심볼(GNameBlocksDebug, GObjectArrayForDebugVisualizers)이라 엔진 PDB 없이 게임 모듈 PDB 만으로 동작한다. 기준 모듈은 게임 본체 → 플러그인 → 엔진 순으로 자동 선택한다. 게임 본체의 PDB 를 쓸 수 없으면(실행 중인 DLL 과 빌드가 다름 등) 다른 모듈로 해석하고, ue_* 결과와 status 에 이유를 표시한다. 이때 엔진 공통 타입(FName, 객체, 컨테이너)은 보이지만 게임 클래스의 필드는 보이지 않는다. 커밋된 DLL 을 pull 받은 뒤 다시 링크되지 않으면 이렇게 된다. 게임 모듈을 다시 빌드하거나 PDB 를 DLL 과 함께 받는다.

• ue_worlds / ue_find_objects 결과의 type_module 이 식에서 캐스트할 때 쓰는 모듈 한정자다. 예: ue_inspect(pid, "*(UnrealEditor_ChronoSpace!ACSCharacterPlayer*)0x1e1d3c6e600", depth=1)

• 구조체는 PDB 필드로 depth 만큼 내려가고, 베이스 클래스는 이름만 둔다 (UObject 계층은 필드가 수백 개).

• 희소 델리게이트 저장소처럼 인스턴스 레이아웃이 PDB 에 없는 엔진 내부 TMap 은, 다른 TMap 인스턴스의 컨테이너 배치 + 키·값 크기·정렬로 원소 위치를 계산한다 (할당 비트 검증이 계산 실수를 잡는다).

• 미지원: FText. 블루프린트 변수(리플렉션)는 다음 단계.

그 밖의 주의

• UE 모듈은 빌드 구성과 무관하게 기본 /GR- (RTTI 꺼짐)다 (CppCompileEnvironment.bUseRTTI = false). dynamic_type 은 vftable 심볼(??_7Class@@6B@)로 실제 클래스를 판별하므로 RTTI 가 필요 없다.

• 런처 엔진은 "디버깅용 에디터 심볼" 옵션을 켜야 엔진 PDB 가 설치된다. 설치했다면 LIVEDBG_SYMBOL_DIRS 에 Engine\Binaries\Win64 를 넣어 복사 없이 쓴다 (재빌드되지 않으므로 안전).

• 블루프린트 변수는 PDB 에 없다 (리플렉션에만 있다). 아직 지원하지 않는다.

• 리슨 서버에서 한쪽을 오래 멈추면 상대가 네트워크 타임아웃으로 끊긴다.

• Development 에디터는 최적화 빌드라 locals 에서 지역 변수가 사라져 있을 수 있다.

• cdb 는 파이프 입출력을 시스템 ANSI 코드 페이지(한국어 Windows 는 CP949)로 처리하므로 서버도 그 인코딩으로 주고받는다. FString(UTF-16)의 한글은 evaluate 에서 정상으로 보인다. 메모리의 UTF-8 char* 문자열과 UTF-8 소스 파일의 줄 표시(lsa)는 cdb 가 이미 깨진 채로 출력한다. ue_inspect 는 cdb 를 거치지 않고 직접 디코딩하므로 영향이 없다.

개발

테스트는 다섯 단계다. 위에서부터 차례로 돌린다.

powershell -NoProfile -ExecutionPolicy Bypass -File tests\fixtures\build.ps1

uv run python tests\test_units.py

uv run python tests\test_mcp_e2e.py

uv run python tests\test_unreal_decoders.py

uv run python tests\test_unreal_live.py

빌드 스크립트는 실행 정책이 막힌 PC 를 위해 -ExecutionPolicy Bypass 로 돌린다 (그 프로세스에만 적용된다). test_unreal_live.py 는 pid 를 생략하면 UnrealEditor.exe 를 찾는다.

e2e 시나리오 (G 가 약 35초 걸려 전체는 몇 분 걸린다):

끝나면 cdb 프로세스가 남지 않았는지 확인한다.

라이선스

MIT (LICENSE). 의존 패키지 mcp, comtypes 도 MIT 다. cdb.exe 와 msdia140.dll 은 이 저장소에 포함되지 않으며 이 라이선스의 대상이 아니다 (요구 사항 참고).