OpenInputBridge-MCP

OpenInputBridge(Interception-kompatibler Kernel-Level-Tastatur-/Mauseingabetreiber) wird hier als Server bereitgestellt, der die Funktionalität über MCP (Model Context Protocol) als Werkzeuge verfügbar macht.

Als Alternative bzw. höherwertige Kompatibilitätslösung zu SendInput() / UI Automation / koordinatenbasierten Automatisierungswerkzeugen in der Testautomatisierung von GUI-/nativen Anwendungen können KI-Agenten (wie Claude Code) oder Testcode Kernel-Level-synthetische Tastatur-/Mauseingaben senden.

⚠️ Dieses Projekt basiert in keiner Weise auf dem Code von oblitum/Interception(LGPL/kommerzielle Dual-Lizenz). Die Hilfsprogramm-Datei (helper/oib_bridge.c) implementiert die IOCTLs eigenständig, ausschließlich auf Grundlage des in der docs/PROTOCOL.md der OpenInputBridge dokumentierten Drahtprotokolls.

Wofür ist dieses Werkzeug gedacht?

SendInput() / UI Automation / koordinatenbasierte Automatisierung mit PyAutoGUI, Selenium usw. haben strukturelle Grenzen, auf die man in der Testautomatisierungspraxis häufig stößt. Dieses Werkzeug umgeht diese, indem es synthetische Eingaben auf Treiberebene injiziert.

Hinweis: Die obigen Punkte sind lediglich Umgehungen technischer Grenzen und stellen keine Garantie dar, dass die Eingaben „nicht erkannt" werden. Dass Kernel-Level-Filtertreiber selbst erkannt werden können, ist in SECURITY.md dokumentiert. Die Nutzung außerhalb von Testumgebungen, für die man selbst die Berechtigung hat bzw. die man verwaltet (z. B. zur Umgehung von Anti-Cheat-Systemen fremder Spiele/Apps), ist nicht vorgesehen. Verwenden Sie das Werkzeug nicht für Zwecke, die gegen die Nutzungsbedingungen der Zielsoftware verstoßen könnten.

Related MCP server: ScreenHand

Architektur

flowchart TB
    Client["MCPクライアント<br/>(Claude Desktop / Claude Code など)"]

    subgraph Server["openinputbridge-mcp (Node.js/TypeScript)"]
        direction TB
        McpServer["MCP Server<br/>(stdio transport, ネットワーク非公開)"]
        Safety["Safety Gate<br/>arm必須化 + レート制限"]
        Bridge["OibBridge<br/>JSON Linesクライアント"]
        McpServer --> Safety --> Bridge
    end

    subgraph Helper["oib_bridge.exe (自作Cヘルパー, MIT)"]
        direction TB
        StdioLoop["stdin/stdout<br/>JSON Lines プロトコル"]
        Watchdog["排他モード<br/>ウォッチドッグスレッド"]
        Ioctl["DeviceIoControl呼び出し"]
        StdioLoop --> Ioctl
        Watchdog -.監視.-> Ioctl
    end

    subgraph Driver["OpenInputBridgeドライバ"]
        direction TB
        Devices["\\.\interception00-19<br/>(コントロールデバイス)"]
        Filter["oib_kbd.sys / oib_mou.sys<br/>(キーボード/マウス フィルタドライバ)"]
        Devices --> Filter
    end

    Target["対象アプリケーション<br/>(実際のキーボード/マウス入力として着弾)"]

    Client -- "MCPプロトコル (stdio, JSON-RPC)" --> McpServer
    Bridge -- "子プロセスspawn<br/>stdin/stdout (JSON Lines)" --> StdioLoop
    Ioctl -- "IOCTL_WRITE / IOCTL_SET_FILTER 等" --> Devices
    Filter -- "合成入力として注入<br/>(実HIDスタックと同じ経路)" --> Target

