mcp-windows-debug

Ein TypeScript/Node.js-MCP-Server, der über stdio in OpenCode eingebunden wird und dem Modell Augen und Hände auf einem Windows-Rechner verschafft: Er liest Projektdateien, erstellt Screenshots, bewegt die Maus, tippt Tasten und führt eine automatische Debug-Schleife gegen eine Zielanwendung aus.

Sicherheit ist der Kern des gesamten Designs. Ein separater nativer C++-Watchdog-Prozess installiert globale Low-Level-Tastatur- und Maus-Hooks, sodass ein Mensch jederzeit einen geschützten Abbrechen-Button klicken kann, selbst während das Modell Eingaben injiziert. Der Node-MCP-Server und der Watchdog sind zwei unabhängige Prozesse, sodass eine hängende Node-Ereignisschleife weder Ihre Eingaben einfrieren noch die Sicherheitsebene stillschweigend entfernen kann. Jede Aktion durchläuft drei Tore: einen Governor, eine Frischeprüfung und eine Fensterbereichs-Wache. Details finden Sie im Abschnitt Sicherheitsmodell unten.

Dies ist eine reine Windows-v1-Version. macOS- und Linux-Backends werden später hinter denselben Provider-Schnittstellen angeschlossen; sie sind noch nicht implementiert.

Schnellstart

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

Installation

Voraussetzungen:

• Node.js 20 oder neuer, plus npm

• Windows 10 oder 11

• Administratorzugriff, nur erforderlich zum Ausführen des Watchdogs (siehe unten)

Installieren Sie die Abhängigkeiten und bauen Sie den TypeScript-Code:

npm install
npm run build

npm run build führt tsc aus und erzeugt dist/index.js, den Einstiegspunkt, den OpenCode startet.

Bauen Sie als Nächstes den Watchdog. Es handelt sich um eine C++-Win32-Konsolenanwendung, die mit MSVC kompiliert wird; CMake, MSBuild oder MinGW sind nicht beteiligt:

cd src\watchdog
build.bat

build.bat erfordert die VS2019 Build Tools (MSVC 14.29) und das Windows SDK. Die Toolchain-Pfade sind im Skript fest codiert, sodass es sie an ihren Standardinstallationsorten erwartet. Die Ausgabe ist src\watchdog\watchdog.exe, die der Node-Server zur Laufzeit relativ zum Projektstamm findet.

Der Watchdog muss mit erhöhten Rechten ausgeführt werden. Globale Low-Level-Hooks weigern sich, aus einem nicht erhöhten Prozess installiert zu werden. Zwei Möglichkeiten, dies zu erfüllen:

1. Starten Sie OpenCode aus einem Terminal mit erhöhten Rechten, damit der gestartete Watchdog die Erhöhung erbt.

2. Starten Sie den Watchdog selbst als Administrator, bevor Sie eine Debug-Sitzung beginnen.

Der Server kann in dieser Version keine UAC-Erhöhung selbst anfordern. Eine Debug-Sitzung, die keinen erhöhten Watchdog erreichen kann, schlägt mit ELEVATION_REQUIRED fehl, und ein nicht erhöhter Watchdog-Lauf gibt ERROR_ACCESS_DENIED aus und beendet sich mit Code 1, anstatt stillschweigend nichts zu tun.

OpenCode-Konfiguration

Fügen Sie unter dem Schlüssel mcp in Ihrer OpenCode-Konfiguration (opencode.json) einen Eintrag windows-debug hinzu. Beachten Sie, dass der Schlüssel mcp ist, nicht mcpServers:

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

Ersetzen Sie <abs-path> durch den absoluten Pfad zu diesem Projekt, und verwenden Sie Vorwärtsschrägstriche, damit das JSON keine Maskierung benötigt. Wenn sich das Projekt beispielsweise unter G:\工程开发\AI全场景图形化调试 befindet, lautet der Befehl:

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

Der command ist ein Array aus argv-Token. Die environment-Map ist standardmäßig leer; das pro Sitzung gültige Watchdog-Token wird vom Server selbst erzeugt und über die Prozessumgebung an den Watchdog übergeben, sodass Sie hier nichts festlegen müssen.

Verwendung

