mcp-windows-debug

stdio를 통해 OpenCode에 연결되는 TypeScript/Node.js MCP 서버로, 모델에게 Windows 머신을 보고 조작할 수 있는 능력을 부여합니다. 프로젝트 파일을 읽고, 스크린샷을 캡처하고, 마우스를 움직이고 키를 입력하며, 대상 애플리케이션에 대해 자동 디버그 루프를 실행합니다.

안전성이 이 설계 전체의 핵심입니다. 별도의 네이티브 C++ watchdog 프로세스가 전역 저수준 키보드 및 마우스 후크를 설치하여, 모델이 입력을 주입하는 동안에도 사람이 항상 보호된 중단 버튼을 클릭할 수 있게 합니다. Node MCP 서버와 watchdog은 서로 독립적인 두 프로세스이므로, Node 이벤트 루프가 멈춰도 입력이 얼어붙거나 안전 계층이 조용히 사라지지 않습니다. 모든 작업은 세 개의 관문을 통과합니다: 거버너(governor), 신선도 검사(freshness check), 창 범위 가드(window-scoping guard). 자세한 내용은 아래 보안 모델 섹션을 참조하세요.

이것은 Windows 전용 v1입니다. macOS 및 Linux 백엔드는 나중에 동일한 공급자 인터페이스 뒤에 연결될 예정이며, 아직 구현되지 않았습니다.

빠른 시작

git clone https://github.com/wgm66/mcp-windows-debug.git
cd mcp-windows-debug
npm install && npm run build
cd src\watchdog && build.bat   # build the C++ watchdog (MSVC required)
node dist\index.js --validate-config  # verify your OpenCode config

Related MCP server: Desktop Commander MCP Server

설치

전제 조건:

• Node.js 20 이상, 그리고 npm

• Windows 10 또는 11

• 관리자 권한 — watchdog 실행에만 필요합니다(아래 참조)

의존성을 설치하고 TypeScript를 빌드합니다:

npm install
npm run build

npm run build는 tsc를 실행하여 dist/index.js를 생성하며, 이것이 OpenCode가 실행하는 진입점입니다.

다음으로 watchdog을 빌드합니다. MSVC로 컴파일된 C++ Win32 콘솔 앱이며, CMake, MSBuild, MinGW는 사용하지 않습니다:

cd src\watchdog
build.bat

build.bat는 VS2019 Build Tools(MSVC 14.29)와 Windows SDK가 필요합니다. 툴체인 경로는 스크립트에 하드코딩되어 있으므로 기본 설치 위치에 있어야 합니다. 출력물은 src\watchdog\watchdog.exe이며, Node 서버는 런타임에 프로젝트 루트를 기준으로 이 파일을 찾습니다.

watchdog은 관리자 권한으로 실행되어야 합니다. 전역 저수준 후크는 비관리자 프로세스에서는 설치가 거부됩니다. 이를 충족하는 두 가지 방법:

1. 관리자 터미널에서 OpenCode를 시작하여, 생성된 watchdog이 승격을 상속받게 합니다.

2. 디버그 세션을 시작하기 전에 직접 관리자 권한으로 watchdog을 미리 실행합니다.

이 빌드에서 서버는 자체적으로 UAC 승격을 요청할 수 없습니다. 승격된 watchdog에 도달할 수 없는 디버그 세션은 ELEVATION_REQUIRED로 실패하며, 비관리자 watchdog 실행은 ERROR_ACCESS_DENIED를 출력하고 조용히 아무것도 하지 않는 대신 코드 1로 종료됩니다.

OpenCode 구성

OpenCode 구성(opencode.json)의 mcp 키 아래에 windows-debug 항목을 추가하세요. 키가 mcpServers가 아니라 mcp임에 유의하세요:

{
  "mcp": {
    "windows-debug": {
      "type": "local",
      "command": ["node", "<abs-path>/dist/index.js"],
      "environment": {}
    }
  }
}

<abs-path>를 이 프로젝트의 절대 경로로 바꾸고, JSON에서 이스케이프가 필요 없도록 슬래시를 사용하세요. 예를 들어 프로젝트가 G:\工程开发\AI全场景图形化调试에 있다면 명령은 다음과 같아집니다:

