Tiance GUI MCP · 天策 GUI MCP

递归网格定位，让 AI 从整屏逐层看清目标，再用格内比例坐标操作 Windows。

English · 操作指南 · 架构与边界 · 反馈问题

核心特点

传统截图操作经常要求模型估算目标的绝对像素坐标。这套工具把定位过程变成可逐层确认的步骤：

1. 获取窗口或屏幕截图，叠加编号网格。

2. 选择一个格子，或组成完整矩形的多个格子，放大该区域。

3. 放大视图重新划分网格，可以继续选格、继续放大。

4. 使用当前视图的格号与格内 x/y 比例定位；程序负责映射回真实屏幕像素。

例如：整屏 → 第 4 格 → 放大视图第 2 格 → x=0.5037, y=0.62。无需手算每层裁剪偏移、缩放倍率或绝对坐标。

坐标规则很重要： 格号从左上角开始按行排列；格内比例原点在左下角，x 向右增加、y 向上增加，范围均为 0～1。支持任意小数，最终才取整到物理屏幕像素。放大只帮助观察，不生成新的图像细节，也不会突破原始像素精度。

此外支持：

• Windows UIAutomation 控件读取、分页、身份/焦点校验与可写控件赋值。

• 鼠标点击、拖动、移动、滚动；键盘文字、按键和组合键。

• 可选落点预览；直接点击不要求先预览。

• gui_batch 顺序执行连续动作，失败即停止并报告已经完成的步骤。

• 输入锁、柔和边框提示、Esc 退出、空闲释放、进程退出释放。

• 标准 MCP 图片结果，不依赖天策客户端读取本地图片。

这是从 天策 GUI 工具提取的独立项目。不需要天策、模型密钥、供应商配置或会话数据库。 当前是首个独立版本，支持 Windows 本地 stdio；不提供远程桌面服务。

Related MCP server: Windows-MCP

环境

• Windows 10/11，交互式用户桌面；推荐 64 位 Python 3.11 或更新版本。

• Windows PowerShell 5.1（用于系统 UIAutomation 桥）。

• 支持本地 stdio MCP 和图片结果的客户端。

• 默认只为 GUI 辅助进程请求管理员权限，AI 客户端本身不必提权。UAC 弹窗需要人确认。

Windows 服务的 Session 0、锁屏、UAC 安全桌面和断开后的远程桌面不属于支持的操作环境。即使管理员身份，也不能控制所有受保护界面。Electron、游戏和自绘控件不保证提供完整控件树，可使用截图网格路径。

安装

在准备保存项目的位置打开 PowerShell：

git clone https://github.com/LikeMirage/Tiance-GUI-MCP.git
cd Tiance-GUI-MCP
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .

也可使用已安装的 Python 3.11/3.12/更新版本创建虚拟环境。此仓库尚未发布到 PyPI；请从源码安装，不要假设同名 PyPI 包属于本项目。

接入 MCP 客户端

在客户端的 MCP 配置中添加以下内容，把示例路径换成实际项目位置：

{
  "mcpServers": {
    "tiance-gui": {
      "command": "C:\\path\\to\\Tiance-GUI-MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "tiance_gui_mcp"]
    }
  }
}

不同客户端配置文件位置不同；支持表单配置时，分别填写上述 command 和 args。服务只向标准输出写 MCP 协议，诊断走标准错误。

首次使用 gui_runtime start 时，如果服务不是管理员，默认通过 Windows UAC 启动管理员 GUI 辅助进程；取消授权则返回失败，不静默降级。空闲释放后再次 start 可能再次请求授权。

可选启动参数：

例如把数据保存在便携目录：

"args": ["-m", "tiance_gui_mcp", "--data-dir", "D:\\Tiance-GUI-MCP\\data"]

五个工具

基本顺序：gui_runtime start → 等待成功 → gui_inspect start → 观察/操作 → gui_runtime stop。 list_windows 也要求先锁定。跨工具的并行调用不代表先后依赖；需要连续操作时使用批量工具。

数据与生命周期

Tiance-GUI-MCP/
├─ screenshots/
│  └─ gui_<id>/
│     ├─ session.json
│     ├─ frame_000/
│     └─ previews/
└─ runtime/
   └─ mcp_<id>.json

截图默认保留，包含模型看到的屏幕、网格、预览和坐标记录。没有隐藏的保留天数、自动数量截断或自动上传；可在运行器停止后手动清理，或明确选用 session 策略。被连接的 AI 客户端如何把图片发送给模型，由客户端控制。

运行状态不是正式会话数据库；里面含本机辅助进程连接凭据，正常停止时删除，不能提交到仓库或发到 Issue。源码目录的 data/ 已加入 Git 忽略。

同一个交互式 Windows 会话内，各实例共用系统互斥锁，即使配置不同数据目录也不能同时控制桌面。连接之间不共享截图操作引用。MCP 连接不等于某一条 AI 对话；如果宿主把一个连接共享给多个聊天，本服务无法识别宿主未提供的聊天身份，应由宿主隔离连接。

默认空闲 120 秒释放，可在 gui_runtime start 中设置 idle_timeout_seconds。正在执行的动作不算空闲，status 不续期。Esc、显式 stop、活动调用被取消、stdio 关闭或 MCP 进程退出都会进入释放流程；强制结束进程仍由辅助进程的父进程监测和空闲超时处理。聊天回复结束本身不是标准 MCP 退出事件，模型必须显式 stop。

开发与验证

.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m build

常规测试不操作用户应用。真实桌面测试单独启用，只创建并操作测试自身窗口，但会短暂锁定输入：

$env:TIANCE_GUI_MCP_DESKTOP_TEST = "1"
.\.venv\Scripts\python.exe -m pytest tests/test_desktop.py

取消测试、UAC、任务栏、不同 DPI 与多显示器的实测情况见 验证记录。不要把模拟测试通过当作对所有 Windows 应用的兼容承诺。

贡献与许可

欢迎带复现步骤反馈网格、坐标、控件识别和生命周期问题。请先阅读 贡献指南 与 安全边界，不要上传含私人内容的截图或运行状态文件。

Apache-2.0，来源与修改说明见 NOTICE。