WinKit

Lokale Windows-Beobachtbarkeit und Diagnostik für KI-Agenten, bereitgestellt über das Model Context Protocol (MCP).

WinKit ist ein standardmäßig schreibgeschützter, lokaler MCP-Server, der Codierungsagenten eine strukturierte, berechtigte Ansicht des Windows-Rechners bietet, auf dem sie ausgeführt werden: Prozesse, Netzwerk, Speicher, Dienste, Ereignisprotokolle, Fenster und – über den ersten tiefen Anwendungsadapter – Live-Chrome-Tab-Inspektion plus einen isolierten, WinKit-eigenen verwalteten Browser zur Diagnose lokaler Web-Apps. Hinter den Werkzeugen sitzt eine deterministische Diagnose-Engine, die trennt, was gemessen wurde, von dem, was interpretiert wird, sodass ein Agent echte Fragen beantworten kann, ohne zu raten. Keine Telemetrie, keine Cloud; die einzige ausgehende Oberfläche ist ein abgeschirmter, berechtigungsgeprüfter Start eines verwalteten Browsers.

v1 ist standardmäßig schreibgeschützt. Jedes Inspektionswerkzeug gibt Beweise zurück und nichts kann Ihr System verändern. Die einzigen Aktionen, die WinKit ausführen kann – das Starten oder Schließen seiner eigenen isolierten verwalteten Chrome-Sitzungen – sind deaktiviert, es sei denn, [chrome.managed] enabled = true ist gesetzt, sind durch eine separate application.browser.*-Berechtigung abgeschirmt, die der safe/read_only-Modus niemals gewährt, und betreffen nur Ressourcen, die WinKit selbst erstellt hat.

Was WinKit beantwortet

WinKit ist um drei Fragen herum aufgebaut, die jeweils von einem Werkzeug beantwortet werden:

Zusammen erzählen sie die ganze Geschichte in unter einer Minute: zuerst die Maschine, dann den einzelnen schwersten Tab, dann ob es schlimmer wird.

Related MCP server: DivLens MCP

Highlights

• 69 MCP-Werkzeuge in den Bereichen System, Prozess, Netzwerk, Speicher, Hardware, Stromversorgung, Dienst, Ereignis, Fenster, Entwicklerumgebung, Anwendung, Chrome, verwalteter Browser und Maschinengesundheit, organisiert in Werkzeugprofilen (core, developer [Standard], browser, full), sodass ein Agent nur sieht, was er braucht.

• Entwickler-Workflow-Werkzeuge — diagnose_workspace, diagnose_local_webapp, list_dev_servers, begrenzte wait_for_*-Werkzeuge, correlate_recent_failures, und system_health_trend lösen vollständige Probleme (veralteter Port, falscher Port, HTTP 500, leere Seite), anstatt rohe Messwerte offenzulegen.

• Beweisorientierte Diagnostik — jeder hochrangige Bericht ist eine stabile Hülle mit bewerteten Befunden, stabilen Befund-/Beweis-IDs und einer confirmed/observed/likely/possible/unknown-Vertrauenssprache, die niemals Kausalität aus zeitlicher Nähe behauptet. Reine Schwellwertlogik: kein LLM, keine Zufälligkeit, keine erfundenen Behauptungen.

• Ehrliche Vollständigkeit — system_diagnose meldet evidence_completeness: "full" | "limited", wenn eine Dimension nicht gemessen werden konnte, und fehlgeschlagene Dimensionen werden aus der gesunden Menge ausgeschlossen. WinKit sagt Ihnen, was es nicht sehen konnte.

• Chrome-Tiefeninspektion über CDP — Tabs, Leistung, Speicher, Netzwerk, Laufzeitkonsole, ein kombinierter Diagnosebericht und ein Stichproben-Trend. Header, Cookies und Anforderungstexte werden nie erfasst.

