zeuxis

zeuxis

Zeuxis es un servidor local de capturas de pantalla MCP que permite a los agentes de IA capturar el escritorio actual, ventanas, regiones del cursor y rectángulos exactos a través de herramientas MCP.

Se ejecuta como un único binario local sobre stdio por defecto. Los resultados de captura permanecen en la máquina como artefactos de imagen gestionados y se devuelven al cliente MCP como enlaces de recursos file:// más metadatos estructurados. Zeuxis no sube capturas de pantalla, no realiza OCR, no controla la interfaz de usuario ni expone herramientas de control del sistema.

Plataformas compatibles

Plataforma	Estado	Notas
macOS	De primera clase	Zeuxis verifica el permiso de Grabación de Pantalla antes de capturar. Las herramientas basadas en cursor también pueden necesitar permiso de Accesibilidad.
Linux	Mejor esfuerzo	El comportamiento depende del entorno de escritorio, compositor, tipo de sesión y soporte del backend.
Otras plataformas	No compatible en v1	Las herramientas devuelven capture_unsupported_on_platform.

Instalación

Utilice una de las siguientes vías de instalación.

Cargo

Requiere Rust 1.88 o más reciente.

cargo install zeuxis
zeuxis --version

Homebrew

brew install bnomei/zeuxis/zeuxis
zeuxis --version

Lanzamientos de GitHub

Descargue un archivo precompilado desde Lanzamientos de GitHub, extráigalo y coloque zeuxis en su PATH.

Verifique el binario:

zeuxis --help

Desde el código fuente

git clone https://github.com/bnomei/zeuxis.git
cd zeuxis
cargo build --release
./target/release/zeuxis --version

Inicio rápido

Añada Zeuxis a un cliente MCP como servidor stdio:

{
  "mcpServers": {
    "zeuxis": {
      "command": "zeuxis",
      "args": []
    }
  }
}

Si utiliza Codex CLI:

codex mcp add zeuxis -- zeuxis
codex mcp list

Si utiliza Amp CLI:

amp mcp add zeuxis -- zeuxis
amp mcp list

Después de que el cliente se conecte, llame primero a get_runtime_diagnostics. Un resultado saludable informa permission_ok=true y monitors_ok=true. Luego llame a capture_screen para la primera captura de pantalla.

Las herramientas de captura exitosas devuelven:

• un breve resumen de texto,
• un enlace de recurso file:// al artefacto local,
• campos estructurados como path, uri, output_format, mime_type, artifact_sha256, width, height, capture_mode, captured_at_utc, source_scale_factor y target.

Elija una herramienta de captura

Intención del usuario	Herramienta
Ver toda la pantalla u obtener contexto inicial	capture_screen
Capturar la ventana de la aplicación enfocada	capture_active_window
Capturar la ventana bajo el cursor	capture_cursor_window
Capturar una ventana específica desde un listado de ventanas	list_windows, luego capture_window
Capturar un tooltip, menú o área pequeña adyacente al cursor	capture_cursor_region
Capturar coordenadas globales exactas del escritorio	capture_rect
Capturar coordenadas exactas locales al monitor	capture_monitor_region
Reutilizar la última captura de esta sesión del servidor	get_latest_capture
Inspeccionar o eliminar artefactos de Zeuxis de esta sesión	list_session_artifacts, clear_session_artifacts

Para una captura de ventana determinista, llame a list_windows y pase tanto snapshot_id como window_id de esa misma respuesta a capture_window. Los IDs de ventana están limitados a la instantánea, no son duraderos entre listados.

Herramientas MCP

Los esquemas de las herramientas se definen en src/mcp/tools.rs. Los payloads de resultados se construyen en src/mcp/result.rs, y los errores estables se definen en src/mcp/errors.rs.

