### Quick Start: Electron Forge Projects

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

A guide for Electron Forge projects, outlining the steps to first start the development server manually and then launch the application using Circuit MCP.

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

--------------------------------

### Quick Start: Packaged Desktop Apps

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Guide for launching packaged desktop applications (e.g., .app, .exe, AppImage) using Circuit MCP.

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

--------------------------------

### Local Development Setup Commands

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Bash commands for setting up the local development environment for Circuit MCP, including cloning the repository, installing dependencies, building, and running in watch mode.

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

# Install dependencies
pnpm install

# Build all packages
pnpm -r build

# Watch mode development
pnpm -r dev
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/specification.md

Provides examples of how to use the Snowfort Circuit MCP command-line interface for both web and Electron automation. It shows the necessary flags for launching servers with specific configurations.

```bash
# Web (Chromium)
circuit-web --port 5110 --headed

# Electron
electron‑forge make  # builds ./dist/MyApp
electron‑circuit --app ./dist/MyApp --port 5111
```

--------------------------------

### Quick Start: Regular Electron Projects

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Instructions for launching regular Electron projects directly with Circuit MCP in development mode, with an option to disable automatic DevTools opening.

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

--------------------------------

### Build and Test Local MCP

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/CLAUDE.md

Steps to build the MCP packages and run the local test script to validate server initialization and responses. This is crucial before publishing to npm.

```bash
npm run build
```

```bash
node test-local-mcp.js
```

--------------------------------

### AI-Optimized Browser Launch Example

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Demonstrates launching a browser with specific AI optimizations like screenshot compression and quality settings, followed by navigation to a URL which automatically captures a snapshot with element references.

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

--------------------------------

### Multi-Tab Browser Workflow Example

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Illustrates managing multiple browser tabs within a single session, including creating new tabs, switching between them, navigating, and listing all open tabs.

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

--------------------------------

### Electron Forge Support - Recommended Approach

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Provides the recommended method for launching Electron Forge projects by manually starting the development server first, then launching the application with Circuit MCP in development mode.

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

--------------------------------

### Electron Forge Support - Experimental Auto-Start

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Details an experimental feature in Circuit MCP that attempts to automatically start the development server for Electron Forge projects using the `startScript` option.

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

--------------------------------

### Troubleshooting: Electron Not Found Solutions

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Offers solutions for when the MCP cannot locate the Electron executable. This includes installing Electron locally or globally, or specifying a custom path to the executable.

```bash
1. Install Electron locally: `npm install electron --save-dev`
2. Specify custom path: `{"electronPath": "/custom/path/to/electron"}`
3. Install globally: `npm install -g electron`
```

--------------------------------

### AI Agent Commands for Automation

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Examples of commands an AI agent can use with Snowfort Circuit MCP to automate browser and Electron applications. Includes launching browsers with specific settings and interacting with application elements.

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

--------------------------------

### Configure Electron Window Timeout

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/CLAUDE.md

Adjusts the timeout for Electron app window detection. Use the `windowTimeout` option in `app_launch` to increase the default 30-second limit for apps that take longer to create windows.

```javascript
app_launch({
  windowTimeout: 120000 // 2-minute timeout
});
```

--------------------------------

### Contribution Workflow

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Steps outlining the contribution process for the Circuit MCP project, including forking, creating branches, committing changes, and opening pull requests.

```bash
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
```

--------------------------------

### Circuit MCP Automation Tools Overview

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/electron-toolset-plan.md

Lists the implemented automation tools categorized by implementation phase, highlighting their functionality and contribution to the overall toolset.

```APIDOC
Circuit MCP Automation Tools:

Phase 1 Critical Tools:
  - keyboard_press: Direct keyboard input for terminal automation.
  - click_by_text: Semantic element selection by visible text.
  - add_locator_handler: Automatic modal/overlay handling.

Phase 2 Robustness Tools:
  - click_by_role: Accessibility-based element selection.
  - click_nth: Element disambiguation by index.
  - keyboard_type: Advanced text input with timing control.

Phase 3 Polish Tool:
  - wait_for_load_state: Page state management.

Total Tools: 18 (11 existing + 7 new)
```

