WinKit

로컬 Windows 가시성 및 진단 기능을 AI 에이전트에 제공하며, Model Context Protocol (MCP)을 통해 노출됩니다.

WinKit은 기본적으로 읽기 전용이며, 로컬 우선 MCP 서버입니다. 코딩 에이전트에게 프로세스, 네트워크, 스토리지, 서비스, 이벤트 로그, 창, 그리고 첫 번째 심층 애플리케이션 어댑터를 통해 라이브 Chrome 탭 검사와 로컬 웹 앱 진단을 위한 격리된 WinKit 소유의 관리 브라우저 등 Windows 머신의 구조화되고 권한이 부여된 보기를 제공합니다. 도구 뒤에는 결정론적 진단 엔진이 있어 측정된 것과 해석된 것을 분리하므로 에이전트가 추측 없이 실제 질문에 답할 수 있습니다. 원격 측정, 클라우드 없음; 유일한 외부 표면은 게이트가 있고 권한이 확인된 관리 브라우저 실행입니다.

v1은 기본적으로 읽기 전용입니다. 모든 검사 도구는 증거를 반환하며 시스템을 수정할 수 없습니다. WinKit이 수행할 수 있는 유일한 작업 — 자체 격리된 관리 Chrome 세션을 시작하거나 닫는 것 — 은 [chrome.managed] enabled = true가 설정된 경우에만 활성화되며, safe/read_only 모드에서는 절대 부여되지 않는 별도의 application.browser.* 권한에 의해 제어되며, WinKit이 직접 생성한 리소스에만 영향을 미칩니다.

WinKit이 답변하는 것

WinKit은 세 가지 질문을 중심으로 구축되었으며, 각 질문은 도구로 답변됩니다:

이것들은 함께 1분 이내에 전체 이야기를 전달합니다: 머신 먼저, 그 다음 가장 무거운 단일 탭, 그리고 그것이 악화되고 있는지 여부.

Related MCP server: windows-admin-mcp

주요 기능

• 69개의 MCP 도구 — 시스템, 프로세스, 네트워크, 스토리지, 하드웨어, 전원, 서비스, 이벤트, 창, 개발자 환경, 애플리케이션, Chrome, 관리 브라우저, 머신 상태 영역에 걸쳐 있으며, 도구 프로필(core, developer [기본값], browser, full)로 구성되어 에이전트가 필요한 것만 볼 수 있습니다.

• 개발자 워크플로 도구 — diagnose_workspace, diagnose_local_webapp, list_dev_servers, 제한된 wait_for_* 도구, correlate_recent_failures, system_health_trend는 원시 측정값을 노출하는 대신 완전한 문제(오래된 포트, 잘못된 포트, HTTP 500, 빈 페이지)를 해결합니다.

• 증거 우선 진단 — 모든 상위 수준 보고서는 순위가 매겨진 결과, 안정적인 결과/증거 ID, 그리고 시간적 근접성에서 인과 관계를 주장하지 않는 confirmed/observed/likely/possible/unknown 신뢰 언어를 포함하는 안정적인 봉투입니다. 순수 임계값 로직: LLM, 무작위성, 조작된 주장이 없습니다.

• 정직한 완전성 — system_diagnose는 차원을 측정할 수 없을 때 evidence_completeness: "full" | "limited"를 보고하며, 실패한 차원은 건강한 집합에서 제외됩니다. WinKit은 볼 수 없었던 것을 알려줍니다.

• CDP를 통한 Chrome 심층 검사 — 탭, 성능, 메모리, 네트워크, 런타임 콘솔, 결합된 진단 보고서, 샘플링된 추세. 헤더, 쿠키, 요청 본문은 절대 캡처되지 않습니다.

