Skip to main content
Glama
deenesjakoruzh
chriswu727

Screen Agent

by chriswu727
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

屏幕代理 (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: vision-input

为什么选择它？

每个测试工具都让你面临选择：快速但脆弱 (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

AXPerformAction

原生 macOS 应用 — 语义化，无需坐标

2

CGEvent

CGEventPost

游戏、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

工具

感知

工具

描述

capture_screen

截图（全屏或区域），返回图像供视觉分析

list_windows

列出所有可见窗口及其位置

get_active_window

当前聚焦的窗口

get_cursor_position

当前鼠标位置

输入（全部支持 verify: true 以进行操作后截图）

工具

描述

click

在坐标处点击（左/右/中，多击）

type_text

在光标处输入文本（macOS 上通过剪贴板使用 Unicode）

press_key

带修饰键的按键（例如 Cmd+C）

scroll

在可选位置滚动鼠标滚轮

move_mouse

移动光标而不点击

drag

在两点之间点击并拖动

focus_window

通过部分标题匹配将窗口置于前台

OCR（自动检测中文、日文、韩文、英文）

工具

描述

ocr

提取所有带边界框的文本

find_text

查找文本并返回位置

click_text

查找文本并点击其中心

自主测试（差异化功能）

工具

描述

run_test

自主执行完整的测试计划 — 无需 LLM 往返。速度提升 15 倍。

act

视觉优先：返回截图 → LLM 查看 → 在坐标处执行

eval_js

通过 CDP 执行 JavaScript。DOM 断言、元素点击、状态检查

interact

基于 OCR：查找文本元素 + 在一次调用中点击/输入

后台测试

工具

描述

window_scope

锁定到窗口。Chrome：自动 CDP（任何空间）。原生：CGWindowList（同一空间）。

window_release

释放窗口范围，返回全屏模式

视觉 E2E 测试

工具

描述

test_start

启动测试会话并自动收集截图

test_step

开始测试步骤（自动捕获“之前”的截图）

test_verify

通过 OCR 文本检查或截图差异验证步骤

test_end

结束会话，生成带证据的 Markdown 报告

test_status

当前会话状态

安全（输入守护者）

工具

描述

add_app

将应用添加到白名单 — 代理只能与列出的应用交互

remove_app

从白名单中移除应用

set_region

限制在像素区域内

clear_scope

移除所有限制

get_agent_status

守护者状态、后端统计信息、范围信息

后台测试

屏幕代理可以在不占用您屏幕的情况下测试应用程序。三种模式，自动选择：

模式 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. 用户优先 — 任何键盘/鼠标活动都会立即暂停代理。只有在您空闲 1.5 秒（可配置）后才会恢复。

  2. 范围锁定 — 将代理限制在特定应用和/或屏幕区域。

# 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)

配置

所有参数均可通过环境变量进行配置：

变量

默认值

描述

SCREEN_AGENT_COOLDOWN

1.5

守护者冷却秒数

SCREEN_AGENT_GUARDIAN_DISABLED

0

设置为 "1" 以禁用

SCREEN_AGENT_INPUT_BACKENDS

ax,cgevent,pyautogui

后端优先级顺序

SCREEN_AGENT_MAX_DIMENSION

2560

最大截图尺寸

SCREEN_AGENT_LOG_LEVEL

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers