OpenInputBridge-MCP

OpenInputBridge（Interception совместимый драйвер ввода клавиатуры/мыши уровня ядра)を、MCP (Model Context Protocol) 経由のツールとして公開するサーバーです。 Сервер, публикующий OpenInputBridge — совместимый с Interception драйвер ввода клавиатуры/мыши на уровне ядра — в виде инструментов через MCP (Model Context Protocol).

GUI/ネイティブアプリのテスト自動化における SendInput() / UI Automation / 座標ベースの自動化ツールの代替・上位互換として、AIエージェント（Claude Codeなど）やテストコードから、カーネルレベルの合成キーボード/マウス入力を送信できます。 Вы можете отправлять синтетический ввод с клавиатуры/мыши на уровне ядра от AI-агентов (например, Claude Code) или тестового кода — как альтернативу и более продвинутую замену SendInput(), UI Automation и инструментам автоматизации на основе координат при тестировании GUI/нативных приложений.

⚠️ 本プロジェクトは oblitum/Interception（LGPL/商用デュアルライセンス）のコードには一切依存していません。ヘルパー実行ファイル（helper/oib_bridge.c）は、OpenInputBridge本体の docs/PROTOCOL.md に文書化されたワイヤプロトコルだけを根拠に、独自にIOCTLを実装しています。

⚠️ Этот проект полностью не зависит от кода oblitum/Interception (двойная лицензия LGPL/коммерческая). Вспомогательный исполняемый файл (helper/oib_bridge.c) реализует собственный IOCTL, опираясь исключительно на проводной протокол, задокументированный в docs/PROTOCOL.md самой OpenInputBridge.

これは何のためのツールか

Related MCP server: ScreenHand

Каково назначение этого инструмента?

SendInput() / UI Automation / PyAutoGUI +[Pause] Selenium等の座標ベース自動化には、テスト自動化の現場でよく遭遇する、構造的な限界があります。本ツールはそれらを、ドライバレベルで合成入力を注入することで回避します。

У средств автоматизации на основе координат, таких как SendInput(), UI Automation, PyAutoGUI и Selenium, есть структурные ограничения, с которыми часто сталкиваются при автоматизации тестирования. Этот инструмент обходит их, внедряя синтетический ввод прямо на уровне драйвера.

注意: 上記はあくまで技術的な限界の回避策であり、「検知されない」ことを保証するものではありません。カーネルレベルのフィルタドライバ自体が検知される可能性があることは SECURITY.md に記載されています。自分が権限を持つ・管理しているテスト環境以外（他社のゲーム・アプリのアンチチート回避目的など）での利用は想定しておらず、対象ソフトウェアの利用規約に違反する可能性がある用途には使用しないでください。

Внимание. Вышеописанное — лишь обход технических ограничений, и это не гарантирует, что действие останется «незамеченным». О возможности обнаружения самого фильтрующего драйвера уровня ядра написано в SECURITY.md. Инструмент не предназначен для использования вне сред, которыми вы владеете или управляете (например, для обхода анти-чита в чужих играх/приложениях); не используйте его в целях, которые могут нарушать условия использования соответствующего ПО.

アーキテクチャ

Архитектура

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

• stdioトランスポートのみ。ネットワーク・リスナーは一切持ちません。MCPクライアントがローカルでサブプロセスとして起動する通常の使い方のみを想定しています。

• Только stdio-транспорт. Никаких сетевых listeners. Предусмотрен только обычный вариант, когда MCP-клиент запускает его как локальный подпроцесс.

• ヘルパー（oib_bridge.exe）とドライバの間は docs/PROTOCOL.md を単一の仕様源とし、third_party/interception（LGPL）には一切依存しません。

• Между хелпером (oib_bridge.exe) и драйвером единственным источником спецификации является docs/PROTOCOL.md; зависимостей от third_party/interruption (LGPL) нет.

• MCPサーバー（Node.js）とヘルパー（C言語）の間は、1行に1つのJSONオブジェクトという、単純なリクエスト/レスポンス方式です。

• Между MCP-сервером (Node.js) и хелпером (C) — простой протокол запроса/ответа: одна строка — один JSON-объект.

できること（v1ツール一覧）

Возможности (список инструментов v1)

送信専用です。物理入力の内容を読み取る・監視するツールは意図的に含まれていません（詳細は SECURITY.md）。 Только отправка. Инструменты для чтения/наблюдения содержимого физического ввода намеренно не включены (см. SECURITY.md).

AIエージャントが知っておくべき仕様

