Snowfort Circuit MCP

Automatiza navegadores web y aplicaciones de escritorio Electron para agentes de codificación de IA.

Documentación

Circuit MCP - Uso de computadora para aplicaciones web y aplicaciones Electron

Circuit MCP es un conjunto completo de servidores del Protocolo de Contexto de Modelo (MCP) que permite a los agentes de codificación de IA automatizar tanto navegadores web como aplicaciones de escritorio Electron con una precisión y flexibilidad incomparables.

🚀 Inicio Rápido para Agentes de IA

Configuración de MCP

Agrega a tu archivo de configuración de MCP del agente de IA:

Solo Automatización Web

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

Solo Automatización de Escritorio

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

Configuración Completa de Doble Motor (Recomendado)

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

Primeros Comandos

Una vez configurado, tu agente de IA puede comenzar a automatizar inmediatamente:

// 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']"})

✨ Características

🌐 Automatización Web (29 Herramientas)

Soporte Multi-Navegador: Chromium, Firefox, WebKit
🎯 Instantáneas Optimizadas para IA: Auto-instantáneas con referencias de elementos después de cada acción
📸 Compresión Inteligente de Capturas: Compresión JPEG para flujos de trabajo de IA más rápidos (configurable)
Conjunto Completo de Interacciones: Clic, escribir, pasar el cursor, arrastrar, desplazarse con auto-contexto
🖱️ Gestión de Múltiples Pestañas: Crear, cambiar, listar y cerrar pestañas del navegador
📊 Monitoreo de Red y Consola: Seguimiento de solicitudes en tiempo real y captura de consola
Entrada Avanzada: Cargas de archivos, selección de listas desplegables, atajos de teclado
Extracción de Contenido: Contenido HTML, contenido de texto, árboles de accesibilidad con referencias de elementos
Captura Visual: Capturas comprimidas, generación de PDF
Navegación: Control de historial, recarga de página, navegación por URL
Manejo de Diálogos: Gestión automática de alertas/confirmaciones/aviso
Control del Navegador: Redimensionamiento de la ventana gráfica, gestión de ventanas
🧪 Generación de Pruebas: Genera automáticamente código de prueba Playwright a partir de acciones registradas
Ejecución de JavaScript: Ejecuta scripts personalizados en el contexto de la página
Espera Inteligente: Aparición de elementos, inactividad de red, estados de carga de página

🖥️ Automatización de Escritorio (32 Herramientas)

🎯 Control de Escritorio Optimizado para IA: Inicia y controla aplicaciones Electron con auto-instantáneas
📸 Compresión Inteligente de Capturas: Compresión JPEG para flujos de trabajo de IA más rápidos (configurable)
🔧 Soporte de Modo Desarrollo: Inicia aplicaciones durante el desarrollo con detección automática
Soporte Universal de Electron: Cualquier aplicación Electron (empaquetada o en desarrollo)
Gestión de Múltiples Ventanas: Controla múltiples ventanas de aplicaciones simultáneamente
Comunicación IPC: Comunicación directa entre procesos con aplicaciones
Sistema de Archivos Nativo: Lee/escribe archivos directamente
Segmentación Mejorada: Clics basados en roles, selección de enésimo elemento, segmentación basada en texto
Accesibilidad Primero: Navegación integrada por árbol de accesibilidad con referencias de elementos
Gestión de Estado: Espera y monitoreo avanzado del estado de la página
🐛 Monitoreo de Consola y Red: Captura registros de aplicaciones y solicitudes de red para depuración
Todas las Herramientas Web: Cada herramienta de automatización web funciona en contexto de escritorio

🔧 Beneficios de Arquitectura

🤖 Diseño Primero para IA: Auto-instantáneas, referencias de elementos e imágenes comprimidas para flujos de trabajo de IA óptimos
Selección de Aplicación en Tiempo de Ejecución: Especifica aplicaciones Electron en el momento de la llamada a la herramienta, no al inicio
Gestión de Sesiones: Múltiples sesiones de automatización concurrentes con aislamiento completo
Seguridad de Tipos: Soporte completo de TypeScript con definiciones de tipos exhaustivas
Manejo de Errores: Reporte de errores robusto y recuperación
Rendimiento Optimizado: Uso eficiente de recursos y ejecución rápida

📚 Referencia Completa de Herramientas

🌐 Herramientas Web