"command": ["node", "G:/工程开发/AI全场景图形化调试/dist/index.js"]

command는 argv 토큰의 배열입니다. environment 맵은 기본적으로 비어 있습니다. 세션별 watchdog 토큰은 서버 자체가 생성하여 프로세스 환경을 통해 watchdog에 전달하므로 여기에 설정할 것이 없습니다.

사용법

디버그 세션은 고정된 형태를 가집니다: 보호된 중단 버튼을 등록하고, 세션을 시작하고, 모델이 자동 디버그 루프를 통해 작업하게 한 다음, 세션을 종료합니다.

중단 버튼 등록. 세션은 보호 영역이 0개인 상태로 시작할 수 없습니다. start_debug_session에 하나 이상의 화면 사각형을 regions({ x, y, w, h, id }, 물리 픽셀)로 전달하세요. 등록된 영역 내부를 향한 주입 입력은 watchdog에 의해 차단됩니다. 사람의 입력은 항상 통과하므로, 해당 영역은 모델이 도달할 수 없는 물리적 중단 구역이 보장됩니다. 영역은 세션 수명 동안 추가 전용(append-only)입니다. 시작 후에는 제거하거나 이동할 수 있는 방법이 의도적으로 없습니다.

세션 시작. start_debug_session은 watchdog을 생성하거나 연결하고, 모든 영역을 등록하고, 하트비트를 시작합니다. 오케스트레이터는 현재 포그라운드 창을 디버그 대상으로 모니터링하기 시작합니다. sandbox: 'desktop'를 전달하면 SendInput(실제 커서를 움직임) 대신 개인 Win32 데스크톱(PostMessage 기반, 사용자의 실제 마우스/키보드는 건드리지 않음)에서 주입을 실행합니다. sandbox: 'rdp'는 예약되어 있지만 v1에서는 구현되지 않았습니다.

자동 디버그 루프. 세션이 활성화된 동안 오케스트레이터는 대상 창의 변경 사항(제목, 사각형, 포그라운드 상태, 선택적으로 스크린샷 서명 차이)을 폴링합니다. 트리거가 발생하면 새 스크린샷을 캡처하여 debug://context 리소스로 노출합니다. 클라이언트(OpenCode)는 debug://context를 폴링하고, 무엇을 할지 결정한 다음, 그 결정으로 execute_action을 호출합니다. 오케스트레이터는 자체적으로 작업을 결정하지 않습니다. 거버너, 신선도, 안전 관문이 모두 통과한 후에만 클라이언트 결정을 실행할 뿐입니다.

세션 종료. end_debug_session은 SHUTDOWN을 보내고, watchdog이 1초 내에 응답하지 않으면 종료시키고, 보류 중인 수정자 키를 해제하고, IDLE로 돌아갑니다. MCP 프로세스가 정리 종료 없이 죽으면 watchdog의 dead-man 스위치가 자체적으로 후크를 제거합니다(보안 모델 섹션 참조).

도구

10개의 도구가 등록되어 있습니다.

네 개의 입력 도구(mouse_click, mouse_move, key_press, type_text)는 모두 안전 계층의 injectGuarded 관문을 통과합니다. 활성 세션이 없으면 NO_ACTIVE_SESSION을 반환합니다. 커서나 키보드 포커스가 대상 창 밖에 있으면 WINDOW_SCOPE_VIOLATION을 반환합니다.

리소스

세 개의 리소스가 등록되어 있습니다.

거버너 제한

오케스트레이터는 개입에 대해 고정된 스로틀을 적용합니다:

• 작업 간 5초 쿨다운

• 분당 6회 개입

• 연속 3회 실패 후 자동 일시 중지

• 하드 30분 세션 상한 — 이후 세션은 자동 종료

쿨다운, 속도 제한, 일시 중지로 인한 거부는 실패가 아니라 스로틀링입니다. 3회 실패 일시 중지에 집계되는 것은 오래된 상태 거부 또는 주입 오류뿐입니다.

보안 모델

이 설계가 보장하는 것과 보장하지 않는 것.