Что следует знать AI-агенту

このMCPサーバーを操作するAIエージェント（あるいはこれを実装する開発者）は、以下の点を理解しておく必要があります。 AI-агенту (или разработчику, реализующему данного AI-агента), который будет работать с этим MCP-сервером, необходимо понимать следующее.

1. Перед отправкой обязательно вызвать enable_input_control

サーバー起動直後は、すべての送信系ツール（press_key 等）が NotArmedError で拒否されます。MCPクライアント自体のツール許可UIとは別に、このドライバー固有の強力さにふさわしい,もう一段の明示的な同意ステップです。セッション中に一度呼んでえば、以後そのプロセスが生きている間は有効です。

Сразу после запуска сервера все отправные инструменты (например, press_key) отклоняются с ошибкой NotArmedError. Это дополнительный явный шаг согласия, соответствующий особенностям драйвера, в дополнение к интерфейсу разрешений инструментов самого MCP-клиента. Достаточно вызвать его один раз в текущей сессии, и он останется активным в течение всего времени жизни процесса.

2. Имена клавиш — словарь KeyboardEvent.code из DOM

press_key/key_down(../key_up) — параметр key key_upc — для параметра key используется та же терминология, что понятна инженерам тестовой автоматизации на Playwright/Selenium: это нотация DOM KeyboardEvent.code (например KeyA…KeyZ, Digit0…Digit9, Enter, ArrowUp, ShiftLeft, F1…F12, а также IntlRo/IntlYen/Convert/NonConvert/KanaMode, присущие японской раскладке JIS). Полный список см. в KEY_TABLE в src/keycodes.ts. Поскольку эти коды основаны на физическом расположении клавиш, они работают независимо от раскладки.

type_text должен вычислять обратную связь: из вводимых символов восстанавливать нажатия клавиш и состояние Shift, а это уже зависит от активной раскладки клавиатуры на стороне ОС. По умолчанию (layout: "auto") для каждого вызова определяется поле ввода locale окна, находящегося в фокусе, и автоматически выбирается между американской (US) и японской (JIS) раскладкой (можно также задать явно через параметр layout). Обе раскладки — US и JIS — проверены на реальном оборудовании (см. test/REALWORLD TESTING.md). Прочие клавиатурные раскладки (кроме US/JIS) пока не поддерживаются и считаются US. Ввод хираганы/汉字 через IME «не входит» в область отвественности.

3. type_text сначала полностью проверяет текст и только потом отправляет (без частичных побочных эффектов)

Если в строке есть хотя бы один неподдерживаемый символ (например, не ASCII), то ничего не отправляется и возвращается ошибка. Не бывает такого, чтобы часть текста уже была введена, а остаток не смог.

4. Границы слотов устройств могут быть переменными

Среди двадцати слотов \\.\interception00…19 то, где заканчется клавиатура и начинается мышь, зависит от параметра KeyboardSlotCount, заданного при установке драйвера (по умолчанию — 10/10). Встроенные значения по умолчанию в инструментах (для клавиатуры device=0, для мыши — device=10) рассчитываются на стандартную конфигурацию, поэтому при работе с несколькими устройствми или нестандартной конфигурацией сначала проверьте поля keyboardSlotCount/mouseSlotCount в get_driver_status.

5. Лимит частоты запросов

По умолчанию разрешается не более 500 событий ввода за 10 секунд (может меняться через переменные среды OIB_MCP_RATE_LIMIT_MAX / OIB_MCP_RATE_LIMIT_WINDOW_MS). Это защита от непрерывной отправки событий ввышедшим из-под контроля агентом (включая применение при инъекции в промпт). При превышении возвращается RateLimitError.

6. Исключительный режим — это мощно и опасно. Только на CI / специализированных тестовых машинах

При включении enable_exclusive_input_mode текущая и физическая клавиатура/мышь оператора вообще не будут передавать ввод в целевое приложение. Включение этого режима на ежедневно используемой рабочей машине приведет к тому, что физическая клавиатура/мышь перестанет работать — поэтому он предназначен только для автоматических тестов без наблюдателя (CI, отдельные тестовые машины).

• Если heartbeat не поступает в течение заданного времени (по умолчанию 5 секунд, настройка через watchdogTimeoutMs), режим автоматически отключается.

• disable_exclusive_mode disable_exclusive_start? Описка: disable_exclusive_input_mode — может быть вызкан всегда, независимо от наличия arm или лимита частоты запросов.

