KD-MCP

kd-mcp는 Windows 커널 디버깅을 위해 kd.exe 또는 WinDbg를 제어하는 MCP(Model Context Protocol) 서버입니다.

이 프로젝트는 Windows 호스트에서 실행되며, KDNET을 통해 Windows 게스트 VM의 커널 디버깅 세션을 자동으로 연결하고 제어할 수 있습니다.

Features

• KDNET 자동 연결
• kd.exe 제어
• WinDbg 제어
• 상태 파일 기반 자동 연결
• 디버거 명령 실행
• 디버거 출력 수집
• KD break 상태에서 WinRM 재시도를 돕는 resume_for_winrm
• 현재 연결 상태 조회
• 세션 종료
• WinRM-MCP 연동

Architecture

KD-MCP는 항상 호스트 Windows에서 실행됩니다.

게스트 Windows에서는 KDNET 커널 디버깅만 활성화되어 있으면 됩니다.

Host Windows
  ├─ Codex / MCP Client
  ├─ kd-mcp
  ├─ kd.exe
  └─ WinDbg

Guest Windows VM
  ├─ Windows Kernel
  └─ KDNET Target

Integration With WinRM-MCP

KD-MCP는 WinRM-MCP와 함께 사용하는 것을 권장합니다.

WinRM-MCP는 게스트 VM 설정과 KDNET 활성화를 담당하고, KD-MCP는 실제 커널 디버거 연결과 제어를 담당합니다.

일반적인 작업 순서는 다음과 같습니다.

1. WinRM-MCP 실행
2. configure_kdnet()
3. 게스트 재부팅
4. KD-MCP 실행
5. start_from_state()
6. KDNET 연결
7. 커널 디버깅 시작

KD가 break 또는 breakpoint 상태에 들어가면 게스트 커널, 스케줄러, 네트워크 스택이 멈출 수 있습니다. 이 상태에서는 WinRM도 응답하지 않는 것이 정상입니다.

WinRM 작업이 timeout되거나 연결 실패가 발생하고 KD가 break 상태라면, 먼저 resume_for_winrm 또는 continue_go를 호출하여 g 명령을 실행하고 기본 5초 동안 기다린 뒤 WinRM 작업을 다시 시도합니다.

1. kd-mcp: resume_for_winrm(session_id)
2. 약 5초 대기
3. winrm-mcp: health_check 또는 기존 WinRM 작업 재시도

State File

WinRM-MCP의 configure_kdnet()는 상태 파일을 생성합니다.

상태 파일에는 다음 정보가 포함됩니다.

• Guest Host
• Host IP
• KDNET Port
• KDNET Key
• 생성 시각

KD-MCP는 이 정보를 사용하여 자동으로 디버거를 연결합니다.

Requirements

호스트에는 다음이 필요합니다.

• Windows 10/11
• Windows Server
• Python 3.10 이상
• kd.exe 또는 WinDbg
• Debugging Tools for Windows

게스트에는 다음이 필요합니다.

• Windows 10/11
• Windows Server
• KDNET 지원 커널
• 네트워크 연결 가능 환경

Installation

git clone https://github.com/haoylle/26_KD-MCP.git
cd 26_KD-MCP
.\scripts\install.ps1

설치 후 상태 파일 경로와 디버거 실행 경로를 설정합니다.

Configuration

KD-MCP는 상태 파일을 읽어 KDNET 연결을 구성합니다.

일반적으로 다음 정보를 사용합니다.

{
  "schema": "winrm-kd-session-v1",
  "guest_host": "192.168.122.50",
  "host_ip": "192.168.122.1",
  "port": 50000,
  "key": "1.2.3.4"
}

WinRM-MCP와 KD-MCP는 동일한 포트, 키, 상태 파일을 사용해야 합니다.

continue_wait_sec는 continue_go 또는 resume_for_winrm이 g 명령을 보낸 뒤 기다리는 기본 시간입니다.

kd:
  continue_wait_sec: 5.0

MCP Client Configuration

{
  "mcpServers": {
    "kd": {
      "command": "C:\\tools\\26_KD-MCP\\.venv\\Scripts\\kd-mcp.exe"
    }
  }
}

Tools

start_from_state

상태 파일을 읽어 KDNET 연결을 시작합니다.

대부분의 사용자는 이 기능을 통해 자동 연결을 수행하면 됩니다.

start_kd

포트, 키, 타겟 값을 직접 지정하여 KDNET 연결을 수행합니다.

kd_command

kd.exe 또는 WinDbg에 디버거 명령을 전달합니다.

예시는 다음과 같습니다.

!process 0 0
lm
!thread
k

break_in

실행 중인 KD 세션에 break 신호를 보냅니다.

break 상태에서는 게스트 커널과 네트워크 스택이 멈출 수 있으므로 WinRM이 timeout되는 것이 정상일 수 있습니다.

continue_go

KD 세션에 g 명령을 보내 게스트 실행을 재개합니다.

wait_sec 값을 생략하면 설정 파일의 kd.continue_wait_sec 값만큼 기다린 뒤 반환합니다.

resume_for_winrm

KD break 또는 bp 상태에서 WinRM을 다시 사용해야 할 때 호출하는 helper입니다.

내부적으로 g 명령을 실행하고 기본 5초 동안 기다린 뒤, WinRM 재시도를 권장하는 결과를 반환합니다.

read_output

현재 KD 세션의 출력 버퍼를 반환합니다.

stop_kd

현재 디버깅 세션을 종료합니다.

list_sessions

현재 활성 KD 세션 목록을 반환합니다.

Common Commands

커널 디버깅 시 자주 사용하는 명령은 다음과 같습니다.

!process 0 0
!thread
!handle
!pool
!pte
lm
k
r

필요에 따라 WinDbg 확장 명령도 사용할 수 있습니다.

Troubleshooting

Cannot connect to KDNET target

다음을 확인합니다.

• KDNET 설정 적용 여부
• 게스트 재부팅 여부
• 포트 번호
• KDNET Key
• 방화벽 설정

WinRM does not respond while KD is attached

KD가 단순히 연결되어 있는 상태라면 WinRM은 동작할 수 있습니다.

하지만 KD가 break 상태이거나 breakpoint에 걸려 kd> 프롬프트에서 멈춰 있으면 게스트 커널과 네트워크 스택이 멈추므로 WinRM이 응답하지 않을 수 있습니다.

이 경우 다음 순서로 처리합니다.

1. resume_for_winrm(session_id)
2. 5초 정도 대기
3. WinRM 작업 재시도

Waiting to reconnect

게스트가 아직 재부팅 중이거나 KDNET 설정이 적용되지 않았을 수 있습니다.

게스트에서 다음 명령을 확인합니다.

bcdedit /dbgsettings
bcdedit /enum {current}

State file not found

WinRM-MCP의 configure_kdnet()가 상태 파일을 생성했는지 확인합니다.

두 MCP 서버가 동일한 상태 파일 경로를 사용해야 합니다.

Security Notes

KDNET 연결 정보는 신뢰할 수 있는 환경에서만 사용해야 합니다.

상태 파일에는 디버깅 연결 정보가 포함되어 있으므로 접근 권한을 적절히 제한하는 것이 좋습니다.

License

MIT License