Snowfort Circuit MCP

Automatize navegadores web e aplicativos desktop Electron para agentes de codificação de IA.

Documentação

Circuit MCP - Uso de computador para aplicações web e apps Electron

O Circuit MCP é um conjunto completo de servidores Model Context Protocol (MCP) que permite que agentes de codificação de IA automatizem navegadores web e aplicações desktop Electron com precisão e flexibilidade incomparáveis.

🚀 Início Rápido para Agentes de IA

Configuração do MCP

Adicione ao arquivo de configuração do MCP do seu agente de IA:

Apenas Automação Web

{
  "mcpServers": {
    "circuit-web": {
      "command": "npx",
      "args": ["@snowfort/circuit-web@latest"]
    }
  }
}

Apenas Automação Desktop

{
  "mcpServers": {
    "circuit-electron": {
      "command": "npx",
      "args": ["@snowfort/circuit-electron@latest"]
    }
  }
}

Configuração Completa com Dois Motores (Recomendado)

{
  "mcpServers": {
    "circuit-web": {
      "command": "npx",
      "args": ["@snowfort/circuit-web@latest"]
    },
    "circuit-electron": {
      "command": "npx",
      "args": ["@snowfort/circuit-electron@latest"]
    }
  }
}

Primeiros Comandos

Uma vez configurado, seu agente de IA pode começar a automatizar imediatamente:

// Launch browser with optimized AI settings
browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 50
})
browser_navigate({"sessionId": "...", "url": "https://github.com"})
// Auto-snapshot included in response!

// Launch and control any Electron app
app_launch({"app": "/Applications/Visual Studio Code.app"})
click({"sessionId": "...", "selector": "button[title='New File']"})

✨ Recursos

🌐 Automação Web (29 Ferramentas)

Suporte a Múltiplos Navegadores: Chromium, Firefox, WebKit
🎯 Snapshots Otimizados para IA: Auto-snapshots com referências de elementos após cada ação
📸 Compressão Inteligente de Screenshots: Compressão JPEG para fluxos de IA mais rápidos (configurável)
Conjunto Completo de Interações: Clique, digitação, hover, arrastar, rolar com auto-contexto
🖱️ Gerenciamento de Múltiplas Abas: Criar, alternar, listar e fechar abas do navegador
📊 Monitoramento de Rede e Console: Rastreamento de requisições em tempo real e captura de console
Entrada Avançada: Upload de arquivos, seleção em menus suspensos, atalhos de teclado
Extração de Conteúdo: Conteúdo HTML, conteúdo de texto, árvores de acessibilidade com referências de elementos
Captura Visual: Screenshots comprimidos, geração de PDF
Navegação: Controle de histórico, recarregamento de página, navegação por URL
Tratamento de Diálogos: Gerenciamento automático de alertas/confirmações/prompts
Controle do Navegador: Redimensionamento de viewport, gerenciamento de janelas
🧪 Geração de Testes: Gera automaticamente código de teste Playwright a partir de ações registradas
Execução de JavaScript: Executar scripts personalizados no contexto da página
Espera Inteligente: Aparecimento de elementos, inatividade de rede, estados de carregamento de página

🖥️ Automação Desktop (32 Ferramentas)

🎯 Controle Desktop Otimizado para IA: Inicia e controla apps Electron com auto-snapshots
📸 Compressão Inteligente de Screenshots: Compressão JPEG para fluxos de IA mais rápidos (configurável)
🔧 Suporte ao Modo de Desenvolvimento: Inicia apps durante o desenvolvimento com detecção automática
Suporte Universal a Electron: Qualquer aplicação Electron (empacotada ou em desenvolvimento)
Gerenciamento de Múltiplas Janelas: Controla múltiplas janelas de aplicativos simultaneamente
Comunicação IPC: Comunicação direta entre processos com os aplicativos
Sistema de Arquivos Nativo: Leitura/escrita de arquivos diretamente
Segmentação Aprimorada: Cliques baseados em papéis, seleção do enésimo elemento, segmentação baseada em texto
Acessibilidade em Primeiro Lugar: Navegação integrada pela árvore de acessibilidade com referências de elementos
Gerenciamento de Estado: Espera e monitoramento avançado de estados de página
🐛 Monitoramento de Console e Rede: Captura logs de aplicativos e requisições de rede para depuração
Todas as Ferramentas Web: Toda ferramenta de automação web funciona no contexto desktop

🔧 Benefícios da Arquitetura