• 격리된 관리 브라우저 — chrome_start_managed_session은 일회용 프로필과 루프백 전용 DevTools 엔드포인트로 WinKit 소유의 Chrome을 생성하고, 페이지를 검사(chrome_get_page_summary, chrome_capture_screenshot)하며, chrome_stop_managed_session은 이를 닫고 프로필을 제거합니다. Windows x64 전용; Chrome은 절대 다운로드되지 않습니다. 기본적으로 헤디드: 실제 보이는 Chrome 창이 바탕 화면에 열립니다(--headless 플래그 없음, 헤드리스 전용 GPU 우회 없음, 창 크기 1280x900). 기본 헤디드 실행이 시작 중에 충돌하는 경우(GPU 프로세스 실패), 검증된 헤디드 소프트웨어 렌더링 폴백(headed-software)이 동일한 보이는 창을 엽니다 — 절대 숨겨지거나 헤드리스가 되지 않습니다. 헤드리스는 옵트인(headless: true)이며 설계상 창을 열지 않습니다. 소프트웨어 경로에서 안전한 고정 인수로 렌더링합니다(headless-software: --disable-gpu --disable-gpu-compositing --use-angle=swiftshader --disable-gpu-program-cache --disable-gpu-shader-disk-cache; 소프트웨어 모드가 시작 시 충돌하면 프로세스 내 GPU 폴백이 실행됩니다). 선택된 모드는 항상 보고되며(headless, window_mode, launch_mode) 절대 조용히 변경되지 않습니다. 세션은 브라우저가 짧은 안정화 검사를 통과한 후에만 ready로 선언됩니다 — DevTools는 Chrome이 죽기 직전에 연결 가능해질 수 있으므로(예: GPU 프로세스 충돌), /json/version이 한 번 응답했다고 해서 준비 상태가 반환되지는 않습니다. 브라우저의 stdout은 MCP 스트림을 손상시킬 수 없도록 리디렉션되며, stderr는 진단을 위해 제한된 편집된 꼬리로 캡처되고(Chrome이 보고할 때 GPU 프로세스 종료 코드 포함), 예상치 못한 종료는 소유한 프로세스 트리(crashpad/GPU/utility/renderer, 정확한 소유 프로필 경로로 식별됨)를 회수하고 소유 프로필을 제거합니다 — 사용자의 Chrome은 절대 아닙니다. 기능 게이트, 권한 게이트, Playwright 없음, 수동 디버그 플래그 없음.

• 계층형 권한 모델 — 14개의 v1 읽기 기능과 별도로 게이트된 application.browser.launch/navigate/close 작업 기능에 대해 네 가지 모드(safe, read_only, approval, unrestricted). 거부 시 정확히 무엇이 필요한지 설명합니다.

• 제공자 아키텍처 — 모든 것은 WindowsBackend / ApplicationProvider 트레이트 뒤에 있습니다. 실제 Win32 계층은 완전히 분리 가능하며, 모의 백엔드와 결정론적 픽스처가 머신 종속성 없이 381개의 테스트 스위트(cargo test --features mocks)를 지원합니다.

• 구성에 의한 강화 — 제한된 결과, 도구별 타임아웃, 페이로드 상한, 8MiB 전송 프레임 상한, 엄격한 JSON 스키마 검증, 프로토콜-클린 stdout(모든 진단은 stderr로 이동).

• npm 배포 — 두 패키지, @winkit/mcp (실행기) 및 @winkit/win32-x64-msvc (Windows x64 네이티브 런타임), npx --yes @winkit/mcp@latest로 설치. 설치 스크립트, 브라우저 자동화 종속성 없음; 네이티브 실행 파일은 구현 세부 사항입니다.

• 에이전트 스킬 — skills/winkit-developer-debugging/SKILL.md는 코딩 에이전트에게 질문→도구 라우팅, 권한 및 프로필 선택, 안전/읽기 전용 경계를 가르칩니다.

• 평가 스위트 — tests/eval/은 픽스처 기반의 결정론적 18개 시나리오 스위트로, WinKit이 진단하도록 구축된 실패 모드에 대해 상태, 증거, 결과 ID, 지지/반박 증거, 편집, 제한된 출력, 권한 동작, 거짓 근본 원인 주장 없음을 확인합니다.

빠른 시작

요구 사항: Windows 10/11 x64 및 Node.js >= 18 (npm 경로) 또는 Rust 1.75+ (소스에서).

npx --yes @winkit/mcp@latest doctor   # verify the install

또는 소스에서 빌드:

cargo build --release
.\target\release\winkit --help

WinKit은 MCP 클라이언트에 의해 stdio 서브프로세스로 실행되며, npx 실행기를 통해 또는 빌드된 바이너리에서 직접 실행됩니다(docs/mcp-integration.md 참조):

• OpenCode — examples/mcp/opencode.json

• Claude Code — examples/mcp/claude-code.json

• 모든 MCP 클라이언트 — examples/mcp/generic.json

설정 파일 없이 WinKit은 안전한 기본값으로 실행됩니다: read_only 권한 모드, 두 내장 제공자 활성화, 문서화된 제한. 전체 표면은 config/example.toml를, 완전한 설정 스토리는 docs/installation.md를 참조하세요.

Chrome 검사 및 관리 브라우저

Chrome 심층 검사는 Chrome이 DevTools 엔드포인트를 노출해야 합니다. WinKit이 이를 대신 수행할 수 있습니다: [chrome.managed] enabled = true와 application.browser.launch 권한으로 chrome_start_managed_session은 자체 격리된 Chrome 인스턴스(일회용 프로필, 루프백 전용 DevTools 엔드포인트)를 생성하므로 수동 디버그 플래그나 별도의 브라우저 프로세스가 필요 없습니다. 기본적으로 실제 보이는 Chrome 창이 바탕 화면에 열립니다; 비가시적 자동화/CI 세션이 필요한 경우에만 headless: true를 전달하세요(해당 모드는 설계상 창을 열지 않습니다):

