MCP Test Utils

MCP Test Utils

Servidor MCP para testes automatizados de UI desktop. Um único binário — sem runtime, sem dependências, sem instalação.

Apenas Windows x64. Suporte para macOS e Linux está planejado.

Dá olhos e mãos aos agentes de IA: capturas de tela, gerenciamento de janelas, mouse, teclado, UI Automation, OCR, busca de arquivos.

Por quê

Agentes de IA podem acionar ações em aplicativos, mas não conseguem ver a tela. Este servidor preenche essa lacuna:

Agent triggers action → takes screenshot → sees the result →
switches window → clicks a button → verifies → writes report

Totalmente autônomo, sem necessidade de envolvimento do usuário.

Demonstração

3.25.1 — um formulário do VS Code preenchido, enviado e verificado em alguns minutos. Assista no YouTube →

3.10.1 — configuração, definições e as ferramentas básicas: 10 tarefas em uma única tomada. Assista no YouTube →

MCP Test Utils vs Anthropic Computer Use

O Claude Cowork agora inclui Computer Use integrado — o Claude tira capturas de tela e clica nas interfaces visualmente. Funciona sem configuração. O MCP Test Utils adota uma abordagem diferente: em vez de adivinhar onde clicar a partir de uma captura de tela, ele lê a estrutura real da UI por meio das APIs do Windows.

	MCP Test Utils	Computer Use
Precisão do clique	Exata — API de UI Automation	Estimativa visual a partir da captura de tela
Velocidade e custo de tokens	Rápido, baixo custo — respostas em texto	Mais lento, caro — imagem em cada etapa
Estrutura da UI	Árvore completa: funções, estados, coordenadas	Não disponível
OCR	Coordenadas em nível de palavra, multilíngue	Não disponível (apenas visão do modelo)
Gerenciamento de janelas	Baseado em API, coordenadas relativas à janela	Navegação visual
Busca de arquivos	Mecanismo Ripgrep integrado	Não disponível
Registro de sessão	JSONL + capturas de tela, log ao vivo na bandeja	Não disponível
Cliques verificados	Por id do elemento, recusado se coberto	Estimativa visual
Espera e agrupamento	wait_for, batch com assert	Não disponível
Análise visual	✅ Mesmo modelo Claude, resolução total 1:1	✅ Mesmo modelo Claude
Configuração	Baixar binário, adicionar à configuração	Integrado, um único interruptor
Mobile / Dispatch	—	✅ Tarefas pelo celular
Multiplataforma	Windows (macOS/Linux planejado)	macOS + Windows

O MCP Test Utils é mais rápido, mais preciso e mais barato por ação. O Computer Use é mais fácil de iniciar e funciona em várias plataformas. Eles se complementam.

Plataformas

Plataforma	Status
Windows x64	✅ Suporte completo
macOS arm64	⏳ Planejado
Linux x64	⏳ Planejado

Ferramentas (21)

Visão

Ferramenta	Descrição
take_screenshot	Captura de tela do desktop inteiro com qualidade configurável
take_window_screenshot	Captura de tela de uma janela específica (modo de captura de tela ou de janela)
read_screen_text	OCR da tela inteira (Windows.Media.Ocr)
read_region_text	OCR de uma região da tela com coordenadas precisas de palavras

Gerenciamento de Janelas

Ferramenta	Descrição
list_windows	Lista janelas com id, título, aplicativo, posição, tamanho, minimizada, focada
focus_window	Traz uma janela para a frente, restaura se minimizada

Entrada

Ferramenta	Descrição
mouse_click	Clique (esquerdo / direito / do meio) em um elemento de UI por id, ou em coordenadas relativas à tela / janela
mouse_move	Move o cursor para um ponto ou para um elemento de UI
mouse_drag	Arrasta do ponto A ao ponto B
mouse_scroll	Rola a roda do mouse
keyboard_type	Digita texto (Unicode completo — latino, cirílico, CJK, emoji)
keyboard_press	Pressiona uma tecla (Enter, Tab, F1–F12, setas, etc.)
keyboard_shortcut	Combinações de teclas (Ctrl+S, Alt+F4, Ctrl+Shift+P, etc.)

Acesso Estruturado à UI

Ferramenta	Descrição
list_ui_elements	Árvore de UI Automation — botões, campos, menus com ids, valores, estados e coordenadas exatas; filtra por nome, valor, classe

Espera e Agrupamento

Ferramenta	Descrição
wait_for	Aguarda uma janela, um elemento ou seu estado em vez de dormir
batch	Executa até 20 chamadas de ferramenta em uma única solicitação, com etapas de find e assert

Busca de Arquivos

Ferramenta	Descrição
search_in_files	Busca texto ou regex em arquivos dentro de diretórios permitidos (como Localizar em Arquivos do VS Code)
find_files	Encontra arquivos e diretórios por padrão de nome (glob), como "Ir para Arquivo"

