MCP Test Utils

MCP Test Utils

用于自动化桌面 UI 测试的 MCP 服务。单个二进制文件——无需运行时、依赖项或安装程序。

仅支持 Windows x64。 目前尚无 macOS 或 Linux 版本。如有需要，请联系 [email protected]：您的需求将决定后续开发方向。

为 AI Agent 提供眼睛和双手：屏幕截图、窗口管理、鼠标、键盘、UI Automation、OCR、文件搜索。 可将已保存的场景作为回归测试运行——每次构建后都能运行，无需 Agent 参与。记录您的操作并生成场景草稿， 检查无障碍功能，并监控被测应用的资源。

为什么

AI Agent 可以在应用中触发操作，却看不到屏幕。此服务填补了这一空白：

Agent triggers action → takes screenshot → sees the result →
switches window → clicks a button → verifies → writes report

完全自主，无需用户参与。

演示

3.26 — 场景运行 Claude 重放已保存的测试：232 个步骤，一次调用，66 秒

安装和设置 设置服务和基本工具

设置

1. 从 Releases 下载 mcp-test-utils.exe（旁边的 .sig 文件供内置更新程序使用——您不需要它）。
2. 将其添加到 MCP 客户端：

Claude Desktop： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "test-utils": {
      "command": "D:\\path\\to\\mcp-test-utils.exe"
    }
  }
}

Claude Code：

claude mcp add test-utils -- "D:\path\to\mcp-test-utils.exe"

其他客户端请参阅相应文档。

3. 重启客户端。
4. 在聊天中尝试：“Take a screenshot”——Agent 将返回桌面截图。

可选设置（日志记录、文件搜索、启动程序）可放入 env 中——请参阅 环境变量：

{
  "mcpServers": {
    "test-utils": {
      "command": "D:\\path\\to\\mcp-test-utils.exe",
      "env": {
        "MCP_LOG_DIR": "D:\\path\\to\\logs",
        "MCP_SEARCH_DIRS": "D:\\Projects\\app1;D:\\Projects\\app2",
        "MCP_LAUNCH_APPS": "C:\\Program Files\\MyApp\\myapp.exe"
      }
    }
  }
}

工具（31）

其中 4 个工具仅在完成配置后显示：配置 MCP_SEARCH_DIRS 后显示 search_in_files 和 find_files，配置 MCP_LOG_DIR 后显示 enable_logging 和 disable_logging——默认情况下，服务会列出 27 个工具。

视觉

工具	描述
take_screenshot	整个桌面的屏幕截图；提供从完整到最简的质量预设（可减少令牌用量）
take_window_screenshot	指定窗口的屏幕截图
read_screen_text	对整个屏幕执行 OCR（Windows OCR）
read_region_text	对屏幕区域执行 OCR，并提供精确的单词坐标

窗口管理

工具	描述
list_windows	列出窗口及其 ID、标题、应用、进程 ID、位置、大小和状态
focus_window	将窗口置于前台，并在窗口最小化时将其还原；还可选择设置其位置和大小
launch_app	从服务配置的允许列表（MCP_LAUNCH_APPS）中启动程序，并等待其窗口出现
close_window	像点击窗口的 X 按钮一样关闭窗口，并等待窗口关闭；会报告“保存更改？”提示

输入

工具	描述
mouse_click	按元素 ID 或坐标单击（左键／右键／中键、双击）；可以等待预期效果并重试
mouse_move	将光标移动到某个点或 UI 元素
mouse_drag	以接近人类的速度在元素或点之间拖动（支持 HTML5 拖放）
mouse_scroll	在某个元素上滚动鼠标滚轮，并等待滚动停止
keyboard_type	输入文本（完整 Unicode 支持，包括拉丁字母、西里尔字母、CJK 字符和表情符号），并检查字段是否显示了输入内容
keyboard_press	按下按键（Enter、Tab、F1–F12、方向键等），可选择重复按下
keyboard_shortcut	按下组合键（Ctrl+S、Alt+F4、Ctrl+Shift+P 等）

结构化 UI 访问

工具	描述
list_ui_elements	UI 自动化树 — 显示按钮、字段、菜单的 ID、值、状态和精确坐标；可按名称、值、类筛选
get_focused_element	当前具有键盘焦点的元素及其所在窗口
read_text	通过 UI 自动化读取文档或字段的全部文本（每次调用最多 100 000 个字符），无需 OCR
ui_action	无需鼠标或键盘即可操作元素：调用、切换、展开、选择选项、设置值、滚动到可见区域
check_accessibility	无障碍缺陷：未命名的控件、Tab 键无法访问的控件、重复 ID、尺寸为零的控件