Eine Debug-Sitzung hat eine feste Form: Registrieren Sie geschützte Abbrechen-Buttons, starten Sie die Sitzung, lassen Sie das Modell die automatische Debug-Schleife durchlaufen und beenden Sie dann die Sitzung.

Abbrechen-Buttons registrieren. Eine Sitzung kann nicht ohne geschützte Bereiche starten. Übergeben Sie ein oder mehrere Bildschirmrechtecke an start_debug_session als regions ({ x, y, w, h, id }, physische Pixel). Injizierte Eingaben, die auf einen registrierten Bereich zielen, werden vom Watchdog blockiert. Menschliche Eingaben passieren immer, daher ist der Bereich ein garantierter physischer Abbrechen-Bereich, den das Modell nicht erreichen kann. Bereiche sind für die Lebensdauer der Sitzung append-only; es gibt bewusst keine Möglichkeit, einen nach dem Start zu entfernen oder zu verschieben.

Sitzung starten. start_debug_session startet den Watchdog oder bindet ihn an, registriert jeden Bereich und startet den Heartbeat. Der Orchestrator beginnt, das aktuelle Vordergrundfenster als Debug-Ziel zu überwachen. Übergeben Sie sandbox: 'desktop', um die Injektion auf einem privaten Win32-Desktop auszuführen (PostMessage-basiert, die echte Maus und Tastatur des Benutzers bleiben unberührt) anstelle von SendInput (das den echten Cursor bewegt). sandbox: 'rdp' ist reserviert, aber in v1 nicht implementiert.

Die automatische Debug-Schleife. Während die Sitzung aktiv ist, fragt der Orchestrator das Zielfenster auf Änderungen ab: Titel, Rechteck, Vordergrundstatus und optional eine Screenshot-Signatur-Differenz. Wenn ein Auslöser feuert, erfasst er einen frischen Screenshot und stellt ihn als Ressource debug://context bereit. Der Client (OpenCode) fragt debug://context ab, entscheidet, was zu tun ist, und ruft execute_action mit dieser Entscheidung auf. Der Orchestrator entscheidet nie selbst über Aktionen; er führt nur Client-Entscheidungen aus, und nur wenn Governor-, Frische- und Sicherheitstore alle passieren.

Sitzung beenden. end_debug_session sendet SHUTDOWN, beendet den Watchdog, wenn er nicht innerhalb einer Sekunde antwortet, gibt alle gehaltenen Modifikatortasten frei und kehrt zu IDLE zurück. Wenn der MCP-Prozess ohne sauberes Herunterfahren stirbt, entfernt der Dead-Man-Schalter des Watchdogs die Hooks selbstständig (siehe Abschnitt Sicherheitsmodell).

Tools

Zehn Tools sind registriert.

Die vier Eingabe-Tools (mouse_click, mouse_move, key_press, type_text) laufen alle durch das injectGuarded-Tor der Sicherheitsebene. Ein Aufruf ohne aktive Sitzung gibt NO_ACTIVE_SESSION zurück. Ein Aufruf, während sich der Cursor oder der Tastaturfokus außerhalb des Zielfensters befindet, gibt WINDOW_SCOPE_VIOLATION zurück.

Ressourcen

Drei Ressourcen sind registriert.

Governor-Grenzen

Der Orchestrator erzwingt eine feste Drosselung von Eingriffen:

• 5 Sekunden Abklingzeit zwischen Aktionen

• 6 Eingriffe pro Minute

• automatische Pause nach 3 aufeinanderfolgenden Fehlern

• harte 30-Minuten-Obergrenze für die Sitzung, nach der die Sitzung automatisch endet

Ablehnungen wegen Abklingzeit, Ratenlimit oder Pause sind Drosselungen, keine Fehler. Nur eine Verweigerung wegen veralteten Zustands oder ein Injektionsfehler zählt auf die 3-Fehler-Pause.

Sicherheitsmodell

Was dieses Design garantiert und was nicht.

Dual-Prozess-Isolation. Der Node-MCP-Server und der native Watchdog sind getrennte Prozesse. Eine hängende Node-Ereignisschleife kann weder die Hooks blockieren noch die Sicherheitsebene entfernen, weil der Watchdog seine eigene Nachrichtenschleife betreibt.