--------------------------------

### AI-Optimized Desktop Application Launch

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Details launching desktop applications with optimized AI settings, including screenshot compression and quality. Interactions automatically include window snapshots with element references.

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

--------------------------------

### Testing and Cleaning Commands

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Bash commands for running all tests and cleaning build artifacts across all packages in the Circuit MCP project.

```bash
# Run all tests
pnpm -r test

# Clean all builds
pnpm -r clean
```

--------------------------------

### Running Local Development Servers

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Bash commands to run the local development servers for web and desktop automation using the built CLI scripts.

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

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

--------------------------------

### Troubleshooting: Ensure Valid Session for Commands

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Illustrates the correct way to use MCP commands by ensuring a valid session is established before executing actions. It contrasts an incorrect attempt without a session with the correct procedure of launching the app first.

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

--------------------------------

### Automate Code Editor Actions

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Demonstrates automating a traditional packaged application, specifically Visual Studio Code. It shows how to launch the app, click UI elements like 'New File', type code snippets, and use keyboard shortcuts for saving.

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

--------------------------------

### Run Circuit Web Server

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Command to run the Circuit Web server with optional browser and headed mode configurations. Uses npx for execution.

```bash
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)
```

--------------------------------

### Web Element Targeting and Interaction

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Demonstrates how to navigate to a URL, retrieve element references from auto-snapshots, and click elements using various selectors. The responses include updated page snapshots reflecting the interaction results.

```javascript
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
```

--------------------------------

### Electron Application Automation Tools

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Enables automation of Electron applications, including launching, managing application windows, interacting with Inter-Process Communication (IPC), file system operations, and keyboard input.

```APIDOC
app_launch(app, mode, projectPath, startScript, disableDevtools, compressScreenshots, screenshotQuality)
  Launches an Electron application with AI optimizations.
  Parameters:
    app: Path to the Electron application executable or package.
    mode: The mode to launch the app in (e.g., 'production', 'development').
    projectPath: Path to the project directory.
    startScript: The script to run to start the app.
    disableDevtools: Boolean, whether to disable developer tools.
    compressScreenshots: Boolean, whether to compress screenshots.
    screenshotQuality: Integer, the quality of screenshots (0-100).

get_windows(sessionId)
  Lists all windows associated with the Electron application session and identifies their types.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
  Returns: An array of window objects with type identification.

ipc_invoke(sessionId, channel, args)
  Invokes an IPC method within the Electron application.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    channel: The IPC channel name.
    args: Arguments to pass to the IPC method.

fs_write_file(sessionId, filePath, content)
  Writes content to a file on the disk within the Electron environment.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    filePath: The path to the file to write.
    content: The content to write to the file.

fs_read_file(sessionId, filePath)
  Reads content from a file on the disk within the Electron environment.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    filePath: The path to the file to read.
  Returns: The content of the file.

keyboard_press(sessionId, key, modifiers)
  Presses a keyboard key, optionally with modifier keys.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    key: The key to press (e.g., 'a', 'Enter').
    modifiers: Array of modifier keys (e.g., ['Ctrl', 'Shift']).

click_by_text(sessionId, text, exact)
  Clicks on an element that contains the specified text.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    text: The text content of the element to click.
    exact: Boolean, whether the text must match exactly.

click_by_role(sessionId, role, name)
  Clicks on an element identified by its accessibility role and name.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    role: The accessibility role of the element (e.g., 'button', 'link').
    name: The accessibility name of the element.

click_nth(sessionId, selector, index)
  Clicks the nth element that matches the given selector.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    selector: The CSS selector for the elements.
    index: The index (0-based) of the element to click.

keyboard_type(sessionId, text, delay)
  Types text into the active input field with a specified delay between characters.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    text: The text to type.
    delay: The delay in milliseconds between each character typed.

add_locator_handler(sessionId, selector, action)
  Adds a handler to manage modals or popups identified by a selector.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    selector: The CSS selector for the modal/popup.
    action: The action to perform when the modal/popup appears (e.g., 'accept', 'dismiss').

wait_for_load_state(sessionId, state)
  Waits for the page or application to reach a specific load state.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    state: The load state to wait for (e.g., 'load', 'domcontentloaded', 'networkidle').

smart_click(sessionId, target, strategy, windowId)
  Performs a click using a smart strategy that can auto-detect elements by references, text, or CSS.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
    target: The target element identifier (reference, text, or selector).
    strategy: The click strategy to use (e.g., 'ref', 'text', 'css').
    windowId: Identifier for the specific window/frame.

browser_console_messages(sessionId)
  Retrieves console logs from the Electron app's web content.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
  Returns: An array of console message objects.

browser_network_requests(sessionId)
  Retrieves network requests made within the Electron app's web content.
  Parameters:
    sessionId: The unique identifier for the Electron application session.
  Returns: An array of network request objects.
```

