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"
      }
    }
  }
}

环境变量

工具一览（39 个）

截图与窗口

交互

VLM 视觉（核心）

沙箱

Playbook 与报告

辅助工具

典型工作流

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