Herramienta	Parámetros	Descripción
list_monitors	ninguno	Lista monitores con IDs, nombres, límites lógicos y banderas de principal/incorporado.
list_windows	focused_only?, include_system_windows?, app_contains?, title_contains?	Lista ventanas y registra una instantánea para capture_window. Las superficies de UI del sistema se excluyen a menos que se soliciten.
get_runtime_diagnostics	ninguno	Informa contexto de OS/sesión, estado de permisos, descubrimiento de monitores y disponibilidad del cursor.
get_latest_capture	ninguno	Devuelve el último artefacto de la sesión actual del servidor sin tomar una nueva captura.
list_session_artifacts	ninguno	Lista artefactos creados en la sesión actual del servidor y marca el más reciente.
clear_session_artifacts	ninguno	Elimina artefactos creados en la sesión actual del servidor y restablece el estado de última captura.
capture_screen	monitor_id? más parámetros de captura compartidos	Captura un monitor completo. Omitir monitor_id selecciona el monitor principal.
capture_active_window	parámetros de captura compartidos	Captura la ventana enfocada y no minimizada.
capture_cursor_window	include_system_windows? más parámetros de captura compartidos	Captura la ventana no del sistema bajo el cursor por defecto.
capture_window	snapshot_id, window_id más parámetros de captura compartidos	Captura una ventana seleccionada de una instantánea de list_windows.
capture_cursor_region	size más parámetros de captura compartidos	Captura una región cuadrada centrada en el cursor.
capture_rect	x, y, width, height más parámetros de captura compartidos	Captura un rectángulo global del escritorio en puntos lógicos.
capture_monitor_region	monitor_id, x, y, width, height más parámetros de captura compartidos	Captura un rectángulo local al monitor en puntos lógicos.

Parámetros de captura compartidos:

Parámetro	Tipo	Predeterminado	Notas
delay_ms	entero	no establecido	Retraso opcional previo a la captura en milisegundos. Rango: 0..=30000. No combinar con delay_seconds.
delay_seconds	número	no establecido	Retraso opcional previo a la captura en segundos. Rango: 0..=30. No combinar con delay_ms.
play_sound	booleano	false	Reproduce retroalimentación de captura completada tras una captura exitosa.
output	cadena u objeto	"analysis"	Controla el formato del artefacto, la reducción de escala y la calidad JPEG.

Ejemplos:

{ "delay_ms": 800, "play_sound": true }

{ "output": "compact" }

{
  "output": {
    "mode": "custom",
    "format": "webp",
    "max_dimension": 2048
  }
}

Opciones de salida

Modos de salida preestablecidos:

Preestablecido	Formato	Dimensión máxima	Calidad JPEG	Úselo cuando
analysis	PNG	2560	n/a	Análisis LLM predeterminado con reducción de escala moderada.
exact	PNG	tamaño original	n/a	Necesita píxeles originales y salida sin pérdida.
compact	JPEG	1600	85	Desea artefactos más pequeños para transferencia más rápida.

Modo de salida personalizado:

Campo	Requerido	Restricciones
mode	sí	Debe ser "custom".
format	sí	"png", "jpeg" o "webp".
max_dimension	no	Lado de salida más largo en píxeles, 256..=8192.
jpeg_quality	solo para JPEG	40..=95. Rechazado para PNG y WebP.

Si ZEUXIS_ARTIFACT_HMAC_KEY está establecido, los resultados de captura también incluyen artifact_hmac_sha256.

Coordenadas y límites

Las entradas de coordenadas utilizan puntos lógicos del escritorio. Las dimensiones de imagen capturadas utilizan píxeles de origen. Use los campos devueltos input_units, source_units y source_scale_factor para razonar sobre el escalado HiDPI.

Límites de tiempo de ejecución:

Límite	Valor
delay_ms	0..=30000
delay_seconds	0..=30
Ancho o alto de captura	1..=16384
Área de captura	<= 40000000 píxeles
max_dimension de salida personalizado	256..=8192
Calidad JPEG	40..=95

Los retrasos solicitados se ejecutan antes del trabajo de captura y son aditivos al tiempo de espera de captura. Por ejemplo, una solicitud con delay_ms=30000 y el --blocking-task-timeout-ms=15000 predeterminado puede tardar hasta unos 45 segundos antes de que el cliente reciba un tiempo de espera o un resultado.

