zeuxis

zeuxis

Zeuxis é um servidor local de captura de tela via MCP que permite que agentes de IA capturem a área de trabalho atual, janelas, regiões do cursor e retângulos exatos por meio de ferramentas MCP.

Ele roda como um único binário local via stdio por padrão. Os resultados da captura permanecem na máquina como artefatos de imagem gerenciados e são retornados ao cliente MCP como links de recursos file:// além de metadados estruturados. Zeuxis não envia capturas de tela, não realiza OCR, não controla a interface do usuário nem expõe ferramentas de controle do sistema.

Plataformas suportadas

Plataforma	Status	Observações
macOS	Classe principal	Zeuxis verifica a permissão de Gravação de Tela antes da captura. Ferramentas baseadas em cursor podem precisar também da permissão de Acessibilidade.
Linux	Melhor esforço	O comportamento depende do ambiente de área de trabalho, compositor, tipo de sessão e suporte do backend.
Outras plataformas	Não suportado na v1	As ferramentas retornam capture_unsupported_on_platform.

Instalação

Use um dos seguintes caminhos de instalação.

Cargo

Requer Rust 1.88 ou mais recente.

cargo install zeuxis
zeuxis --version

Homebrew

brew install bnomei/zeuxis/zeuxis
zeuxis --version

GitHub Releases

Baixe um arquivo pré-compilado em GitHub Releases, extraia-o e coloque zeuxis no seu PATH.

Verifique o binário:

zeuxis --help

A partir do código-fonte

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

Início rápido

Adicione Zeuxis a um cliente MCP como servidor stdio:

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

Se você usa Codex CLI:

codex mcp add zeuxis -- zeuxis
codex mcp list

Se você usa Amp CLI:

amp mcp add zeuxis -- zeuxis
amp mcp list

Após o cliente conectar, chame get_runtime_diagnostics primeiro. Um resultado saudável informa permission_ok=true e monitors_ok=true. Em seguida, chame capture_screen para a primeira captura de tela.

Ferramentas de captura bem-sucedidas retornam:

• um breve resumo em texto,
• um link de recurso file:// para o artefato local,
• campos estruturados como path, uri, output_format, mime_type, artifact_sha256, width, height, capture_mode, captured_at_utc, source_scale_factor e target.

Escolha uma ferramenta de captura

Intenção do usuário	Ferramenta
Ver a tela inteira ou obter contexto inicial	capture_screen
Capturar a janela do aplicativo em foco	capture_active_window
Capturar a janela sob o cursor	capture_cursor_window
Capturar uma janela específica a partir de uma listagem de janelas	list_windows, depois capture_window
Capturar uma dica de ferramenta, menu ou pequena área adjacente ao cursor	capture_cursor_region
Capturar coordenadas globais exatas da área de trabalho	capture_rect
Capturar coordenadas exatas locais do monitor	capture_monitor_region
Reutilizar a última captura desta sessão do servidor	get_latest_capture
Inspecionar ou excluir artefatos do Zeuxis desta sessão	list_session_artifacts, clear_session_artifacts

Para captura determinística de janelas, chame list_windows e passe tanto snapshot_id quanto window_id da mesma resposta para capture_window. Os IDs de janela são limitados ao instantâneo, não são duráveis entre listagens.

Ferramentas MCP

Os esquemas das ferramentas estão definidos em src/mcp/tools.rs. Os payloads de resultado são construídos em src/mcp/result.rs, e erros estáveis estão definidos em src/mcp/errors.rs.

Ferramenta	Parâmetros	Descrição
list_monitors	nenhum	Lista monitores com IDs, nomes, limites lógicos e sinalizadores de primário/embutido.
list_windows	focused_only?, include_system_windows?, app_contains?, title_contains?	Lista janelas e registra um instantâneo para capture_window. Superfícies de UI do sistema são excluídas, a menos que solicitadas.
get_runtime_diagnostics	nenhum	Informa contexto de SO/sessão, status de permissão, descoberta de monitores e disponibilidade do cursor.
get_latest_capture	nenhum	Retorna o artefato mais recente da sessão atual do servidor sem tirar uma nova captura.
list_session_artifacts	nenhum	Lista artefatos criados na sessão atual do servidor e marca o mais recente.
clear_session_artifacts	nenhum	Exclui artefatos criados na sessão atual do servidor e redefine o estado da última captura.
capture_screen	monitor_id? mais parâmetros de captura compartilhados	Captura um monitor inteiro. Omitir monitor_id seleciona o monitor primário.
capture_active_window	parâmetros de captura compartilhados	Captura a janela em foco, não minimizada.
capture_cursor_window	include_system_windows? mais parâmetros de captura compartilhados	Captura a janela não pertencente ao sistema sob o cursor por padrão.
capture_window	snapshot_id, window_id mais parâmetros de captura compartilhados	Captura uma janela selecionada a partir de um instantâneo de list_windows.
capture_cursor_region	size mais parâmetros de captura compartilhados	Captura uma região quadrada centralizada no cursor.
capture_rect	x, y, width, height mais parâmetros de captura compartilhados	Captura um retângulo global da área de trabalho em pontos lógicos.
capture_monitor_region	monitor_id, x, y, width, height mais parâmetros de captura compartilhados	Captura um retângulo local do monitor em pontos lógicos.

