GitHub - icefort-ai/circuit-mcp: Computer use-like MCP for webapps and electron apps, to enable AI agents to test their changes

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

npx @icefort/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)

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

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

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

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

Published Packages:
├── @icefort/circuit-core@latest      # Core MCP infrastructure
├── @icefort/circuit-web@latest       # Web automation server (29 tools)
└── @icefort/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

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

# Install dependencies
pnpm install

# Build all packages
pnpm -r build

# Watch mode development
pnpm -r dev

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

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

# Run all tests
pnpm -r test

# Clean all builds
pnpm -r clean