OpenInputBridge-MCP

OpenInputBridge(Interception 호환의 커널 레벨 키보드/마우스 입력 드라이버)를 MCP(Model Context Protocol) 경유의 도구로 공개하는 서버입니다.

GUI/네이티브 앱 테스트 자동화에 있어 SendInput() / UI Automation / 좌표 기반 자동화 도구의 대안이자 상위 호환으로서, AI 에이전트(Claude Code 등)나 테스트 코드에서 커널 레벨의 합성 키보드/마우스 입력을 전송할 수 있습니다.

⚠️ 본 프로젝트는 oblitum/Interception(LGPL/상용 듀얼 라이선스)의 코드에 전혀 의존하지 않습니다. 헬퍼 실행 파일(helper/oib_bridge.c)은 OpenInputBridge 본체의 docs/PROTOCOL.md에 문서화된 와이어 프로토콜만을 근거로 독자적으로IOCTL을 구현하고 있습니다.

어떤 용도의 도구인가

SendInput() / UI Automation / PyAutoGUI・Selenium 등의 좌표 기반 자동화에는 테스트 자동화 현장에서 자주 접하게 되는 구조적 한계가 있습니다. 본 도구는 그 한계를 드라이버 레벨에서 합성 입력을 주입하여 회피합니다.

주의: 위의 내용은 어디까지나 기술적 한계의 회피 수단이며, "탐지되지 않음"을 보장하는 것은 아닙니다. 커널 레벨의 필터 드라이버가 탐지될 수 있다는 점은 SECURITY.md에 기재되어 있습니다. 자신이 권한을 가지거나 관리하는 테스트 환경 이외(타사 게임・앱의 안티치트 회피 목적 등)에서의 사용은 상정하지 않고 있으며, 대상 소프트웨어의 이용약관을 위반할 가능성이 있는 용도에는 사용하지 마십시오.

Related MCP server: ScreenHand

아키텍처

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 클라이언트가 로컬에서 부프로세스 시작할 때 일반적인 사용법만 상정하고 있습니다.

• 헬러(oib_bridge.exe)와 드라이버 사이에는 docs/PROTOCOL.md를 단일한 사양 원으로서 본체시, third_party/interception(LGPL)에는 일절 의존하지 않습니다.

• MCP 서버(Node.js)와 헬퍼(C) 사이는 1행 1JSON 오브젝트의 간단한 요청/응답 프로토콜입니다.

제공 기능(v1 도구 일람)

전송 전용입니다. 물리 입력의 내용을 판독하거나 감시하는 도구는 의도적으로 포함하지 않습니다(자세한 내용은 SECURITY.md).

AI 에이전트가 알아야 할 스펙

이 MCP 서버를 조작하는 AI 에이전트(또는 그것을 구현하는 개발자)는 아래를 이해할 필요가 있습니다.

1. 송신 전 반드시 enable_input_control 호출

서버 기동 후 직후에는 모든 전송계 도구(press_key 등)가 NotArmedError로 거부됩니다. MCP 클라이언트 자신의 도구 허가 UI와는 별도로, 이 드라이버 특유의 강함과 균형이 맞는 한층 더 명시적인 동의 준비입니다. 세션 중 1회 호출하면 이후 그 프로세스가 살아 있는 동안 유효합니다.

2. 키 이름은 DOM KeyboardEvent.code 어휘

press_key/key_down/key_up의 key 파라미마타는 Playwright/Selenium과 테스트 자동화 엔에서는 익숙한 DOM KeyboardEvent.code 명명(KeyA〜KeyZ, Digit0〜Digit9, Enter, ArrowUp, ShiftLeft, F1〜F12 等, 특히 JIS 배열 전용 IntlRo/IntlYen/Convert/NonConvert/KanaMode 포함)을 사용합니다. 전체 목록은 src/keycodes.ts 중 KEY_TABLE에 있습니다. 이들은 물리 키 위치 기반이므로 레이아웃에 의존하지 않고 동작합니다.