Dead-Man-Schalter. Der Watchdog lauscht auf einer benannten Pipe und behandelt jedes Byte als Heartbeat. Wenn länger als 2 Sekunden kein Heartbeat eintrifft, ruft er UnhookWindowsHookEx für beide Hooks auf und beendet sich sauber. Zusammen mit der Entfernungs-Gnadenfrist werden die Hooks innerhalb von 3 Sekunden nach dem Tod des MCP entfernt, sodass ein abgestürzter oder beendeter Server niemals Eingaben blockiert zurücklässt. Dies ist der Fail-Safe-Vertrag; es ist keine Sub-Sekunden-Garantie.

Fensterbereichsbegrenzung. Jede Injektion wird verweigert, es sei denn, eine Sitzung ist aktiv und der Cursor und der Tastaturfokus befinden sich innerhalb des Sitzungszielfensters.

Behandlung des sicheren Desktops. Wenn das Betriebssystem zum sicheren Desktop wechselt (UAC-Eingabeaufforderung oder Sperrbildschirm), pausiert der Orchestrator und verweigert die Injektion, ohne dass eine Eingabe versucht wird.

Append-only-Audit-Log. Jedes Dateilesen, jede injizierte Aktion, jede Screenshot-Anfrage und jede Eingriffsentscheidung wird in einem Append-only-Audit-Log protokolliert. Tastaturanschlaginhalte und Dateiinhalte werden niemals dort hineingeschrieben.

Was es NICHT garantiert. Lesen Sie diesen Teil sorgfältig, denn dies sind die ehrlichen Restrisiken.

• Die Filterung injizierter Eingaben ist keine absolute Blockierung. Der Watchdog blockiert Eingaben, die die Flags LLKHF_INJECTED / LLMHF_INJECTED tragen, wenn das Ziel in einen geschützten Bereich fällt. Das stoppt maschineninjizierte Eingaben, also das, was SendInput erzeugt. Es stoppt nicht jede mögliche Eingabequelle. Ein anderer Prozess könnte theoretisch nicht gekennzeichnete Eingaben auf andere Weise erzeugen, und diese Eingabe würde den Filter passieren. Dieses Werkzeug erhebt keinen Anspruch auf absolute physische Blockierung. Behandeln Sie den Abbrechen-Button als starkes Best-Effort-Sicherheitsnetz, nicht als mathematische Garantie.

• Im schlimmsten Fall ist es eine Fernsteuerungs-Primitive. Die vollständige Tool-Oberfläche besteht aus Dateilesen plus Screenshot-Erfassung plus Tastatur- und Mausinjektion. Wenn ein Angreifer oder ein fehlverhaltendes Modell die Kontrolle darüber hat, ist das die Fähigkeit, die sie erhalten. Verwenden Sie es auf einem Rechner und gegen Fenster, auf die Sie diese Oberfläche gerichtet haben möchten.

• Antiviren- und EDR-Produkte können es als Bedrohung einstufen. Globale Low-Level-Hooks und SendInput-Injektion sind genau die Techniken, die Fernzugriffs-Tools und Keylogger verwenden. Rechnen Sie mit Fehlalarmen von AV/EDR-Produkten, einschließlich des Watchdogs, der mitten in der Sitzung unter Quarantäne gestellt oder beendet wird. Der Dead-Man-Schalter macht das sicher (Hooks werden entfernt), aber es wird Sitzungen unterbrechen. Siehe Fehlerbehebung.

• Erhöhte Rechte erweitern die Angriffsfläche. Der Watchdog benötigt Administratorrechte, um globale Hooks zu installieren, daher läuft eine Sitzung mit einem erhöhten Prozess im Spiel. Führen Sie ihn nicht auf einem Rechner aus, auf dem diese Gefährdung inakzeptabel ist.

Vom Watchdog werden niemals Tastaturanschläge oder Button-Inhalte gelesen oder protokolliert; es werden nur das injizierte Flag und das Cursorziel geprüft. Der Transport ist ausschließlich die lokale benannte Pipe. Es gibt kein TCP, keinen Netzwerk-Listener und keine Fernsteuerung.

Fehlerbehebung

