Deskhand-mcp

Windows 桌面操控 MCP server——DeskHand 引擎的独立发行版，采用 host-as-VL 架构： 本 server 只做确定性的事（UIA 控件树 / 元素记忆 / OCR / 像素 diff / 精确读写）， 一切视觉判断交回主模型——标注图通过 MCP ImageContent 直接进主模型上下文， 不需要额外的视觉模型。

从 DeskHand（AstrBot 插件版）到 Deskhand-mcp 的核心变化：

安装

pip install deskhand-mcp[all]   # 或 pip install -e .[all]
deskhand-mcp                     # stdio server，直接配进 MCP host

依赖说明：mcp/pywin32/Pillow/uiautomation 为必需；winsdk（WinRT OCR）、 rapidocr-onnxruntime（OCR 兜底）、opencv-python-headless（CV 候选框）、 windows-capture（WGC 后台抓图）可选，缺哪个对应通道就静默降级。

Related MCP server: opencode-gui-bridge

工具一览（14 个）

看界面（图随结果返回，主模型自己看图）

• look(window="") — 编号元素卡片（UIA 控件 + OCR 文字 + CV 候选框三通道）

  • 元素标注图（框和编号与卡片一一对应）

• scene_grid(window="") — 图形/自绘界面的 3×3 编号网格图 + 格→屏幕坐标映射

• verify_point(x, y) — 画十字准星返回 320px 局部放大图，主模型看图确认落点

操作

• click(element="eN" | target="文字" | x, y) — UIA 控件后台点击不抢焦点； element 路径带现场签名校验 + OCR 自愈；动作后像素 diff 验证

• type_text(text, element=) — UIA 输入控件走后台安全追加（回读验证）， 否则点击聚焦 + 键鼠输入

• press_key / scroll / drag / wait_change / window_action — 按键 / 滚动 / 拖拽 / 等画面变化 / 窗口管理（min/max/restore/close/focus/move/resize…）

精确读写（ValuePattern / TextPattern，逐字精确）

• read_value(element=) — 读输入框当前值（ValuePattern）

• read_document(element=) — 读文档全文（TextPattern → ValuePattern → OCR 降级， OCR 结果如实标 exact:false）

• append_text(text, element=) — 安全追加：读旧值 → 身份校验 → 追加 → SetValue → 回读逐字验证

• set_value(text, confirm_overwrite=true) — 整篇覆盖（危险，默认拒绝）

在 MCP host 中配置

{
  "mcpServers": {
    "deskhand": {
      "command": "deskhand-mcp"
    }
  }
}

未安装为包时可直接用源码运行：

{
  "mcpServers": {
    "deskhand": {
      "command": "python",
      "args": ["-m", "deskhand_mcp.server"],
      "cwd": "C:\\path\\to\\deskhand-mcp"
    }
  }
}

记忆库（元素位置 + 图像签名）存于 %LOCALAPPDATA%\deskhand-mcp\deskhand_memory.db， 设环境变量 DESKHAND_DATA_DIR 可改目录。

架构：为什么砍掉 VL

实测对比（见 DeskHand 深度评测）：VL 漏斗最贵的一环（每点一次都要调视觉模型） 恰恰是最不可靠的一环——黑盒坐标、不可解释、延迟高。而现代主模型基本都已多模态， 看图能力远超专用小 VL。host-as-VL 的思路：把「看」还给主模型，把「做」做扎实——

• 能确定性的绝不给模型猜：UIA 控件树、OCR 文字、像素 diff、ValuePattern 回读；

• 必须视觉判断的地方，把图直接塞进主模型上下文（标注图/网格图/准星放大图）， 由主模型下结论或给修正量——agent-in-the-loop，每一步都可解释；

• 精确读写绕过像素层：TextPattern 的 DocumentRange.GetText(-1) 读全文逐字精确， 彻底告别「看图识字」的保真度问题。

安全边界

• UAC 提权窗口、以管理员运行的窗口：UIA/win32 无法穿透，工具会如实报错；

• 最小化窗口 UIA 树为空：先 window_action(action="restore")；

• set_value 覆盖写入默认拒绝，必须显式 confirm_overwrite=true；

• 目标身份不符（弹窗遮挡/界面移动）时报 stale 中止，绝不盲点旧坐标。

协议

AGPL-3.0-only，与 DeskHand 一致。