Screen Agent
屏幕代理 (Screen Agent)
AI 原生测试代理,像真实用户一样查看您的应用 — 比 Claude Code 快 15 倍,且无需占用您的屏幕。
一个用于自主视觉测试的 MCP 服务器。AI 以自然语言规划测试步骤,服务器无需 LLM 往返即可执行所有步骤。通过 CDP (Chrome) 或辅助功能 API (原生应用) 在后台运行。
快速演示
# The AI plans. The server executes. No LLM round-trips. Background. 3 seconds.
run_test(name="Login Flow", steps=[
{"find": "Email", "action": "click_and_type", "text": "user@test.com"},
{"find": "Password", "action": "click_and_type", "text": "secret123"},
{"find": "Log in", "action": "click"},
{"verify": "Dashboard"},
])
# → ✅ 4/4 passed in 800ms. Screenshot evidence attached.Related MCP server: Open Computer Use
为什么选择它?
每个测试工具都让你面临选择:快速但脆弱 (Playwright) 或 智能但缓慢 (Claude Code 计算机使用)。屏幕代理两者兼备:
自主执行 —
run_test()在服务器端执行所有步骤。无需 LLM 往返。每步 150 毫秒,而 Claude Code 每步 1-3 秒。速度提升 15 倍。视觉优先 — LLM 可以“看到”屏幕并决定点击位置。不依赖 DOM 选择器。UI 变更不会导致测试失败,因为 LLM 会重新解读屏幕。
act+eval_js—act返回截图供 LLM 进行视觉分析,然后在 LLM 提供的坐标处执行。eval_js通过 CDP 运行 JavaScript 进行断言。0.6 秒内完成 5 个测试。后台测试 —
window_scope+ CDP 让您可以在任何 macOS 空间测试 Chrome 应用,而无需占用您的屏幕。对于原生应用,可在同一空间的其他窗口后方进行测试。多后端输入链 — 三种输入方法(辅助功能 API → CGEvent → pyautogui)并带有自动回退机制。适用于原生应用、Electron 应用和游戏引擎。
输入守护者 (Input Guardian) — 实时安全系统,当您触摸鼠标或键盘时,会暂停所有代理操作。没有其他工具提供此功能。
跨应用工作流 — 测试跨多个应用(电子邮件 → 浏览器 → Slack)的流程。没有其他工具能做到这一点,因为它们都是单应用工具。
架构
┌──────────────────────────────────┐
│ MCP Layer │ 22 tools via Model Context Protocol
├──────────────────────────────────┤
│ Engine Layer │ InputChain (fallback) + Guardian (safety)
│ │ + WindowSession (background testing)
├──────────────────────────────────┤
│ Platform Layer │ Protocol-based backends
│ AX → CGEvent → pyautogui │ macOS / Windows / Linux
└──────────────────────────────────┘输入后端链
核心设计挑战:pyautogui 适用于约 80% 的应用,但在游戏引擎和许多 Electron 应用中会失败。屏幕代理通过“责任链”模式解决了这个问题:
优先级 | 后端 | 方法 | 最适合 |
1 | AX |
| 原生 macOS 应用 — 语义化,无需坐标 |
2 | CGEvent |
| 游戏、Electron — 原生 OS 事件注入 |
3 | pyautogui | Python 包装器 | 跨平台回退 |
每个后端都实现了相同的 InputBackend 协议。如果一个失败,链条会自动尝试下一个。所有尝试都会记录遥测数据以供观察。
安装
pip install screen-agent
# Recommended: install macOS native backends
pip install screen-agent[macos]快速入门
使用 Claude Code
claude mcp add screen -- screen-agent serve使用 Cursor / 其他 MCP 客户端
添加到您的 MCP 配置中:
{
"mcpServers": {
"screen": {
"command": "screen-agent",
"args": ["serve"]
}
}
}检查系统能力
screen-agent check工具
感知
工具 | 描述 |
| 截图(全屏或区域),返回图像供视觉分析 |
| 列出所有可见窗口及其位置 |
| 当前聚焦的窗口 |
| 当前鼠标位置 |
输入(全部支持 verify: true 以进行操作后截图)
工具 | 描述 |
| 在坐标处点击(左/右/中,多击) |
| 在光标处输入文本(macOS 上通过剪贴板使用 Unicode) |
| 带修饰键的按键(例如 Cmd+C) |
| 在可选位置滚动鼠标滚轮 |
| 移动光标而不点击 |
| 在两点之间点击并拖动 |
| 通过部分标题匹配将窗口置于前台 |
OCR(自动检测中文、日文、韩文、英文)
工具 | 描述 |
| 提取所有带边界框的文本 |
| 查找文本并返回位置 |
| 查找文本并点击其中心 |
自主测试(差异化功能)
工具 | 描述 |
| 自主执行完整的测试计划 — 无需 LLM 往返。速度提升 15 倍。 |
| 视觉优先:返回截图 → LLM 查看 → 在坐标处执行 |
| 通过 CDP 执行 JavaScript。DOM 断言、元素点击、状态检查 |
| 基于 OCR:查找文本元素 + 在一次调用中点击/输入 |
后台测试
工具 | 描述 |
| 锁定到窗口。Chrome:自动 CDP(任何空间)。原生:CGWindowList(同一空间)。 |
| 释放窗口范围,返回全屏模式 |
视觉 E2E 测试
工具 | 描述 |
| 启动测试会话并自动收集截图 |
| 开始测试步骤(自动捕获“之前”的截图) |
| 通过 OCR 文本检查或截图差异验证步骤 |
| 结束会话,生成带证据的 Markdown 报告 |
| 当前会话状态 |
安全(输入守护者)
工具 | 描述 |
| 将应用添加到白名单 — 代理只能与列出的应用交互 |
| 从白名单中移除应用 |
| 限制在像素区域内 |
| 移除所有限制 |
| 守护者状态、后端统计信息、范围信息 |
后台测试
屏幕代理可以在不占用您屏幕的情况下测试应用程序。三种模式,自动选择:
模式 1:CDP (Chrome/Electron — 任何空间,完全不可见)
# Start Chrome with debugging port
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 --user-data-dir=/tmp/chrome-test# Connect — works even if Chrome is on a different desktop
window_scope(app="Chrome", url="localhost:3000")
# All operations go through Chrome's internal pipeline
interact(target="Submit", action="click")
interact(target="Email", action="click_and_type", text="test@example.com")
window_release()CDP 完全绕过了 macOS 窗口服务器。截图来自 Chrome 的渲染器,点击通过 Chrome 的输入系统进行。您的屏幕永远不会被触碰。
模式 2:窗口捕获 (任何 macOS 应用 — 同一空间)
# Works with Figma, Xcode, Terminal, games — any app
window_scope(app="Figma", title="Design v2")
interact(target="Export", action="click")
window_release()使用 CGWindowListCreateImage 即使在其他应用后方也能捕获窗口。需要相同的 macOS 空间。
模式 3:全屏 (原始模式)
如果没有 window_scope,则像以前一样在全屏上操作。
回退优先级
window_scope called → try CDP (Chrome) → try CGWindowList (same Space) → error
no scope → full screen mode输入守护者 (Input Guardian)
屏幕代理独特的安全系统,提供两项保证:
用户优先 — 任何键盘/鼠标活动都会立即暂停代理。只有在您空闲 1.5 秒(可配置)后才会恢复。
范围锁定 — 将代理限制在特定应用和/或屏幕区域。
# Agent can only interact with Chrome and Figma
add_app("Chrome")
add_app("Figma")
# Or restrict to a region
set_region(x=0, y=0, width=800, height=600)配置
所有参数均可通过环境变量进行配置:
变量 | 默认值 | 描述 |
| 1.5 | 守护者冷却秒数 |
| 0 | 设置为 "1" 以禁用 |
| ax,cgevent,pyautogui | 后端优先级顺序 |
| 2560 | 最大截图尺寸 |
| INFO | 日志级别 |
平台支持
功能 | macOS | Windows | Linux |
截图 | mss | mss | mss |
AX 输入 | Quartz AX | - | - |
CGEvent 输入 | Quartz | - | - |
pyautogui 输入 | 回退 | 回退 | 回退 |
窗口管理 | AppleScript | - | wmctrl |
OCR | Vision Framework | - | - |
Retina 缩放 | 自动检测 | - | - |
窗口捕获 | CGWindowListCreateImage | PrintWindow | xdotool+ImageMagick |
开发
git clone https://github.com/chriswu727/screen-agent
cd screen-agent
pip install -e ".[dev,macos]"
pytest tests/unit/ -v
ruff check src/ tests/请参阅 DEVPATH.md 了解开发历史和架构决策。
许可证
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI to capture screenshots and control mouse and keyboard for automated desktop interaction.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to observe and control the user's live desktop by listing apps, reading accessibility trees, and performing clicks, typing, scrolling, dragging, and other input actions with per-action approvals and local audit archives.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to drive Windows desktop automation — opening and interacting with applications, native UI controls, keyboard/mouse input, files, processes, clipboard, and Chrome/Edge browsing via UI Automation and CDP. All actions pass through a safety policy with human approval, emergency stop, and deterministic verification.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to inspect and control allowlisted Windows applications using screenshots, mouse actions, Unicode keyboard input, UI Automation, and an Esc/F12 emergency stop.1Apache 2.0