이중 프로세스 격리. Node MCP 서버와 네이티브 watchdog은 별도의 프로세스입니다. Node 이벤트 루프가 멈춰도 후크를 차단하거나 안전 계층을 떨어뜨릴 수 없습니다. watchdog은 자체 메시지 루프를 실행하기 때문입니다.

Dead-man 스위치. watchdog은 명명된 파이프를 수신하며 모든 바이트를 하트비트로 취급합니다. 하트비트가 2초 이상 도착하지 않으면 두 후크 모두에 UnhookWindowsHookEx를 호출하고 정상 종료합니다. 제거 유예 기간과 결합하여, MCP가 죽은 후 3초 이내에 후크가 내려오므로 충돌하거나 종료된 서버가 입력을 차단한 채 남는 일이 없습니다. 이것이 fail-safe 계약이며, 1초 미만의 보장은 아닙니다.

창 범위 지정. 세션이 활성화되어 있고 커서와 키보드 포커스가 세션 대상 창 내부에 있는 경우에만 모든 주입이 허용됩니다.

보안 데스크톱 처리. OS가 보안 데스크톱(UAC 프롬프트 또는 잠금 화면)으로 전환하면 오케스트레이터는 일시 중지하고 입력을 전혀 시도하지 않은 채 주입을 거부합니다.

추가 전용 감사. 모든 파일 읽기, 주입된 작업, 스크린샷 요청, 개입 결정은 추가 전용 감사 로그에 기록됩니다. 키 입력 내용과 파일 내용은 절대 기록되지 않습니다.

보장하지 않는 것. 이 부분을 주의 깊게 읽으세요. 이것들이 정직한 잔여 위험입니다.

• 주입 입력 필터링은 절대적 차단이 아닙니다. watchdog은 대상이 보호 영역 내부에 있을 때 LLKHF_INJECTED / LLMHF_INJECTED 플래그를 가진 입력을 차단합니다. 이는 SendInput이 생성하는 기계 주입 입력을 막습니다. 모든 가능한 입력 소스를 막지는 않습니다. 다른 프로세스가 이론적으로 다른 수단으로 플래그가 없는 입력을 합성할 수 있으며, 그 입력은 필터를 통과할 것입니다. 이 도구는 절대적인 물리적 차단을 주장하지 않습니다. 중단 버튼을 수학적 보장이 아닌 강력한 최선 노력 안전망으로 취급하세요.

• 최악의 경우 원격 제어 프리미티브입니다. 전체 도구 표면은 파일 읽기 + 스크린샷 캡처 + 키보드 및 마우스 주입입니다. 공격자나 오작동하는 모델이 이를 제어한다면, 그들이 얻는 능력이 바로 이것입니다. 이 표면이 향하게 해도 괜찮은 머신과 창에 대해서만 사용하세요.

• 안티바이러스 및 EDR이 플래그할 수 있습니다. 전역 저수준 후크와 SendInput 주입은 원격 액세스 도구와 키로거가 사용하는 바로 그 기법입니다. AV/EDR 제품의 오탐지를 예상하세요. 세션 중간에 watchdog이 격리되거나 종료되는 경우도 포함됩니다. dead-man 스위치가 이를 안전하게 만듭니다(후크가 내려옴). 하지만 세션은 중단됩니다. 문제 해결 섹션을 참조하세요.

• 승격은 표면을 넓힙니다. watchdog은 전역 후크를 설치하려면 관리자가 필요하므로, 세션은 승격된 프로세스가 관여한 상태로 실행됩니다. 그러한 노출이 허용되지 않는 머신에서는 실행하지 마세요.

watchdog은 키 입력이나 버튼 내용을 절대 읽거나 기록하지 않습니다. 주입 플래그와 커서 대상 위치만 검사합니다. 전송은 로컬 명명된 파이프뿐입니다. TCP, 네트워크 리스너, 원격 제어가 없습니다.

문제 해결

