desktop-touch-mcp

desktop-touch-mcp

日本語

Windows 向けのコンピューター操作用 MCP サーバーです。 Claude、Cursor、または任意の MCP クライアントから Windows 10/11 デスクトップを表示して操作できます。スクリーンショット、UI Automation、Chrome CDP、キーボード／マウス、ターミナルに対応し、セマンティックな「検出してから操作」するターゲティングによりピクセル座標を推測する必要がなく、アクションごとの知覚ガードにより、誤ったウィンドウへの入力を事前に検出します。

npx -y @harusame64/desktop-touch-mcp

32 個のツール、ネイティブ Rust エンジン（UIA を 2 ms で処理）、設定不要の PowerShell フォールバック、CJK の完全サポート、MIT ライセンス。上記のスニペットを Claude／Cursor／VS Code Copilot の設定に追加すると、Claude から Notepad、Excel、Chrome、Windows Terminal など、マシン上のあらゆるアプリを操作できます。

ピクセルをクリックする方式より優れている理由は？ すべてのツールに、2 つの考え方が反映されています。検出してから操作する方式では、desktop_discover が生の座標ではなく有効期限の短いリース付きで操作可能な要素を返すため、desktop_act は場所ではなく、意図した対象を操作できます。さらに、アクションごとの知覚ガードが入力前に対象ウィンドウの識別情報と境界を確認し、誤ったウィンドウへの入力や古い座標でのクリックを事前に検出します。

2.1 では、深さではなく要素数に基づいて UI Automation を読み取ります。Chrome、Edge、VS Code のページ、Explorer と Settings の値、Word の本文を読み取って操作でき、UIA でまだ見えない部分はこれまでどおり OCR と Set-of-Marks にフォールバックします。desktop_act は Word の本文にも、ユーザーに確認したうえで Windows Terminal にも入力します。2.0 では実行できないアクションに理由を添えて拒否し、実行済みと報告することはありません。また、hwnd を指定したアクションは、そのウィンドウだけを対象とします。CHANGELOG をご覧ください。

---

機能