Antivirus- oder EDR-Software kennzeichnet den Watchdog. Fügen Sie eine Ausnahme für src\watchdog\watchdog.exe (oder das Projektverzeichnis) in Ihrer AV-/EDR-Konsole hinzu. Die dauerhafte Lösung ist die Code-Signierung: Eine signierte Binärdatei wird deutlich seltener unter Quarantäne gestellt. Wenn der Watchdog mitten in einer Sitzung beendet wird, wechselt die Sitzung in den Zustand IDLE, und alle Eingabewerkzeuge werden verweigert, bis eine neue Sitzung über start_debug_session gestartet wird.

Windows entfernt den Hook (LowLevelHooksTimeout). Low-Level-Hook-Prozeduren haben ein festes Ausführungsbudget, das über HKCU\Control Panel\Desktop\LowLevelHooksTimeout (Standard: 300 ms) gesteuert wird. Läuft die Hook-Prozedur zu lange, entfernt Windows sie stillschweigend. Der Watchdog hält seine Hook-Prozedur deutlich unter 100 ms, was das im normalen Betrieb nicht auslösen. Wenn Sie feststellen, dass auf einem stark ausgelasteten System Hooks wegfallen, liegt das Problem an der Systemlast oder an. Einem anderen Low-Level-Hook – nicht an diesem Tool.

Klicks landen bei einem Multi-Monitor- oder Mixed-DPI-Setup an der falschen Stelle.. Koordinaten werden über die Per-Monitor-DPI zwischen logischen und physischen Pixel übergeführt. Bei Mixed-DPI-Multi-Monitor-Setups gibt es eine bekannte Einschränkung: Die Umrechnung von logischen in physische Koordinaten übergibt logische Koordinaten an einen Aufruf, der physische Pixel erwartet. Bei 96 DPI ist das unproblematisch, bei skalierten Monitoren kann es aber zu Abweichungen kommen. Wenn die Maus falsch klickt, machen Sie zuerst einen Screenshot, lesen Sie die Zielkoordinaten daraus ab und arbeiten Sie bevorzugt auf dem primären Monitor.

Es erscheint eine UAC-Aufforderung oder die Injektion schlägt still fehl. Der Watchdog läuft mit erhöhten Rechten, sodass das Erzeugenüg eine UAC-Aufforderung einputen kann. Falls Sie abbrechen, schlägt die Sitzung mit ELEVATION_REQUIRED fehl. Der Server kann in dieser Version nicht selbstständig erneut erhöhte Rechte anfordern. Starten Sie den Watchdog daher vorab als Administrator, bevor Sie die Sitzung beginnen, oder starten Sie OpenCode aus einem Terminal mit erhöhten Rechent.

ERROR_ACCESS_DENIED beim manuellen Ausführen des Watchdogs. Das ist das erwartete Verhalten bei einer Shell ohne erhöhte Rechte. Der Watchdog weigert sich, ohne Administratorberechtigungen zu laufen, und gibt ERROR_ACCESS_DENIED mit Exit-Code 1 aus – es findet also kein stilles No-op statt. Führen Sie es stattdessen über eine PowerShell mit erhöhten Rechten aus.

Sitzungsaufzeichnung

Sitzungen können als JSON-Transkripte aufgezeichnet und später wieder abgespielt werden. Der Recorder verbindet sich mit dem Audit-Log und erfasst jeden Tool-Aufruf (name, args, result, timestamp) ohne Tastatureingaben (Datensparsamkeit). Die gespeichert Transkripte werden unter .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 (Barrierefreiheits-API)

Das Tool inspect_element listet die sichtbaren UI-Elemente über den UIAutomation-Tree-Walker auf (Feature-Parität mit terminator-mcp-agent und Windows MCP. Inspector). In v1 ist das ein Stub, der Element aus der Nahtstelle der injizierten Abhängigkeiten zurückgibt; vollständiger COM-Interop erfordert ein natives N-API-Addon (steht noch aus). Die Klasse UIAutomationProvider implementiert InputProvider, wirft in v1 für Injektionsmethoden jedoch UIAutomationError – verwenden Sie für die eigentliche Injektion die SendInput- oder PostMessage-Pfade.