chrome_start_managed_session(url="http://localhost:3000")  # opens a visible Chrome window
  -> chrome_get_page_summary(session_id)     # runtime errors, failed requests, headings
  -> chrome_capture_screenshot(session_id)   # optional visual check
  -> chrome_stop_managed_session(session_id) # closes Chrome, removes the profile

이미 실행 중인 Chrome(예: 개발자가 --remote-debugging-port로 시작한 Chrome)을 검사하려면 WinKit은 fallback_port(기본값 9222)를 프로빙하고 CDP를 통해 연결하여 엔드포인트를 발견합니다. 전체 수명 주기, 상태 및 보안 규칙은 docs/chrome.md를 참조하세요.

성능

종단 간 중간 대기 시간, Windows 10 데스크탑(8코어, 16GB RAM)에서 릴리스 빌드 및 호출당 새 서버 프로세스로 측정 — 따라서 숫자에는 프로세스 시작 및 MCP 초기화 핸드셰이크가 포함됩니다:

관찰 창 도구는 구성된 창에 따라 확장되며 시스템 크기에는 영향을 받지 않습니다. 다른 모든 도구는 프로세스, 포트 또는 탭 수에 관계없이 100ms 미만을 유지합니다. 전체 표 및 방법론: docs/performance.md.

도구 표면

전체 참조 및 인수 스키마: docs/tools.md.

아키텍처

WinKit의 파이프라인은 세 가지 계층으로 책임을 분리합니다 — WinKit이 측정하고, WinKit이 신호를 해석하며, WinKit이 증거 기반 결과를 순위화합니다; LLM이 이를 설명합니다:

                 WinKit
                   │
      ┌────────────┼────────────┐
      │            │            │
  Observation  Correlation  Diagnosis
      │            │            │
      ↓            ↓            ↓
  Windows/App   Evidence    Findings
    metrics      linking     ranking

server (MCP over stdio, JSON-RPC 2.0, session lifecycle)
  ├── tools        (59 tool definitions + argument handling + registry)
  │     ├── providers (WindowsBackend / ApplicationProvider traits)
  │     │     └── chrome::managed (isolated WinKit-owned sessions)
  │     └── platform::windows (real Win32 implementations, windows-sys 0.59)
  ├── permissions  (modes, capabilities, policy, approval surface)
  ├── config       (winkit.toml, strict, deny-unknown-keys)
  ├── models       (unified data models shared by providers/tools/diagnostics)
  └── diagnostics  (measurements → signals → ranked findings)

계층 규칙은 엄격합니다: MCP 표면은 Win32에 직접 접근하지 않으며, Windows 계층은 모의 백엔드를 통해 테스트 가능합니다 (cargo test --features mocks). 자세히 알아보기: docs/architecture.md.

보안 모델

• 기본적으로 읽기 전용 — 모든 검사 도구는 읽기 전용이며, 유일한 작업(관리형 브라우저 실행/탐색/닫기)은 [chrome.managed] enabled에 의해 기능 게이트되며 safe/read_only 모드에서는 거부됩니다.

• 권한 모드는 모든 도구 호출을 디스패치 전에 게이트하며, 관리형 브라우저 수명 주기 도구에는 별도의 작업 게이트가 있습니다.

• 관리형 브라우저는 격리되고 자체 정리됨 — 관리 루트 아래의 일회용 프로필, 루프백 전용 DevTools, 관리 루트 외부의 모든 경로를 거부하는 정리, 그리고 일반 Chrome 프로필에 절대 연결되지 않습니다.

• 비밀번호는 캡처되지 않음 — Chrome 네트워크/런타임 검사는 출력을 자르고 헤더, 쿠키, 본문을 명시적으로 제외합니다; URL은 편집됩니다(쿼리 문자열 제거).

• 모든 곳에서 작업 범위 제한 — 결과 상한, 타임아웃, 페이로드 상한, 프레임 상한.

• 자세한 내용: SECURITY.md 및 docs/security.md.

알려진 제한 사항

WinKit은 한계를 버그가 아닌 일급 출력으로 처리합니다:

• 프로세스별 CPU 백분율은 실시간 샘플이며 누적 측정이 아닙니다. 단순 시스템 비율 계산은 멀티코어 머신에서 오해를 불러일으키므로 list_processes(저렴한 전체 스냅샷)는 cpu_percent: null을 보고합니다. 실행 중인 프로세스를 찾기 위해 get_process는 300ms 창에 걸쳐 명시적 기준(system_capacity_all_cores)으로 두 개의 실시간 CPU 백분율 샘플을 수집합니다; 집계 보기(ApplicationGroupInfo)는 1초 샘플로 동일한 작업을 수행합니다.

