Skip to main content
Glama
Windows UI Control

Windows UI Control

by Lycheen97
README.md
# Windows UI Control

一个运行在 Windows 交互桌面上的本地 MCP 服务。它对指定的桌面应用提供窗口发现、UI Automation 控件检查、截图、有限的鼠标/键盘输入,以及窗口最小化、恢复和激活;ComeIn 路演窗口另有 HTTPS 地址和窗口登记校验。

## 环境要求

- Windows 10/11
- Python 3.11 或更高版本
- 可选应用:微信、钉钉、Wind、Google Chrome
- 使用截图、控件检查或输入工具时,需要有可见的交互式桌面会话;服务本身不提供无桌面运行能力。

## 安装

```powershell
git clone https://github.com/Lycheen97/windows-ui-control.git windows-ui-control
cd windows-ui-control
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

仓库内的 `.mcp.json` 使用通用 `python` 命令和 `./scripts/server.py`,其 `cwd` 为仓库根目录。接入客户端时,推荐把命令替换成虚拟环境中的 Python 绝对路径:

```json
{
  "mcpServers": {
    "windows-ui-control": {
      "command": "C:\\path\\to\\windows-ui-control\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\windows-ui-control\\scripts\\server.py"],
      "cwd": "C:\\path\\to\\windows-ui-control",
      "env": {
        "PYTHONUTF8": "1",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

如果使用 Codex,可按 `codex mcp add [OPTIONS] <NAME> (--url <URL> | -- <COMMAND>...)` 的命令形式注册;`--env KEY=VALUE` 可放在 `--` 之前:

```powershell
codex mcp add windows-ui-control --env PYTHONUTF8=1 --env PYTHONUNBUFFERED=1 -- "C:\path\to\windows-ui-control\.venv\Scripts\python.exe" "C:\path\to\windows-ui-control\scripts\server.py"
```

普通入口是 `scripts/server.py`。若客户端需要不显示控制台窗口,可将命令换成虚拟环境中的 `pythonw.exe`,并把参数改为 `scripts/server_windowless.pyw` 的绝对路径;该入口仍需要继承 MCP 的标准输入、输出和错误管道,也仍需要交互式桌面。

## 可选路径配置

启动进程前可用环境变量覆盖默认可执行文件路径和 Chrome profile。路径变量应指向对应应用的可执行文件;应用识别仍按白名单中的可执行文件名匹配。

| 环境变量 | 默认值 |
| --- | --- |
| `WINDOWS_UI_CONTROL_WEIXIN_PATH` | `C:\Program Files\Tencent\Weixin\Weixin.exe` |
| `WINDOWS_UI_CONTROL_DINGTALK_PATH` | `C:\Program Files (x86)\DingDing\main\current_new\DingTalk.exe` |
| `WINDOWS_UI_CONTROL_WIND_PATH` | `C:\Wind\Wind.NET.Client\WindNET\bin\WindNET.exe` |
| `WINDOWS_UI_CONTROL_CHROME_PATH` | `C:\Program Files\Google\Chrome\Application\chrome.exe` |
| `WINDOWS_UI_CONTROL_CHROME_PROFILE` | `Default` |

运行日志和 ComeIn 窗口登记默认写入 `%LOCALAPPDATA%\WindowsUIControl\`,不会使用仓库内文件,并与现有 Gardenia 插件的运行记录分开。

## 功能与边界

- 白名单应用为 `Weixin`、`DingTalk`、`Wind` 和 `ComeInChrome`。可列出窗口、启动前三个应用、激活、最小化/恢复、检查 UI Automation 控件、截图,并在目标窗口内执行有限点击、按键和文本输入。
- 白名单依赖可执行文件名(例如 `weixin.exe`、`dingtalk.exe`、`wmain.exe`/`windnet.exe`/`windnavigator.exe`、`chrome.exe`)及必要的窗口类名/标题标记;它不负责验证数字签名,也不把安装路径本身当作安全证明。
- ComeIn 只接受 `https://www.comein.cn/roadshow/` 下的地址,在专用 Chrome app 窗口创建并登记后才允许继续操作或关闭该窗口。示例地址:`https://www.comein.cn/roadshow/home/123`。
- `windows_screenshot` 会把目标窗口的屏幕像素返回给调用客户端,`windows_inspect_controls` 会把控件名称、类型、自动化 ID、位置和可见性等信息返回给客户端;请勿在这些结果中放入不应进入客户端上下文的敏感内容。
- `windows_type_text` 使用 pywinauto 的按键发送语法;特殊字符可能被解释为按键语法。需要明确按键组合时使用 `windows_keypress`,并谨慎处理文本内容。
- 点击、按键、文本输入和截图都要求目标窗口已被服务识别并处于可操作状态。服务不会承诺隔离其他桌面程序;调用方应在执行前检查窗口列表和控件结果。

## 开发与测试

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
```

测试只覆盖 URL 校验、窗口登记和边界逻辑,不会打开或操作真实桌面应用。

## 许可证

本项目采用 [MIT License](LICENSE)。