• 🔁 あらゆる操作で実行内容を報告 — desktop_act は変更内容を回答します。新たに表示または消失した要素、モーダル、フォーカスの移動、画面の再描画（observation）に加え、narrate:"rich" を指定すると、変更された値や名前も報告します。エージェントはスクリーンショットをもう一度撮ることなく、返信からクリックの結果を確認できます。UIA が認識できない対象では、変更があった領域だけの PNG も添付できます（roiCapture は、目に見える変化があった場合にデフォルトで有効です。無効にするには returnCapture:"never"、常に有効にするには "always" を指定します）。
• 🛑 実行できない操作は、実行済みと報告せず拒否 — フィールドに届かない入力、ダイアログに遮られたウィンドウ、閉じたウィンドウ、別の仮想デスクトップ上のウィンドウには、何も送信しません。返信では理由と次に行うべきことを伝えます。hwnd を指定した操作が、同じタイトルの別のウィンドウに送られることはありません。
• 🌐 深い階層のウィンドウも読み取り（2.1） — UI Automation の読み取りは、深さ 64、要素数 500 まで対応します。2.0 では認識できなかった Chrome、Edge、VS Code のページや、読み取り対象から漏れていた Explorer と Settings の値、Word の本文も読み取り、操作できます（Chrome のページでは、6 要素を 387 ms で読み取り、45 要素を 186 ms で読み取ります）。
• 🎯 Set-of-Marks（SoM）視覚フォールバック — ゲーム、RDP セッション、アクセシビリティツリーのないアプリでも、クリック可能な要素を返します。UIA が認識できない場合、desktop_discover と screenshot(detail="text") は Hybrid Non-CDP パイプラインに切り替わります。Rust によるグレースケール化とバイリニア拡大 → Windows OCR → クラスタリング → 番号付きバッジ（[1]、[2]…）付きの赤いバウンディングボックスを行います。空間的な位置関係を把握できる PNG と、clickAt 座標を含む elements[] リストの 2 種類を返します。CDP は不要です。
• ⌨️ バックグラウンド入力が届かない場所にも入力 — Windows Terminal では、毎回ユーザーに確認してから入力します（stdio 経由でエリシテーションに対応した MCP クライアントが必要です）。Word の本文では、ウィンドウが前面でも背面でも、Word のキャレット位置に入力します。
• 🔐 Key Locker — ターミナルで SSH / sudo パスワードを自動入力 — ロッカー専用の安全なダイアログに認証情報を一度保存します（Windows DPAPI でマシン上に暗号化して保存され、アシスタントには表示されません）。その後、key_locker(action='launch_console') で開いたコンソールで ssh / sudo を実行すると、隠されたプロンプトが表示されたときにパスワードが自動入力されます。デフォルトでは、入力のたびに確認プロンプトが表示されます。Key Locker をご覧ください。
• ⚡ Rust ネイティブコア — UIA ブリッジと画像差分処理は、Rust ネイティブアドオン（napi-rs + windows-rs）で実装されています。UIA は PowerShell を起動せず、専用スレッドから COM 経由で呼び出され、画像差分には SSE2 SIMD を使用します。アドオンがない場合は、すべての関数が透過的に PowerShell にフォールバックします。npm ランチャーは、バージョンに一致する GitHub Release のみを取得し、Windows ランタイムの zip を検証してから展開します。
• LLM ネイティブ設計 — 人間のクリック方法ではなく、LLM の思考方法に合わせて設計されています。run_macro は複数の操作を 1 回の API 呼び出しにまとめ、diffMode は前のフレームから変化したウィンドウだけを送信します。トークン数も往復回数も最小限に抑えます。
• リアクティブ知覚グラフ — ウィンドウまたはブラウザータブに lensId を登録してアクションツールに渡すと、各アクションの後にガードチェック済みの post.perception フィードバックを受け取れます。screenshot / desktop_state の繰り返し呼び出しを減らし、誤ったウィンドウへの入力や古い座標でのクリックを防ぎます。
• CJK を完全サポート — ウィンドウタイトルの取得に Win32 の GetWindowTextW を使用し、nut-js による文字化けを防ぎます。日本語／中国語／韓国語の環境では IME バイパス入力に対応しています。
• 3 段階のトークン削減 — detail="image"（約 443 トークン）／detail="text"（約 100～300 トークン）／diffMode=true（約 160 トークン）。ピクセル情報は、実際に必要なときだけ送信します。
• 1:1 座標モード — dotByDot=true を指定すると、ネイティブ解像度でキャプチャします（WebP）。画像のピクセルが画面座標と一致するため、スケール計算は不要です。origin と scale を mouse_click に渡すと、サーバーが座標を変換するため、1 ピクセルのずれやスケールの不具合を解消できます。
• ブラウザーキャプチャのデータ削減 — grayscale=true（サイズを約 50% 削減）、dotByDotMaxDimension=1280（座標を維持して自動スケーリング）、windowTitle + region によるサブクロップを使うと、ブラウザーの枠や不要なピクセルを除外できます。大きなキャプチャでは、通常 50～70% 削減できます。
• Chromium スマートフォールバック — Chrome／Edge／Brave で detail="text" を指定すると、UIA は非常に遅いため自動的にスキップし、Windows OCR を実行します。hints.chromiumGuard と hints.ocrFallbackFired で、実行された経路を確認できます。
• UIA 要素の抽出 — detail="text" を指定すると、ボタン名と clickAt 座標を JSON で返します。Claude はスクリーンショットを見ることなく、正しい要素をクリックできます。
• CLI の自動ドッキング — window_dock(action='dock') は、任意のウィンドウを常に最前面に表示したまま画面の隅に配置します。DESKTOP_TOUCH_DOCK_TITLE='@parent' を設定すると、MCP の起動時に Claude をホストしているターミナルを自動的にドッキングできます。プロセスツリーをたどってウィンドウを特定するため、タイトルに左右されません。
• 緊急停止（フェイルセーフ） — マウスをプライマリモニターの左上隅（0,0 から 10px 以内）に 500ms 間置くと、緊急停止が作動します。

---

