@harusame64/desktop-touch-mcp 1.10.4 → 1.12.0

package/README.ja.md

@@ -10,7 +10,7 @@
 npx -y @harusame64/desktop-touch-mcp
 ```
 
-28 ツール、Rust ネイティブエンジン (UIA 2ms)、PowerShell 透過フォールバック、日本語/CJK 完全対応、MIT。上記 1 行を Claude / Cursor / VS Code Copilot の MCP 設定に追加するだけで、Notepad、Excel、Chrome、Windows Terminal、その他あらゆるアプリを Claude が操作できるようになります。
+32 ツール、Rust ネイティブエンジン (UIA 2ms)、PowerShell 透過フォールバック、日本語/CJK 完全対応、MIT。上記 1 行を Claude / Cursor / VS Code Copilot の MCP 設定に追加するだけで、Notepad、Excel、Chrome、Windows Terminal、その他あらゆるアプリを Claude が操作できるようになります。
 
 > *v0.15: Rust ネイティブエンジンにより**平均 82 倍高速化** — UIA フォーカス取得 2ms、SSE2 SIMD 画像差分 13〜15 倍速。設定不要：エンジンは自動ロード、不在時は PowerShell に透過フォールバック。*
 > *v0.15.5: **固定リリース検証** — npm ランチャーは対応する GitHub Release tag だけを取得し、Windows runtime zip を検証してから展開します。*
@@ -47,6 +47,8 @@ npx -y @harusame64/desktop-touch-mcp
 > **注意:** nut-js のネイティブバインディングは Visual C++ 再頒布可能パッケージを必要とします。  
 > インストール済みでない場合は [Microsoft公式](https://learn.microsoft.com/ja-jp/cpp/windows/latest-supported-vc-redist) からダウンロードしてください。
 
+> **注意 (Key Locker):** Key Locker が使う認証情報ヘルパーは未署名の実行ファイルのため、環境によっては初回起動時に Windows SmartScreen やアンチウイルスが「発行元不明」の警告を表示することがあります。これは想定内で、ヘルパーは desktop-touch-mcp に同梱され、お使いのマシン上でローカルに動作します。許可して続行して問題ありません。（コード署名は今後のリリースで対応予定です。）
+
 ---
 
 ## インストール
@@ -137,19 +139,25 @@ npm run build
 
 ---
 
-## ツール一覧 (28 ツール — 26 stub catalog + 2 dynamic v2)
+## ツール一覧 (32 ツール — 30 stub catalog + 2 dynamic v2)
 
 > 📖 **詳細リファレンス**: [`docs/system-overview.md`](docs/system-overview.md) — 各ツールのパラメータ・応答形式・座標計算・レイヤーバッファ・技術ノートを網羅（英語）。
 
 ### スクリーンショット系 (5)
 | ツール | 概要 |
 |---|---|
-| `screenshot` | メインキャプチャ。`detail` / `dotByDot` / `dotByDotMaxDimension` / `grayscale` / `region` / `diffMode` 対応 |
+| `screenshot` | メインキャプチャ。`detail` / `dotByDot` / `dotByDotMaxDimension` / `grayscale` / `region` / `diffMode` 対応。画像はインライン展開せず、ディスク保存した画像への安価なリンク `screenshot://by-ref/{id}` を返す |
 | `screenshot_background` | 背面・最小化ウィンドウをキャプチャ (PrintWindow API) |
 | `screenshot_ocr` | Windows OCR で文字と `clickAt` 座標を取得 |
 | `get_screen_info` | モニター解像度・DPI・カーソル位置 |
 | `scroll(action='capture')` | ページ全体をスクロールしながらスティッチ |
 
+### スクリーンショットキャッシュ (2)
+| ツール | 概要 |
+|---|---|
+| `screenshot_query` | by-ref リンクの裏にあるディスクキャッシュの一覧を、ピクセルを再読込せずに取得（captureId・by-ref uri・サイズ・寸法・時刻・tag、キャッシュ全体の合計）。パスは一切返さない |
+| `screenshot_gc` | 保持ポリシー（最新 N 件 / バイト上限 / 経過時間）でキャッシュを掃除。既定は dry-run（削除対象の一覧のみ）。実削除は `dryRun:false` かつ `confirm:true` の両方が必要 |
+
 ### ウィンドウ管理 (4)
 | ツール | 概要 |
 |---|---|