--------------------------------

### Launch Browser in Development Mode with Full Quality

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Launches a browser instance in development mode with uncompressed screenshots for detailed debugging. It configures the browser to be visible and sets a specific viewport size.

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

--------------------------------

### Web Dialog Handling

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Explains how to set up automatic handling for browser dialogs, such as alerts, confirms, or prompts, by specifying an action and optional default text.

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

--------------------------------

### Manage Multiple Windows in an Application

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Illustrates how to manage multiple windows within an Electron application. It covers launching an app, retrieving a list of available windows, and interacting with specific elements within a designated window.

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

--------------------------------

### Web Browser Automation Tools

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Provides a comprehensive set of tools for controlling web browsers, including launching, navigation, tab management, element interaction, and retrieving page content or network data. Many actions include automatic snapshotting with element references.

```APIDOC
browser_launch(browser, headed, viewport, compressScreenshots, screenshotQuality)
  Launches a browser with AI optimizations.
  Parameters:
    browser: The browser to launch (e.g., 'chrome', 'firefox').
    headed: Boolean, whether to run the browser in headed mode.
    viewport: Object, specifies the viewport dimensions {width, height}.
    compressScreenshots: Boolean, whether to compress screenshots.
    screenshotQuality: Integer, the quality of screenshots (0-100).

browser_navigate(sessionId, url)
  Navigates the browser to a specified URL, including an auto-snapshot.
  Parameters:
    sessionId: The unique identifier for the browser session.
    url: The URL to navigate to.
  Returns: Auto-snapshot with element references.

browser_resize(sessionId, width, height)
  Resizes the browser viewport.
  Parameters:
    sessionId: The unique identifier for the browser session.
    width: The new width of the viewport.
    height: The new height of the viewport.

browser_handle_dialog(sessionId, action, promptText)
  Sets an auto-response for browser dialogs.
  Parameters:
    sessionId: The unique identifier for the browser session.
    action: The action to take ('accept' or 'dismiss').
    promptText: The text to enter if accepting a prompt dialog.

browser_tab_new(sessionId)
  Creates a new browser tab.
  Parameters:
    sessionId: The unique identifier for the browser session.
  Returns: The ID of the newly created tab.

browser_tab_list(sessionId)
  Lists all currently open browser tabs.
  Parameters:
    sessionId: The unique identifier for the browser session.
  Returns: An array of tab objects, each with title, URL, and active status.

browser_tab_select(sessionId, tabId)
  Switches the active tab in the browser.
  Parameters:
    sessionId: The unique identifier for the browser session.
    tabId: The ID of the tab to switch to.

browser_tab_close(sessionId, tabId)
  Closes a specific browser tab.
  Parameters:
    sessionId: The unique identifier for the browser session.
    tabId: The ID of the tab to close.

browser_network_requests(sessionId)
  Retrieves the history of network requests made within the browser session.
  Parameters:
    sessionId: The unique identifier for the browser session.
  Returns: An array of network request objects.

browser_console_messages(sessionId)
  Retrieves the history of console messages logged within the browser session.
  Parameters:
    sessionId: The unique identifier for the browser session.
  Returns: An array of console message objects.

browser_generate_playwright_test(sessionId)
  Generates Playwright test code based on recorded actions in the session.
  Parameters:
    sessionId: The unique identifier for the browser session.

click(sessionId, selector, windowId)
  Clicks on an element identified by a selector. Includes auto-snapshot.
  Parameters:
    sessionId: The unique identifier for the browser session.
    selector: The CSS selector for the element to click.
    windowId: Identifier for the specific window/frame.

type(sessionId, selector, text, windowId)
  Types text into an input element identified by a selector. Includes auto-snapshot.
  Parameters:
    sessionId: The unique identifier for the browser session.
    selector: The CSS selector for the input element.
    text: The text to type.
    windowId: Identifier for the specific window/frame.

hover(sessionId, selector, windowId)
  Hovers the mouse over an element identified by a selector. Includes auto-snapshot.
  Parameters:
    sessionId: The unique identifier for the browser session.
    selector: The CSS selector for the element to hover over.
    windowId: Identifier for the specific window/frame.

drag(sessionId, sourceSelector, targetSelector)
  Drags an element identified by sourceSelector to a target element.
  Parameters:
    sessionId: The unique identifier for the browser session.
    sourceSelector: The CSS selector for the element to drag.
    targetSelector: The CSS selector for the target element.

key(sessionId, key, windowId)
  Presses a keyboard key. Includes auto-snapshot.
  Parameters:
    sessionId: The unique identifier for the browser session.
    key: The key to press (e.g., 'Enter', 'Escape').
    windowId: Identifier for the specific window/frame.

select(sessionId, selector, value)
  Selects an option from a dropdown element.
  Parameters:
    sessionId: The unique identifier for the browser session.
    selector: The CSS selector for the dropdown element.
    value: The value of the option to select.

upload(sessionId, selector, filePath)
  Uploads a file to an input element.
  Parameters:
    sessionId: The unique identifier for the browser session.
    selector: The CSS selector for the file input element.
    filePath: The path to the file to upload.

back(sessionId)
  Navigates the browser back in its history.
  Parameters:
    sessionId: The unique identifier for the browser session.

forward(sessionId)
  Navigates the browser forward in its history.
  Parameters:
    sessionId: The unique identifier for the browser session.

refresh(sessionId)
  Reloads the current page in the browser.
  Parameters:
    sessionId: The unique identifier for the browser session.

screenshot(sessionId, path)
  Takes a compressed screenshot of the current page.
  Parameters:
    sessionId: The unique identifier for the browser session.
    path: The file path to save the screenshot.

snapshot(sessionId)
  Retrieves the accessibility tree of the current page along with element references.
  Parameters:
    sessionId: The unique identifier for the browser session.
  Returns: Accessibility tree data.

pdf(sessionId, path)
  Generates a PDF of the current page.
  Parameters:
    sessionId: The unique identifier for the browser session.
    path: The file path to save the PDF.

content(sessionId)
  Retrieves the full HTML content of the current page.
  Parameters:
    sessionId: The unique identifier for the browser session.
  Returns: The HTML content as a string.

text_content(sessionId)
  Retrieves the visible text content of the current page.
  Parameters:
    sessionId: The unique identifier for the browser session.
  Returns: The visible text content as a string.

evaluate(sessionId, script)
  Executes arbitrary JavaScript code within the browser context.
  Parameters:
    sessionId: The unique identifier for the browser session.
    script: The JavaScript code to execute.
  Returns: The result of the script execution.

wait_for_selector(sessionId, selector, timeout)
  Waits for an element matching the selector to appear on the page.
  Parameters:
    sessionId: The unique identifier for the browser session.
    selector: The CSS selector for the element to wait for.
    timeout: The maximum time in milliseconds to wait.

close(sessionId)
  Closes the browser session.
```

