Agente de Pantalla

Agente de pruebas nativo de IA que ve su aplicación como un usuario real: 15 veces más rápido que Claude Code, sin tocar su pantalla.

Un servidor MCP para pruebas visuales autónomas. La IA planifica los pasos de la prueba en lenguaje natural, el servidor los ejecuta todos sin viajes de ida y vuelta al LLM. Funciona en segundo plano a través de CDP (Chrome) o la API de Accesibilidad (aplicaciones nativas).

Demo Rápida

# 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

¿Por qué?

Cada herramienta de pruebas le obliga a elegir: rápida pero frágil (Playwright) o inteligente pero lenta (uso de computadora de Claude Code). El Agente de Pantalla es ambas cosas:

• Ejecución Autónoma — run_test() ejecuta TODOS los pasos en el lado del servidor. Sin viajes de ida y vuelta al LLM. 150ms/paso frente a los 1-3s/paso de Claude Code. 15 veces más rápido.

• Visión Primero — el LLM VE la pantalla y decide dónde hacer clic. No usa selectores DOM. Los cambios en la interfaz de usuario no rompen las pruebas porque el LLM reinterpreta la pantalla.

• act + eval_js — act devuelve una captura de pantalla para que el LLM la analice visualmente, luego ejecuta en las coordenadas proporcionadas por el LLM. eval_js ejecuta JavaScript a través de CDP para aserciones. 5 pruebas en 0.6s.

• Pruebas en Segundo Plano — window_scope + CDP le permite probar aplicaciones de Chrome en cualquier Espacio de macOS sin tocar la pantalla del usuario. Para aplicaciones nativas, prueba detrás de otras ventanas en el mismo Espacio.

• Cadena de Entrada Multi-Backend — tres métodos de entrada (API de Accesibilidad → CGEvent → pyautogui) con respaldo automático. Funciona con aplicaciones nativas, aplicaciones Electron y motores de juegos.

• Guardián de Entrada — sistema de seguridad en tiempo real que pausa todas las acciones del agente cuando toca el ratón o el teclado. Ninguna otra herramienta ofrece esto.

• Flujos de Trabajo entre Aplicaciones — flujos de prueba que abarcan múltiples aplicaciones (correo electrónico → navegador → Slack). Ninguna otra herramienta puede hacer esto porque todas son de una sola aplicación.

Arquitectura

┌──────────────────────────────────┐
│          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
└──────────────────────────────────┘

Cadena de Backend de Entrada

El desafío de diseño central: pyautogui funciona para aproximadamente el 80% de las aplicaciones, pero falla en motores de juegos y muchas aplicaciones Electron. El Agente de Pantalla resuelve esto con un patrón de Cadena de Responsabilidad:

Cada backend implementa el mismo protocolo InputBackend. Si uno falla, la cadena intenta automáticamente el siguiente. Todos los intentos se registran con telemetría para la observabilidad.

Instalación

pip install screen-agent

# Recommended: install macOS native backends
pip install screen-agent[macos]

Inicio Rápido

Con Claude Code

claude mcp add screen -- screen-agent serve

Con Cursor / otros clientes MCP

Añadir a su configuración de MCP:

{
  "mcpServers": {
    "screen": {
      "command": "screen-agent",
      "args": ["serve"]
    }
  }
}

Comprobar capacidades del sistema

screen-agent check

Herramientas

Percepción

Entrada (todas admiten verify: true para capturas de pantalla post-acción)

OCR (detecta automáticamente chino, japonés, coreano, inglés)

Pruebas Autónomas (el diferenciador)

Pruebas en Segundo Plano

Pruebas Visuales E2E

Seguridad (Guardián de Entrada)

Pruebas en Segundo Plano

El Agente de Pantalla puede probar aplicaciones sin ocupar su pantalla. Tres modos, seleccionados automáticamente:

Modo 1: CDP (Chrome/Electron — cualquier Espacio, totalmente invisible)

# 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 evita el servidor de ventanas de macOS por completo. Las capturas de pantalla provienen del renderizador de Chrome, los clics pasan a través del sistema de entrada de Chrome. Su pantalla nunca es tocada.

Modo 2: Captura de Ventana (cualquier aplicación de macOS — mismo Espacio)

# Works with Figma, Xcode, Terminal, games — any app
window_scope(app="Figma", title="Design v2")
interact(target="Export", action="click")
window_release()

Utiliza CGWindowListCreateImage para capturar la ventana incluso cuando está detrás de otras aplicaciones. Requiere el mismo Espacio de macOS.

Modo 3: Pantalla Completa (original)

Sin window_scope, opera en la pantalla completa como antes.

Prioridad de Respaldo

window_scope called → try CDP (Chrome) → try CGWindowList (same Space) → error
no scope → full screen mode

Guardián de Entrada

El sistema de seguridad único del Agente de Pantalla con dos garantías:

1. Prioridad del Usuario — cualquier actividad de teclado/ratón pausa instantáneamente al agente. Se reanuda solo después de que usted haya estado inactivo durante 1.5s (configurable).

2. Bloqueo de Alcance — restringir al agente a aplicaciones específicas y/o regiones de pantalla.

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

Configuración

Todos los parámetros son configurables a través de variables de entorno:

Soporte de Plataforma

Desarrollo

git clone https://github.com/chriswu727/screen-agent
cd screen-agent
pip install -e ".[dev,macos]"
pytest tests/unit/ -v
ruff check src/ tests/

Consulte DEVPATH.md para conocer el historial de desarrollo y las decisiones arquitectónicas.

Licencia

MIT