@@ -235,6 +243,16 @@ DOM を触る `browser_*` ツールは `includeContext:false` で末尾の `acti
 | `scroll(action='to_element')` | 要素名またはCSS selectorで対象をviewportへスクロール |
 | `scroll(action='smart')` | CDP → UIA → 画像binary-searchの統合スクロール。ネスト・仮想リスト・sticky header対応 |
 
+### Office (Excel) (1)
+| ツール | 概要 |
+|---|---|
+| `excel` | Excel VBA マクロを COM 経由で記述・実行。`action='run_vba'` はマクロを管理下の Trusted Location に書き込んで実行、`action='check_access_vbom'` は読み取り専用の事前チェック。数式だけでは届かない処理を VBA で実行。初回のみ `node scripts/enable-access-vbom.mjs` |
+
+### Key Locker (1)
+| ツール | 概要 |
+|---|---|
+| `key_locker` | ターミナルが自動入力する認証情報（SSH 鍵のパスフレーズ、sudo / ログインパスワード）を管理。秘密情報はロッカー自身のセキュアダイアログに一度だけ入力し、この PC 上で暗号化保存（Windows DPAPI, current user）— アシスタントには一切見えない。`action='launch_console'` で自動入力対応コンソールを起動（返る `paneId` を `terminal` に渡して `ssh`/`sudo` を流す）/ `save`（登録）/ `list` / `forget` / `set_policy` / `status`。自動入力は `launch_console` で開いたコンソールでのみ発火。`DESKTOP_TOUCH_DISABLE_KEY_LOCKER=1` で無効化 |
+
 ---
 
 ## 推奨ワークフロー (v1.0.0)
@@ -537,15 +555,27 @@ V1 ツールはすべてそのまま動作します。再インストール不
 
 フラグのセマンティクス（完全一致: 文字列 `"1"` のみ有効）:
 
-| `DISABLE_FUKUWARAI_V2` | `ENABLE_FUKUWARAI_V2` | V2 状態 |
+| `DISABLE_FUKUWARAI_V2` | V2 状態 |
+|---|---|
+| 未設定 / `"1"` 以外 | **ON**（デフォルト） |
+| `"1"` | **OFF**（kill switch） |
+
+### スクリーンショットキャッシュ (by-ref ストレージ)
+
+`screenshot` などの画像系応答は、ピクセルを毎回インライン展開する代わりに、ディスク保存した画像への安価なリンク `screenshot://by-ref/{id}` を返します（look→act→confirm の反復が大幅に低トークン化）。キャッシュは自動で上限管理され、`screenshot_query` / `screenshot_gc` で確認・掃除できます。
+
+| 環境変数 | デフォルト | 効果 |
 |---|---|---|
-| 未設定 / `"1"` 以外 | 未設定 / `"1"` 以外 | **ON**（デフォルト） |
-| 未設定 / `"1"` 以外 | `"1"` | ON（後方互換で受理、後述） |
-| `"1"` | 任意 | **OFF** — DISABLE が優先 |
+| `DESKTOP_TOUCH_SCREENSHOTS_DIR` | *(ユーザー別キャッシュ)* | キャッシュ保存先を固定。既定フォルダが作成・書き込み不可（ロックダウン PC など）の場合、この値 → runtime dir → OS の一時フォルダの順に書き込み可否を自動判定し、最初に書ける場所を使う（キャッシュを諦めない）。 |
+| `DESKTOP_TOUCH_SCREENSHOT_MAX_COUNT` | `200` | 保持する最大キャプチャ数。 |
+| `DESKTOP_TOUCH_SCREENSHOT_MAX_BYTES` | `256 MiB` | ディスク上のキャッシュ総量の上限。 |
+| `DESKTOP_TOUCH_SCREENSHOT_MAX_AGE_MS` | *(無効)* | この経過時間（ms）より古いキャプチャを削除（opt-in）。 |
+| `DESKTOP_TOUCH_SCREENSHOT_AUTOPRUNE` | `on` | 新規保存のたびに自動で間引く。`0` で無効化。 |
+| `DESKTOP_TOUCH_SCREENSHOT_MIN_EVICT_AGE_MS` | `60000` | この時間（ms）より新しいキャプチャは自動退避しない。同一 PC 上で別の AI/プロセスが大量キャプチャしていても、渡したばかりの by-ref リンクが開けるよう保護。`0` で無効化。 |
 