--------------------------------

### Desktop Application Launch in Development Mode

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Covers launching Electron applications in development mode, with options for automatic detection of the launch mode (packaged vs. development).

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

--------------------------------

### Launch in Production Mode with Optimized Performance

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Configures application launches for production environments, optimizing for performance through maximum screenshot compression and headless operation. This applies to both web browser and Electron applications.

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

--------------------------------

### Development MCP Server Configuration

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

JSON configuration for setting up MCP servers in a development environment, specifying commands and arguments for web and electron servers.

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

--------------------------------

### Production MCP Server Configuration

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

JSON configuration for setting up MCP servers in a production environment, specifying commands for web and electron servers.

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

--------------------------------

### Run Circuit Electron Server

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Command to run the Circuit Electron server, allowing configuration of the server name for MCP handshake. Uses npx for execution.

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

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

--------------------------------

### API Design Principles

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/electron-toolset-plan.md

Outlines the consistent parameter patterns, naming conventions, and error handling strategies for the Circuit MCP API.

```APIDOC
Consistent Parameter Patterns:
1. sessionId (required) - Always first parameter
2. Primary action parameters (required) - Core functionality
3. Options (optional) - Modifiers and configuration
4. windowId (optional) - Always last for multi-window support

Naming Convention:
- Action_Target: click_by_text, keyboard_press
- Descriptive: Clear intent from name alone
- Consistent: Follows existing tool patterns

Error Handling:
- Timeout support for interactive tools
- Clear error messages with context
- Graceful degradation when possible
```

