Macbeth

Macbeth — Uso de Computador Open-source para macOS

Dê ao agente que você já usa mãos e olhos no seu Mac.

Veja e opere aplicativos Mac através de MCP ou TypeScript, incluindo interfaces nativas e Electron.

Acesso estruturado à interface quando possível. Capturas de tela e OCR quando necessário.
Pense no Playwright para todo o seu Mac.

_{Demonstração simulada da superfície atual de ferramentas MCP do Macbeth: Configurações do Sistema, interação com Electron e captura de tela/OCR.}

Início Rápido · Exemplos · Por que Macbeth? · TypeScript · Segurança · Habilidades

Início Rápido

Dê ao Claude Code acesso ao Macbeth:

claude mcp add macbeth -- npx -y macbeth

Depois peça para ele verificar a conexão:

Usando Macbeth, liste os aplicativos em execução, conecte-se ao Finder, inspecione sua janela frontal e resuma os primeiros controles que você consegue ver. Não execute nenhuma outra ação.

O Macbeth vem com um daemon universal pré-compilado, assinado e notarizado. Nenhuma cadeia de ferramentas Swift ou instalação manual de serviço é necessária. Se a configuração falhar, execute npx macbeth doctor; ele imprime um prompt de diagnóstico autocontido que você pode colar de volta no seu agente.

Qualquer cliente MCP que possa iniciar um servidor stdio pode usar npx -y macbeth. Veja Configuração do MCP para configuração genérica, atualizações e a lista completa de ferramentas.

Deixe seu agente guiar a instalação

Adicione o Macbeth como um servidor MCP usando npx -y macbeth. Execute npx macbeth doctor, me guie na concessão apenas das permissões que eu preciso e verifique a configuração inspecionando o Finder. Não tome nenhuma ação não relacionada.

Em todo o seu Mac

Trabalhe dentro do Unity, Logic Pro e outras ferramentas complexas

"No Logic Pro, defina o tempo do projeto para 128 BPM e inicie a reprodução."

O Macbeth combina controles estruturados, menus, entrada de teclado, capturas de tela, OCR e orientação específica de aplicativos. O Logic Pro tem uma habilidade dedicada. Aplicativos com árvores de acessibilidade mais finas, incluindo partes do Unity, podem combinar controles estruturados com teclado, menu, captura de tela e fallbacks de OCR.

Automatize o próprio macOS

"Abra as Configurações do Sistema, encontre os controles de firewall e relate seu estado atual sem alterar nada."

O Macbeth pode inspecionar controles e valores nomeados, selecionar itens de menu nativos e usar entrada de teclado quando uma ação semântica não estiver disponível.

Use aplicativos mesmo quando eles não têm API

"Abra o HEY, encontre o thread visível mais recente da equipe de design e resuma-o sem enviar ou alterar nada."

O Macbeth pode trabalhar através de interfaces Electron expostas mesmo quando o serviço não fornece a API que seu agente precisa. O HEY funciona através do suporte genérico a Electron do Macbeth; os resultados variam com a árvore de acessibilidade e a versão do aplicativo.

Veja o que a árvore de acessibilidade não captura

"Capture a janela frontal do Notes e extraia todo o texto visível."

Capturas de tela do ScreenCaptureKit e OCR local do Vision fornecem um fallback para conteúdo que o macOS não expõe como dados de acessibilidade úteis.

Crie scripts e testes repetíveis

O mesmo mecanismo está disponível como uma API TypeScript com localizadores preguiçosos, ações com espera automática, esperas explícitas de estado, capturas de tela e conexões de aplicativos.

[!IMPORTANT] O Macbeth pode agir dentro de aplicativos em seu nome. Conecte apenas agentes confiáveis e exija aprovação para ações consequentes.

Por que Macbeth?

• Use seu próprio agente. O Macbeth é uma camada de controle, não um modelo ou runtime de agente.
• Estruturado quando possível. Consulte papéis, rótulos, valores, estado habilitado, hierarquia e identificadores estáveis em vez de depender apenas de coordenadas.
• Visual quando necessário. Recorra à captura de janela e OCR quando os metadados de acessibilidade forem escassos.
• Ciente de aplicativos. Habilidades versionadas preservam fluxos de trabalho, atalhos e modos de falha conhecidos.
• Scriptável. Use os mesmos primitivos interativamente via MCP ou diretamente do TypeScript.

