@harusame64/desktop-touch-mcp 0.15.2 → 0.15.4

package/README.ja.md

@@ -7,14 +7,17 @@
 > **「Claude CLI にスクショを毎回コピーしていたあなたへ。」**
 
 Claude がデスクトップを直接見て、直接操作する。  
-マウス・キーボード・スクリーンショット・Windows UI Automation・Chrome DevTools Protocol・ターミナル・SmartScroll・Reactive Perception Graph を統合した 56 のツールを提供する MCP サーバーです。
+マウス・キーボード・スクリーンショット・Windows UI Automation・Chrome DevTools Protocol・ターミナル・SmartScroll・Reactive Perception Graph を統合した 57 のツールを提供する MCP サーバーです。
 
-> *ウィンドウキャプチャに MPEG P フレーム方式の差分処理を適用。初回フレーム以降は変化したウィンドウのみを送信するため、一般的な自動化ループでトークン使用量を約 60〜80% 削減できます。*
+> *v0.15: Rust ネイティブエンジンにより**平均 82 倍高速化** — UIA フォーカス取得 2ms、SSE2 SIMD 画像差分 13〜15 倍速。設定不要：エンジンは自動ロード、不在時は PowerShell に透過フォールバック。*
+> *v0.15.4: **Set-of-Marks (SoM) ビジュアルフォールバック** — ゲーム・RDP・非対応 Electron アプリでも OCR + Rust 画像前処理で操作可能な要素を返す。UIA が完全に無効でも動作します。*
 
 ---
 
 ## 特徴
 
+- **⚡ 高性能 Rust ネイティブコア** — UIA ブリッジと画像差分エンジンを Rust (`napi-rs` + `windows-rs`) で実装し、ネイティブ `.node` アドオンとしてロード。専用 MTA スレッドからの直接 COM 呼び出しにより PowerShell プロセス起動を排除 — `getFocusedElement` は **2ms**（160 倍高速）、`getUiElements` はバッチ型 BFS アルゴリズムでクロスプロセス RPC を最小化し **約 100ms** で完了。画像差分は **SSE2 SIMD** で 13〜15 倍のスループット。ネイティブエンジンが利用不可の場合、全関数が PowerShell に透過フォールバック — 設定不要。
+- **🎯 Set-of-Marks (SoM) ビジュアルフォールバック** — ゲーム・RDP・非対応 Electron アプリで UIA が完全に機能しない場合でも、`screenshot(detail="text")` が Hybrid Non-CDP パイプラインを自動起動。Rust 画像前処理 → Windows OCR → クラスタリング → 赤い枠線 + 番号バッジ（`[1]`、`[2]`…）付き PNG 画像を生成し、`clickAt` 座標付きの要素リストを返します。CDP 不要。
 - **LLM ネイティブ設計** — 人間の操作を模倣するのではなく、「LLM がいかにコンテキストを消費せず高速に動けるか」を前提に設計。`run_macro` による複数操作の一括実行（API 往復の削減）と、**MPEG P-frame 方式のレイヤー差分** (`diffMode`) を組み合わせることで、無駄な画像転送や推論ループを極限まで削ぎ落とす。
 - **Reactive Perception Graph** — ウィンドウやブラウザタブに `lensId` を登録し、以後の action tool に渡すだけで、操作前の安全 guard と操作後の `post.perception` フィードバックを受け取れます。`screenshot` / `get_context` の反復を減らし、別ウィンドウへの誤入力や古い座標クリックを防ぎます。
 - **日本語/CJK 完全対応** — ウィンドウタイトル取得に Win32 `GetWindowTextW` を使用。nut-js の文字化けを回避。IME バイパス入力にも対応。
@@ -22,6 +25,8 @@ Claude がデスクトップを直接見て、直接操作する。
 - **座標変換不要の 1:1 モード** — `dotByDot=true` で WebP 1:1 キャプチャ。画像上のピクセル座標 = 画面座標なのでスケール計算が不要。
 - **ブラウザキャプチャのデータ削減** — `grayscale=true`、`dotByDotMaxDimension=1280`、`windowTitle + region` の部分切り出しで、ブラウザ chrome や不要な余白を除外。重いキャプチャで 50〜70% 程度の削減を狙えます。
 - **UIA アクション要素抽出** — `detail="text"` でボタン・入力欄の名前と `clickAt` 座標を JSON で返すため、画像を見なくても操作できる。