--------------------------------

### Launch Electron App in Development Mode with Full Quality

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Launches an Electron application in development mode, prioritizing full screenshot quality for debugging. This configuration ensures that screenshots are not compressed, aiding in detailed visual analysis.

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

--------------------------------

### Monitor Console Logs and Network Requests

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Shows how to launch an Electron app and monitor its console output and network activity. It includes performing actions that generate logs and network requests, then retrieving and logging this data for debugging purposes.

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

--------------------------------

### Troubleshooting: Stop Existing Process to Launch MCP

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Provides a bash command to stop any running Electron processes that might conflict with the MCP launching its own instance. This ensures the MCP can properly manage the application lifecycle.

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

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

--------------------------------

### Launch Electron App for Development

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Launches a new instance of an Electron application in development mode using Playwright. It returns a sessionId for subsequent automation commands. This method is designed to manage the app lifecycle and provides full automation control.

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

--------------------------------

### Driver Interface Definition

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/specification.md

Defines the core interface for drivers used in the Snowfort Circuit MCP. It outlines methods for launching sessions and performing common actions like navigation and clicking, with specific types for options and sessions.

```typescript
export interface Driver {
  launch(opts: LaunchOpts): Promise<Session>
  navigate?(session: Session, url: string): Promise<void>
  click(session: Session, selector: string): Promise<void>
  /* shared verbs */
}
```

--------------------------------

### Web Network and Console Monitoring

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Shows how to monitor network requests and console messages during web page navigation. It also includes generating Playwright test code from recorded actions.

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

--------------------------------

### MCP Configuration for AI Agents

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/README.md

Configure your AI agent's MCP settings to enable web, desktop, or dual-engine automation using Snowfort Circuit. This involves specifying the command to run the respective Circuit MCP server.

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

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

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

--------------------------------

### HTML Structure for Electron App

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/test-app.html

Defines the basic HTML structure for the Electron application, including buttons and an output area. It also includes inline CSS for basic styling.

```html
Test Electron App body { font-family: Arial, sans-serif; padding: 20px; }
button { padding: 10px 20px; margin: 10px; font-size: 16px; }
#output { margin-top: 20px; padding: 10px; background: #f0f0f0; }
```

--------------------------------

### Smart Element Selection Tools

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

Improves element selection by allowing clicks based on text content with disambiguation and selecting the Nth element matching a selector.

```javascript
// Improved click with disambiguation:
clickWithText(sessionId, elementType, text, index?)
clickNth(sessionId, selector, index)
```

--------------------------------

### Circuit MCP Automation Benefits

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/electron-toolset-plan.md

Summarizes the key benefits and impact achieved by the comprehensive automation toolset provided by the Electron MCP, focusing on reliability and workflow efficiency.