• Isolierter verwalteter Browser — chrome_start_managed_session erzeugt einen WinKit-eigenen Chrome mit einem Wegwerfprofil und einem Loopback-DevTools-Endpunkt, inspiziert die Seite (chrome_get_page_summary, chrome_capture_screenshot), und chrome_stop_managed_session schließt ihn und entfernt das Profil. Nur Windows x64; Chrome wird nie heruntergeladen. Standardmäßig mit Fenster: Ein echtes sichtbares Chrome-Fenster öffnet sich auf dem Desktop (kein --headless-Flag, keine Headless-GPU-Workarounds, Fenstergröße 1280x900). Wenn der standardmäßige Start mit Fenster während des Startvorgangs abstürzt (ein GPU-Prozessfehler), wird ein verifizierter Software-Rendering-Fallback mit Fenster (headed-software) geöffnet, der dasselbe sichtbare Fenster öffnet – es wird nie versteckt oder headless. Headless ist optional (headless: true) und öffnet standardmäßig kein Fenster; es rendert auf dem Software-Pfad mit sicheren festen Argumenten (headless-software: --disable-gpu --disable-gpu-compositing --use-angle=swiftshader --disable-gpu-program-cache --disable-gpu-shader-disk-cache; ein In-Prozess-GPU-Fallback läuft, wenn der Software-Modus beim Start abstürzt). Der ausgewählte Modus wird immer gemeldet (headless, window_mode, launch_mode) und nie stillschweigend geändert. Eine Sitzung wird erst nach einer kurzen Ruheprüfung als ready deklariert – DevTools können Momente bevor Chrome stirbt (z. B. ein GPU-Prozessabsturz) erreichbar werden, daher wird ready nie nur zurückgegeben, weil /json/version einmal geantwortet hat. Die Standardausgabe des Browsers wird umgeleitet, sodass sie niemals den MCP-Stream beschädigen kann, seine Fehlerausgabe wird in einem begrenzten redigierten Ende zur Diagnose erfasst (einschließlich des GPU-Prozess-Exit-Codes, wenn Chrome einen meldet), und ein unerwarteter Beendigungsvorgang bereinigt den eigenen Prozessbaum (Crashpad/GPU/Dienstprogramm/Renderer, identifiziert durch den genauen eigenen Profilpfad) und entfernt das eigene Profil – niemals das Chrome des Benutzers. Funktionsgeschützt, berechtigungsgeschützt, kein Playwright, keine manuellen Debug-Flags.

• Mehrschichtiges Berechtigungsmodell — vier Modi (safe, read_only, approval, unrestricted) über 14 v1-Lesefähigkeiten plus die separat geschützten application.browser.launch/navigate/close-Aktionsfähigkeiten. Ablehnungen erklären genau, was erforderlich wäre.

• Provider-Architektur — alles sitzt hinter WindowsBackend / ApplicationProvider-Traits; die echte Win32-Ebene ist vollständig trennbar, und ein Mock-Backend plus deterministische Fixtures treiben eine 381-Test-Suite an (cargo test --features mocks) ohne Maschinenabhängigkeit.

• Durch Konstruktion gehärtet — begrenzte Ergebnisse, Zeitüberschreitungen pro Werkzeug, Nutzlastbegrenzungen, eine 8-MiB-Transportrahmenbegrenzung, strenge JSON-Schema-Validierung und Standardausgabe protokollrein gehalten (alle Diagnosen gehen nach stderr).

• npm-Verteilung — zwei Pakete, @winkit/mcp (Starter) und @winkit/win32-x64-msvc (Windows x64 native Laufzeit), installiert mit npx --yes @winkit/mcp@latest. Keine Installationsskripte, keine Browser-Automatisierungsabhängigkeiten; die native ausführbare Datei ist ein Implementierungsdetail.

• Agenten-Fähigkeit — skills/winkit-developer-debugging/SKILL.md lehrt Codierungsagenten die Frage→Werkzeug-Routing, Berechtigungs- und Profilauswahl und die safe/read_only-Grenzen.

• Evaluierungssuite — tests/eval/ ist eine fixture-gestützte, deterministische 18-Szenario-Suite, die Status, Beweise, Befund-IDs, unterstützende/widersprechende Beweise, Redaktion, begrenzte Ausgabe, Berechtigungsverhalten und keine falschen Ursachenbehauptungen für die Fehlermodi überprüft, für deren Diagnose WinKit entwickelt wurde.

Schnellstart

Voraussetzungen: Windows 10/11 x64 und Node.js >= 18 (npm-Pfad) oder Rust 1.75+ (aus dem Quellcode).

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

Oder aus dem Quellcode erstellen:

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

WinKit wird von einem MCP-Client als stdio-Subprozess gestartet, entweder über den npx-Starter oder direkt aus der erstellten Binärdatei (siehe docs/mcp-integration.md):