• Chrome은 항상 탭을 PID에 매핑할 수 없음 — 어댑터는 process_mapping: "none"을 보고하고 실패하거나 추측하지 않고 순수 CDP 증거로 계속 진행합니다.

• 일부 Windows 프로세스는 읽기 액세스를 거부함 — 읽을 수 없는 필드에 대해 null로 계속 나열되며 절대 조용히 삭제되지 않습니다.

• 진단은 측정된 것과 측정되지 않은 것을 구분함 — system_diagnose는 evidence_completeness를 포함하며, 보고서에는 limitations 항목이 포함될 수 있으므로 에이전트가 부분 보기를 과도하게 읽지 않습니다.

• 이미 실행 중인 Chrome을 검사하려면 원격 디버깅 포트가 필요합니다. 관리형 브라우저 워크플로는 로컬 앱 진단을 위해 해당 요구 사항을 제거합니다: WinKit은 기능과 권한이 활성화되면 자체 격리된 Chrome을 생성합니다; 일반 브라우징 프로필은 항상 변경되지 않습니다.

개발

cargo check                 # compile checks
cargo build                 # debug build
cargo test --features mocks # full test suite (381 tests)
cargo clippy --all-targets  # lint

# evaluation suite (fixture-backed failure scenarios)
cargo test --features mocks --test eval

# npm launcher + package validation (after cargo build --release)
powershell -ExecutionPolicy Bypass -File npm/scripts/copy-native.ps1
node --test npm/test/launcher.test.js npm/test/package.test.js
powershell -ExecutionPolicy Bypass -File npm/scripts/test-packed.ps1

# opt-in live tests (need a real Windows machine / Chrome install)
$env:WINKIT_LIVE_WINDOWS = "1"; cargo test --features live-windows
# live managed-Chrome lifecycle, both modes (requires an installed Google
# Chrome on an interactive desktop; run ten consecutive isolated runs per
# mode before any release-ready claim)
$env:WINKIT_LIVE_CHROME = "1"; cargo test --features live-chrome --lib live_managed_chrome_headed_start_inspect_stop -- --nocapture
$env:WINKIT_LIVE_CHROME = "1"; cargo test --features live-chrome --lib live_managed_chrome_headless_start_inspect_stop -- --nocapture

실시간 관리형 Chrome 테스트는 WINKIT_LIVE_CHROME이 1이 아닐 때 명시적인 건너뛰기 이유를 출력합니다; 헤드형 테스트는 대화형 데스크톱이 없을 때도 건너뜁니다(헤드형 동작 미확인 표시). 건너뛰어진 실시간 테스트는 통과로 간주되지 않으며, 실제 Chrome 설치에서 두 모드 모두 통과하지 않으면 프로젝트는 "릴리스 준비 완료" 상태가 아닙니다(docs/release.md 참조).

통합 테스트는 실제 머신을 건드리지 않고 MCP 프로토콜, 도구 디스패치, 권한 시행, 픽스처 기반 모의 제공자를 테스트합니다; 평가 스위트(tests/eval/)는 18가지 결정론적 실패 시나리오를 다룹니다. docs/development.md 및 CONTRIBUTING.md를 참조하세요.

문서

• docs/installation.md — 빌드, 구성, MCP 클라이언트에 연결

• docs/architecture.md — 계층, 데이터 흐름, 제공자 모델

• docs/diagnostics.md — 증거 우선 보고서 형태 및 점수 공식

• docs/security.md — 위협 모델 및 완화 조치

• docs/permissions.md — 모드, 기능, 정책 테이블

• docs/tools.md — 인수가 포함된 도구 참조

• docs/configuration.md — 모든 구성 키 및 기본값

• docs/application-adapters.md — 어댑터 연결 방법

• docs/chrome.md — Chrome 검색, CDP, 관리형 세션 및 주의사항

• docs/performance.md — 벤치마크 방법론 및 전체 테이블

• docs/demos.md — 세 가지 데모 스크립트 및 녹화 가이드

• docs/mcp-integration.md — 클라이언트 설정 예제

• docs/development.md — 빌드, 테스트, 기여

• docs/release.md — 릴리스 프로세스 및 체크리스트

• tests/eval/README.md — 평가 스위트 실행 방법

• skills/winkit-developer-debugging/SKILL.md — 에이전트 스킬

라이선스

MIT — LICENSE 참조. WinKit은 로컬 우선 및 오픈 소스입니다; 루프백 Chrome DevTools 프로브를 제외한 원격 측정 및 네트워크 호출이 없습니다.