Parâmetros de captura compartilhados:

Parâmetro	Tipo	Padrão	Observações
delay_ms	inteiro	não definido	Atraso opcional antes da captura em milissegundos. Intervalo: 0..=30000. Não combine com delay_seconds.
delay_seconds	número	não definido	Atraso opcional antes da captura em segundos. Intervalo: 0..=30. Não combine com delay_ms.
play_sound	booleano	false	Reproduz feedback de captura concluída após uma captura bem-sucedida.
output	string ou objeto	"analysis"	Controla o formato do artefato, redução de escala e qualidade JPEG.

Exemplos:

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

{ "output": "compact" }

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

Opções de saída

Modos de saída predefinidos:

Predefinição	Formato	Dimensão máxima	Qualidade JPEG	Use quando
analysis	PNG	2560	n/a	Análise padrão de LLM com redução de escala moderada.
exact	PNG	tamanho original	n/a	Você precisa dos pixels originais e saída sem perdas.
compact	JPEG	1600	85	Você quer artefatos menores para transferência mais rápida.

Modo de saída personalizado:

Campo	Obrigatório	Restrições
mode	sim	Deve ser "custom".
format	sim	"png", "jpeg" ou "webp".
max_dimension	não	Lado de saída mais longo em pixels, 256..=8192.
jpeg_quality	somente para JPEG	40..=95. Rejeitado para PNG e WebP.

Se ZEUXIS_ARTIFACT_HMAC_KEY estiver definido, os resultados da captura também incluem artifact_hmac_sha256.

Coordenadas e limites

As entradas de coordenadas usam pontos lógicos da área de trabalho. As dimensões da imagem capturada usam pixels de origem. Use os campos retornados input_units, source_units e source_scale_factor para raciocinar sobre o dimensionamento HiDPI.

Limites de tempo de execução:

Limite	Valor
delay_ms	0..=30000
delay_seconds	0..=30
Largura ou altura da captura	1..=16384
Área de captura	<= 40000000 pixels
max_dimension de saída personalizado	256..=8192
Qualidade JPEG	40..=95

Os atrasos solicitados são executados antes do trabalho de captura e são aditivos ao tempo limite de captura. Por exemplo, uma solicitação com delay_ms=30000 e o --blocking-task-timeout-ms=15000 padrão pode levar até cerca de 45 segundos antes que o cliente receba um tempo limite ou resultado.

Configuração

A configuração é resolvida como CLI flag > environment variable > default. Zeuxis não lê arquivos de configuração.

A configuração de tempo de execução está em src/runtime_config.rs.

Sinalizador CLI	Variável de ambiente	Padrão	Intervalo	Descrição
--max-concurrent-captures	ZEUXIS_MAX_CONCURRENT_CAPTURES	2	1..=16	Número máximo de trabalhadores de captura simultâneos.
--max-artifacts	ZEUXIS_MAX_ARTIFACTS	64	1..=10000	Número máximo de arquivos de imagem temporários retidos do Zeuxis.
--max-artifact-bytes	ZEUXIS_MAX_ARTIFACT_BYTES	536870912	1024..=10737418240	Número máximo de bytes de artefatos retidos.
--artifact-dir	ZEUXIS_ARTIFACT_DIR	diretório temporário do sistema	caminho	Diretório para artefatos de captura gerenciados.
--blocking-task-timeout-ms	ZEUXIS_BLOCKING_TASK_TIMEOUT_MS	15000	100..=300000	Tempo limite para captura, listagem e trabalho de armazenamento. Os atrasos são executados antes deste tempo limite.
--worker-kill-grace-ms	ZEUXIS_WORKER_KILL_GRACE_MS	250	10..=30000	Período de graça entre o encerramento suave do trabalhador e o encerramento forçado.
--max-worker-stdout-bytes	ZEUXIS_MAX_WORKER_STDOUT_BYTES	65536	1024..=4194304	Máximo de bytes de stdout IPC do trabalhador aceitos pelo processo pai.
--capture-sound-file	ZEUXIS_CAPTURE_SOUND_FILE	padrão da plataforma	caminho	Arquivo de som personalizado opcional para play_sound=true.
n/a	ZEUXIS_ARTIFACT_HMAC_KEY	não definido	string não vazia	Chave HMAC opcional para metadados de integridade de artefatos.
n/a	RUST_LOG	info	filtro de rastreamento	Filtro de registro em tempo de execução. Os registros vão para stderr para manter o stdout do MCP limpo.

Exemplo:

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

Permissões da plataforma

macOS

