UiaMcp：Windows UI 自动化 MCP 服务器

基于 Windows UI Automation (UIA) 技术，通过 MCP (Model Context Protocol) 协议向客户端暴露桌面 UI 查询接口。

📥 获取方式：私信作者获取程序

---

一、使用演示

以下演示如何通过 AI Agent 调用 UiaMcp 工具完成实际任务。

1.1 场景：获取客服助手中的客户信息

目标：在千牛工作台"接待中心"窗口中，找到客服助手面板里的客户昵称元素，并导出为 XML 格式。

1.2 操作步骤

第一步：搜索目标窗口

在 AI 对话中发送指令，调用 uia_find_element 工具搜索包含"接待中心"的窗口：

调用 uia_find_element，name 包含"接待中心"，control_type 为 Window

第二步：获取元素树

找到窗口后，调用 uia_get_element_tree 导出该窗口下的完整控件树结构，设置合适的深度参数。

第三步：定位目标元素

在返回的元素树中查找目标元素（如"硝烟的过客"），确认其层级路径。

第四步：构建 XML

根据元素树的层级关系，按照参考格式构建 XML 结构，包含每个元素的 uia-name 和 type 属性。

1.3 输出示例

最终生成的 XML 片段：

<Locator>
<window uia-name="淘捷宠物:淘淘-接待中心 [ChatView]" type="Window">
<pane uia-name="千牛工作台" type="Pane">
<document uia-name="智能客服" type="Document">
<group uia-name="买家昵称 硝烟的过客" type="Group">
<text uia-name="硝烟的过客" type="Text">

---

二、项目简介

UiaMcp 是一个用 C++17 + Qt 6.5.3 编写的 Windows GUI 应用程序，核心功能是将 Windows 桌面上的 UI 元素（窗口、按钮、输入框、菜单等）通过 MCP 协议暴露给客户端调用。

支持的功能：

• 获取桌面顶层窗口列表
• 多条件搜索定位 UI 元素
• 获取指定元素的完整属性信息
• 查询屏幕坐标点下的元素链路
• 导出元素树形结构

---

三、五大核心工具

工具	能力
uia_get_desktop	获取桌面所有顶层窗口
uia_find_element	多条件搜索 UI 元素
uia_get_element_info	获取元素完整属性
uia_list_elements_at_point	查询坐标点元素链路
uia_get_element_tree	导出元素树形结构

3.1 多条件搜索与降级匹配

uia_find_element 支持窗口标题、类名、进程名、AutomationId、Name、ClassName、ControlType 共 7 个维度的组合搜索。如果全条件匹配失败，会自动放宽条件重试（去掉 AutomationId → 仅剩 Name+Class+Type），并以 200ms 间隔轮询直到超时（默认 3 秒）。

3.2 坐标点元素链路查询

uia_list_elements_at_point 给定一个屏幕坐标，会从桌面根元素一路追溯到最底层的叶元素，形成完整的元素链路。

[1] Desktop (Pane)
[2] 记事本 - 无标题 (Window) | notepad.exe
[3] 编辑区 (Edit)
[4] 文本内容 (Text)

3.3 元素树导出

uia_get_element_tree 支持深度控制、属性定制、离屏过滤、分页输出，可用于分析应用内部结构或生成自动化脚本。

---

四、可视化界面

4.1 工具状态监控

主界面以表格形式展示所有已注册的 MCP 工具，实时显示运行状态、成功调用次数和调用错误次数。绿色数字代表成功，红色数字代表错误。

4.2 连接配置窗口

点击菜单栏"显示" → “MCP 连接信息”，即可弹出完整的 Streamable HTTP 连接配置窗口，包含 JSON 配置模板、请求头说明、请求方法详解和 SSE 事件类型说明。

4.3 系统托盘与窗口置顶

• 窗口置顶：菜单栏一键切换
• 最小化到托盘：关闭窗口不退出，托盘图标常驻后台
• 双击恢复：双击托盘图标唤回主界面

---

五、快速启动教程

5.1 解压文件

解压后文件结构如下：

5.2 以管理员身份运行

右击 UiaMcp.exe → 选择"以管理员身份运行"

⚠️ 注意：Windows UI Automation (UIA) 需要访问桌面上的所有窗口元素，普通权限无法获取部分系统窗口和其他应用的信息。

5.3 运行异常处理

如果启动时提示缺少运行库，双击目录中的 vc_redist.x64.exe 安装 VC++ 2019 运行库即可。

---

六、MCP 客户端配置教程

UiaMcp 启动后，默认在 http://127.0.0.1:3100/mcp 提供 Streamable HTTP 服务。

6.1 获取配置 JSON

在 UiaMcp 主界面，点击菜单栏"显示" → “MCP 连接信息”，复制其中的 JSON 配置：

{
  "mcpServers": {
    "uia-mcp-server": {
      "url": "http://127.0.0.1:3100/mcp"
    }
  }
}

6.2 在客户端中添加配置

打开你的 MCP 客户端（如 Trae、Cursor、Claude Desktop 等），进入 MCP Servers 管理页面，选择手动配置，将上面的 JSON 粘贴到输入框中：

点击"确认"保存后，客户端会自动连接到 UiaMcp。

6.3 验证连接成功

配置完成后，在 MCP Servers 列表中可以看到 uia-mcp-server 已启用，并展开显示全部 5 个工具：

• uia_find_element
• uia_get_desktop
• uia_get_element_info
• uia_get_element_tree
• uia_list_elements_at_point

绿灯亮起，说明连接成功。

---

七、工程实现细节

7.1 MSAA 循环检测

Chrome/CEF 应用的 UIA 树存在循环引用，简单的递归遍历会死循环。UiaMcp 通过 RuntimeId 哈希集合检测已访问节点，避免死循环。

7.2 超时熔断机制

所有 UIA 操作都有超时保护，树构建支持全局截止时间戳熔断，防止操作无限挂起。

7.3 双层缓存策略

• LRU 元素缓存：最多缓存 200 个元素，O(1) 查找
• TTL 进程名缓存：120 秒有效期，减少重复 COM 调用

7.4 异步取消支持

通过原子标志支持安全取消正在进行的 UIA 操作，无需强制终止线程。

7.5 独立工作线程

UIA 的 COM 初始化运行在独立线程中，GUI 界面始终保持流畅，不会因为后台查询而卡顿。

---

八、应用场景

1. RPA 流程自动化：替代人工重复性桌面操作
2. 自动化测试：获取控件信息，生成测试脚本
3. 桌面辅助开发：分析应用 UI 结构
4. 桌面监控：实时追踪窗口和控件状态变化

---

九、项目信息

协议：MCP 2025-11-25
运行要求：Windows 10+，管理员权限