-### 非推奨: `DESKTOP_TOUCH_ENABLE_FUKUWARAI_V2`
+### 削除済み: `DESKTOP_TOUCH_ENABLE_FUKUWARAI_V2`
 
-v0.16.x での opt-in フラグです。v0.17 では後方互換として受理されますが、サーバー起動時に非推奨の警告が表示されます。v0.18 で完全に削除されます。アップグレード時にはこのフラグを設定から削除してください。
+v0.16.x での opt-in フラグです。v0.17 以降は V2 がデフォルト ON のため、このフラグは効果を持たず、設定から削除して問題ありません。V2 を無効化するには `DESKTOP_TOUCH_DISABLE_FUKUWARAI_V2=1` を設定してください。
 
 ### V2 が失敗した場合のリカバリ
 
@@ -669,9 +699,9 @@ keyboard(action='type')(use_clipboard=true) を使うこと（IME バイパス
 
 ---
 
-## 🚀 2,000+ Downloads!
+## 🚀 3,000+ Downloads!
 
-おかげさまで2,000ダウンロードを突破しました！この実験的なツールを試し、
+おかげさまで3,000ダウンロードを突破しました！この実験的なツールを試し、
 Issue や PR、バグ報告で貢献してくれたすべての方に感謝します。皆さんの声が
 次のリリースをより良くしてくれました。一緒に育ててくれてありがとう！
 

package/README.md

@@ -10,7 +10,7 @@
 npx -y @harusame64/desktop-touch-mcp
 ```
 
-29 tools, native Rust engine (UIA in 2 ms), zero-config PowerShell fallback, full CJK support, MIT licensed. Add the snippet above to your Claude / Cursor / VS Code Copilot config and Claude can drive Notepad, Excel, Chrome, Windows Terminal, and any other app on your machine.
+32 tools, native Rust engine (UIA in 2 ms), zero-config PowerShell fallback, full CJK support, MIT licensed. Add the snippet above to your Claude / Cursor / VS Code Copilot config and Claude can drive Notepad, Excel, Chrome, Windows Terminal, and any other app on your machine.
 
 > **Why this over pixel-clicking?** Two ideas run through every tool: **discover-then-act** — `desktop_discover` returns interactive entities with short-lived leases instead of raw coordinates, so `desktop_act` operates on *what* you mean, not *where* it was — and **per-action perception guards** that verify the target window's identity and bounds before input lands, catching wrong-window typing and stale-coordinate clicks before they happen.
 >
@@ -48,6 +48,11 @@ npx -y @harusame64/desktop-touch-mcp
 > **Note:** nut-js native bindings require the Visual C++ Redistributable.
 > Download from [Microsoft](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) if not already installed.
 
+> **Note (Key Locker):** The credential helper Key Locker uses is an unsigned executable, so on
+> some machines Windows SmartScreen or antivirus may show an "unknown publisher" warning the
+> first time it runs. This is expected — the helper ships with desktop-touch-mcp and runs locally
+> on your machine; you can allow it to proceed. Code signing is planned for a future release.
+
 ---
 
 ## Installation
@@ -141,7 +146,7 @@ For a local checkout, register the built server directly:
 
 ---
 
-## Tools (29 Optimized Tools)
+## Tools (32 Optimized Tools)
 
 > 📖 **Full Reference**: [`docs/system-overview.md`](docs/system-overview.md) — Exhaustive guide on parameters, return schemas, and coordinate math.
 
@@ -155,7 +160,8 @@ For a local checkout, register the built server directly:
 | Tool | Description |
 |---|---|
 | `desktop_state` | Lightweight check of focus, active window, cursor, and Auto-Perception attention signal. |
-| `screenshot` | Multi-mode capture: `detail='text'` (UIA/OCR), `diffMode` (P-frame), `dotByDot` (1:1), and `background`. |
+| `screenshot` | Multi-mode capture: `detail='text'` (UIA/OCR), `diffMode` (P-frame), `dotByDot` (1:1), and `background`. Returns a cheap `screenshot://by-ref/{id}` link to the saved image instead of inlining pixels every time. |
+| `screenshot_query` / `screenshot_gc` | Inspect and prune the on-disk screenshot cache behind the by-ref links: `screenshot_query` lists saved captures without re-reading pixels; `screenshot_gc` reclaims space by retention policy (dry-run by default). |
 | `workspace_snapshot` | Instant session orientation: all window thumbnails + UI summaries in one call. |
 | `server_status` | Diagnostic check for native engine health and feature activation. |
 