바이러스 백신 또는 EDR이 watchdog을 플래그합니다. AV/EDR 콘솔에서 src\watchdog\watchdog.exe(또는 프로젝트 디렉터리)에 대한 예외를 추가하세요. 영구적인 해결책은 코드 서명입니다. 서명된 바이너리는 격리될 가능성이 훨씬 낮습니다. 세션 중간에 watchdog이 종료되면 세션은 IDLE로 전환되고 새로운 start_debug_session이 시작될 때까지 모든 입력 도구가 거부됩니다.

Windows가 후크를 분리합니다(LowLevelHooksTimeout). 로우 레벨 후크 프로시저에는 HKCU\Control Panel\Desktop\LowLevelHooksTimeout(기본값 300ms)에 의해 제어되는 엄격한 실행 예산이 있습니다. 후크 프로시저가 너무 오래 실행되면 Windows가 경고 없이 제거합니다. watchdog은 후크 프로시저를 100ms보다 훨씬 짧게 유지하므로 정상적인 사용에서는 이 문제가 발생하지 않아야 합니다. 부하가 높은 머신에서 후크가 끊어지는 경우 문제는 시스템 부하 또는 다른 로우 레벨 후크의 간섭이지 이 도구가 아닙니다.

다중 모니터 또는 혼합 DPI 설정에서 클릭이 잘못된 위치에 찍힙니다. 좌표는 모니터별 DPI를 사용하여 논리적 픽셀과 물리적 픽셀 간에 매핑됩니다. 혼합 DPI 다중 모니터 설정에는 알려진 제한 사항이 있습니다. 논리적 좌표를 물리적 픽셀로 변환할 때 물리적 픽셀을 기대하는 호출에 논리적 좌표를 전달합니다. 96 DPI에서는 무해하지만 배율이 적용된 모니터에서는 드리프트가 발생할 수 있습니다. 클릭이 빗나가면 먼저 스크린샷을 캡처하고, 스크린샷에서 대상 좌표를 읽은 다음, 기본 모니터에서 작업하는 것이 좋습니다.

UAC 프롬프트가 나타나거나 주입이 조용히 실패합니다. watchdog은 관리자 권한으로 실행되므로 watchdog을 실행하면 UAC 프롬프트가 표시될 수 있습니다. 취소하면 세션이 ELEVATION_REQUIRED로 실패합니다. 이 빌드에서 서버는 자체적으로 승격을 다시 요청할 수 없으므로 세션을 시작하기 전에 watchdog을 관리자 권한으로 미리 시작하거나 관리자 권한 터미널에서 OpenCode를 실행하세요.

watchdog을 수동으로 실행할 때 ERROR_ACCESS_DENIED가 발생합니다. 이는 관리자 권한이 없는 셸에서 예상되는 동작입니다. watchdog은 관리자 권한 없이는 실행을 거부하고 종료 코드 1과 함께 ERROR_ACCESS_DENIED를 출력하므로 조용히 아무것도 하지 않고 넘어가는 일은 없습니다. 대신 관리자 권한 PowerShell에서 실행하세요.

세션 기록

세션은 나중에 재생할 수 있도록 JSON 트랜스크립트로 기록할 수 있습니다. 레코더는 감사 로그에 연결되어 키 입력 내용 없이 모든 도구 호출(이름, 인수, 결과, 타임스탬프)을 캡처합니다(데이터 최소화). 트랜스크립트는 .omo/recordings/session-<id>.json에 저장됩니다.

# A session transcript can be replayed programmatically:
node -e "const { SessionRecorder } = require('./dist/recording'); SessionRecorder.replay('.omo/recordings/session-xxx.json', async (call) => { console.log(call.toolName, call.args); })"

UIAutomation(접근성 API)

inspect_element 도구는 UIAutomation 트리 워커를 통해 표시되는 UI 요소를 열거합니다(terminator-mcp-agent 및 Windows MCP Inspector와 동등한 수준). v1에서 이는 주입된 deps seam에서 요소를 반환하는 스텁입니다. 전체 COM interop에는 네이티브 N-API 애드온이 필요합니다(향후 작업). UIAutomationProvider 클래스는 InputProvider를 구현하지만 v1에서는 주입 메서드에 대해 UIAutomationError를 던집니다. 실제 주입에는 SendInput 또는 PostMessage 경로를 사용하세요.