26_KD-MCP
haoylle/26_KD-MCP
MCP server for automating KDNET-based Windows kernel debugging with kd.exe and WinDbg, designed to integrate with WinRM-MCP.
Instalação
npx convez-ai haoylle/26_KD-MCP1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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