Metadata-Version: 2.4
Name: desktop-test-mcp
Version: 0.1.0
Summary: MCP server for Windows desktop UI E2E testing with VLM-powered visual assertion
Author: Desktop Test MCP Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: e2e-testing,mcp,ui-automation,vlm,windows
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: comtypes>=1.4.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: windows-capture>=0.4.0
Description-Content-Type: text/markdown

# Desktop Test MCP

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

通过 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 协议，让 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

## 快速开始

### 安装

```bash
pip install -e .
```

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

### 配置 MCP 客户端

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

```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](https://github.com/windowsox/Windows-MCP) — 多后端截图、截图标注、窗口管理思路
- [Python-UIAutomation-for-Windows](https://github.com/yinkaisheng/Python-UIAutomation-for-Windows) — UIA COM 封装库（Apache 2.0）

## License

MIT