• Nur stdio-Transport. Es gibt keinerlei Netzwerk-Listener. Es wird nur der übliche Anwendungsfall vorausgesetzt, bei dem der MCP-Client das Programm lokal als Subprozess startet.

• Zwischen dem Hilfsprogramm (oib_bridge.exe) und dem Treiber dient docs/PROTOCOL.md als einzige Spezifikationsquelle; es besteht keinerlei Abhängigkeit von third_party/interception(LGPL).

• Zwischen dem MCP-Server (Node.js) und dem Hilfsprogramm (C) wird ein einfaches Request/Response-Protokoll mit einem JSON-Objekt pro Zeile verwendet.

Verfügbare Funktionen (v1-Werkzeugliste)

Nur zum Senden. Werkzeuge zum Lesen/Überwachen physischer Eingaben sind bewusst nicht enthalten (Details in SECURITY.md).

Spezifikationen, die KI-Agenten kennen sollten

KI-Agenten, die diesen MCP-Server bedienen (oder Entwickler, die ihn implementieren), sollten Folgendes verstehen.

1. Vor dem Senden muss unbedingt enable_input_control aufgerufen werden

Direkt nach dem Serverstart werden alle Sendewerkzeuge (press_key usw.) mit NotArmedError abgelehnt. Unabhängig von der Werkzeugfreigabe-UI des MCP-Clients selbst ist dies ein zusätzlicher expliziter Zustimmungsschritt, der der besonderen Leistungsfähigkeit dieses Treibers entspricht. Einmal pro Sitzung aufgerufen, bleibt die Aktivierung für die Lebensdauer des Prozesses gültig.

2. Tastennamen folgen der DOM-KeyboardEvent.code-Terminologie

Der key-Parameter von press_key/key_down/key_up verwendet die für Testautomatisierungsentwickler mit Playwright/Selenium vertraute DOM-KeyboardEvent.code-Nomenklatur (KeyA–KeyZ, Digit0–Digit9, Enter, ArrowUp, ShiftLeft, F1–F12 usw., einschließlich der JIS-Layout-spezifischen Tasten IntlRo/IntlYen/Convert/NonConvert/KanaMode). Die vollständige Liste finden Sie in der KEY_TABLE in src/keycodes.ts. Da diese auf physischen Tastenpositionen basieren, funktionieren sie unabhängig vom Layout.

type_text muss aus den eingegebenen Zeichen die Tasten+Umschalt-Zustände zurückrechnen, was vom aktiven Tastaturlayout des Betriebssystems abhängt. In der Standardeinstellung (layout: "auto") wird bei jedem Aufruf das Eingabegebietsschema des fokussierten Fensters erkannt und automatisch zwischen US-/JIS-(japanischem) Layout gewählt (auch explizit über den layout-Parameter möglich). Sowohl US- als auch JIS-Layout wurden auf echter Hardware verifiziert (siehe test/REALWORLD_TESTING.md). Andere Layouts als US/JIS werden derzeit nicht unterstützt (sie werden als US behandelt). Die Eingabe von Hiragana/Kanji über IME-Umwandlung liegt außerhalb des Anwendungsbereichs.

3. type_text validiert alles, bevor es sendet (keine teilweisen Nebenwirkungen)

Wenn auch nur ein einziges nicht unterstütztes Zeichen (z. B. Nicht-ASCII) enthalten ist, wird nichts gesendet und ein Fehler zurückgegeben. Es kann nicht der Zustand eintreten, dass teilweise eingegeben wird und der Rest fehlschlägt.

4. Die Grenzen der Geräteslots sind variabel

Von den 20 Slots \\.\interception00–19 hängt es von der bei der Treiberinstallation festgelegten Konfiguration (KeyboardSlotCount) ab, wo die Tastatur aufhört und die Maus beginnt (Standard ist 10/10). Die Standardwerte der Werkzeuge (Tastaturbezogen device=0, Mausbezogen device=10) setzen die Standardkonfiguration voraus. Wenn Sie mit mehreren Geräten oder einer nicht standardmäßigen Konfiguration arbeiten, prüfen Sie zuerst keyboardSlotCount/mouseSlotCount in get_driver_status.