```APIDOC
Key Benefits of Circuit MCP Automation:

- Terminal Automation: Direct keyboard control eliminates complex JavaScript workarounds.
- Element Selection: Text and role-based selection prevents timeout failures.
- Modal Handling: Automatic overlay management prevents click interception.
- Workflow Efficiency: Comprehensive toolset supports any desktop automation scenario.

Approach:
- Maximizes value while minimizing redundancy.
- Directly addresses observed pain points.
- Leverages Playwright's proven capabilities.
```

--------------------------------

### Wait for Load State

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/electron-toolset-plan.md

Waits for the page to reach a specific load state (e.g., 'load', 'domcontentloaded', 'networkidle'). This helps synchronize automation with page rendering and network activity, improving reliability.

```typescript
wait_for_load_state(sessionId: string, state?: "load" | "domcontentloaded" | "networkidle", windowId?: string)
```

--------------------------------

### Modal and Overlay Handling Tools

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

Provides functions to automatically dismiss common modals by button text and to detect and return information about active modals.

```javascript
dismissModal(sessionId, buttonText?)
detectModals(sessionId)
```

--------------------------------

### Expose Playwright Keyboard and Locator APIs

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

This snippet lists Playwright APIs that should be exposed directly through the MCP tools. These include keyboard actions like press and type, locator methods such as getByText, getByRole, and nth, and utility functions like addLocatorHandler and waitForLoadState. These are intended to replace custom wrapper methods.

```typescript
keyboard_press(sessionId, key, modifiers?)
keyboard_type(sessionId, text, options?)
get_by_text(sessionId, text, options?)
get_by_role(sessionId, role, options?)
locator_nth(sessionId, selector, index)
add_locator_handler(sessionId, selector, action)
wait_for_load_state(sessionId, state?)
```

--------------------------------

### UI State Management Tools

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

Offers utilities to wait for specific UI changes, modal closures, or the clearing of overlays within a given session and timeout.

```javascript
waitForUIChange(sessionId, timeout?)
waitForModalClose(sessionId, timeout?)
waitForOverlaysClear(sessionId, timeout?)
```

--------------------------------

### Playwright Element Selection Strategies

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

Playwright offers advanced element selection capabilities beyond basic CSS selectors, including text-based matching (exact, partial, regex), nth-element selection, role-based selection, and combining multiple conditions.

```Python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")

    # Get by text (exact match)
    page.getByText("Submit").click()

    # Get by text (partial match)
    page.getByText("user", exact=False).click()

    # Get by role (e.g., a button with accessible name 'Submit')
    page.getByRole("button", name="Submit").click()

    # Get by CSS selector and filter by text content
    page.locator(':has-text("Welcome")').click()

    # Get by CSS selector and filter by text content using locator.filter
    page.locator("div").filter(has_text="Welcome").click()

    # Nth selection: get the second element matching the selector
    page.locator("li").nth(1).click()

    # Get the first matching element
    page.locator("button").first.click()

    # Get the last matching element
    page.locator("input").last.click()

    # Combine conditions: find a button that contains the text 'Save'
    page.locator("button").filter(has_text="Save").click()

    # Combine conditions using .and_()
    page.locator("input").and_(page.locator("[type='email']")).fill("test@example.com")

    # Combine conditions using .or_()
    page.locator("button").or_(page.locator("a")).click()

    # Filter by child elements
    page.locator("div").filter(has=page.locator("button")).click()

    browser.close()
```

--------------------------------

### Enhanced Keyboard Support Tools

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

Provides functions for simulating single key presses with optional modifiers and sequences of key presses within a session.

```javascript
// New tools needed:
keyPress(sessionId, key, modifiers?)
keySequence(sessionId, sequence)
```

--------------------------------

### Playwright Keyboard APIs

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

Playwright provides a rich set of native keyboard interaction APIs, including typing text, pressing single keys or combinations, and fine-grained key control. It also supports cross-platform modifier keys and complex key sequences.