进程

工具	描述
process_info	被测应用的内存、句柄、GDI 对象、线程和 CPU 使用情况 — 可重复调用以发现泄漏

等待、批处理和场景

工具	描述
wait_for	等待窗口、元素或其状态，而不是休眠
batch	在一个请求中运行最多 20 次工具调用，支持 find 和 assert 步骤
run_scenario	重放已保存的场景、套件或数据行，并获取通过／失败报告（参见无 Agent 的回归运行）
record_scenario	将你在一个窗口中的操作录制为场景草稿（参见录制）

文件搜索

工具	描述
search_in_files	在允许的目录中搜索文件文本或正则表达式（类似 VS Code 的“在文件中查找”）
find_files	按名称模式（glob）查找文件和目录，类似“转到文件”

Agent 指南

工具	描述
get_usage_guide	Agent 使用指南：核心规则和按需查看的章节
prepare_feedback	为作者准备建议文件（个人数据会被遮蔽；由你审核后通过电子邮件发送 — 不会自动发送任何内容）

会话日志

工具	描述
enable_logging	开始将工具调用记录到 JSONL 和屏幕截图中（选择启用）
disable_logging	停止记录并获取会话统计信息

无 Agent 的回归运行

Agent 在你的应用中探索一次路径，并将其保存为 场景 — 一个 JSON 文件。之后，场景会在没有 Agent 的情况下重放：速度快、每次方式相同、不消耗 token。

mcp-test-utils --check order-form.json     # validate the file, touch nothing
mcp-test-utils --run order-form.json       # run: report in the console and in order-form.report.json

• 退出代码：0 — 通过，1 — 某个步骤失败，2 — 未运行。每次构建后即可用于 CI 任务。
• 发生故障时，你会获得屏幕截图、元素树和提示：场景已过时，或应用已更改。
• Agent 使用 run_scenario(path) 运行场景，并通过 get_usage_guide(section: "scenarios") 了解格式。
• 套件和数据行： --suite 按顺序运行多个场景文件，并提供一份摘要；--data rows.csv 对每一行运行一次场景（列会成为变量）；--junit report.xml 为 CI 添加 JUnit XML。

  mcp-test-utils --suite regress.suite.json --junit regress.xml
  

• 没有许可证密钥时，场景最多运行 50 个步骤（参见许可证密钥）。

录制

自行执行这些步骤，直接生成一个草稿场景，而不是向 Agent 描述步骤：

mcp-test-utils --record order-form.json --app myapp

录制内容仅包括该窗口及其对话框，屏幕上会显示通知；按 Ctrl+Alt+Shift+R（或在控制台中按 Enter）可停止录制。绝不会读取密码字段；只有使用 --keys-text 时，才会录制输入终端的文本。Agent 可以通过 record_scenario 启动同样的录制。

环境变量

变量	描述	默认值
MCP_LOG_DIR	日志会话的路径。未设置时，日志工具将被隐藏	—
MCP_LOG_MAX_MB	会话大小上限（超出时发出警告）	500
MCP_LOG_RETAIN_DAYS	自动删除超过 N 天的会话。设为 0 可禁用	30
MCP_SEARCH_DIRS	search_in_files 和 find_files 可访问的目录（以 ; 分隔）。未设置时，这两个工具都会被隐藏	—
MCP_LAUNCH_APPS	launch_app 可以启动的程序（.exe 文件或文件夹，以 ; 分隔）。即使列出，Shell、脚本宿主和解释器也会被拒绝。未设置时，launch_app 不会启动任何程序	—
MCP_NOTIFY	设为 off 可隐藏系统托盘图标和实时调用日志窗口	—
MCP_INPUT_LOCK	设为 off 可在服务发送输入时禁用键盘和鼠标锁定	—
MCP_INPUT_LOCK_STALL_MS	服务静默超过此时长（毫秒）后，锁定会解除，恢复你的输入	60000

系统托盘图标、更新和输入锁定