Zeuxis verifica a permissão de Gravação de Tela antes da captura. Se a permissão estiver ausente, Zeuxis solicita acesso ao macOS e retorna permission_denied para essa mesma chamada de ferramenta. Conceda a permissão de Gravação de Tela ao terminal ou aplicativo host que inicia o Zeuxis e tente novamente a chamada da ferramenta.

Ferramentas dependentes do cursor leem a posição global do cursor e podem exigir também a permissão de Acessibilidade. Se falharem, tente capture_screen ou capture_rect enquanto atualiza as permissões.

Linux

O suporte à captura no Linux depende da sessão gráfica e dos recursos do backend. Se a captura falhar, chame get_runtime_diagnostics e verifique xdg_session_type, display, wayland_display, monitors_ok e cursor_ok.

No Wayland, o comportamento de captura do cursor e de janelas pode ser mais limitado do que a captura de tela cheia. Prefira capture_screen primeiro e depois restrinja a regiões se o compositor permitir.

Solução de problemas

permission_denied

Causa: O SO negou a permissão de captura de tela.

Correção:

1. No macOS, conceda a permissão de Gravação de Tela ao terminal ou aplicativo host do MCP.
2. Tente novamente a mesma chamada de ferramenta após conceder a permissão.

Verificação:

1. Chame get_runtime_diagnostics.
2. Confirme permission_ok=true.

cursor_unavailable

Causa: Zeuxis não conseguiu ler a posição global do cursor.

Correção:

1. Conceda a permissão de Acessibilidade se sua plataforma exigir.
2. Use capture_screen, capture_active_window ou capture_rect quando a posição do cursor não estiver disponível.

window_not_found

Causa: A janela em foco, a janela do cursor ou a janela do instantâneo solicitado não está mais disponível.

Correção:

1. Chame list_windows novamente.
2. Tente novamente com um snapshot_id e window_id novos, ou use capture_screen como alternativa.

invalid_region

Causa: O retângulo solicitado está fora dos limites suportados ou excede os limites de tamanho.

Correção:

1. Verifique os limites do monitor com list_monitors.
2. Reduza width e height.
3. Mantenha a área de captura em ou abaixo de 40000000 pixels.

no_capture_yet

Causa: get_latest_capture foi chamado antes de esta sessão do servidor capturar um artefato.

Correção:

1. Chame uma ferramenta de capture_* primeiro.
2. Tente get_latest_capture novamente.

storage_failed

Causa: Falha na gravação do artefato, limpeza de retenção, IPC do trabalhador ou tratamento de tempo limite.

Correção:

1. Verifique se ZEUXIS_ARTIFACT_DIR é gravável, se definido.
2. Aumente --blocking-task-timeout-ms para capturas lentas.
3. Tente a captura novamente. Processos de trabalhador com tempo limite são encerrados e coletados antes de Zeuxis retornar.

Privacidade e segurança

Zeuxis foi projetado para observação local:

• Ele serve MCP via stdio local.
• Ele retorna links de artefatos locais file://.
• Ele não envia capturas de tela para serviços remotos.
• Ele não realiza OCR, detecção de elementos de interface, automação de entrada, execução de shell ou controle de janelas.
• Ele valida os parâmetros das ferramentas antes da captura.
• O trabalho de captura é executado em um subprocesso worker com timeout e término impostos pelo processo pai.
• clear_session_artifacts exclui apenas artefatos gerenciados pela Zeuxis da sessão atual.

Arquivos de artefato gerenciados usam o prefixo zeuxis- e o sufixo .png, .jpg ou .webp. A poda de retenção é feita com melhor esforço e nunca exclui o artefato que está sendo retornado no momento.

Desenvolvimento

Pontos de entrada úteis no código-fonte:

Arquivo	Finalidade
src/main.rs	Análise de CLI, inicialização do servidor stdio, modo worker oculto, configuração de rastreamento.
src/runtime_config.rs	Padrões de CLI/env, intervalos e configurações de tempo de execução.
src/mcp/tools.rs	Esquemas de ferramentas MCP, validação, execução de captura, configurações de saída.
src/mcp/result.rs	Payloads de resultados MCP e links de recursos.
src/mcp/errors.rs	Códigos de erro estáveis e capacidade de nova tentativa.
src/capture/backend.rs	Trait de backend de captura e metadados de monitor/janela.
src/worker/contract.rs	Contrato JSON entre processo pai e worker.
skills/capturing-ui-with-zeuxis/SKILL.md	Orientação de skill do Codex para uso proativo da Zeuxis.
specs/	Especificações históricas de design e requisitos.

Execute verificações locais:

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

Em ambientes Ubuntu/Linux semelhantes a CI, instale primeiro as dependências de build do 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 repositório também inclui um prek.toml para gates leves de commit local:

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

Os hooks configurados executam cargo fmt --all -- --check e cargo clippy --all-targets --all-features -- -D warnings.

Licença

Zeuxis é licenciado sob a Licença MIT.