• OpenCode — examples/mcp/opencode.json

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

• Jeder MCP-Client — examples/mcp/generic.json

Ohne Konfigurationsdatei läuft WinKit mit sicheren Standardeinstellungen: read_only-Berechtigungsmodus, beide integrierten Provider aktiviert und dokumentierte Grenzen. Siehe config/example.toml für die vollständige Oberfläche und docs/installation.md für die vollständige Einrichtungsgeschichte.

Chrome-Inspektion und der verwaltete Browser

Chrome-Tiefeninspektion erfordert, dass Chrome seinen DevTools-Endpunkt freigibt. WinKit kann dies für Sie erledigen: mit [chrome.managed] enabled = true und der application.browser.launch-Berechtigung erzeugt chrome_start_managed_session eine eigene isolierte Chrome-Instanz (Wegwerfprofil, Loopback-DevTools-Endpunkt), sodass keine manuellen Debug-Flags oder ein separater Browserprozess erforderlich sind. Standardmäßig öffnet sich ein echtes sichtbares Chrome-Fenster auf dem Desktop; übergeben Sie headless: true nur, wenn eine nicht sichtbare Automatisierungs-/CI-Sitzung gewünscht wird (dieser Modus öffnet standardmäßig kein Fenster):

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

Um einen bereits laufenden Chrome zu inspizieren (z. B. einen, den der Entwickler mit --remote-debugging-port gestartet hat), findet WinKit den Endpunkt durch Abfragen von fallback_port (Standard 9222) und Verbindung über CDP. Siehe docs/chrome.md für den vollständigen Lebenszyklus, Zustände und Sicherheitsregeln.

Leistung

Ende-zu-Ende-Medianlatenz, gemessen auf einem Windows 10-Desktop (8 Kerne, 16 GB RAM) mit einem Release-Build und einem neuen Serverprozess pro Aufruf – die Zahlen enthalten also den Prozessstart und den MCP-Initialize-Handshake:

Beobachtungsfenster-Werkzeuge skalieren mit ihrem konfigurierten Fenster, nicht mit der Systemgröße; jedes andere Werkzeug bleibt unter 100 ms, unabhängig davon, wie viele Prozesse, Ports oder Tabs vorhanden sind. Vollständige Tabelle und Methodik: docs/performance.md.

Die Werkzeugoberfläche

Vollständige Referenz mit Argumentschemata: docs/tools.md.

Architektur

Die Pipeline von WinKit ist eine dreischichtige Aufgabentrennung – WinKit misst, WinKit interpretiert Signale, WinKit bewertet evidenzgestützte Ergebnisse; das LLM erklärt sie:

                 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)

Die Schichtungsregeln sind streng: Die MCP-Oberfläche berührt Win32 nie direkt, und die Windows-Schicht ist über einen Mock-Backend testbar (cargo test --features mocks). Tiefergehende Informationen: docs/architecture.md.

Sicherheitsmodell

• Standardmäßig schreibgeschützt – jedes Inspektionswerkzeug ist schreibgeschützt; die einzigen Aktionen (Start/Navigation/Schließen des verwalteten Browsers) sind durch [chrome.managed] enabled feature-gesteuert und in den Modi safe/read_only verweigert.

• Berechtigungsmodi steuern jeden Werkzeugaufruf vor der Ausführung, mit einer separaten Aktionssteuerung für Werkzeuge des verwalteten Browser-Lebenszyklus.

• Der verwaltete Browser ist isoliert und selbstreinigend – ein Wegwerfprofil unter dem verwalteten Stammverzeichnis, Loopback-Only DevTools, Bereinigung, die jeden Pfad außerhalb des verwalteten Stammverzeichnisses ablehnt, und er verbindet sich nie mit dem normalen Chrome-Profil.

• Es werden keine Geheimnisse erfasst – Die Chrome-Netzwerk-/Laufzeitinspektion kürzt die Ausgabe und schließt explizit Header, Cookies und Bodies aus; URLs werden redigiert (Abfragezeichenfolgen entfernt).

• Begrenzte Arbeit überall – Ergebnisobergrenzen, Timeouts, Nutzlastobergrenzen, Rahmenobergrenzen.

• Vollständige Details: SECURITY.md und docs/security.md.