• 系统托盘图标会实时显示工具调用日志，每个会话对应一个标签页，错误以红色显示；设为 MCP_NOTIFY=off 可将其隐藏。
• **更新：**系统托盘菜单 → Check for updates…。只会安装由作者签名的版本；安装后请重启 MCP 客户端。只有在你点击后，服务才会联网。
• **输入锁定：**服务输入文字或点击时，键盘和鼠标按键会暂停（指针仍可移动）。按 Esc 可停止操作并恢复输入。设为 MCP_INPUT_LOCK=off 可关闭锁定。

反馈

如果 Agent 遇到工具无法处理的情况，它会询问是否准备一份简短的建议文件（prepare_feedback）。该文件会保存到 Documents\mcp-test-utils feedback\，个人数据会经过遮蔽，且不包含屏幕截图；请检查文件并通过电子邮件发送至 [email protected]。不会自动发送任何内容。

用例

• 自动化 QA — Agent 浏览应用、逐步点击操作流程、截取每一步的屏幕截图，并撰写测试报告
• 回归测试 — 每次构建后，通过脚本或 CI 任务重放已保存的场景，无需 Agent
• 录制测试 — 自行走一遍操作路径，生成草稿场景，再让 Agent 将其转换为测试
• 桌面自动化 — 填写表单、在窗口之间复制数据、运行工作流
• 无障碍审计 — check_accessibility 可查找未命名的控件、按 Tab 键无法访问的控件以及重复的 ID
• 资源泄漏 — process_info 可显示多次调用过程中持续增长的句柄数和 GDI 对象数
• 视觉检查 — Agent 比较不同构建版本之间的屏幕截图
• 数据提取 — 通过 UI Automation 读取文档文本，或对无法提供文本的应用执行 OCR
• 代码搜索 — 无需离开 Agent 会话，即可跨多个项目查找匹配模式

安全性

• 仅响应 MCP 客户端的请求；不会开放网络端口
• 仅在你要求时写入文件：日志、场景报告和 JUnit 文件、录制的草稿、封存的场景、反馈文件、许可证文件，以及 %LOCALAPPDATA%\mcp-test-utils\ 中的小型设置文件和你安装的更新
• 不会向外发送任何数据；只有当你在托盘窗口中点击 Check for updates（和 Download and install）时才会联网——Agent 的工具调用绝不会联网，并且只会安装由作者签名的文件
• 仅在发送输入的调用、batch 或场景运行期间接管键盘和鼠标按键——按 Esc 可立即释放
• 仅启动你在 MCP_LAUNCH_APPS 中列出的程序（绝不启动 shell 或解释器）；强制执行 close_window 时，只会终止它启动的程序
• 仅在收到明确命令时录制，并且全程在屏幕上显示提示；绝不会读取密码字段
• 屏幕截图会捕获整个屏幕——请确保其中没有敏感信息
• 文件搜索受沙箱限制——只能访问 MCP_SEARCH_DIRS 中的目录

工作原理

MCP Test Utils 是一个通过 stdin/stdout 通信的 MCP 服务：你的 MCP 客户端会启动该 exe 并调用其工具。它使用原生 Windows API（UI Automation、Win32 输入、Windows OCR）——不使用 PowerShell、辅助工具或网络访问，但你主动启动的更新检查除外。已通过 Claude Desktop 和 Claude Code 测试。

许可证密钥

所有工具均可免费使用。许可证密钥仅用于解除场景运行的 50 步限制。

目前，密钥通过早期体验计划发放：前 30 位用户可获得免费的一年期密钥，以换取首月结束后的简短反馈——请将你的电子邮件地址和电脑的机器码发送至 [email protected]。密钥绑定到该电脑。你的 Agent 可在 get_usage_guide 的第二行查看机器码，你也可以自行打印：

mcp-test-utils --machine-id

在该电脑上注册一次密钥：

mcp-test-utils --set-license <email> <key>

重新安装 Windows 或仅更换主板后，密钥仍然有效；换用新电脑则需要新密钥——再次写信即可。

封存的场景可在任何地方运行，不受限制——仅限该文件，并且必须与封存时完全一致。 在已授权的电脑上运行 mcp-test-utils --seal order-form.json，即可将密封信息写入文件；没有密钥的 CI Agent 或同事随后也能完整运行该场景。任何步骤（或其包含的文件）发生更改都会使密封失效——请在已授权的电脑上重新封存。

支持我们

如果你觉得它有用——jeenyjai.github.io

许可证

版权所有 2026 JeenyJAI。保留所有权利。

---

🚀 使用 Claude 创建