@@ -184,6 +190,7 @@ For a local checkout, register the built server directly:
 | `workspace_launch` | Launch apps and auto-detect new HWNDs (supports localized titles). |
 | `run_macro` | Batch up to 50 operations into a single round-trip for maximum efficiency. |
 | `clipboard` / `notification_show` | System-level text exchange and user alerts. |
+| `key_locker` | Manage credentials the terminal autofills for you (SSH key passphrases, sudo / login passwords). Secrets are entered once into the locker's own secure dialog and stored encrypted on this machine (Windows DPAPI); they are never shown to the assistant. `action='launch_console'` opens an autofill-capable console (returns a `paneId` to drive `ssh`/`sudo` into via `terminal`); `save` / `list` / `forget` / `set_policy` / `status` manage bindings. Autofill only fires in a console opened by `launch_console`. Disable with `DESKTOP_TOUCH_DISABLE_KEY_LOCKER=1`. |
 
 ### 📊 Office (Excel)
 | Tool | Description |
@@ -357,6 +364,19 @@ Keep Claude CLI visible while operating other apps full-screen. Set env vars in
 
 > **Input routing gotcha:** when a pinned window is active (e.g. Claude CLI), `keyboard(action='type')` / `keyboard(action='press')` send keys to it, **not** the app you wanted to type into. Always call `focus_window(title=...)` before keyboard operations, then verify `isActive=true` via `screenshot(detail='meta')`.
 
+### Screenshot cache (by-ref storage)
+
+`screenshot` and the other visual results return a cheap `screenshot://by-ref/{id}` link to an image saved on disk instead of inlining the pixels every time, so routine look-act-confirm loops cost far fewer tokens. The cache bounds itself automatically and `screenshot_query` / `screenshot_gc` let you inspect and prune it. Tune the storage with:
+
+| Env var | Default | Notes |
+|---|---|---|
+| `DESKTOP_TOUCH_SCREENSHOTS_DIR` | *(per-user cache dir)* | Pin the cache to a specific folder. If the default folder can't be created or written (e.g. corporate policy blocking new folders under your profile), the server auto-probes this → the runtime dir → an OS temp folder and uses the first writable one instead of giving up on the cache. |
+| `DESKTOP_TOUCH_SCREENSHOT_MAX_COUNT` | `200` | Keep at most this many captures in the cache. |
+| `DESKTOP_TOUCH_SCREENSHOT_MAX_BYTES` | `256 MiB` | Cap the total cache size on disk. |
+| `DESKTOP_TOUCH_SCREENSHOT_MAX_AGE_MS` | *(off)* | Drop captures older than this many milliseconds (opt-in). |
+| `DESKTOP_TOUCH_SCREENSHOT_AUTOPRUNE` | `on` | Auto-trim the cache as new captures are saved. Set `0` to disable. |
+| `DESKTOP_TOUCH_SCREENSHOT_MIN_EVICT_AGE_MS` | `60000` | Never auto-evict a capture younger than this (ms), so a by-ref link you were just handed survives long enough to open even when another AI/process on the same PC is also capturing. `0` disables. |
+
 ### Auto Perception (always-on)
 
 Phase 4 privatizes the explicit `perception_*` tool family — the v0.12 Auto
@@ -739,15 +759,14 @@ All V1 tools continue to work without interruption — no reinstall required. Re
 
 Flag semantics (exact-match: only the literal string `"1"` counts):
 
-| `DISABLE_FUKUWARAI_V2` | `ENABLE_FUKUWARAI_V2` | V2 state |
-|---|---|---|
-| unset / not `"1"` | unset / not `"1"` | **ON** (default) |
-| unset / not `"1"` | `"1"` | ON (legacy flag — see below) |
-| `"1"` | any | **OFF** — DISABLE wins |
+| `DISABLE_FUKUWARAI_V2` | V2 state |
+|---|---|
+| unset / not `"1"` | **ON** (default) |
+| `"1"` | **OFF** (kill switch) |
 
-### Deprecated: `DESKTOP_TOUCH_ENABLE_FUKUWARAI_V2`
+### Removed: `DESKTOP_TOUCH_ENABLE_FUKUWARAI_V2`
 