Herramienta	Descripción	Parámetros Clave
`browser_launch`	Inicia el navegador con optimizaciones de IA	`browser`, `headed`, `viewport`, `compressScreenshots`, `screenshotQuality`
`browser_navigate`	Navega a una URL (incluye auto-instantánea)	`sessionId`, `url`
`browser_resize`	Redimensiona la ventana gráfica del navegador	`sessionId`, `width`, `height`
`browser_handle_dialog`	Establece la auto-respuesta de diálogos	`sessionId`, `action`, `promptText`
`browser_tab_new`	Crea una nueva pestaña del navegador	`sessionId`
`browser_tab_list`	Lista todas las pestañas abiertas	`sessionId`
`browser_tab_select`	Cambia a una pestaña específica	`sessionId`, `tabId`
`browser_tab_close`	Cierra una pestaña específica	`sessionId`, `tabId`
`browser_network_requests`	Obtiene el historial de solicitudes de red	`sessionId`
`browser_console_messages`	Obtiene el historial de mensajes de consola	`sessionId`
`browser_generate_playwright_test`	Genera código de prueba a partir de acciones	`sessionId`
`click`	Clic en elemento (incluye auto-instantánea)	`sessionId`, `selector`, `windowId`
`type`	Escribe texto (incluye auto-instantánea)	`sessionId`, `selector`, `text`, `windowId`
`hover`	Pasa el cursor sobre un elemento (incluye auto-instantánea)	`sessionId`, `selector`, `windowId`
`drag`	Arrastra un elemento hasta el objetivo	`sessionId`, `sourceSelector`, `targetSelector`
`key`	Presiona una tecla del teclado (incluye auto-instantánea)	`sessionId`, `key`, `windowId`
`select`	Selecciona una opción de lista desplegable	`sessionId`, `selector`, `value`
`upload`	Sube un archivo a la entrada	`sessionId`, `selector`, `filePath`
`back`	Navega hacia atrás en el historial	`sessionId`
`forward`	Navega hacia adelante en el historial	`sessionId`
`refresh`	Recarga la página actual	`sessionId`
`screenshot`	Toma una captura comprimida	`sessionId`, `path`
`snapshot`	Obtiene el árbol de accesibilidad con referencias de elementos	`sessionId`
`pdf`	Genera un PDF de la página	`sessionId`, `path`
`content`	Obtiene el contenido HTML	`sessionId`
`text_content`	Obtiene el texto visible	`sessionId`
`evaluate`	Ejecuta JavaScript	`sessionId`, `script`
`wait_for_selector`	Espera un elemento	`sessionId`, `selector`, `timeout`
`close`	Cierra la sesión del navegador	`sessionId`

🖥️ Herramientas Electron

Herramienta	Descripción	Parámetros Clave
`app_launch`	Inicia la aplicación Electron con optimizaciones de IA	`app`, `mode`, `projectPath`, `startScript`, `disableDevtools`, `compressScreenshots`, `screenshotQuality`
`get_windows`	Lista ventanas con identificación de tipo	`sessionId`
`ipc_invoke`	Llama al método IPC	`sessionId`, `channel`, `args`
`fs_write_file`	Escribe un archivo en el disco	`sessionId`, `filePath`, `content`
`fs_read_file`	Lee un archivo del disco	`sessionId`, `filePath`
`keyboard_press`	Presiona una tecla con modificadores	`sessionId`, `key`, `modifiers`
`click_by_text`	Clic en elemento por texto	`sessionId`, `text`, `exact`
`click_by_role`	Clic por rol de accesibilidad	`sessionId`, `role`, `name`
`click_nth`	Clic en el enésimo elemento coincidente	`sessionId`, `selector`, `index`
`keyboard_type`	Escribe con retraso	`sessionId`, `text`, `delay`
`add_locator_handler`	Maneja modales/ventanas emergentes	`sessionId`, `selector`, `action`
`wait_for_load_state`	Espera el estado de la página	`sessionId`, `state`
`smart_click`	Clic inteligente con auto-detección (refs/texto/CSS)	`sessionId`, `target`, `strategy`, `windowId`
`browser_console_messages`	Obtiene registros de consola de la aplicación Electron	`sessionId`
`browser_network_requests`	Obtiene solicitudes de red de la aplicación Electron	`sessionId`
+ Herramientas Web Compartidas	Herramientas web principales: `click`, `type`, `screenshot`, `evaluate`, etc.

💡 Ejemplos de Uso

Flujos de Trabajo de Automatización Web

Inicio de Navegador Optimizado 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"

Flujo de Trabajo Multi-Pestaña

// 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

Segmentación de Elementos con Referencias

// 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

Monitoreo de Red y Consola

// 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})

Manejo 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

Automatización de Aplicaciones de Escritorio

Inicio de Escritorio Optimizado 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"

Soporte de Modo Desarrollo

// 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
})

Soporte de Electron Forge (NUEVO en v0.5.7)

Enfoque Recomendado (Más Confiable):

// 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

Característica Experimental de Inicio Automático:

// 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

🚀 Guía de Inicio Rápido para Automatización Electron

Usa esta guía para agentes de IA (CLAUDE.md) o referencia manual