🤖 Design Priorizando IA: Auto-snapshots, referências de elementos e imagens comprimidas para fluxos de IA ideais
Seleção de App em Tempo de Execução: Especifique apps Electron no momento da chamada da ferramenta, não na inicialização
Gerenciamento de Sessões: Múltiplas sessões de automação simultâneas com isolamento completo
Segurança de Tipos: Suporte completo a TypeScript com definições de tipos abrangentes
Tratamento de Erros: Relatórios de erro robustos e recuperação
Performance Otimizada: Uso eficiente de recursos e execução rápida

📚 Referência Completa de Ferramentas

🌐 Ferramentas Web

Ferramenta	Descrição	Parâmetros Principais
`browser_launch`	Iniciar navegador com otimizações de IA	`browser`, `headed`, `viewport`, `compressScreenshots`, `screenshotQuality`
`browser_navigate`	Navegar para URL (inclui auto-snapshot)	`sessionId`, `url`
`browser_resize`	Redimensionar viewport do navegador	`sessionId`, `width`, `height`
`browser_handle_dialog`	Definir resposta automática de diálogos	`sessionId`, `action`, `promptText`
`browser_tab_new`	Criar nova aba no navegador	`sessionId`
`browser_tab_list`	Listar todas as abas abertas	`sessionId`
`browser_tab_select`	Alternar para aba específica	`sessionId`, `tabId`
`browser_tab_close`	Fechar aba específica	`sessionId`, `tabId`
`browser_network_requests`	Obter histórico de requisições de rede	`sessionId`
`browser_console_messages`	Obter histórico de mensagens do console	`sessionId`
`browser_generate_playwright_test`	Gerar código de teste a partir de ações	`sessionId`
`click`	Clicar no elemento (inclui auto-snapshot)	`sessionId`, `selector`, `windowId`
`type`	Digitar texto (inclui auto-snapshot)	`sessionId`, `selector`, `text`, `windowId`
`hover`	Passar o mouse sobre o elemento (inclui auto-snapshot)	`sessionId`, `selector`, `windowId`
`drag`	Arrastar elemento até o alvo	`sessionId`, `sourceSelector`, `targetSelector`
`key`	Pressionar tecla do teclado (inclui auto-snapshot)	`sessionId`, `key`, `windowId`
`select`	Selecionar opção em menu suspenso	`sessionId`, `selector`, `value`
`upload`	Enviar arquivo para input	`sessionId`, `selector`, `filePath`
`back`	Voltar no histórico	`sessionId`
`forward`	Avançar no histórico	`sessionId`
`refresh`	Recarregar página atual	`sessionId`
`screenshot`	Tirar screenshot comprimido	`sessionId`, `path`
`snapshot`	Obter árvore de acessibilidade com referências de elementos	`sessionId`
`pdf`	Gerar PDF da página	`sessionId`, `path`
`content`	Obter conteúdo HTML	`sessionId`
`text_content`	Obter texto visível	`sessionId`
`evaluate`	Executar JavaScript	`sessionId`, `script`
`wait_for_selector`	Aguardar elemento	`sessionId`, `selector`, `timeout`
`close`	Fechar sessão do navegador	`sessionId`

🖥️ Ferramentas Electron

Ferramenta	Descrição	Parâmetros Principais
`app_launch`	Iniciar app Electron com otimizações de IA	`app`, `mode`, `projectPath`, `startScript`, `disableDevtools`, `compressScreenshots`, `screenshotQuality`
`get_windows`	Listar janelas com identificação de tipo	`sessionId`
`ipc_invoke`	Chamar método IPC	`sessionId`, `channel`, `args`
`fs_write_file`	Escrever arquivo no disco	`sessionId`, `filePath`, `content`
`fs_read_file`	Ler arquivo do disco	`sessionId`, `filePath`
`keyboard_press`	Pressionar tecla com modificadores	`sessionId`, `key`, `modifiers`
`click_by_text`	Clicar no elemento por texto	`sessionId`, `text`, `exact`
`click_by_role`	Clicar por papel de acessibilidade	`sessionId`, `role`, `name`
`click_nth`	Clicar no enésimo elemento correspondente	`sessionId`, `selector`, `index`
`keyboard_type`	Digitar com atraso	`sessionId`, `text`, `delay`
`add_locator_handler`	Tratar modais/popups	`sessionId`, `selector`, `action`
`wait_for_load_state`	Aguardar estado da página	`sessionId`, `state`
`smart_click`	Clique inteligente com detecção automática (refs/texto/CSS)	`sessionId`, `target`, `strategy`, `windowId`
`browser_console_messages`	Obter logs do console do app Electron	`sessionId`
`browser_network_requests`	Obter requisições de rede do app Electron	`sessionId`
+ Ferramentas Web Compartilhadas	Ferramentas web principais: `click`, `type`, `screenshot`, `evaluate`, etc.