type_text는 입력된 문자로부터 키+Shift 상태를 대중하는 뒷待 필요가 있으며 이는 OS 측의 활성 키보드 레이아웃에 의존합니다. 기본(layout: "auto") 시에는 포커스가 있는 토입 창의 입력 로케일에 대해 호출 시마다 검출해서 US/JIS(JAPANESE) 배열을 자동으로 선택합니다(layout 파라미터에서 명시 지정도 가능). US/JIS 모두 실기에서 확인 완료였습니다(test/REALWORLD_TESTING.md 참조). US/JIS 이외의 레이아웃은 현재 미지원(U.S.로 처리됨). IME 리는 편리한 글자/한자 변환은 대상 외입니다.

3. type_text는 전체 검증 후 전송됨(부분적인 부작용 없음)

미지원 문자(비ASCII 전체 등)가 한 글자라도 포함하는 경우 아무것도 전송하지 않고 오류를 반환합니다. 도중까지 입력되었지만 나머지가 실패하는 상태로는 되지 않습니다.

4. 장치 슬롯의 경계선은 가변

\\.\interception00〜19의 20 슬롯 중 어디까지가 키보드에서 어디부터가 마우스인가는드라이버의 설치 설정(KeyboardSlotCount)에 따라 바뀝니다(기본 10/10). 도구 기본값(키계는 device=0、마우스계는 device=10)은 기본 구성을 전제로 하고 있으므로, 다중 디바이스/비기본 구성을 다룰 때는 먼저 get_driver_status의 keyboardSlotCount/mouseSlotCount가 나타납니다.

5. 레이트 제한이 있습니다

기본적으로 10초 이내 최대 500개의 입력 이벤트(환경 변수 OIB_MCP_RATE_LIMIT_MAX / OIB_MCP_RATE_LIMIT_WINDOW_MS로 변경 가능). 잘못 에이전트(프롬프트 주입 등)가 입력을 계속 연사하는 것을 막기 위해서입니다. 초과 시 RateLimitError도 반환됩니다.

6. 배타 모드는 강력・위험. CI/전용 테스트기 이외에는 사용하지 않습니다

enable_exclusive_input_mode를 유효화하면 운전자가 물리 키보드/마우스를 조작해도 대상 앱에는 전혀 반영되지 않습니다. 일상에서 사용 중인 PC에서 유효화하면 물리 입력이 사용 불능이 되므로, 무인 테스트 실행 환경(CI・전용 테스트기)에서의 사용을 전제로 합니다.

• 하트바트가 일정 시간(기본 5초, watchdogTimeoutMs로 설정 가능) 중단되면 자동으로 해제됩니다.

• disable_exclusive_input_mode는 arm 상태・레이트 제한과 관계없이 항상 호출 가능합니다.

• MCP 서버나 AI 에이전트 자체가 응답 불능이 된 경우 최종 수단으로 oib_bridge.exe의 프로세스를 종료하면 드라이들 측의 드라이마 장치로 즉시 물리 입력이 복원됩니다(Interception 프로토콜의 핸들 닫힘 클리닝에Hot, 그 밖의 어떤 프로세스를 대체할 것도 불가능). 상세한 것은 SECURITY.md 참조.

7. v1에는 “판독·모니터링” 도구가 없다

물리 키보드/마우스 입력 내용을 AI 에이전트에 전달하는 도구(IO被_READ/Inception` 의 _receive에 해당)는 의도적으로 구현하지 않았습니다. 이것은 "MCP를 통하여 AI가 시전체 전체의 키입력을 감청한다" 는 가장 강한 남용 시나이로는 설계에서 제외.

전제 조건

• Windows 전용(OpenInputBridge가 Windows 전용이므로)

• OpenInputBridge 드라이버가 설치·기동되어 있는 것(sc.exe query OpenInputBridgeKeyboard / OpenInputBridgeMouse가 RUNNING)

• Node.js 생생 18 초이

• 헬퍼 실행 생성 (Visual Studio 2022 (C++ 빌드 도구) — 필요한 자산은 사전 빌드. 사전 배포된 바이너리는 준비 중(이후 "既知の制限" 참조)

퀵스타트

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 클라이언트(예: Claude Code의 .mcp.json)에 등록합니다.

{
  "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 배열 지원(HTTP type_text 자동 검출을 호출하다고 하는 포커스 창 레이아웃, 명시 지정). 그 외의 레이아웃(독일과 프링스 배열 등) 현재 미지능 TEXT로 처리됩니다. IME를