precision-desktop

precision-desktop

mcp-name: io.github.ikoskela/precision-desktop

Windows デスクトップ自動化における DPI 座標スケーリングを修正する、コンパニオン MCP サーバーです。

Windows の DPI スケーリングは、デスクトップ上でクリック、入力、ホバーを行うすべての MCP ツールを気付かないうちに動作不良にします。precision-desktop は座標の不一致を検出して修正し、AI エージェントのクリックが意図した位置に届くようにします。

問題

Windows には2つの座標系があり、どちらを使っているかは通知されません。

Windows の DPI スケーリングが 100% を超えている場合（最近のノート PC やモニターの多くが該当します）、Windows の API によって異なる座標系の座標が返されます。

座標系	使用するもの	4K ディスプレイの横幅 50% の位置の例
物理（ピクセル）	マウスイベント、SetCursorPos、UI Automation*	1920, 1080
論理（DPI スケーリング）	GetWindowRect、Cursor.Position、.NET、スクリーンショット	1097, 617（175% スケーリング時）

* UI Automation は DPI 対応プロセスでは物理座標を、その他のプロセスでは論理座標を返します。さらに一貫性を欠く要因です。

この2つの比率が DPI スケール係数です（例：1.25x、1.5x、1.75x、2.0x）。

問題は、単に「一部の API が論理座標を返す」ことではありません。API ごとに、どちらの座標系が返されるのかを示す情報がないまま、異なる座標系が返されることです。フラグも、ヘッダーも、型注釈もなく、見た目は同じでも意味がまったく異なる数値だけが返されます。

AI エージェントに起こる3つの問題

1. API の不一致 — クリックツールは物理座標を受け取りますが、一般的な Windows API は論理座標を返します。

What the AI wants to click: [Button at physical (1920, 1080)]
What GetWindowRect says:    [Button at logical  (1097, 617)]
Where the click lands:                          (1097, 617) in physical space
                                                 ^^^^^^^^^ WRONG - completely different spot

2. スクリーンショットの不一致 — 画面キャプチャは論理解像度で撮影されますが、クリックツールは物理座標を要求します。175% スケーリングの 3840x2400 ディスプレイでは、スクリーンショットは 2194x1371 ピクセルです。ビジョンモデル（GPT-4o、Claude、CogAgent）がスクリーンショットを見て「ボタンはピクセル座標 (500, 300) にある」と推定した場合、それは論理座標です。物理座標でその位置をクリックすると、数百ピクセルずれてしまいます。

Vision model sees:    [Button at (500, 300) in screenshot]
Screenshot space:     Logical (2194x1371)
Click-Tool expects:   Physical (3840x2400)
Correct click:        (875, 525)  ← needs 1.75x conversion

3. 同じツール内での座標系の混在 — 1つのツールでも、両方の座標系が返されることがあります。たとえば、windows-mcp の State-Tool は要素の座標を物理座標で返すため、クリックに適していますが、スクリーンショットは論理解像度で撮影されます。アクセシビリティツリーから要素の位置を読み取り、さらにスクリーンショットから位置を推定するなど、両方を組み合わせるエージェントは、気付かないうちに座標系を混在させてしまいます。

これは特殊なケースではありません

• 世界中で稼働中の Windows デバイスは 約10億台
• 約30〜50% が 100% を超える DPI スケーリングを使用しており、3億〜5億台に相当します
• 最近のノート PC のほとんどでは、Windows が 100% を超えるスケーリングを自動的に有効にします（1080p 以上の 13〜16 インチ画面では、既定で 125〜150% に設定されます）
• 現在、PC ユーザーの 47% が 1080p を超える解像度を使用しています（Steam Hardware Survey）。1440p が 21%、2560x1600 が 5%、4K が 4.2% で、さらに増加しています
• MCP エコシステムには 5,800 以上のサーバーと月間 9,700 万回以上の SDK ダウンロードがあり、Windows デスクトップ自動化サーバーはすべてこの問題に直面します

AI エージェントが自信満々に、まさに間違った場所をクリックするのを見たことがあるなら、その原因は DPI スケーリングである可能性が高いでしょう。

解決策

precision-desktop は、デスクトップ自動化 MCP（windows-mcp など）と並行して動作するコンパニオン MCP サーバーで、次の機能を提供します。