-This was the opt-in switch in v0.16.x. It is still accepted for backward compatibility but no longer required — the server prints a deprecation warning on startup when it is set. Remove it from your config; V2 is on by default.
+This was the opt-in switch in v0.16.x. V2 is on by default since v0.17, so the flag no longer has any effect and is safe to delete from your config. To turn V2 off, set `DESKTOP_TOUCH_DISABLE_FUKUWARAI_V2=1`.
 
 ### Recovery when V2 fails
 
@@ -790,9 +809,9 @@ For `desktop_discover` warnings (`visual_provider_unavailable`, `visual_provider
 
 ---
 
-## 🚀 2,000+ Downloads!
+## 🚀 3,000+ Downloads!
 
-This project just passed **2,000+ downloads**. Huge thanks to everyone who
+This project just passed **3,000+ downloads**. Huge thanks to everyone who
 tried an experimental desktop-automation MCP server, filed issues, opened PRs,
 and shared what broke. Every bug report made the next release better.
 Thank you for building with me!

package/bin/launcher.js

@@ -18,15 +18,15 @@ import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
-const PACKAGE_VERSION = "1.10.4";
+const PACKAGE_VERSION = "1.12.0";
 const RELEASE_TAG = `v${PACKAGE_VERSION}`;
 const REPO_API_URL = `https://api.github.com/repos/Harusame64/desktop-touch-mcp/releases/tags/${RELEASE_TAG}`;
 const ASSET_NAME = "desktop-touch-mcp-windows.zip";
 const RELEASE_METADATA_FILE = ".desktop-touch-release.json";
 const RELEASE_MANIFEST = {
-  tagName: "v1.10.4",
+  tagName: "v1.12.0",
   assetName: ASSET_NAME,
-  sha256: "4147296c5ebe2532e1bcf5e92b13f33b651dd7cbc4d074b2540bef170a5d74c9",
+  sha256: "41751d3686d567f7e29638ccc1eca0af6ad744b2327c7d557f41f5e21da4abfc",
 };
 const CACHE_ROOT = process.env.DESKTOP_TOUCH_MCP_HOME
   ? path.resolve(process.env.DESKTOP_TOUCH_MCP_HOME)

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@harusame64/desktop-touch-mcp",
-  "version": "1.10.4",
+  "version": "1.12.0",
   "mcpName": "io.github.Harusame64/desktop-touch-mcp",
-  "description": "Let Claude, Cursor, or any MCP client see and operate your Windows 10/11 desktop. 29 tools for screenshots, UI Automation, Chrome CDP, keyboard/mouse, terminal, with semantic discover-then-act targeting and per-action perception guards that avoid wrong-window typing and stale-coordinate clicks.",
+  "description": "Let Claude, Cursor, or any MCP client see and operate your Windows 10/11 desktop. 31 tools for screenshots, UI Automation, Chrome CDP, keyboard/mouse, terminal, with semantic discover-then-act targeting and per-action perception guards that avoid wrong-window typing and stale-coordinate clicks.",
   "keywords": [
     "mcp",
     "mcp-server",
@@ -100,22 +100,23 @@
     "build:rs": "node scripts/build-rs.mjs --release",
     "build:rs:debug": "node scripts/build-rs.mjs --debug",
     "artifacts:rs": "napi artifacts",
-    "bench:envelope-size": "node benches/l4_envelope_size.mjs"
+    "bench:envelope-size": "node benches/l4_envelope_size.mjs",
+    "bench:wgc-latency": "node benches/wgc_latency.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/sdk": "^1.10.0",
     "@napi-rs/cli": "^3.7.2",
     "@nut-tree-fork/nut-js": "^4.2.6",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.1.0",
     "@types/ws": "^8.18.1",
-    "eslint": "^10.5.0",
+    "eslint": "^10.6.0",
     "fast-check": "^4.8.0",
-    "globals": "^17.5.0",
-    "sharp": "^0.35.1",
+    "globals": "^17.7.0",
+    "sharp": "^0.35.3",
     "typescript": "^6.0.2",
-    "typescript-eslint": "^8.61.0",
-    "vitest": "^4.1.8",
+    "typescript-eslint": "^8.62.1",
+    "vitest": "^4.1.10",
     "ws": "^8.21.0",
     "zod": "^4.3.6"
   }