Configuración

La configuración se resuelve como CLI flag > environment variable > default. Zeuxis no lee archivos de configuración.

La configuración de tiempo de ejecución vive en src/runtime_config.rs.

Bandera CLI	Variable de entorno	Predeterminado	Rango	Descripción
--max-concurrent-captures	ZEUXIS_MAX_CONCURRENT_CAPTURES	2	1..=16	Máximo de trabajadores de captura concurrentes.
--max-artifacts	ZEUXIS_MAX_ARTIFACTS	64	1..=10000	Máximo de archivos de imagen temporales de Zeuxis retenidos.
--max-artifact-bytes	ZEUXIS_MAX_ARTIFACT_BYTES	536870912	1024..=10737418240	Máximo de bytes de artefactos retenidos.
--artifact-dir	ZEUXIS_ARTIFACT_DIR	directorio temporal del sistema	ruta	Directorio para artefactos de captura gestionados.
--blocking-task-timeout-ms	ZEUXIS_BLOCKING_TASK_TIMEOUT_MS	15000	100..=300000	Tiempo de espera para captura, listado y trabajo de almacenamiento. Los retrasos se ejecutan antes de este tiempo de espera.
--worker-kill-grace-ms	ZEUXIS_WORKER_KILL_GRACE_MS	250	10..=30000	Período de gracia entre la terminación suave del trabajador y el cierre forzado.
--max-worker-stdout-bytes	ZEUXIS_MAX_WORKER_STDOUT_BYTES	65536	1024..=4194304	Máximo de bytes de stdout IPC del trabajador aceptados por el proceso padre.
--capture-sound-file	ZEUXIS_CAPTURE_SOUND_FILE	predeterminado de plataforma	ruta	Archivo de sonido personalizado opcional para play_sound=true.
n/a	ZEUXIS_ARTIFACT_HMAC_KEY	no establecido	cadena no vacía	Clave HMAC opcional para metadatos de integridad de artefactos.
n/a	RUST_LOG	info	filtro de tracing	Filtro de registro de tiempo de ejecución. Los registros van a stderr para mantener limpio el stdout de MCP.

Ejemplo:

ZEUXIS_MAX_CONCURRENT_CAPTURES=4 \
ZEUXIS_MAX_ARTIFACTS=128 \
zeuxis --blocking-task-timeout-ms 30000

Permisos de plataforma

macOS

Zeuxis verifica el permiso de Grabación de Pantalla antes de capturar. Si falta el permiso, Zeuxis solicita acceso a macOS y devuelve permission_denied para esa misma llamada de herramienta. Conceda el permiso de Grabación de Pantalla a la terminal o aplicación anfitriona que inicia Zeuxis y luego reintente la llamada de herramienta.

Las herramientas dependientes del cursor leen la posición global del cursor y también pueden requerir permiso de Accesibilidad. Si fallan, intente capture_screen o capture_rect mientras actualiza los permisos.

Linux

El soporte de captura en Linux depende de la sesión gráfica y las capacidades del backend. Si la captura falla, llame a get_runtime_diagnostics y verifique xdg_session_type, display, wayland_display, monitors_ok y cursor_ok.

En Wayland, el comportamiento de captura de cursor y ventanas puede ser más limitado que la captura de pantalla completa. Prefiera capture_screen primero, luego reduzca a regiones si el compositor lo permite.

Solución de problemas

permission_denied

Causa: El sistema operativo denegó el permiso de captura de pantalla.

Solución:

1. En macOS, conceda el permiso de Grabación de Pantalla a la terminal o aplicación anfitriona de MCP.
2. Reintente la misma llamada de herramienta después de conceder el permiso.

Verificación:

1. Llame a get_runtime_diagnostics.
2. Confirme permission_ok=true.

cursor_unavailable

Causa: Zeuxis no pudo leer la posición global del cursor.

Solución:

1. Conceda el permiso de Accesibilidad si su plataforma lo requiere.
2. Use capture_screen, capture_active_window o capture_rect cuando la posición del cursor no esté disponible.

window_not_found

Causa: La ventana enfocada, la ventana del cursor o la ventana de instantánea solicitada ya no está disponible.

Solución:

1. Llame a list_windows nuevamente.
2. Reintente con un snapshot_id y window_id frescos, o recurra a capture_screen.

invalid_region

Causa: El rectángulo solicitado está fuera de los límites compatibles o excede los límites de tamaño.

Solución:

1. Verifique los límites del monitor con list_monitors.
2. Reduzca width y height.
3. Mantenga el área de captura en o por debajo de 40000000 píxeles.

no_capture_yet

Causa: get_latest_capture se llamó antes de que esta sesión del servidor capturara un artefacto.

Solución:

1. Llame primero a una herramienta de capture_*.
2. Reintente get_latest_capture.

storage_failed

Causa: Falló la escritura del artefacto, la limpieza de retención, el IPC del trabajador o el manejo de tiempo de espera.

Solución:

1. Verifique que ZEUXIS_ARTIFACT_DIR sea escribible, si está establecido.
2. Aumente --blocking-task-timeout-ms para capturas lentas.
3. Reintente la captura. Los procesos de trabajador con tiempo de espera agotado se terminan y se recolectan antes de que Zeuxis devuelva.

Privacidad y seguridad

Zeuxis está diseñado para observación local:

• Sirve MCP a través de stdio local.
• Devuelve enlaces de artefactos locales file://.
• No sube capturas de pantalla a servicios remotos.
• No realiza OCR, detección de elementos de interfaz, automatización de entrada, ejecución de shell ni control de ventanas.
• Valida los parámetros de las herramientas antes de la captura.
• El trabajo de captura se ejecuta en un subproceso trabajador con tiempo de espera y terminación impuestos por el proceso padre.
• clear_session_artifacts elimina únicamente los artefactos gestionados por Zeuxis de la sesión actual.

Los archivos de artefactos gestionados usan el prefijo zeuxis- y el sufijo .png, .jpg o .webp. La poda de retención se realiza con el mejor esfuerzo y nunca elimina el artefacto que se está devolviendo actualmente.

Desarrollo

Puntos de entrada útiles del código fuente:

Archivo	Propósito
src/main.rs	Análisis de CLI, inicio del servidor stdio, modo trabajador oculto, configuración de trazado.
src/runtime_config.rs	Valores predeterminados de CLI/entorno, rangos y configuraciones de ejecución.
src/mcp/tools.rs	Esquemas de herramientas MCP, validación, ejecución de captura, configuraciones de salida.
src/mcp/result.rs	Cargas útiles de resultados MCP y enlaces de recursos.
src/mcp/errors.rs	Códigos de error estables y capacidad de reintento.
src/capture/backend.rs	Rasgo del backend de captura y metadatos de monitor/ventana.
src/worker/contract.rs	Contrato JSON entre proceso padre y trabajador.
skills/capturing-ui-with-zeuxis/SKILL.md	Guía de habilidades de Codex para usar Zeuxis de forma proactiva.
specs/	Especificaciones históricas de diseño y requisitos.

Ejecuta comprobaciones locales:

cargo check
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets

En entornos similares a CI de Ubuntu/Linux, instala primero las dependencias de compilación del backend de captura:

sudo apt-get update
sudo apt-get install -y \
  pkg-config \
  libclang-dev \
  libxcb1-dev \
  libxrandr-dev \
  libdbus-1-dev \
  libpipewire-0.3-dev \
  libwayland-dev \
  libegl-dev \
  libdrm-dev \
  libgbm-dev

Este repositorio también incluye un prek.toml para compuertas de confirmación locales ligeras:

prek validate-config
prek run --all-files
prek install

Los hooks configurados ejecutan cargo fmt --all -- --check y cargo clippy --all-targets --all-features -- -D warnings.

Licencia

Zeuxis está licenciado bajo la Licencia MIT.