desktop-test-mcp 0.1.0

MCP server for Windows desktop UI E2E testing with VLM-powered visual assertion

Desktop Test MCP

基于 VLM（视觉语言模型）的 UI 自动化测试 MCP 服务器。

通过 MCP (Model Context Protocol) 协议，让 AI Coding Agent 像人眼一样从截图理解界面，用坐标完成交互，并用 VLM 做视觉断言。元素定位与交互全程不依赖无障碍树，纯视觉驱动。

核心特性

• 纯 VLM 元素定位 — vlm_snapshot 从截图识别全部 UI 元素，vlm_click 用自然语言描述目标后由 VLM 定位并点击，无需 ref、无需坐标猜测
• 坐标式后台交互 — coord_click / coord_type 经 PostMessage 投递，不抢焦点、不移动光标，可对后台窗口操作
• VLM 视觉断言 — vision_assert / vlm_assert 用自然语言描述预期视觉状态，由 VLM 判定 PASS/FAIL
• OODA 自动探索 — vlm_navigate 以观察-决策-执行-验证循环自动完成多步场景，并记忆 Playbook 复用
• 多后端截图 — PrintWindow 后台截取 → 屏幕区域回退，支持窗口/全屏
• 沙箱环境 — Linux（Docker + Xvfb）/ Android（Redroid）/ iOS（Simctl）隔离运行环境，配套点击/输入/截图/按键
• 测试报告 — OODA 结果一键导出 JSON / JUnit XML

快速开始

安装

pip install -e .

要求：Python 3.10+，Windows 10/11（桌面端）；沙箱需要 Docker。

配置 MCP 客户端

以 Claude Desktop 为例，编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "desktop-test": {
      "command": "python",
      "args": ["-m", "desktop_test_mcp"],
      "env": {
        "VLM_BASE_URL": "http://localhost:11434/v1",
        "VLM_MODEL": "qwen3-vl:8b"
      }
    }
  }
}

环境变量

变量	默认值	说明
VLM_BASE_URL	http://localhost:11434/v1	OpenAI 兼容 API 地址
VLM_MODEL	smolvlm	视觉模型名称（需为支持图像的 VLM）
VLM_API_KEY	ollama	API Key（ollama 不需要真实 key）
VLM_TIMEOUT	120	VLM 请求超时秒数
VLM_MAX_TOKENS	1024	最大生成 token 数
VLM_PROVIDER	ollama	VLM 后端：ollama 或 openai

工具一览（39 个）

截图与窗口

工具	说明
desktop_list_windows	列出所有可见顶层窗口及句柄
desktop_screenshot	截取窗口/全屏截图，返回 base64 JPEG
desktop_launch	启动应用，可选等待窗口出现
desktop_switch_window	将窗口切换到前台
desktop_resize_window	移动和调整窗口大小
desktop_maximize_window / desktop_minimize_window / desktop_close_window	窗口最大化/最小化/关闭

交互

工具	说明
desktop_shortcut	发送键盘快捷键（{Ctrl}c, {Alt}{F4}），PostMessage 后台投递

VLM 视觉（核心）

工具	说明
vlm_snapshot	VLM 从截图识别全部 UI 元素及坐标
vlm_click	用自然语言描述目标，VLM 定位后在坐标处点击
vlm_assert	VLM 视觉断言，返回 PASS/FAIL
vlm_navigate	OODA 循环自动探索，完成多步场景
desktop_vision_ask	向 VLM 提问关于当前屏幕的问题
desktop_vision_assert	用自然语言描述视觉断言，VLM 返回 PASS/FAIL
desktop_vision_compare	对比参考截图与当前屏幕的差异

沙箱

工具	说明
sandbox_create / sandbox_destroy / sandbox_list	创建/销毁/列出沙箱容器
sandbox_install_app / sandbox_launch_app	沙箱内安装/启动应用
sandbox_screenshot / sandbox_click / sandbox_type / sandbox_scroll / sandbox_key	沙箱内截图/点击/输入/滚动/按键
sandbox_build_image / sandbox_cleanup	构建 Linux 镜像 / 清理过期容器

Playbook 与报告

工具	说明
playbook_list / playbook_show / playbook_delete	列出/查看/删除记忆的 Playbook
test_report	生成 JSON / JUnit XML 测试报告

辅助工具

工具	说明
desktop_shell	执行 shell 命令
desktop_list_processes / desktop_kill_process	列出/终止进程
desktop_clipboard_get / desktop_clipboard_set	读写剪贴板
desktop_wait_for_window / desktop_wait	等待窗口出现 / 等待指定时长

典型工作流

1. desktop_list_windows            → 找到目标窗口
2. vlm_snapshot                    → VLM 从截图识别界面元素与坐标
3. vlm_click("登录按钮")           → VLM 定位并在坐标处点击
4. vlm_navigate("输入用户名并登录") → OODA 循环：自动定位输入框、输入文本、提交
5. vlm_assert("已进入主界面")       → VLM 视觉断言验证

项目结构

src/desktop_test_mcp/
├── __init__.py / __main__.py / config.py / server.py
├── providers/                   # 平台抽象层
│   ├── base.py                  # PlatformProvider Protocol
│   └── windows.py               # Windows 实现（截图/坐标交互/窗口管理）
├── core/                        # 核心引擎
│   ├── screenshot.py            # 多后端截图
│   ├── bg_capture.py            # 后台窗口截取（PrintWindow）
│   ├── bg_interact.py           # 后台坐标交互（PostMessage）
│   ├── annotation.py            # 截图标注覆盖
│   ├── wait.py / window_manager.py
├── tools/                       # MCP 工具注册
│   ├── snapshot.py / interact.py / app.py
│   ├── vision.py / vlm_tools.py / sandbox.py
│   ├── shell.py / process.py / clipboard.py / wait_tools.py
├── vision/                      # VLM 视觉模块
│   ├── vlm_client.py            # OpenAI 兼容 HTTP 客户端（带自动拉起/恢复）
│   ├── vlm_elements.py          # VLM 元素定位 + 点击坐标计算
│   ├── ooda_engine.py           # OODA 自动探索引擎
│   ├── vision_ask.py / vision_assert.py / vision_compare.py
│   ├── vlm_base.py / vlm_factory.py / vlm_openai.py
├── sandbox/                     # 跨平台沙箱
│   ├── docker_manager.py        # Linux 沙箱（Docker + Xvfb）
│   ├── xvfb_provider.py         # Linux 交互
│   ├── redroid_provider.py / simctl_provider.py  # Android / iOS
│   ├── registry.py / junit_reporter.py / test_results.py
├── playbook/                    # 场景记忆
│   ├── storage.py / extractor.py / models.py
└── uia/                         # vendored yinkaisheng UIA 库（Apache 2.0）

致谢

• Windows-MCP — 多后端截图、截图标注、窗口管理思路
• Python-UIAutomation-for-Windows — UIA COM 封装库（Apache 2.0）

License

MIT