1. キャリブレーション — 画面上の既知の目印を使って、このマシン固有の実際の DPI スケール係数を測定します
2. 座標変換 — 必要に応じて物理座標系と論理座標系を相互に変換します
3. UI 要素の検索 — Windows UI Automation を使って名前から要素を特定し、クリックにすぐ使える物理座標を返します
4. ヘルスチェック — キャリブレーションの有効期限切れを検出し、UI Automation の利用可否を確認し、コンパニオン MCP の状態をチェックします
5. パッチ状況の把握 — コンパニオン MCP に適用された DPI 対応パッチを追跡します

ツール

ツール	説明
calibrate	物理座標と論理座標が既知の2つ以上の基準点から、DPIスケール係数を計算します
calibrate_verify	テストクリックが正しい位置に着地したことを確認した後、キャリブレーションを検証済みとしてマークします
get_calibration	現在のキャリブレーション状態（スケール係数、検証状態、経過時間）を読み取ります
convert_coordinates	物理座標系と論理座標系の間で座標ペアを変換します
find_ui_element	Windows UI Automation を使用して、名前から単一の UI 要素を検索します。物理座標を返します
find_all_ui_elements	名前に一致するすべての UI 要素を検索します。物理座標を含むリストを返します
list_ui_elements	ウィンドウ内の名前付きインタラクティブ要素（ボタン、テキストフィールドなど）をすべて一覧表示します
find_window	タイトルの一部からウィンドウハンドル（hwnd）を検索します
health_check	環境チェックを実行します：キャリブレーションの鮮度、UI Automation、コンパニオン MCP の状態
patch_status	コンパニオン MCP に適用されている DPI 対応パッチを確認します

クイックスタート

1. インストール

このリポジトリをクローンし、依存関係をインストールします：

git clone https://github.com/ikoskela/precision-desktop.git
cd precision-desktop
pip install -e .

2. MCP を設定

Claude Code の MCP 設定（.mcp.json または設定）に追加します：

{
  "mcpServers": {
    "precision-desktop": {
      "command": "python",
      "args": ["C:/path/to/precision-desktop/server.py"]
    }
  }
}

または、Claude Desktop を使用している場合は、claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "precision-desktop": {
      "command": "python",
      "args": ["C:\\path\\to\\precision-desktop\\server.py"]
    }
  }
}

3. キャリブレーション

AI エージェントは初回使用時に自動でキャリブレーションを行います。手順は次のとおりです：

1. エージェントが health_check を呼び出す — キャリブレーションが設定されていないことを検出します
2. エージェントが基準点を収集する — 座標読み取りツール（MPos など）または Move-Tool + Cursor.Position を使用して、画面上の既知のランドマーク2か所以上で物理座標と論理座標の両方を取得します
3. エージェントが基準点を指定して calibrate を呼び出す — スケール係数を計算します
4. エージェントが検証する — カーソルを既知の要素に移動し、正しい位置に着地したことを確認してから、calibrate_verify を呼び出します

キャリブレーションは state/calibration.json に保存されます。DPI 設定またはディスプレイ構成が変わらない限り、再実行する必要はありません。

キャリブレーションガイド

必要なもの

同じ点に対する2種類の座標読み取り：

• 物理座標 — Move-Tool、Click-Tool、または State-Tool から取得します（これらのツールは物理空間で動作します）
• 論理座標 — PowerShell の [System.Windows.Forms.Cursor]::Position、または GetWindowRect API 呼び出しから取得します

キャリブレーションに適したランドマーク

• スタートボタン（タスクバーの左下） — 正確に見つけやすい
• 日付と時刻（タスクバーの右下） — 反対側の角の基準になります
• 最大化されたウィンドウの最小化ボタン — 位置が明確なクリック対象です

キャリブレーション呼び出しの例

{
  "points": [
    {
      "physical_x": 38,
      "physical_y": 2365,
      "logical_x": 21,
      "logical_y": 1351,
      "label": "start_button"
    },
    {
      "physical_x": 3691,
      "physical_y": 2332,
      "logical_x": 2109,
      "logical_y": 1332,
      "label": "datetime"
    }
  ]
}

これによりスケール係数（この例では約1.75倍）が計算され、今後の座標変換に使えるよう保存されます。

検証

キャリブレーション後、エージェントは次の操作を行います：

1. convert_coordinates を使用して、既知の論理座標を物理座標に変換します
2. Move-Tool を使用して、カーソルをその位置に移動します
3. カーソルが想定した対象上にあることを確認します
4. success: true を指定して calibrate_verify を呼び出します