Para Proyectos 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 Proyectos 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 Aplicaciones Empaquetadas:

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

Características Clave:

📸 Cada acción devuelve una instantánea lista para IA con referencias de elementos (e1, e2, etc.)
🎯 Múltiples métodos de clic: por selector, texto, rol o enésimo elemento
🔧 Automatización completa: capturas, evaluar JS, control de teclado/ratón
🧹 Limpieza automática: Las sesiones y servidores de desarrollo se cierran automáticamente
🪟 Gestión inteligente de ventanas: DevTools filtrados automáticamente, detección de ventana principal

Consejos Profesionales:

Usa compressScreenshots: true (predeterminado) para un procesamiento de IA más rápido
El MCP inicia una nueva instancia - no puede adjuntarse a aplicaciones en ejecución
Para Electron Forge: Siempre inicia primero el servidor de desarrollo, luego inicia con MCP
Las ventanas de DevTools se filtran automáticamente - siempre obtendrás la ventana principal de la aplicación
Usa disableDevtools: true para evitar que DevTools se abra automáticamente
Usa get_windows para ver todas las ventanas con identificación de tipo (principal/devtools/otras)

¡Eso es todo! Todas las demás herramientas funcionan igual que la versión web. ¡Feliz automatización! 🎉

📖 Instrucciones Legadas para Agentes de IA (Claude, CLAUDE.md, etc.)

⚠️ Importante: El MCP inicia su propia instancia de Electron - no puedes conectarte a una aplicación ya en ejecución.

Para proyectos de desarrollo Electron:

Detén cualquier proceso npm run start existente
Deja que el MCP inicie tu aplicación en su lugar:

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

Cómo Funciona:

🚀 Inicia una nueva instancia de tu aplicación Electron usando Playwright
🎯 Control de automatización completo a través del Protocolo de DevTools de Chrome
📸 No puede adjuntarse a procesos existentes en ejecución

Beneficios Clave para Flujos de Trabajo de IA:

🤖 Auto-instantáneas después de cada acción con referencias de elementos (ref="e1", ref="e2")
📸 Capturas comprimidas por defecto para un procesamiento más rápido
🎯 Segmentación directa de elementos usando las refs proporcionadas en las instantáneas
🔄 No se necesitan llamadas manuales de instantáneas - el contexto se proporciona automáticamente

Automatización de Editores 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"]})

Gestión Multi-Ventana

// 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"})

Monitoreo de Consola y Red

// 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)

Configuración Avanzada

Modo Desarrollo Web con Calidad Completa

// 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 Desarrollo 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 Producción con Rendimiento Optimizado

// 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
})

🔧 Solución de Problemas

Problemas Comunes de Desarrollo Electron

Error "No Conectado"

Problema: Intentar usar comandos MCP sin una sesión válida

Solución:

// ❌ 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})

No se Puede Conectar a una Aplicación en Ejecución

Problema: Intentar conectarse a un proceso npm run start existente

Solución: Detén el proceso existente, deja que el MCP inicie tu aplicación en su lugar

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

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

Electron No Encontrado

Problema: El MCP no puede encontrar el ejecutable de Electron

Soluciones:

Instala Electron localmente: npm install electron --save-dev
Especifica una ruta personalizada: {"electronPath": "/custom/path/to/electron"}
Instala globalmente: npm install -g electron

🛠️ Opciones de Configuración

Opciones 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)

Configuraciones Avanzadas de MCP

Configuración de Desarrollo

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

Configuración de Producción

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

🏗️ Arquitectura

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

📦 Paquetes Publicados

Paquete	Versión	Descripción
`@snowfort/circuit-core`		Infraestructura central de MCP
`@snowfort/circuit-web`		CLI de automatización web (29 herramientas)
`@snowfort/circuit-electron`		CLI de automatización de escritorio (más de 25 herramientas)

🔧 Desarrollo

Configuración de Desarrollo 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

Ejecución de Servidores de Desarrollo Locales

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

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

Pruebas

# Run all tests
pnpm -r test

# Clean all builds
pnpm -r clean

🤝 Contribuciones

¡Agradecemos las contribuciones! Consulta nuestra Guía de Contribución para más detalles.

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/amazing-feature)
Haz commit de tus cambios (git commit -m 'Add some amazing feature')
Sube los cambios a la rama (git push origin feature/amazing-feature)
Abre un Pull Request

📄 Licencia

Este proyecto está licenciado bajo la Apache License 2.0; consulta el archivo LICENSE para más detalles.

Implementación independiente para pruebas de automatización integrales

🙏 Agradecimientos

Playwright por el framework de automatización
MCP SDK por la implementación del protocolo
La comunidad de Model Context Protocol por impulsar la innovación en la integración de herramientas de IA