Guia do Agente

Ferramenta	Descrição
get_usage_guide	Guia de fluxo de trabalho compacto para agentes LLM — cliques de precisão, metadados de coordenadas, dicas de qualidade

Registro de Sessão

Ferramenta	Descrição
enable_logging	Inicia a gravação de chamadas de ferramenta em JSONL + capturas de tela (opt-in)
disable_logging	Para a gravação, obtém estatísticas da sessão

Instalação

1. Baixe o binário em Releases.
2. Adicione-o à configuração do seu cliente MCP. O exemplo abaixo é para o Claude Desktop — para outros clientes, consulte a documentação deles.

Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "test-utils": {
      "command": "D:\\path\\to\\mcp-test-utils.exe"
    }
  }
}

3. Reinicie o Claude Desktop.
4. No chat, tente: "Tire uma captura de tela" — o agente retornará uma imagem do seu desktop.

Com Registro e Busca de Arquivos (opcional)

{
  "mcpServers": {
    "test-utils": {
      "command": "D:\\path\\to\\mcp-test-utils.exe",
      "env": {
        "MCP_LOG_DIR": "D:\\path\\to\\logs",
        "MCP_LOG_MAX_MB": "500",
        "MCP_LOG_RETAIN_DAYS": "30",
        "MCP_SEARCH_DIRS": "D:\\Projects\\app1;D:\\Projects\\app2"
      }
    }
  }
}

Predefinições de Qualidade

As capturas de tela suportam qualidade configurável para equilibrar detalhes e custo de tokens:

Predefinição	Escala	Formato	Caso de Uso
full	100%	JPEG q90	Detalhe máximo
standard	50%	JPEG q70	Equilibrado (padrão)
compact	50%	PNG	Quando PNG é necessário
minimal	25%	Escala de cinza	Menor custo de tokens
custom	10–100%	JPEG / PNG / Escala de cinza	Controle total

Variáveis de Ambiente

Variável	Descrição	Padrão
MCP_LOG_DIR	Caminho para sessões de log. Sem ele, as ferramentas de registro ficam ocultas	—
MCP_LOG_MAX_MB	Limite de tamanho da sessão (aviso ao exceder)	500
MCP_LOG_RETAIN_DAYS	Exclusão automática de sessões mais antigas que N dias. 0 para desativar	30
MCP_SEARCH_DIRS	Diretórios permitidos para search_in_files (; no Windows, : no macOS/Linux). Sem ele, a ferramenta fica oculta	—
MCP_NOTIFY	off oculta o ícone da bandeja e a janela de log de chamadas ao vivo	—

Log na Bandeja

O servidor mostra um ícone na bandeja com um log ao vivo das chamadas de ferramenta — uma aba por sessão, erros em vermelho. MCP_NOTIFY=off o oculta; a posição da janela é mantida em %LOCALAPPDATA%\mcp-test-utils\notify.json.

Como Funciona

O MCP Test Utils é um servidor JSON-RPC 2.0 que se comunica via stdin/stdout. Qualquer cliente compatível com MCP inicia o binário, envia chamadas de ferramenta e recebe respostas estruturadas (texto, imagens base64). Testado com o Claude Desktop.

O servidor usa APIs nativas do Windows diretamente — Win32 GDI para capturas de tela, SendInput para mouse e teclado, API COM de UI Automation para inspeção de elementos, WinRT Windows.Media.Ocr para reconhecimento de texto. A busca de arquivos usa o mecanismo ripgrep (grep-regex, grep-searcher, ignore) — multiplataforma, sem dependências externas. Sem PowerShell, sem ferramentas externas, sem acesso à rede.

Casos de Uso

• QA automatizado — o agente navega pelo aplicativo, clica nos fluxos, tira capturas de tela em cada etapa, escreve um relatório de teste
• Automação de desktop — preencher formulários, copiar dados entre janelas, executar fluxos de trabalho
• Auditoria de acessibilidade — verificar a árvore de UI Automation em busca de rótulos ou funções ausentes
• Regressão visual — comparação de capturas de tela entre versões
• Extração de dados — OCR de texto de aplicativos que não expõem APIs
• Busca de código — encontrar padrões em vários projetos sem sair da sessão do agente

Segurança

• Responde apenas a solicitações do cliente MCP
• Não abre portas de rede
• Não grava nada no disco, exceto registro opt-in e as configurações da janela da bandeja (%LOCALAPPDATA%\mcp-test-utils\notify.json)
• Não envia dados externamente
• As capturas de tela capturam a tela inteira — certifique-se de que nenhuma informação sensível esteja visível
• A busca de arquivos é isolada — apenas diretórios em MCP_SEARCH_DIRS são acessíveis

Apoie-nos

Gratuito e sem restrições. Se você achar útil — jeenyjai.github.io

Licença

Copyright 2026 JeenyJAI. Todos os direitos reservados.

---

🚀 Criado com Claude