UI 要素の検索

座標変換に加え、precision-desktop では Windows UI Automation を使用して、座標を指定せずに名前から要素を直接検索できます。

Agent: find_ui_element(element_name="Save", window_title="Notepad")
→ { "name": "Save", "center_x": 450, "center_y": 32, "control_type": "button", ... }
   (coordinates are physical, ready for Click-Tool)

次の対象で動作します：

• Windows ネイティブアプリケーションのコントロール（ボタン、テキストフィールド、メニュー）
• Chrome 拡張機能のポップアップとダイアログ
• State-Tool では認識できないオーバーレイウィンドウ
• Windows UI Automation を介して公開されているあらゆる UI 要素

検索範囲の指定

別のアプリケーション内にある要素を誤って検索しないよう、特定のウィンドウに検索範囲を限定できます：

find_ui_element(element_name="Submit", window_title="My App")
find_ui_element(element_name="Close", window_handle=12345)

要素の確認

要素名がわからない場合は、list_ui_elements を使用して利用可能な要素を確認します：

list_ui_elements(window_title="Settings")
→ [{ "name": "General", "control_type": "tab item", ... },
   { "name": "Apply", "control_type": "button", ... }, ...]

windows-mcp との連携

precision-desktop は、windows-mcp（またはデスクトップのクリック、入力、スクロールツールを提供する任意の MCP）と併用できるよう設計されています。

パッチ適用のコンセプト

windows-mcp をフォークするのではなく、precision-desktop はパッチの意図、つまりコンパニオン MCP に何を変更すべきか、その理由を記述します。AI エージェントはこれらの意図を読み取り、バージョンに応じたパッチを自ら適用します。

現在のパッチの意図：

• dpi_awareness — Click-Tool と Move-Tool に任意の coordinate_system パラメーターを追加し、論理座標を物理座標に自動変換します
• find_and_click — Click-Tool に任意の element_name パラメーターを追加し、名前で要素を検索してクリックします（座標は不要です）

patch_status を使用して、適用済みのパッチを確認してください。

環境変数

windows-mcp が標準以外の場所にインストールされている場合は、WINDOWS_MCP_PATH 環境変数を設定してください。

WINDOWS_MCP_PATH=C:\path\to\windows-mcp

デフォルトでは、標準の Claude Extensions ディレクトリ（%APPDATA%\Claude\Claude Extensions\ant.dir.cursortouch.windows-mcp）を検索します。

アーキテクチャ

precision-desktop/
├── server.py              # MCP server entry point — tool definitions and routing
├── calibration.py         # DPI calibration: compute, persist, convert coordinates
├── find_element.py        # Windows UI Automation: find elements, list elements, find windows
├── health_check.py        # Environment checks: calibration, UI Automation, companion MCP
├── patches/
│   └── windows_mcp.py     # LLM-adaptive patch intents for windows-mcp
├── state/
│   └── calibration.json   # Persisted calibration data (user-specific, gitignored)
└── pyproject.toml

キャリブレーションの仕組み

1. ユーザー（または AI エージェント）が、物理座標と論理座標の両方を含む 2 点以上を指定します
2. calibration.py が、X 軸と Y 軸それぞれの倍率の中央値を計算します
3. 一貫性を確認します。点同士の差が 2% を超える場合は、一貫性がないと判定します
4. オフセットを計算します（通常、標準的な DPI スケーリングでは 0、マルチモニター環境では 0 以外になります）
5. state/calibration.json に保存します
6. 以降の convert_coordinates 呼び出しでは、保存された係数を使用します

UI Automation による要素検索の仕組み

1. find_element.py が、UIAutomationClient と UIAutomationTypes アセンブリを読み込む PowerShell スクリプトを実行します
2. UI Automation ツリーを検索し、指定された名前に一致する要素を探します
3. UI Automation が報告する座標系で境界矩形を返します（DPI 対応プロセスの場合は物理座標です）
4. 結果には、Click-Tool／Move-Tool で直接使用できる中心座標が含まれます

要件

• Windows 10/11（Windows UI Automation を使用）
• Python 3.10+
• PowerShell（Windows に付属）
• mcp >= 1.0.0（MCP SDK）
• MPos または同等の座標リーダー（キャリブレーション用）— 物理座標と論理座標の両方でカーソルの画面上の位置を表示できるツールを使用してください。MPos は軽量でポータブルです（インストール不要）。

ライセンス

MIT