💡 Exemplos de Uso

Fluxos de Trabalho de Automação Web

Inicialização do Navegador Otimizada para IA

// Launch with optimal AI settings
const session = await browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 50,
  "headed": false
})

// Navigation automatically includes page snapshot with element refs
await browser_navigate({
  "sessionId": session.id, 
  "url": "https://github.com"
})
// Response includes auto-snapshot with element references like ref="e1", ref="e2"

Fluxo de Trabalho com Múltiplas Abas

// Create and manage multiple tabs
const session = await browser_launch({})
await browser_navigate({"sessionId": session.id, "url": "https://github.com"})

const newTabId = await browser_tab_new({"sessionId": session.id})
await browser_tab_select({"sessionId": session.id, "tabId": newTabId})
await browser_navigate({"sessionId": session.id, "url": "https://stackoverflow.com"})

const tabs = await browser_tab_list({"sessionId": session.id})
// Shows all tabs with titles, URLs, and active status

Segmentação de Elementos com Referências

// Navigate and get element references
await browser_navigate({"sessionId": session.id, "url": "https://example.com"})
// Auto-snapshot response includes:
// {"role": "button", "name": "Sign In", "ref": "e5"}

// Click using standard selector (auto-snapshot included)
await click({"sessionId": session.id, "selector": "button:has-text('Sign In')"})
// Response includes updated page snapshot showing interaction result

Monitoramento de Rede e Console

// Monitor page activity
await browser_navigate({"sessionId": session.id, "url": "https://api-heavy-site.com"})
const requests = await browser_network_requests({"sessionId": session.id})
const consoleMessages = await browser_console_messages({"sessionId": session.id})

// Generate test code from actions
const testCode = await browser_generate_playwright_test({"sessionId": session.id})

Tratamento de Diálogos

// Set up automatic dialog handling
await browser_handle_dialog({
  "sessionId": session.id,
  "action": "accept",
  "promptText": "Default input"
})
// All subsequent dialogs will be handled automatically

Automação de Aplicações Desktop

Inicialização Desktop Otimizada para IA

// Launch with optimal AI settings for packaged apps
const session = await app_launch({
  "app": "/Applications/Visual Studio Code.app",
  "compressScreenshots": true,
  "screenshotQuality": 50
})
// All interactions automatically include window snapshots with element refs!
await click({"sessionId": session.id, "selector": "[title='New File']"})
// Response includes: "Element clicked successfully" + snapshot with ref="e1", ref="e2"

Suporte ao Modo de Desenvolvimento

// NEW: Launch Electron app during development
const session = await app_launch({
  "app": "/Users/dev/my-electron-project",
  "mode": "development",
  "compressScreenshots": false  // Full quality for debugging
})

// Auto-detect packaged vs development
const session2 = await app_launch({
  "app": "/path/to/app-or-project",
  "mode": "auto"  // Automatically detects launch mode
})

Suporte a Electron Forge (NOVO na v0.5.7)

Abordagem Recomendada (Mais Confiável):

// 1. First, run in a separate terminal:
// npm run start

// 2. Wait for webpack to compile, then launch with MCP:
const session = await app_launch({
  "app": "/path/to/forge-project",
  "mode": "development"
  // Don't use startScript - let manual npm start handle it
})
// This approach ensures proper timing and reliable launches

Recurso Experimental de Inicialização Automática:

// The MCP can attempt to auto-start the dev server (experimental)
const session = await app_launch({
  "app": "/path/to/forge-project",
  "mode": "development",
  "startScript": "start"  // Attempts to run 'npm run start' automatically
})
// Features: 30s timeout, progress updates every 5s, enhanced Forge pattern detection
// Note: If you experience problems, use the manual approach above

🚀 Guia de Início Rápido para Automação Electron

Use este guia para agentes de IA (CLAUDE.md) ou referência manual

Para Projetos Electron Forge:

# Step 1: In terminal, start your dev server first
npm run start

# Step 2: Once webpack compiles, use the MCP to launch
await app_launch({
  "app": "/path/to/your/project",
  "mode": "development"
})

Para Projetos Electron Regulares:

// Just launch directly - no prep needed!
await app_launch({
  "app": "/path/to/project",
  "mode": "development",
  "disableDevtools": true  // Optional: prevent DevTools auto-opening
})