Bekannte Einschränkungen

WinKit behandelt Grenzen als erstklassige Ausgabe, nicht als Fehler:

• Die CPU-Prozentangabe pro Prozess ist eine Live-Stichprobe, kein kumulatives Maß. Die naive Systemverhältnisberechnung ist auf Mehrkernrechnern irreführend, daher meldet list_processes (eine günstige vollständige Momentaufnahme) cpu_percent: null. Um einen außer Kontrolle geratenen Prozess zu erkennen, entnimmt get_process eine Live-Zweistichproben-CPU-Prozentangabe über ein 300-ms-Fenster mit einer expliziten Basis (system_capacity_all_cores); die aggregierte Ansicht (ApplicationGroupInfo) macht dasselbe mit einer 1-s-Stichprobe.

• Chrome kann nicht immer einen Tab einer PID zuordnen – der Adapter meldet process_mapping: "none" und fährt mit reinen CDP-Beweisen fort, anstatt zu fehlschlagen oder zu raten.

• Einige Windows-Prozesse verweigern den Lesezugriff – sie werden weiterhin mit null für die Felder aufgelistet, die nicht gelesen werden konnten, und nie stillschweigend entfernt.

• Diagnosen unterscheiden zwischen Gemessenem und Ungemessenem – system_diagnose enthält evidence_completeness, und Berichte können limitations-Einträge enthalten, damit Agenten eine Teilansicht nicht überinterpretieren.

• Die Inspektion eines bereits laufenden Chrome erfordert einen Remote-Debugging-Port. Der verwaltete Browser-Workflow entfernt diese Anforderung für die Diagnose lokaler Anwendungen: WinKit startet seinen eigenen isolierten Chrome, wenn die Funktion und Berechtigung aktiviert sind; normale Browserprofile bleiben immer unberührt.

Entwicklung

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

Die Live-Tests des verwalteten Chrome geben einen expliziten Überspringungsgrund aus, wenn WINKIT_LIVE_CHROME nicht 1 ist; der Headed-Test wird ebenfalls übersprungen (wodurch das Headed-Verhalten als unverifiziert markiert wird), wenn kein interaktiver Desktop vorhanden ist. Ein übersprungener Live-Test ist niemals ein Bestehen, und ohne dass beide Modi auf einer echten Chrome-Installation bestehen, ist das Projekt nicht "release-ready" (siehe docs/release.md).

Die Integrationstests testen das MCP-Protokoll, die Werkzeugverteilung, die Berechtigungsdurchsetzung und fixture-gestützte Mock-Anbieter, ohne die echte Maschine zu berühren; die Evaluierungssuite (tests/eval/) deckt 18 deterministische Fehlerszenarien ab. Siehe docs/development.md und CONTRIBUTING.md.

Dokumentation

• docs/installation.md – Erstellen, Konfigurieren, Verbinden mit einem MCP-Client

• docs/architecture.md – Schichtung, Datenfluss, Anbietermodell

• docs/diagnostics.md – Das evidenzgestützte Berichtsformat und Bewertungsformeln

• docs/security.md – Bedrohungsmodell und Gegenmaßnahmen

• docs/permissions.md – Modi, Fähigkeiten, Richtlinientabelle

• docs/tools.md – Werkzeugreferenz mit Argumenten

• docs/configuration.md – Jeder Konfigurationsschlüssel und Standardwert

• docs/application-adapters.md – Wie Adapter eingebunden werden

• docs/chrome.md – Chrome-Erkennung, CDP, verwaltete Sitzungen und Einschränkungen

• docs/performance.md – Benchmark-Methodik und vollständige Tabelle

• docs/demos.md – Das Drei-Demo-Skript und Aufnahmeleitfaden

• docs/mcp-integration.md – Client-Einrichtungsbeispiele

• docs/development.md – Erstellen, Testen, Mitwirken

• docs/release.md – Release-Prozess und Checkliste

• tests/eval/README.md – So führen Sie die Evaluierungssuite aus

• skills/winkit-developer-debugging/SKILL.md – Die Agentenfähigkeit

Lizenz

MIT – siehe LICENSE. WinKit ist lokal-first und Open Source; es enthält keine Telemetrie und tätigt keine Netzwerkaufrufe außer der Loopback-Chrome-DevTools-Sonde.