+- **Chromium スマートフォールバック** — Chrome/Edge/Brave に対して `detail="text"` を使うと、低速な UIA を自動スキップし Windows OCR を実行。`hints.chromiumGuard` + `hints.ocrFallbackFired` で経路を判別可能。
+- **CLI 自動ドック** — `dock_window` でウィンドウを画面隅にスナップ＆最前面固定。`DESKTOP_TOUCH_DOCK_TITLE='@parent'` を設定すると、MCP 起動時にプロセスツリーを辿って Claude CLI をホストするターミナルを自動ドック。
 - **緊急停止 (Failsafe)** — マウスを**画面左上コーナー (0,0 付近 10px)** に移動すると MCP サーバーが即座に終了。
 
 ---
@@ -32,7 +37,7 @@ Claude がデスクトップを直接見て、直接操作する。
 |---|---|
 | OS | Windows 10 / 11 (64-bit) |
 | Node.js | v20 以上推奨 (v22+ で動作確認済み) |
-| PowerShell | 5.1 以上 (Windows 標準同梱) |
+| PowerShell | 5.1 以上 (Windows 標準同梱) — Rust ネイティブエンジン不在時のフォールバック用 |
 | Claude CLI | `claude` コマンドが使えること |
 
 > **注意:** nut-js のネイティブバインディングは Visual C++ 再頒布可能パッケージを必要とします。  
@@ -107,7 +112,7 @@ npm install
 
 ---
 
-## ツール一覧 (56 ツール)
+## ツール一覧 (57 ツール)
 
 > 📖 **詳細リファレンス**: [`docs/system-overview.md`](docs/system-overview.md) — 各ツールのパラメータ・応答形式・座標計算・レイヤーバッファ・技術ノートを網羅（英語）。
 