Para Apps Empacotados:

// Launch .app, .exe, or AppImage files
await app_launch({
  "app": "/Applications/YourApp.app"
})

Recursos Principais:

📸 Cada ação retorna um snapshot pronto para IA com referências de elementos (e1, e2, etc.)
🎯 Múltiplos métodos de clique: por seletor, texto, papel ou enésimo elemento
🔧 Automação completa: screenshots, avaliação de JS, controle de teclado/mouse
🧹 Limpeza automática: Sessões e servidores de desenvolvimento fecham automaticamente
🪟 Gerenciamento inteligente de janelas: DevTools filtrados automaticamente, detecção da janela principal

Dicas Profissionais:

Use compressScreenshots: true (padrão) para processamento de IA mais rápido
O MCP inicia uma nova instância - ele não pode se anexar a apps em execução
Para Electron Forge: Sempre inicie o servidor de desenvolvimento primeiro, depois inicie com o MCP
As janelas DevTools são filtradas automaticamente - você sempre receberá a janela principal do app
Use disableDevtools: true para impedir que o DevTools abra automaticamente
Use get_windows para ver todas as janelas com identificação de tipo (principal/devtools/outras)

É isso! Todas as outras ferramentas funcionam como a versão web. Boa automação! 🎉

📖 Instruções Legadas para Agentes de IA (Claude, CLAUDE.md, etc.)

⚠️ Importante: O MCP inicia sua própria instância do Electron - você não pode se conectar a um app já em execução.

Para projetos de desenvolvimento Electron:

Pare qualquer processo npm run start existente
Deixe o MCP iniciar seu app:

const session = await app_launch({
  "app": "/path/to/your/electron/project",
  "mode": "development"
})
// Returns sessionId automatically - use this for all subsequent commands

Como Funciona:

🚀 Inicia nova instância do seu app Electron usando Playwright
🎯 Controle total de automação via Chrome DevTools Protocol
📸 Não pode se anexar a processos existentes em execução

Principais Benefícios para Fluxos de IA:

🤖 Auto-snapshots após cada ação com referências de elementos (ref="e1", ref="e2")
📸 Screenshots comprimidos por padrão para processamento mais rápido
🎯 Segmentação direta de elementos usando as refs fornecidas nos snapshots
🔄 Nenhuma chamada manual de snapshot necessária - o contexto é fornecido automaticamente

Automação de Editor de Código

// Traditional packaged app automation
const session = await app_launch({"app": "/Applications/Visual Studio Code.app"})
await click({"sessionId": session.id, "selector": "[title='New File']"})
await keyboard_type({"sessionId": session.id, "text": "console.log('Hello World');", "delay": 50})
await keyboard_press({"sessionId": session.id, "key": "s", "modifiers": ["ControlOrMeta"]})

Gerenciamento de Múltiplas Janelas

// Work with multiple windows
const session = await app_launch({"app": "/Applications/Slack.app"})
const windows = await get_windows({"sessionId": session.id})
await click({"sessionId": session.id, "selector": ".channel-name", "windowId": "main"})
await type({"sessionId": session.id, "selector": "[data-qa='message-input']", "text": "Hello team!", "windowId": "main"})

Monitoramento de Console e Rede

// Launch Electron app and monitor activity
const session = await app_launch({"app": "/Applications/MyElectronApp.app"})

// Perform some actions that generate logs/network activity
await click({"sessionId": session.id, "selector": "#load-data-button"})
await wait_for_load_state({"sessionId": session.id, "state": "networkidle"})

// Get console logs for debugging
const consoleLogs = await browser_console_messages({"sessionId": session.id})
console.log("App console output:", consoleLogs)

// Get network requests to see API calls
const networkRequests = await browser_network_requests({"sessionId": session.id})
console.log("Network activity:", networkRequests)

Configuração Avançada

Modo de Desenvolvimento Web com Qualidade Total

// Launch browser with uncompressed screenshots for debugging
const session = await browser_launch({
  "compressScreenshots": false,  // Full PNG quality
  "headed": true,                // Visible browser
  "viewport": {"width": 1920, "height": 1080}
})

Modo de Desenvolvimento Electron

// Launch Electron app during development with full quality
const session = await app_launch({
  "app": "/Users/dev/my-electron-project",
  "mode": "development",
  "compressScreenshots": false  // Full PNG quality for debugging
})

Modo de Produção com Performance Otimizada