```Python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")

    # Types text with optional delays
    page.keyboard.type("Hello, Playwright!")

    # Types text with a delay between characters
    page.keyboard.type("Slow typing", delay=100)

    # Presses a single key
    page.keyboard.press("Enter")

    # Presses a key combination (Ctrl+C)
    page.keyboard.press("Control+C")

    # Presses a key combination with modifier on macOS (Cmd+A)
    page.keyboard.press("Meta+A")

    # Fine-grained key control: press and hold Shift, type 'a', release Shift
    page.keyboard.down("Shift")
    page.keyboard.press("a")
    page.keyboard.up("Shift")

    # Inserts text without simulating key events
    page.keyboard.insert_text("Direct text insertion")

    browser.close()
```

--------------------------------

### Terminal Interaction Tools

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

Enables typing commands into a terminal, optionally executing them, and retrieving recent terminal output.

```javascript
terminalType(sessionId, command, execute?)
terminalExecute(sessionId, command)
getTerminalOutput(sessionId, lines?)
```

--------------------------------

### Playwright Modal and Dialog Handling

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/improvements.md

Playwright offers advanced capabilities for handling modals and dialogs, including locator handlers for recurring overlays and built-in dialog event listeners for alerts, confirms, and prompts.

```Python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")

    # Example: Handling a JavaScript alert
    page.on("dialog", lambda dialog: dialog.accept())
    page.evaluate("alert('This is an alert!')")

    # Example: Handling a JavaScript confirm dialog and accepting it
    page.on("dialog", lambda dialog: dialog.accept())
    page.evaluate("confirm('Proceed?')")

    # Example: Handling a JavaScript prompt and accepting with input
    page.on("dialog", lambda dialog:
        dialog.accept(prompt_text='User Input') if dialog.type == 'prompt' else dialog.accept()
    )
    page.evaluate("prompt('Enter your name:')")

    # Example: Using locator handlers for recurring overlays (conceptual)
    # This requires a specific locator that identifies the overlay
    # overlay_locator = page.locator(".modal-backdrop")
    # page.add_locator_handler(overlay_locator, lambda: print("Overlay detected!"))
    # page.click("button") # This click might trigger the overlay

    browser.close()
```

--------------------------------

### Click by Role

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/electron-toolset-plan.md

Semantically selects and clicks an element based on its accessibility role and optional name. This addresses a gap in Playwright's API for more robust and accessible element selection.

```typescript
click_by_role(sessionId: string, role: string, name?: string, windowId?: string)
```

--------------------------------

### Click Nth Element

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/electron-toolset-plan.md

Clicks the Nth element matching a given selector. This is useful when multiple elements match a selector and the desired element can only be distinguished by its order.

```typescript
click_nth(sessionId: string, selector: string, index: number, windowId?: string)
```

--------------------------------

### JavaScript Event Listeners for Electron App

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/test-app.html

Provides JavaScript code to handle user interactions within the Electron application. It attaches event listeners to buttons and an input field to update the output area dynamically.

```javascript
document.getElementById('test-button').addEventListener('click', () => { document.getElementById('output').innerHTML = '<p>Button was clicked!</p>'; });
document.getElementById('change-text').addEventListener('click', () => { document.getElementById('output').innerHTML = '<p>Text changed: ' + new Date().toLocaleTimeString() + '</p>'; });
document.getElementById('test-input').addEventListener('input', (e) => { document.getElementById('output').innerHTML = '<p>You typed: ' + e.target.value + '</p>'; });
```

--------------------------------

### Keyboard Type

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/electron-toolset-plan.md

Types a given string of text into an input field, with optional delay between characters. This provides more flexibility than the standard 'fill' method for complex input scenarios, especially in terminal applications.

```typescript
keyboard_type(sessionId: string, text: string, delay?: number, windowId?: string)
```

--------------------------------

### add_locator_handler Function

Source: https://github.com/snowfort-ai/circuit-mcp/blob/main/electron-toolset-plan.md

Registers a handler for specific element selectors to perform automated actions like dismissing or accepting modals and overlays. This addresses the pain point of UI blocking by invisible elements, enhancing automation reliability. It supports specifying a session ID, the selector, the action to perform, and an optional window ID.

```typescript
add_locator_handler(sessionId: string, selector: string, action: "dismiss" | "accept" | "click", windowId?: string)
```