5. Es gibt eine Ratenbegrenzung

Standardmäßig sind maximal 500 Eingabeereignisse pro 10 Sekunden erlaubt (änderbar über die Umgebungsvariablen OIB_MCP_RATE_LIMIT_MAX / OIB_MCP_RATE_LIMIT_WINDOW_MS). Dies verhindert, dass ein durchgegangener Agent (einschließlich Prompt-Injection) ununterbrochen Eingaben feuert. Bei Überschreitung wird RateLimitError zurückgegeben.

6. Der Exklusivmodus ist mächtig und gefährlich. Nur außerhalb von CI/Dediziert-Testgeräten verwenden

Wenn enable_exclusive_input_mode aktiviert ist, werden physische Tastatur-/Mauseingaben des Bedieners nicht mehr an die Ziel-App weitergeleitet. Wenn Sie ihn auf einem PC im täglichen Gebrauch aktivieren, werden physische Eingaben unbrauchbar. Daher ist er nur für unbeaufsichtigte Testumgebungen (CI, Dediziert-Testgeräte) vorgesehen.

• Wenn der Heartbeat für eine bestimmte Zeit (Standard 5 Sekunden, einstellbar über watchdogTimeoutMs) ausbleibt, wird der Modus automatisch aufgehoben

• disable_exclusive_input_mode kann immer aufgerufen werden, unabhängig vom Arm-Zustand oder der Ratenbegrenzung

• Als letztes Mittel, falls der MCP-Server oder der KI-Agent selbst nicht mehr reagiert: Wenn der oib_bridge.exe-Prozess beendet wird, werden die physischen Eingaben über den Treibermechanismus sofort wiederhergestellt (dies geschieht durch die Bereinigung beim Schließen des Handles im Interception-Protokoll; kein anderer Prozess kann dies ersetzen). Details finden Sie in SECURITY.md.

7. In v1 gibt es keine „Lese-/Überwachungswerkzeuge"

Werkzeuge, die physische Tastatur-/Mauseingaben an den KI-Agenten weitergeben (entsprechend IOCTL_READ/interception_receive), sind bewusst nicht implementiert. Dadurch wird das schwerwiegendste Missbrauchsszenario – dass KI über MCP die Tastatureingaben des gesamten Systems abhören kann – konstruktionsbedingt ausgeschlossen.

Voraussetzungen

• Nur Windows (da OpenInputBridge selbst nur für Windows ist)

• Der OpenInputBridge-Treiber muss installiert und gestartet sein (sc.exe query OpenInputBridgeKeyboard / OpenInputBridgeMouse muss RUNNING anzeigen)

• Node.js 18 oder höher