@@ -179,6 +184,7 @@ DOM を触る `browser_*` ツールは `includeContext:false` で末尾の `acti
 | `get_context` | フォーカス中ウィンドウ・要素・カーソル・ページ状態を軽量取得 |
 | `get_history` | 直近ツール履歴を取得 |
 | `get_document_state` | Chromeページ状態（URL/title/readyState/scroll）をCDPで取得 |
+| `engine_status` | 各サブシステムの動作バックエンドを返す：`uia`（Rust native または powershell）/ `imageDiff`（Rust SSE2 または typescript）。診断用 — パフォーマンス調査時に1回呼ぶ |
 | `wait_until` | window/focus/terminal/browser DOM などの状態変化をサーバー側で待機 |
 | `events_subscribe` / `events_poll` / `events_unsubscribe` / `events_list` | ウィンドウ出現・消滅・フォーカス変化を購読/取得 |
 
@@ -320,7 +326,7 @@ screenshot(diffMode=true)               → 変化した窓だけ確認（~160 t
 
 ### PowerShell インジェクション対策
 
-UIA ブリッジの `-like` パターンには `escapeLike()` でワイルドカード文字 (`*`, `?`, `[`, `]`) をエスケープ済み。
+UIA ブリッジの PowerShell フォールバックパスでは、`-like` パターンに `escapeLike()` でワイルドカード文字 (`*`, `?`, `[`, `]`) をエスケープ済み。v0.15 以降、UIA の主パスは Rust ネイティブエンジン（直接 COM 呼び出し）のため、PowerShell は補助的なフォールバックとしてのみ使用されます。
 
 ---
 
@@ -403,12 +409,44 @@ Windows のフォアグラウンド保護機能により、ピン固定された
 | 制限 | 詳細 | 回避策 |
 |---|---|---|
 | ゲーム・動画プレイヤーの背面キャプチャが黒またはハング | DirectX フルスクリーン等は `PW_RENDERFULLCONTENT (flag=2)` でもキャプチャ不可な場合がある | `screenshot_background(fullContent=false)` で旧フラグに切り替え、それでも黒なら前面キャプチャ (`screenshot`) を使用 |
-| UIA 呼び出しのオーバーヘッド | PowerShell 経由のため 1 回約 300ms。`workspace_snapshot` 内は 2s タイムアウトに短縮 | 操作前に `workspace_snapshot` で一括取得し、以降は `diffMode` で差分確認 |
+| UIA 呼び出しのオーバーヘッド | Rust ネイティブ: フォーカス取得 ~2ms、ツリー走査 ~100ms。PowerShell フォールバック: ~300ms | 操作前に `workspace_snapshot` で一括取得し、以降は `diffMode` で差分確認 |
 | Chrome / WinUI3 の UIA 要素が空 | Chromium は UIA を限定的にしか公開しない | `browser_connect` + `browser_find_element` で DOM ベースのクリックを使用。視覚確認のみなら `screenshot(detail="image")` |
 | レイヤーバッファの TTL | 90 秒操作なしでバッファが自動クリア → 次回 `diffMode` が I-frame になる | 長い待機後は `workspace_snapshot` で明示的にリセット |
 
 ---
 
+## パフォーマンス (v0.15)
+
+### UIA ブリッジ — Rust ネイティブ vs PowerShell
+
+| 関数 | Rust Native | PowerShell | 高速化 |
+|---|---|---|---|
+| `getFocusedElement` | **2.2 ms** | 366 ms | 🚀 **163.9×** |
+| `getUiElements` | **106.5 ms** | 346 ms | 🚀 **3.3×** |
+| **平均** | | | **🚀 ~82×** |
+
+### 画像差分エンジン — Rust SSE2 SIMD vs TypeScript
+
+| 関数 | Rust SSE2 | TypeScript | 高速化 |
+|---|---|---|---|
+| `computeChangeFraction` (1080p) | **0.26 ms** | 3.8 ms | 🚀 **~15×** |
+| `dHash` (1080p) | **0.09 ms** | 1.2 ms | 🚀 **~13×** |
+
+### アーキテクチャ概要
+
+```
+Claude CLI → MCP Server (TypeScript)
+                ├── Rust Native Engine (.node addon)
+                │     ├── UIA: 専用 MTA スレッド → 直接 COM 呼び出し
+                │     └── Image: SSE2 SIMD カーネル
+                └── PowerShell フォールバック（自動切替）
+```
+
+- **バッチ型 BFS**: `FindAllBuildCache(TreeScope_Children)` による階層ごとの一括フェッチ。`maxElements` 到達で即打ち切りし、巨大ツリーでもスケーラブル。
+- **自動フォールバック**: ネイティブエンジンが利用不可の場合、全関数が PowerShell に透過切替 — 設定不要。
+
+---
+
 ## パフォーマンス目安
 
 | モード | 転送トークン | 用途 |

package/README.md

@@ -1,19 +1,22 @@
 # desktop-touch-mcp
 
-[![desktop-touch-mcp MCP server](https://glama.ai/mcp/servers/Harusame64/desktop-touch-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Harusame64/desktop-touch-mcp)
+[![desktop-touch-mcp MCP server](https://glama.ai/mcp/servers/Harusame64/desktop-touch-mcp/badges/card.svg)](https://glama.ai/mcp/servers/Harusame64/desktop-touch-mcp)
 
 [日本語](README.ja.md)
 
 > **Stop pasting screenshots. Let Claude see and control your desktop directly.**
 
-An MCP server that gives Claude eyes and hands on Windows — 56 tools covering screenshots, mouse, keyboard, Windows UI Automation, Chrome DevTools Protocol, clipboard, desktop notifications, SmartScroll, and a Reactive Perception Graph for safe multi-step automation, designed from the ground up for LLM efficiency.
+An MCP server that gives Claude eyes and hands on Windows — 57 tools covering screenshots, mouse, keyboard, Windows UI Automation, Chrome DevTools Protocol, clipboard, desktop notifications, SmartScroll, and a Reactive Perception Graph for safe multi-step automation, designed from the ground up for LLM efficiency.
 
-> *Applies MPEG P-frame diffing to window capture: only changed windows are sent after the first frame, cutting token usage by ~60–80% in typical automation loops.*
+> *v0.15: **82× average speedup** via Rust native engine — UIA focus queries in 2 ms, SSE2-accelerated image diffing at 13–15× native speed. Zero-config: the engine auto-loads when present, with transparent PowerShell fallback.*
+> *v0.15.4: **Set-of-Marks (SoM) visual fallback** — games, RDP sessions, and non-accessible Electron apps now return clickable elements via OCR + Rust image preprocessing, even when UIA is completely unavailable.*
 
 ---
 
 ## Features
 
+- **⚡ High-performance Rust Native Core** — The UIA bridge and image-diff engine are written in Rust (`napi-rs` + `windows-rs`) and loaded as a native `.node` addon. Direct COM calls from a dedicated MTA thread eliminate PowerShell process spawning — `getFocusedElement` completes in **2 ms** (160× faster), and `getUiElements` returns full trees in **~100 ms** with a batch BFS algorithm that minimizes cross-process RPC. Image-diff operations use **SSE2 SIMD** for 13–15× throughput. When the native engine is unavailable, every function transparently falls back to PowerShell — zero config required.
+- **🎯 Set-of-Marks (SoM) visual fallback** — Games, RDP sessions, and non-accessible Electron apps return clickable elements even when UIA is completely blind. `screenshot(detail="text")` automatically detects UIA sparsity and activates a Hybrid Non-CDP pipeline: Rust-powered grayscale + bilinear upscale → Windows OCR → clustering → red bounding-box annotation with numbered badges (`[1]`, `[2]`…). Two parallel representations returned: a visual PNG for spatial orientation and a semantic `elements[]` list with `clickAt` coords — no CDP required.
 - **LLM-native design** — Built around how LLMs think, not how humans click. `run_macro` batches multiple operations into a single API call; `diffMode` sends only the windows that changed since the last frame. Minimal tokens, minimal round-trips.
 - **Reactive Perception Graph** — Register a `lensId` for a window or browser tab, pass it to action tools, and get guard-checked `post.perception` feedback after each action. It reduces repeated `screenshot` / `get_context` calls and prevents wrong-window typing or stale-coordinate clicks.
 - **Full CJK support** — Uses Win32 `GetWindowTextW` for window titles, avoiding nut-js garbling. IME bypass input supported for Japanese/Chinese/Korean environments.
@@ -33,7 +36,7 @@ An MCP server that gives Claude eyes and hands on Windows — 56 tools covering
 |---|---|
 | OS | Windows 10 / 11 (64-bit) |
 | Node.js | v20+ recommended (tested on v22+) |
-| PowerShell | 5.1+ (bundled with Windows) |
+| PowerShell | 5.1+ (bundled with Windows) — used only as fallback when the Rust native engine is unavailable |
 | Claude CLI | `claude` command must be available |
 
 > **Note:** nut-js native bindings require the Visual C++ Redistributable.
@@ -109,7 +112,7 @@ For a local checkout, register the built server directly:
 
 ---
 
-## Tools (56 total)
+## Tools (57 total)
 
 > 📖 **Full command reference**: [`docs/system-overview.md`](docs/system-overview.md) — every tool's parameters, response shape, coordinate math, layer-buffer strategy, and engineering notes in one place.
 
@@ -117,7 +120,7 @@ For a local checkout, register the built server directly:
 ### Screenshot (5)
 | Tool | Description |
 |---|---|
-| `screenshot` | Main capture. Supports `detail`, `dotByDot`, `dotByDotMaxDimension`, `grayscale`, `region` sub-crop, `diffMode` |
+| `screenshot` | Main capture. Supports `detail`, `dotByDot`, `dotByDotMaxDimension`, `grayscale`, `region` sub-crop, `diffMode`. `detail="text"` auto-activates the SoM pipeline when UIA is blind (games, RDP, custom Electron) |
 | `screenshot_background` | Capture a background window without focusing it (PrintWindow API) |
 | `screenshot_ocr` | Windows.Media.Ocr on a window; returns word-level text + screen clickAt coords |
 | `get_screen_info` | Monitor layout, DPI, cursor position |
@@ -176,6 +179,22 @@ All `browser_*` tools that touch the DOM accept `includeContext:false` to omit t
 | `workspace_snapshot` | All windows: thumbnails + UI summaries in one call |
 | `workspace_launch` | Launch an app and auto-detect the new window |
 
+### Context / Wait / History (8)
+| Tool | Description |
+|---|---|
+| `get_context` | Lightweight snapshot of focused window, element, cursor, and page state |
+| `get_history` | Retrieve recent tool invocation history |
+| `get_document_state` | Chrome page state (URL/title/readyState/scroll) via CDP |
+| `engine_status` | Returns which backend is active: `uia` (native Rust or powershell) and `imageDiff` (native Rust SSE2 or typescript). Diagnostic — call once per session when troubleshooting performance |
+| `wait_until` | Server-side wait for window/focus/terminal/browser DOM state changes |
+| `events_subscribe` / `events_poll` / `events_unsubscribe` / `events_list` | Subscribe to and poll window appearance/disappearance/focus events |
+
+### Terminal (2)
+| Tool | Description |
+|---|---|
+| `terminal_read` | Read text from Windows Terminal / PowerShell / cmd / WSL via UIA/OCR. Supports `sinceMarker` for diff reads |
+| `terminal_send` | Send commands to a terminal. Uses clipboard paste by default for IME safety |
+
 ### Pin / Macro (3)
 | Tool | Description |
 |---|---|
@@ -193,7 +212,7 @@ All `browser_*` tools that touch the DOM accept `includeContext:false` to omit t
 |---|---|
 | `notification_show` | Show a Windows system tray balloon notification — useful to alert the user when a long-running task finishes |
 
-### Scroll (1)
+### Scroll (2)
 | Tool | Description |
 |---|---|
 | `scroll_to_element` | Scroll a named element into the viewport without computing scroll amounts. Chrome path: `selector` + `block` alignment. Native path: `name` + `windowTitle` via UIA ScrollItemPattern |
@@ -398,7 +417,7 @@ Script extensions (`.bat`, `.ps1`, `.vbs`, etc.) are rejected. Arguments contain
 
 ### PowerShell injection protection
 
-All `-like` patterns in the UIA bridge are sanitized with `escapeLike()`, which escapes wildcard characters (`*`, `?`, `[`, `]`) before they reach PowerShell.
+All `-like` patterns in the UIA bridge PowerShell fallback path are sanitized with `escapeLike()`, which escapes wildcard characters (`*`, `?`, `[`, `]`) before they reach PowerShell. When the Rust native engine is active, PowerShell is not invoked for UIA operations.
 
 ### Allowlist for `workspace_launch`
 
@@ -594,12 +613,54 @@ Returns `{ ok: true, result: "...", post: { perception: { status: "ok", ... } }
 
 ---
 
+## Performance (v0.15 — Rust Native Engine)
+
+The Rust native engine (`@harusame64/desktop-touch-engine`) replaces PowerShell process spawning with direct COM calls over a persistent MTA thread. It loads automatically as a `.node` addon — no configuration needed.
+
+### UIA Benchmark (vs PowerShell baseline)
+
+| Function | Rust Native | PowerShell | Speedup |
+|---|---|---|---|
+| `getFocusedElement` | **2.2 ms** | 366 ms | **163.9×** |
+| `getUiElements` (Explorer, ~60 elements) | **106.5 ms** | 346 ms | **3.3×** |
+| **Weighted average** | | | **~82×** |
+
+### Image Diff Benchmark (SSE2 SIMD)
+
+| Function | Rust (SSE2) | TypeScript | Speedup |
+|---|---|---|---|
+| `computeChangeFraction` (1920×1080) | **0.26 ms** | 3.8 ms | **~15×** |
+| `dHash` (perceptual hash) | **0.09 ms** | 1.2 ms | **~13×** |
+
+### Architecture
+
+```
+Claude CLI / MCP Client
+    │  stdio or HTTP (MCP protocol)
+    ▼
+desktop-touch-mcp (TypeScript)
+    │
+    ├── Rust Native Engine (.node addon)          ← NEW in v0.15
+    │   ├── UIA: 13 functions via napi-rs + windows-rs 0.62
+    │   │   └── Dedicated COM thread (MTA) + batch BFS algorithm
+    │   └── Image: SSE2 SIMD pixel diff + perceptual hashing
+    │
+    └── PowerShell Fallback (automatic)
+        └── Activates transparently if .node is unavailable
+```
+
+### Why `getUiElements` is 3.3× (not 160×)
+
+The 160× speedup on `getFocusedElement` comes from eliminating PowerShell process startup (~200 ms) and .NET assembly loading. For `getUiElements`, the bottleneck shifts to the **UIA provider** inside the target application (e.g., Explorer) — it must enumerate its UI tree regardless of who asks. The Rust engine uses a **batch BFS algorithm** (`FindAllBuildCache` + `TreeScope_Children`) that minimizes cross-process RPC calls and supports `maxElements` early exit, making it dramatically faster on large trees (VS Code, browsers with 1000+ elements).
+
+---
+
 ## Known limitations
 
 | Limitation | Detail | Workaround |
 |---|---|---|
 | Games / video players may return black or hang in background capture | DirectX fullscreen apps may not work even with `PW_RENDERFULLCONTENT` | Retry with `screenshot_background(fullContent=false)`; if still black, use foreground `screenshot` |
-| UIA call overhead | ~300ms per call via PowerShell; `workspace_snapshot` uses a 2s timeout internally | Batch with `workspace_snapshot` upfront, then use `diffMode` for incremental checks |
+| UIA call overhead | ~2 ms (focus) / ~100 ms (tree) via Rust native engine; ~300 ms via PowerShell fallback | Rust engine loads automatically; `workspace_snapshot` uses a 2 s timeout internally |
 | Chrome / WinUI3 UIA elements are empty | Chromium exposes only limited UIA | `screenshot(detail='text')` auto-detects Chromium and falls back to Windows OCR (`hints.chromiumGuard=true`). For richer DOM access use `browser_connect` + `browser_find_element` |
 | Chromium title-regex misses when sites rewrite `document.title` | Guard relies on the ` - Google Chrome` suffix being present; some sites push it off the end of a long title | Title is treated as plain Chrome (UIA runs). OCR path is still reachable via `ocrFallback='always'` or when UIA returns `<5` elements (`uiaSparse`) |
 | `browser_*` CDP tools need Chrome launched with `--remote-debugging-port` | If Chrome is already running on the default profile without the flag, `browser_launch` / `browser_connect` fail. The CDP E2E suite (`tests/e2e/browser-cdp.test.ts`) will also fail in that state | Close Chrome first, then `browser_launch` will relaunch it in debug mode, or start Chrome manually with `--remote-debugging-port=9222 --user-data-dir=C:\tmp\cdp` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harusame64/desktop-touch-mcp",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "mcpName": "io.github.Harusame64/desktop-touch-mcp",
   "description": "LLM-native Windows computer-use MCP server with 56 tools for screenshots, UIA, mouse/keyboard, Chrome CDP, terminal, SmartScroll, and perception guards",
   "engines": {
@@ -47,8 +47,13 @@
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:capture": "node scripts/test-capture.mjs",
-    "test:e2e": "vitest run tests/e2e",
-    "test:headed": "HEADED=1 vitest run tests/e2e",
+    "test:unit": "vitest run --project=unit",
+    "test:e2e": "vitest run --project=e2e",
+    "test:headed": "HEADED=1 vitest run --project=e2e",
+    "test:e2e:browser": "vitest run --project=e2e \"tests/e2e/browser-*.test.ts\"",
+    "test:e2e:window": "vitest run --project=e2e tests/e2e/dock-window.test.ts tests/e2e/dock-auto.test.ts tests/e2e/focus-integrity.test.ts tests/e2e/force-focus.test.ts tests/e2e/screenshot-electron.test.ts tests/e2e/ui-elements-cache.test.ts",
+    "test:e2e:input": "vitest run --project=e2e tests/e2e/keyboard-focus-lost.test.ts tests/e2e/mouse-focus-lost.test.ts tests/e2e/terminal.test.ts",
+    "test:e2e:perception": "vitest run --project=e2e tests/e2e/perception-mvp.test.ts tests/e2e/rich-narration-edge.test.ts",
     "test:watch": "vitest",
     "generate:stub-catalog": "node scripts/generate-stub-tool-catalog.mjs",
     "check:stub-catalog": "node scripts/generate-stub-tool-catalog.mjs && git diff --exit-code src/stub-tool-catalog.ts",