precision-desktop

precision-desktop

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

一个配套 MCP 服务，可修复 Windows 桌面自动化中的 DPI 坐标缩放问题。

Windows DPI 缩放会悄无声息地破坏所有在桌面上执行点击、输入或悬停操作的 MCP 工具。precision-desktop 会检测并修正坐标不匹配的问题，让 AI Agent 的点击真正落在应在的位置。

问题

Windows 有两种坐标系统，却不会告诉你正在使用哪一种。

当 Windows DPI 缩放设置高于 100% 时（大多数现代笔记本电脑和显示器都是如此），不同的 Windows API 会以不同的系统返回坐标：

坐标系统	使用方	示例：在 4K 显示器横向 50% 处的点
物理（像素）	鼠标事件、SetCursorPos、UI Automation*	1920, 1080
逻辑（DPI 缩放后）	GetWindowRect、Cursor.Position、.NET、屏幕截图	1097, 617（缩放比例为 175% 时）

* 对于 DPI 感知进程，UI Automation 返回物理坐标；对于其他进程，则返回逻辑坐标——又一个不一致之处。

两者的比率就是 DPI 缩放系数（例如，1.25x、1.5x、1.75x、2.0x）。

问题不只是“有些 API 返回逻辑坐标”，而是**不同的 API 会返回不同坐标系统中的坐标，却不说明你拿到的是哪一种。**没有标志、没有标头、没有类型注解——只有看起来相同、含义却截然不同的数字。

AI Agent 受此影响的三种情况

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. 同一工具内的坐标来源混杂 — 即使是单个工具也可能返回两种坐标系统。例如，windows-mcp 的 State-Tool 会以物理坐标报告元素位置（适用于点击），但其屏幕截图却以逻辑分辨率捕获。如果 Agent 同时使用两者——从辅助功能树读取元素位置，并且根据屏幕截图估算位置——就会悄无声息地混用不同坐标系统。

这并非边缘情况

• 全球有约 10 亿 台活跃的 Windows 设备
• 其中约 30-50% 的 DPI 缩放高于 100%——也就是 3 亿至 5 亿台设备
• Windows 会在大多数现代笔记本电脑上自动启用高于 100% 的缩放（13-16 英寸、分辨率为 1080p 或更高的屏幕默认使用 125-150%）
• 现在有 47% 的 PC 用户使用高于 1080p 的分辨率（Steam 硬件调查）——其中 21% 使用 1440p、5% 使用 2560x1600、4.2% 使用 4K，而且这一比例还在上升
• MCP 生态系统拥有 5,800+ 个服务和 每月 9,700 万+ 次 SDK 下载——每个 Windows 桌面自动化服务都会遇到这个问题

如果你曾看着 AI Agent 信心十足地点击，却恰好点错位置，DPI 缩放很可能就是原因。

解决方案

precision-desktop 是一个配套 MCP 服务，可与桌面自动化 MCP（如 windows-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 Agent 会在首次使用时自行校准。流程如下：

1. Agent 调用 health_check — 发现校准缺失
2. Agent 收集参考点 — 使用坐标读取工具（如 MPos）或 Move-Tool + Cursor.Position，在屏幕上 2 个或更多已知位置获取物理坐标和逻辑坐标
3. Agent 调用 calibrate 并传入参考点 — 计算缩放系数
4. Agent 验证 — 将光标移至已知元素，确认位置正确，然后调用 calibrate_verify

校准结果会保存在 state/calibration.json 中。只有 DPI 设置或显示配置发生变化时才需要重新校准。

校准指南

所需内容

同一点的两组坐标读数：

• 物理坐标 — 来自 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 倍），并将其保存，以供后续坐标转换使用。

验证

校准后，Agent 应：

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）配合使用。

补丁概念

precision-desktop 不会分叉 windows-mcp，而是描述补丁意图——需要在配套 MCP 中做哪些更改，以及原因。AI Agent 会读取这些意图，并自行应用适用于相应版本的补丁。

当前补丁意图：

• 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 Agent）提供 2 个或更多同时包含物理坐标和逻辑坐标的点
2. calibration.py 分别计算 X 轴和 Y 轴的中位缩放系数
3. 检查一致性——如果各点的差异超过 2%，则标记为不一致
4. 计算偏移量（标准 DPI 缩放通常为 0，多显示器设置下则可能不为 0）
5. 保存到 state/calibration.json
6. 后续的 convert_coordinates 调用会使用已保存的系数

UI 自动化查找原理

1. find_element.py 运行 PowerShell 脚本，加载 UIAutomationClient 和 UIAutomationTypes 程序集
2. 在 UI 自动化树中搜索与请求名称匹配的元素
3. 返回 UI 自动化所报告坐标系中的边界矩形（对于支持 DPI 的进程，该坐标系为物理坐标系）
4. 结果包含中心坐标，可直接用于 Click-Tool/Move-Tool

要求

• Windows 10/11（使用 Windows UI 自动化）
• Python 3.10+
• PowerShell（随 Windows 提供）
• mcp >= 1.0.0（MCP SDK）
• MPos 或类似的坐标读取工具（用于校准）——任何能同时显示光标屏幕物理坐标和逻辑坐标的工具均可。MPos 轻巧便携（无需安装）

许可证

MIT