Estruturado antes de pixels

Capacidade	Agente típico baseado em capturas de tela	Macbeth
Encontrar um controle rotulado	Inferência visual	Consulta de acessibilidade quando exposta
Ler papel, valor e estado	Inferido	Atributos estruturados
Aguardar uma mudança de interface	Geralmente observado através de capturas repetidas	Esperas explícitas e ações com espera automática
Lidar com metadados de interface incompletos	Visão/OCR	Acessibilidade primeiro, fallback de captura de tela/OCR
Reutilizar conhecimento de aplicativos	Dependente de prompt	Habilidades empacotadas e versionadas

As informações de acessibilidade podem, por si só, ser incompletas ou enganosas. O Macbeth é uma interface híbrida: ele usa primitivos estruturados mais fortes quando o macOS os expõe e mantém fallbacks visuais e de nível de sistema disponíveis quando não o faz.

Segurança e limitações

• O Macbeth requer macOS 14 ou mais recente e Node.js 20 ou mais recente.
• A permissão de Acessibilidade é necessária para inspeção e interação com a interface. A Gravação de Tela é necessária apenas para capturas de tela e OCR de janelas.
• A qualidade da acessibilidade do aplicativo varia. Telas renderizadas sob medida, jogos e algumas ferramentas criativas podem exigir menus, capturas de tela, OCR, entrada de teclado ou orientação específica do aplicativo.
• Mudanças de interface entre versões de aplicativos podem quebrar fluxos de trabalho especializados.
• O brilho de interação torna a atividade do Macbeth visível, mas não é um sistema de aprovação ou um log de auditoria completo.
• Agentes podem cometer erros. Use revisão humana para ações destrutivas, financeiras, de publicação ou sensíveis à privacidade.

O Macbeth usa um servidor MCP stdio local e um socket de domínio Unix; ele não abre um listener TCP. Capturas de tela solicitadas via MCP são gravadas em um diretório temporário e não são excluídas automaticamente. Leia o modelo de segurança para fluxo de dados, revogação de permissões, riscos de processos locais e práticas operacionais mais seguras.

API TypeScript

npm install macbeth

import { connect } from "macbeth";

const app = await connect("TextEdit");
await app.window("Untitled").textField().fill("Hello from Macbeth");
await app.pressKey("s", ["cmd"]);

Veja Desenvolvendo com Macbeth para localizadores, capturas de tela, comportamento do Electron, ciclo de vida e testes.

Ensine um aplicativo ao Macbeth

Uma habilidade do Macbeth é um arquivo SKILL.md, opcionalmente acompanhado por scripts executáveis, que ensina a um agente fluxos de trabalho confiáveis e armadilhas. Chame load_skill sem argumentos para o guia principal do Macbeth. As habilidades de aplicativos empacotadas cobrem Calendário, Contatos, Logic Pro, Mail, Mapas, Mensagens, Música, Notas, Lembretes, Safari, Configurações do Sistema e aplicativos Electron genéricos.

Você pode adicionar uma habilidade sem alterar o daemon Swift. Comece com o guia de contribuição e inclua um prompt reproduzível, versão testada do aplicativo, resultado esperado e modos de falha honestos.

Documentação

Guia	Conteúdo
Servidor MCP	Instalação, teste de fumaça, ferramentas, habilidades e atualizações
CLI	Cada ferramenta MCP como um subcomando macbeth <tool>
API TypeScript	API do cliente, localizadores, Electron e testes
Arquitetura	Daemon, protocolo, fallbacks e notas de design
Segurança	Limites de confiança, tratamento de dados e revogação de permissões
Solução de problemas	Diagnósticos e falhas comuns de configuração
Contribuição	Fluxo de trabalho de desenvolvimento e habilidades de aplicativos

Requisitos

• macOS 14 (Sonoma) ou posterior
• Node.js 20+
• Swift 6.0+ apenas ao compilar o daemon a partir do código-fonte

Licença

MIT