必要条件

OS	Windows 10 / 11（64-bit）。Apple Silicon 搭載の macOS 14 以降：限定プレビュー、利用できるツールは 4 つのみ — macOS（プレビュー）を参照してください
Node.js	v20 以降を推奨（v22 以降でテスト済み）— **開発またはテストスイートの実行には、`^22.12
PowerShell	5.1 以降（Windows に同梱）— Rust ネイティブエンジンを利用できない場合のフォールバックとしてのみ使用されます
Claude CLI	claude コマンドが利用できる必要があります

注： nut-js のネイティブバインディングには Visual C++ Redistributable が必要です。 まだインストールされていない場合は、Microsoft からダウンロードしてください。

注（Key Locker）： Key Locker が使用する認証情報ヘルパーは署名されていない実行ファイルのため、 一部のマシンでは、初回起動時に Windows SmartScreen またはウイルス対策ソフトによって「発行元不明」の警告が表示される場合があります。 これは想定された動作です。ヘルパーは desktop-touch-mcp に同梱され、お使いのマシン上でローカルに実行されるため、実行を許可できます。 コード署名は今後のリリースで対応する予定です。

---

インストール

npx -y @harusame64/desktop-touch-mcp

npm ランチャーは、npm パッケージのバージョンに基づいて実行時環境を厳密に決定します。パッケージが X.Y.Z の場合、GitHub Release タグ vX.Y.Z のみを取得し、お使いのプラットフォーム用の zip（desktop-touch-mcp-windows.zip、Apple Silicon Mac の場合は desktop-touch-mcp-macos-arm64.zip）をダウンロードして、SHA256 ダイジェストを検証した後にのみ、%USERPROFILE%\.desktop-touch-mcp（macOS では ~/.desktop-touch-mcp）の下に展開します。検証済みのキャッシュ済みリリースは、以降の実行時に再利用されます。

DESKTOP_TOUCH_MCP_HOME を設定すると、キャッシュのルートディレクトリを変更できます。

サーバーの起動後、実行中のリリースともう1つのリリースを残して、古いリリースが削除されます（Windows では各約 180 MB）。DESKTOP_TOUCH_MCP_KEEP_RELEASES を設定すると、より多くのリリースを保持できます（0 ではすべて保持します）。別のクライアントが実行中のリリースは保持されます。クライアントが実行していない間であれば、古い releases/vX.Y.Z フォルダーを手動で削除しても問題ありません。

共有ネットワークまたは CI ネットワークを使用していますか？ 初回実行時、ランタイムの zip を探すために GitHub Releases API が呼び出されます。匿名での制限は IP アドレスあたり 1 時間に 60 リクエストです。共有のパブリック IP アドレス（CI ランナー、オフィスの NAT）では、ダウンロードが始まる前に上限に達する可能性があります。環境変数に GITHUB_TOKEN（または GH_TOKEN）を設定すると、ランチャーが認証済みリクエストを行い、上限が 1 時間あたり 5,000 リクエストに引き上げられます。通常の家庭用ネットワークではトークンは不要です。

ソースチェックアウトからランチャーを実行していますか？ ソースビルドの bin/launcher.js には、確定済みのハッシュではなく、プレースホルダーの整合性ハッシュ（sha256: "PENDING"）が含まれています。未検証のランタイムをダウンロードして実行する代わりに、ランチャーはフェイルクローズします。このガードにより、誤って公開された、または未確定のランチャーが未検証のコードを気付かれないまま起動するのを防ぎます。公開済みの npm リリースには常に実際の SHA256 が含まれているため、エンドユーザーがこれを見ることはありません。意図的にソースからランチャーを実行する場合は、整合性検証をスキップするために DESKTOP_TOUCH_MCP_ALLOW_UNVERIFIED=1 を設定してください（開発時のみ）。

ランチャーが終了する前にホストがタイムアウトしますか？ デスクトップホストによっては、プラグインの起動完了までに固定の猶予時間（60 秒が一般的）が設けられており、到達不能な GitHub からの応答を待つランチャーが、その時間を使い切ることがあります。この場合は、2 つの環境変数で対処できます。

DESKTOP_TOUCH_MCP_FETCH_TIMEOUT_MS（デフォルトは 15000）は、GitHub から応答がない状態でランチャーが待機する時間に上限を設けます。リリースの検索とダウンロードの両方に適用されます。ダウンロード時には合計時間ではなく、応答が途切れている時間を計測するため、低速な接続でも大容量のランタイムをインストールできます。ミリ秒単位の正の数ではない値は、警告を出して無視されます。

DESKTOP_TOUCH_MCP_OFFLINE_FALLBACK=1 を設定すると、GitHub にまったく接続できない場合に、インストール済みのリリースでランチャーを起動できます。デフォルトでは無効です。GitHub には常に最初に接続するため、ネットワークに接続できる場合は再ダウンロードして破損したインストールを修復します。フォールバックが使われるのはネットワーク障害が発生した場合のみです。その場合、ディスク上にある同じバージョンのコピーを再検証せずに起動するか、そのバージョンが一度もインストールされていなければ、検証済みのインストールが完了した中で最も新しい以前のリリースを起動します。ネットワーク障害以外の応答（404、API のレート制限、整合性ハッシュの不一致）が発生した場合は、引き続き起動が明確なエラーとともに停止します。ホストのタイムアウトでやむを得ない場合を除き、無効のままにしてください。有効にしている間は、現在のバージョンのインストールが破損していても修復されず、そのまま再利用されます。

2 つの変数は連動します。フォールバックを有効にしても、起動時にはタイムアウトまで待ってからフォールバックするため、ホストの猶予時間が短い場合は DESKTOP_TOUCH_MCP_FETCH_TIMEOUT_MS を小さくしてください。また、ダウンロードが低速でも進行中であれば中断されません。フォールバックが実行されるのはネットワークの応答が途絶えた場合であり、単に低速な場合ではありません。

Claude CLI への登録

~/.claude.json の mcpServers の下に追加します。

{
  "mcpServers": {
    "desktop-touch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@harusame64/desktop-touch-mcp"]
    }
  }
}

システムプロンプトは不要です。 コマンドリファレンスは、MCP の initialize 応答にある instructions フィールドを通じて、自動的に Claude に渡されます。

他のクライアントへの登録（HTTP モード）

HTTP エンドポイントを必要とするクライアント（GPT Desktop、VS Code Copilot、Cursor など）では、組み込みの Streamable HTTP トランスポートを使用できます。

npx -y @harusame64/desktop-touch-mcp --http
# or with a custom port:
npx -y @harusame64/desktop-touch-mcp --http --port 8080

サーバーは http://127.0.0.1:23847/mcp（ローカルホストのみ）で起動します。MCP クライアントの設定に URL を登録してください。ヘルスチェックは http://127.0.0.1:<port>/health で利用できます。

HTTP モードでは、システムトレイアイコンにアクティブな URL が表示され、すばやくコピーしたりブラウザーで開いたりするショートカットを利用できます。

開発用インストール

git clone https://github.com/Harusame64/desktop-touch-mcp.git
cd desktop-touch-mcp
npm install

インストール後にビルドします。

npm run build

ローカルのチェックアウトを使用する場合は、ビルドしたサーバーを直接登録します。

{
  "mcpServers": {
    "desktop-touch": {
      "type": "stdio",
      "command": "node",
      "args": ["D:/path/to/desktop-touch-mcp/dist/index.js"]
    }
  }
}

注： D:/path/to/desktop-touch-mcp を、このリポジトリをクローンした実際のパスに置き換えてください。

macOS（プレビュー）

限定プレビュー。 macOS ビルドで利用できるツールは 4 つのみです。Windows ビルドの一部であり、リリースによって動作が変わる場合があります。

Apple Silicon 搭載の Mac（macOS 14 以降）では、同じ npx コマンドで 4 つのツールを備えた macOS サーバーを起動できます。ツールは desktop_state、desktop_discover、desktop_act（テキストの入力、置換、追記）、screenshot（1 つのウィンドウ）です。その他のツールは Windows 専用で、macOS では一覧に表示されません。

• 「システム設定」›「プライバシーとセキュリティ」で、サーバーを実行するアプリ（Terminal、iTerm、VS Code、Claude アプリなど）にアクセシビリティのアクセス権を付与してください。ウィンドウタイトルとスクリーンショットには、画面収録のアクセス権も必要です。最近の macOS では「アクセシビリティ」パネルの名前が異なる場合があります。次のコマンドで各パネルを直接開けます。

  open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
  open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
  

  その後、MCP サーバーを再起動してください。クライアントでサーバーを再起動または再接続するか、サーバーを実行しているアプリを再起動してください。すでに起動していたサーバーは、新たに付与されたアクセシビリティのアクセス権を認識しません。画面収録のアクセス権を付与してもスクリーンショットを取得できない場合は、そのアプリを終了して再度開いてください。それまでは、ツールは PermissionRequired を返し、付与すべきアクセス権を示します。
• npx のみでインストールしてください。ブラウザーでダウンロードしたリリース zip は、ネイティブモジュールが公証されていないため、Gatekeeper によって拒否されます。
• stdio のみ対応しています（--http はまだ利用できません）。Intel Mac と Linux はサポートされていません。

---

ツール（最適化された 32 個のツール）

📖 完全なリファレンス： docs/system-overview.md — パラメーター、戻り値のスキーマ、座標計算についての詳細なガイドです。

🌐 World-Graph V2（主な利用方法）

ツール	説明
desktop_discover	デスクトップを観察します。リースを持つ対話可能なエンティティ（UIA、CDP、Terminal、Visual SoM）を返します。
desktop_act	リースの検証を通じて、エンティティに対する操作（クリック、入力、値の設定、選択）を実行します。意味的な差分を返します。視覚情報のみのターゲットでは、オプションの roiCapture（変更領域の PNG と次のターゲットのプレビュー）も返します。

👁️ 観察と状態

ツール	説明
desktop_state	フォーカス、アクティブウィンドウ、カーソル、Auto-Perception の注意喚起シグナルを軽量に確認します。
screenshot	複数のキャプチャーモードに対応します。detail='text'（UIA/OCR）、diffMode（P フレーム）、dotByDot（1:1）、background を指定できます。毎回ピクセルをインラインで返す代わりに、保存画像への軽量な screenshot://by-ref/{id} リンクを返します。
screenshot_query / screenshot_gc	by-ref リンクの参照先となる、ディスク上のスクリーンショットキャッシュを調査・整理します。screenshot_query はピクセルを再読み込みせずに保存済みキャプチャーを一覧表示します。screenshot_gc は保持ポリシーに従って容量を確保します（デフォルトではドライラン）。
workspace_snapshot	1 回の呼び出しで、すべてのウィンドウのサムネイルと UI の概要を表示し、すぐにセッションの状況を把握できます。
server_status	ネイティブエンジンの状態と機能の有効化状況を診断します。

⌨️ 入力と制御

ツール	説明
keyboard	キーボード入力を送信します。バックグラウンド入力（WM_CHAR）と、IME に対応したクリップボードのバイパスをサポートします。
mouse_click / mouse_drag	ホーミングとフォーカスの強制保護を備えた、座標ベースの精密な操作を行います。
scroll	複数の方式に対応します。raw（ノッチ）、to_element、smart（仮想リスト）、capture（連結）を使用できます。
click_element	要素名または ID を指定してクリックする、従来の UIA ベースの方法です（エンティティを利用できない場合のフォールバック）。

🌐 Browser CDP（Chrome／Edge／Brave）

ツール	説明
browser_open / browser_navigate	冪等なデバッグモードでの起動と、信頼性の高いナビゲーションを行います。
browser_click / browser_fill / browser_form	再描画やフレームワークによる再レンダリング後も安定して動作する、高レベルの DOM 操作を行います。
browser_eval	js（スクリプト）、dom（HTML）、appState（SPA データの抽出）を使って詳細に調査します。
browser_overview / browser_search / browser_locate	セマンティックな探索、grep のような DOM 検索、ピクセル単位で正確な座標の検索を行います。

🛠️ ユーティリティとワークフロー

ツール	説明
terminal	コマンド実行を一元化します。run（送信＋待機＋読み取り）、read（OCR／UIA）、send を利用できます。run の完了モードは quiet、pattern、exit です（コマンドの終了を待って終了コードを返します。ターミナルコマンドの完了を参照）。
wait_until	ウィンドウ、フォーカス、テキスト、URL の状態変化をサーバー側で効率よくポーリングします。
window_dock / focus_window	ウィンドウを管理します。pin（常に最前面に表示）、unpin、dock（画面の隅にスナップ）、focus を利用できます。
workspace_launch	アプリを起動し、新しい HWND を自動検出します（ローカライズされたタイトルに対応）。
run_macro	最大 50 件の操作を 1 回のラウンドトリップにまとめ、効率を最大限に高めます。
clipboard / notification_show	システムレベルでテキストをやり取りし、ユーザーに通知します。
key_locker	ターミナルで自動入力する認証情報（SSH キーのパスフレーズ、sudo／ログインパスワード）を管理します。秘密情報はロッカー専用の安全なダイアログに一度だけ入力され、このマシン上で暗号化して保存されます（Windows DPAPI）。アシスタントに表示されることはありません。action='launch_console' は自動入力に対応したコンソールを開きます（terminal 経由で ssh／sudo を実行するための paneId を返します）。save／list／forget／set_policy／status ではバインディングを管理できます。fill_once は、自動入力で処理できないプロンプトにパスワードを一度入力するよう求めます（保存されません）。自動入力と fill_once は、launch_console で開いたコンソールでのみ機能します。DESKTOP_TOUCH_DISABLE_KEY_LOCKER=1 で無効にできます。

📊 オフィス（Excel）

ツール	説明
excel	COM 経由で Excel VBA マクロを作成して実行します。action='run_vba' は管理対象の Trusted Location にマクロを書き込み、実行します。action='check_access_vbom' は読み取り専用の事前チェックです。数式のみを使うツールでは実行できない VBA を実行します。初回セットアップ：node scripts/enable-access-vbom.mjs。

---

標準ワークフロー（v1.0.0）

v2 の World-Graph サーフェス（desktop_discover / desktop_act）が、推奨されるディスパッチ経路です。4 回の呼び出しで構成されるこの形式は、ネイティブアプリ、ブラウザー、ターミナルで同じように機能します。

desktop_state          → orient: focused window/element, modal, attention signal
desktop_discover       → find actionable entities (returns lease + windows[])
desktop_act(lease, …)  → act on entity (returns attention + post.perception)
desktop_state          → confirm the world changed as expected

クリックの優先順位：

browser_click(selector)               → Chrome / Edge (CDP, stable across repaints)
desktop_act(lease, action='click')    → native / dialog / visual (entity-based; use after desktop_discover)
click_element(name | automationId)    → native UIA fallback if desktop_act returns ok:false (not for list/tree/grid items)
mouse_click(x, y, origin?, scale?)    → pixel last resort; origin+scale from dotByDot screenshots only

拒否された場合の復旧方法と、リースの有効期限については、ガイド → 復旧方法とリースを参照してください。

---

ガイドの詳細

詳細はガイドをご覧ください。

• 復旧ヒントとリース
• ターミナルコマンドの完了（until）
• Key Locker（ターミナルの認証情報自動入力）
• ブラウザー CDP オートメーション
• 起動時に CLI を自動ドッキング
• マウスのホーム位置補正
• screenshot のキー パラメーター
• セキュリティ
• マウスの移動速度
• 強制フォーカス（AttachThreadInput）
• 自動ガード
• 診断ログ
• 高度な応答オプション
• ネイティブエンジンのパフォーマンス（v0.15 で測定）
• UI 操作レイヤー（V2）
• トークンコストの参考情報

---

既知の制限事項

制限事項	詳細	回避策
ゲーム／動画プレーヤーでは、PrintWindow キャプチャ時に画面が黒くなったり、処理が停止したりすることがあります	DirectX のフルスクリーンアプリは、PW_RENDERFULLCONTENT の下で再描画されない場合があります。ウィンドウを対象とする screenshot(detail='image') は、PrintWindow がデータを返さない場合、または真っ黒で分散がゼロのフレームを返した場合に、自動的に BitBlt にフォールバックします。ただし、呼び出しが停止する DirectX サーフェスでは、フォールバックに移行しません。	screenshot({mode:'background', fullContent:false}) を再試行して、従来の PrintWindow フラグに切り替えます。それでも黒い場合は、BitBlt のフォールバック（既定の mode='normal'）で少なくとも画面上の矩形が返されます。hints.captureFallbackReason は printwindow-all-black になります
UIA 呼び出しのオーバーヘッド	Rust ネイティブエンジン経由で約 2 ms（フォーカス）／約 100 ms（ツリー）、PowerShell フォールバック経由で約 300 ms です	Rust エンジンは自動的に読み込まれます。workspace_snapshot は内部で 2 s のタイムアウトを使用します
screenshot(detail='text') は Chrome／WinUI3 で UIA 要素をほとんど返しません	この読み取りは Chromium では浅いままです（2.1 以降、desktop_discover はページのコントロールを読み取ります）	screenshot(detail='text') は Chromium を自動検出し、Windows OCR にフォールバックします（hints.chromiumGuard=true）。ページのコントロールには desktop_discover を使用するか、DOM にアクセスするには browser_open と browser_locate を使用してください
サイトが document.title を書き換えると、Chromium のタイトル正規表現で検出できないことがあります	ガードは - Google Chrome サフィックスがあることを前提としています。一部のサイトでは、長いタイトルの末尾からこの文字列が押し出されます	タイトルは通常の Chrome のものとして扱われます（UIA が実行されます）。ocrFallback='always' を指定するか、UIA の返す要素が <5 個の場合（uiaSparse）は、引き続き OCR 経路を使用できます
browser_* CDP ツールでは、--remote-debugging-port を指定して Chrome を起動する必要があります	フラグなしで既定のプロファイルの Chrome がすでに実行されている場合、browser_open は失敗します。CDP E2E スイート（tests/e2e/browser-cdp.test.ts）も同じ状態では失敗します	まず Chrome を終了してください。その後、browser_open({launch:{}}) でデバッグモードで再起動できます。または、--remote-debugging-port=9222 --user-data-dir=C:\tmp\cdp を指定して Chrome を手動で起動してください
レイヤーバッファーの TTL	非アクティブ状態が 90s 続くとバッファーが自動的にクリアされ、次の diffMode は I フレームになります	長時間待機した後は、workspace_snapshot を呼び出してバッファーを明示的にリセットしてください
keyboard(action='type')／keyboard(action='press') はフォーカスに従います	window_dock(action='dock')(pin=true) で別のウィンドウ（例：Claude CLI）が最前面に固定されていると、キー入力がそのウィンドウに取り込まれる場合があります	まず focus_window(title=...) を呼び出し、キーを送信する前に screenshot(detail='meta') で isActive=true であることを確認してください
Chrome／Edge での keyboard(action='type') によるダッシュ記号／スマートクォートの入力	非 ASCII の句読点（ダッシュ —、エンダッシュ –、スマートクォート "" ''）はキーボードアクセラレーターとして処理され、アドレスバーにフォーカスが移る場合があります	テキストにこれらの文字が含まれる場合は、必ず use_clipboard=true を使用してください
React／Vue／Svelte の入力欄での browser_eval(action='js')	element.value = ... を設定したり、合成イベントをディスパッチしたりしても、フレームワークの内部状態は更新されません	browser_fill(selector, value) を使用してください。これはネイティブのプロトタイプセッターと InputEvent を使用するため、React／Vue／Svelte の状態も更新されます

---

謝辞

デスクトップ自動化の MCP サーバーを試し、問題を報告し、PR を作成し、問題が発生した箇所を共有してくださった皆さんに心から感謝します。すべてのバグ報告が、次のリリースの改善につながりました。一緒に開発してくださり、ありがとうございます！

---

ライセンス

MIT