• Visual Studio 2022 (C++-Buildtools) zum Erstellen der Hilfsprogramm-Datei – die Verteilung vorgefertigter Binärdateien ist für die Zukunft geplant (siehe „Bekannte Einschränkungen" unten)

Schnellstart

git clone https://github.com/Applet-LLC/OpenInputBridge-MCP.git
cd OpenInputBridge-MCP
npm install
npm run build

# C ヘルパーのビルド (Visual Studio Developer PowerShell/コマンドプロンプトで)
cl.exe /nologo /W4 /utf-8 /Fe:helper\oib_bridge.exe helper\oib_bridge.c

Registrieren Sie den Server im MCP-Client (z. B. in der .mcp.json von Claude Code).

{
  "mcpServers": {
    "openinputbridge": {
      "command": "node",
      "args": ["C:\\path\\to\\OpenInputBridge-MCP\\dist\\index.js"]
    }
  }
}

Prüfen Sie nach der Verbindung zunächst mit get_driver_status, ob der Treiber erkannt wird, rufen Sie dann enable_input_control auf und verwenden Sie anschließend die jeweiligen Werkzeuge.

Bekannte Einschränkungen

Die Verifizierung auf echter Hardware (OpenInputBridge-Installationsumgebung) wurde durchgeführt. Details finden Sie in test/REALWORLD_TESTING.md.

• Unterstützt US-/JIS-Layout (type_text erkennt das Layout des fokussierten Fensters bei jedem Aufruf automatisch, auch explizit angebbar). Andere Layouts (z. B. deutsches/französisches Layout) werden derzeit nicht unterstützt und als US behandelt. Die Eingabe von Hiragana/Kanji über IME-Umwandlung liegt außerhalb des Anwendungsbereichs

• Die „¥"-Taste des JIS-Layouts sendet (aufgrund einer bekannten Windows-Spezifikation) tatsächlich einen ASCII-Backslash; es gibt keine Möglichkeit, das echte Yen-Zeichen (U+00A5) über type_text einzugeben (die physische Taste selbst kann mit press_key({key:"IntlYen"}) gedrückt werden)

• Bei extremen Mustern, bei denen type_text den Umschalt-Zustand pro Zeichen wechselt (z. B. "MiXeD"), kann der Umschalt-Zustand bei einigen Zeichen auch nach Timing-Maßnahmen nicht übernommen werden. Bei normalem englischem Text, Bezeichnern usw. wurde bestätigt, dass dies kein Problem darstellt

• Die relative Mausbewegung (mouse_move, absolute:false) unterliegt der Zeigerbeschleunigung des Betriebssystems; daher stimmt die angegebene Bewegungsmenge nicht mit der tatsächlichen Cursorbewegung überein (da derselbe Pfad wie bei einer physischen Maus verwendet wird, ist dies das erwartete Verhalten)

• Das normalisierte Koordinatensystem der absoluten Mausbewegung (absolute:true) (die Referenz in Multi-Monitor-/DPI-Skalierungsumgebungen) ist nicht spezifiziert. Es wird empfohlen, vor der Verwendung den Zielpunkt in der jeweiligen Umgebung zu überprüfen

• Nur Windows

• Keine Lese-/Überwachungswerkzeuge (bewusst, siehe oben)

• Keine vorgefertigten Binärdateien verteilt: Derzeit muss der Nutzer helper/oib_bridge.c selbst erstellen. Der Build über GitHub Actions und die npm-Veröffentlichung sind zukünftige Meilensteine

Sicherheit

Lesen Sie unbedingt SECURITY.md über die Risiken der Fähigkeiten dieses Werkzeugs (Injektion von Eingaben in das gesamte System aus einem Prozess ohne Rechteerweiterung) und die implementierten Sicherheitsmechanismen.

Roadmap

Künftige Kandidaten für Verifizierung/Verbesserung (Priorität unbestimmt, Details in test/REALWORLD_TESTING.md unter „Nicht durchgeführte Verifizierungen"):

• Verifizierung auf echter Hardware der automatischen Wiederherstellung durch die Treiberbereinigung, wenn oib_bridge.exe während aktivem Exklusivmodus zwangsweise beendet wird

• Einzelne Verifizierung der Koordinatengenauigkeit und des Verhaltens der einzelnen Tasten von mouse_click

• Genaue Spezifikation des Koordinatensystems der absoluten Mausbewegung (absolute:true) (in Multi-Monitor-/DPI-Skalierungsumgebungen)

• Unterstützung anderer Tastaturlayouts als US/JIS

Lizenz

MIT. Es besteht keinerlei Abhängigkeit vom Code von third_party/interception(LGPL).

Mitwirkende

• Applet-LLC — Projektinhaber

• Claude(Anthropic, über Claude Code) — Beitrag zu Implementierung, Verifizierung auf echter Hardware und Dokumenterstellung