• В самом крайнем случае, когда MCP-сервер или сам AI-агент становятся недоступны: завершение процесса oib_bridge.exe возвращает физический ввод немедленно (очистка при закрытии дескриптора по протоколу Interception; этот эффект не может быть заменен никаким другим процессом). Подробности — в SECURITY.md.

7. Набор v1 не включает инструменты «чтения/мониторинга»

Инструменты, которые передают AI-агенту данные о том, что ввелось с физической клавиатуры/мыши (аналоги IOCTL_READ/interception_receive), намеренно отсутствуют реализация. Это — проектировочное решение, которое исключает наиболее серьёзный способ злоупотребления: когда ИИ мог бы через MCP прослушивать весь ввод на системе.

前提条件

Предварительные требования

• Windows特化（OpenInputBridge сам работает только на Windows）

• Только Windows — поскольку сам OpenInputBridge является Windows-only.

• OpenInputBridge-driver должен быть установка и запущен (sc.exe query OpenInputBridgeKeyboard / OpenInputBridgeMouse должны возвращать RUNNING).

• Вожен Node.js 18 или выше

• Для сборки исполняемого файла-хелпера требуется Visual Studio 2022 (C++ Build Tools). Готовые предварительно собранные бинарники будут распространяться позже (см. «Оценные ограничения»).

クイックスタート

Краткое руководство

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

Выполните регистрацию в MCP-клиенте (например, в файле .mcp.json проекта Claude Code).

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

После подключения сначала проверьте, что драйвер поопределяем, через get_driver_status, затем вызовите enable_input_control и только после этого используйте отдельные инструменты.

既知の制限

Известные ограничения

Проверка на реальном оборудовании (в среде с установленным OpenInputBridge) была выполнена.Подробности см. в test/REALWORLD_TESTING.md.

• Поддерживаются американская (US) и японская (JIS) раскладки (type_text для каждого вызова автоматически определяет layout окна в фокусе; можно выбрать и явно). Прочие раскладки (например, немецкая, французская) в настоящее время не поддерживаются — они обрабатываются как US. Ввод хираганы/кандзи через IME не входит в возможности. It is important to note в исходной спецификации содержится это.

• Клавиша «¥» на клавиатуре JIS (в силу известной спецификации Windows) на самом деле отправляет ASCII- backslash \, и в type_text нет способа ввести настоящий символ йены (U+00A5). При этом саму физическую клавишу можно нажать через press_key({ key: "IntlYen" }).

• В type_text при экстремальных паттернах посимвольного переключения Shift (например, "MiXeD") некоторые символы, даже после мер по тайминга, иногда не учитывают Shift. В обычных текстах — английских фразах, идентификаторах — это не проявляется.

• Относительное перемещение мыши (mouse_move с absolute: false) зависит от ускорения указателя ОС, поэтому заданное количество перемещения и фактическое перемещение курсора не совпадают (ожидаемое поведение, поскольку используется путь физической мыши).

• Система координат для абсолютного перемещения мыши (absolute: true) (особенно на мульти мониторах и в сценах с масштабированием DPI) не специфицировано. Рекомендуется заранее проверять, куда попадает указатель, в вашем окружении.

• Windows only

• Нет инструментов чтения / наблюдения (намеренно, см. выше).

• Готовые бинарные файлы не распространяются: в настоящее время пользователь обязан сам собрать helper/oib_bridge.c. Сборка в GitHub Actions и публикация в npm — в будущих маком.

セキュリティ

Безопасность

О рисках возможностей данного инструмента (внедрение ввода по всей системе из процесса без повышенных привелегий) и о реализованных — прочтите SECURITY.md.

ロードマップ

План развития (Roadmap)

Для будущих проверки и улучшений (приоритет не определен, их описание см. раздел «Невыполненные проверки» в test/REALWORLD_TESTING.md):

• Проверка на реальном оборудовании автоматического восстановления через очистку драйвера при уничтожении процесса oib_bridge.exe во время работы в эксклюзивном режиме.

• Отдельные тесты точности координат и поведение каждой кнопки для инструмента mouse_click.

• Точное определение системы координат для абсолютного перемещения мыши (absolute: true) в окружениях с один мульти монитором и масштабированием DPI.

• Поддержка раскладок клавиатуры кроме US/JIS.

ライセンス

Лицензия

MIT. Нет никакой зависимости от кода third_party/interaction (LGPL) — его действительно нет.

Contributors (авторы)

• Applet-LLC — владелец проекта

• Claude (Anthropic, через Claude Code) — вклад в реализацию, проверку на реальном оборудовании и создание документации.