// Web: Launch with maximum compression for speed
const webSession = await browser_launch({
  "compressScreenshots": true,
  "screenshotQuality": 30,      // Maximum compression
  "headed": false               // Headless for performance
})

// Electron: Launch packaged app with compression
const electronSession = await app_launch({
  "app": "/Applications/MyApp.app",
  "compressScreenshots": true,
  "screenshotQuality": 30       // Maximum compression
})

🔧 Solução de Problemas

Problemas Comuns no Desenvolvimento Electron

Erro "Not connected" (Não conectado)

Problema: Tentar usar comandos MCP sem uma sessão válida

Solução:

// ❌ Wrong - no session exists
get_windows({"sessionId": "test"})

// ✅ Correct - launch first, then use returned sessionId
const session = await app_launch({"app": "/path/to/project", "mode": "development"})
get_windows({"sessionId": session.id})

Não é Possível Conectar a um App em Execução

Problema: Tentar conectar a um processo npm run start existente

Solução: Pare o processo existente, deixe o MCP iniciar seu app

# Stop existing process
kill $(ps aux | grep 'Electron .' | awk '{print $2}')

# Let MCP launch instead
app_launch({"app": "/your/project", "mode": "development"})

Electron Não Encontrado

Problema: O MCP não consegue encontrar o executável do Electron

Soluções:

Instale o Electron localmente: npm install electron --save-dev
Especifique um caminho personalizado: {"electronPath": "/custom/path/to/electron"}
Instale globalmente: npm install -g electron

🛠️ Opções de Configuração

Opções de CLI

Servidor Web (`@snowfort/circuit-web`)

npx @snowfort/circuit-web@latest [options]

Options:
  --browser <type>    Browser engine: chromium, firefox, webkit (default: chromium)
  --headed           Run in headed mode (default: headless)
  --name <name>      Server name for MCP handshake (default: circuit-web)

Servidor Electron (`@snowfort/circuit-electron`)

npx @snowfort/circuit-electron@latest [options]

Options:
  --name <name>      Server name for MCP handshake (default: circuit-electron)

Configurações MCP Avançadas

Configuração de Desenvolvimento

{
  "mcpServers": {
    "circuit-web": {
      "command": "npx",
      "args": ["@snowfort/circuit-web@latest", "--headed", "--browser", "chromium"]
    },
    "circuit-electron": {
      "command": "npx",
      "args": ["@snowfort/circuit-electron@latest"]
    }
  }
}

Configuração de Produção

{
  "mcpServers": {
    "circuit-web": {
      "command": "npx",
      "args": ["@snowfort/circuit-web@latest"]
    },
    "circuit-electron": {
      "command": "npx",
      "args": ["@snowfort/circuit-electron@latest"]
    }
  }
}

🏗️ Arquitetura

Published Packages:
├── @snowfort/circuit-core@latest      # Core MCP infrastructure
├── @snowfort/circuit-web@latest       # Web automation server (29 tools)
└── @snowfort/circuit-electron@latest  # Desktop automation server (32 tools)

Local Development:
packages/
├── core/          # Shared MCP infrastructure & Driver interface
├── web/           # Web automation CLI with AI optimizations
└── electron/      # Desktop automation CLI

📦 Pacotes Publicados

Pacote	Versão	Descrição
`@snowfort/circuit-core`		Infraestrutura principal do MCP
`@snowfort/circuit-web`		CLI de automação web (29 ferramentas)
`@snowfort/circuit-electron`		CLI de automação de desktop (25+ ferramentas)

🔧 Desenvolvimento

Configuração do Ambiente de Desenvolvimento Local

# Clone the repository
git clone https://github.com/clharman/circuit-mcp.git
cd circuit-mcp

# Install dependencies
pnpm install

# Build all packages
pnpm -r build

# Watch mode development
pnpm -r dev

Executando Servidores de Desenvolvimento Local

# Web automation server
./packages/web/dist/esm/cli.js --headed

# Desktop automation server  
./packages/electron/dist/esm/cli.js

Testes

# Run all tests
pnpm -r test

# Clean all builds
pnpm -r clean

🤝 Contribuição

Aceitamos contribuições! Consulte nosso Guia de Contribuição para obter detalhes.

Faça um fork do repositório
Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

📄 Licença

Este projeto é licenciado sob a Apache License 2.0 — consulte o arquivo LICENSE para obter detalhes.

Implementação independente para testes abrangentes de automação

🙏 Agradecimentos

Playwright pelo framework de automação
MCP SDK pela implementação do protocolo
À comunidade Model Context Protocol por impulsionar a inovação na integração com ferramentas de IA