Mãozinha

Plugin local que permite a um agente operar o computador. A versão 0.1.0 usa a acessibilidade nativa do macOS para ler interfaces e agir em elementos, além de mouse, teclado e capturas de tela.

Requisitos e instalação

macOS 14 ou superior, Apple Silicon ou Intel.
Node.js 20 ou superior e npm no PATH do aplicativo que inicia o MCP.
Command Line Tools do Xcode com compilador Swift (xcode-select --install se não estiver instalado).
Internet na primeira preparação para instalar as dependências fixadas no lockfile.

No Bithub, instale Mãozinha neste marketplace e habilite para o agente que deve controlar o computador. Os manifests de compatibilidade também estão incluídos para Claude Code e Cursor; a execução completa nesses dois hosts ainda precisa ser validada.

É recomendado preparar o runtime antes da primeira conexão, para evitar o timeout de inicialização do host:

cd plugins/maozinha
node scripts/setup.mjs

A inicialização prepara automaticamente o que estiver faltando. O SDK MCP fica em ~/Library/Application Support/Maozinha/runtime/; o executável Swift fica em ~/Library/Application Support/Maozinha/bin/maozinha-macos. Nenhuma dependência ou binário é gravado no diretório instalado do plugin. Mensagens de preparação e diagnóstico vão ao stderr; stdout contém apenas MCP.

Para configurar manualmente um cliente MCP, use node como comando e o caminho absoluto de scripts/start.mjs como único argumento. mcp.json usa ${PLUGIN_ROOT} para clientes portáveis; .mcp.json usa ${CLAUDE_PLUGIN_ROOT} para os hosts de compatibilidade. O manifesto Bithub aponta explicitamente para .mcp.json.

Permissões do macOS

Na primeira utilização, peça ao agente para consultar desktop_permissions e solicitar a permissão que faltar:

Acessibilidade permite ler elementos e enviar ações, mouse e teclado.
Gravação de Tela é necessária apenas para screenshots.

O macOS exige concessão manual em Ajustes do Sistema → Privacidade e Segurança. Autorize o processo indicado pelo sistema, que pode ser o host ou o executável retornado por desktop_permissions. Se necessário, adicione o executável pelo botão + e Cmd+Shift+G. Reinicie a conexão MCP depois de conceder acesso. Uma recompilação ou atualização pode exigir nova autorização.

A autorização do sistema é do processo, não de uma conversa específica. Habilite o plugin apenas para agentes aos quais deseja fornecer controle. Desative o plugin e encerre a conexão para retirar as ferramentas; revogue a autorização nos Ajustes para retirar o acesso do processo no macOS. O servidor usa somente stdio local, sem porta HTTP, credenciais ou serviço remoto.

Ferramentas

Ferramenta	Função
`desktop_permissions`	Consulta permissões, monitores e caminho do executável
`desktop_request_permission`	Solicita Acessibilidade ou Gravação de Tela
`desktop_apps`	Lista aplicativos e identifica o primeiro plano
`desktop_open_app`	Abre ou ativa aplicativo pelo bundle ID
`desktop_snapshot`	Lê a árvore de acessibilidade, refs, ações e bounds
`desktop_element_action`	Pressiona, foca, substitui valor ou abre menu de um elemento
`desktop_click`	Clique simples, duplo ou direito
`desktop_type_text`	Digitação Unicode sem alterar o clipboard
`desktop_key`	Teclas e atalhos com Command, Shift, Option e Control
`desktop_scroll`	Rolagem vertical ou horizontal em um ponto
`desktop_drag`	Arraste com botão esquerdo
`desktop_screenshot`	PNG de um monitor com escala e origem global

Os refs são locais à conexão e expiram após uma ação, outro snapshot ou 60 segundos. Mouse e teclado exigem expectedPid do app em primeiro plano. Essa conferência reduz erros de foco, mas não bloqueia outros agentes ou a interação manual: evite operadores simultâneos no mesmo desktop. Os atalhos usam códigos físicos do teclado US; texto livre usa Unicode.

Coordenadas de acessibilidade e mouse usam pontos globais, origem superior esquerda da tela principal. Screenshots retornam os fatores necessários para converter pixels em pontos, incluindo monitores Retina e monitores com origem negativa.

Snapshots têm limites de profundidade, quantidade e tempo, indicados por truncated. Valores de campos seguros são omitidos. Apps podem expor apenas parte da interface; campos e telas privadas podem aparecer em capturas. O plugin não mantém histórico de capturas nem grava texto digitado em logs.

Desenvolvimento e novos sistemas

server/server.mjs          ferramentas MCP e validação
server/adapters/macos.mjs  transporte para o processo nativo
server/native/MacOS.swift  AXUIElement, CGEvent e ScreenCaptureKit
scripts/runtime.mjs       preparação, cache e compilação
scripts/start.mjs         composição do servidor e adaptador
tests/                    protocolo, validação e integração nativa

Um novo sistema deve implementar call(operation, parameters) e close() com o mesmo formato de resposta, e ser selecionado em scripts/start.mjs. Também deve ter preparação específica em scripts/runtime.mjs. Windows e Linux ainda não têm implementação; a preparação encerra com mensagem explícita nesses sistemas.

cd plugins/maozinha
node --test tests/*.test.mjs

Os testes fazem handshake MCP real, descoberta e chamadas de leitura. Casos que dependem de permissão verificam a recusa ou executam somente quando o acesso já está concedido. O ensaio de interação usa um aplicativo descartável próprio:

node tests/exercise.mjs

O ensaio abre uma janela de teste, opera somente essa janela e restaura o aplicativo anterior. Requer Acessibilidade já autorizada; não altera documentos existentes nem configura permissões. Para incluir screenshot no ensaio, execute node tests/exercise.mjs --screenshot com Gravação de Tela já autorizada.

Referências: SDK MCP, Acessibilidade, eventos do teclado e mouse e capturas de tela.