AI2QA Local Agent

Universal MCP Server for browser automation. Enables both local AI tools (Claude Code, Cursor, Antigravity) and AI2QA cloud to control browsers.

Features

• Sidecar Mode: Attach to existing Chrome sessions (preserves cookies, auth, VPN access)
• MCP Protocol: Standard Model Context Protocol for AI tool integration
• 9 Browser Tools: navigate, click, fill, hover, press-key, screenshot, snapshot, wait, evaluate

Quick Start

1. Install

cd ai2qa-local-agent
npm install
npm run build

2. Start Chrome with Remote Debugging

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

3. Start the Agent

# Sidecar mode (attach to existing Chrome)
npm start -- start --sidecar

# Or with custom port
npm start -- start --sidecar --port 9222

CLI Commands

# Start with stdio (for local AI tools like Claude Code)
ai2qa-agent start

# Start with sidecar mode (default) with custom CDP port
ai2qa-agent start --sidecar --port 9222

# Start in headless mode (no visible browser window)
ai2qa-agent start --headless

# Login to AI2QA cloud (for remote orchestration)
ai2qa-agent login <token>

# Start connected to AI2QA cloud
ai2qa-agent start --cloud

# Check agent status
ai2qa-agent status

# Logout and clear credentials
ai2qa-agent logout

Claude Code Integration

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ai2qa": {
      "command": "node",
      "args": ["/path/to/ai2qa-local-agent/dist/index.js", "start", "--sidecar"]
    }
  }
}

Or after global install:

npm install -g @ai2qa/local-agent

Then configure:

{
  "mcpServers": {
    "ai2qa": {
      "command": "ai2qa-agent",
      "args": ["start", "--sidecar"]
    }
  }
}

AI2QA Cloud Integration

To connect your local agent to AI2QA cloud for remote test orchestration:

1. Generate a device token from the AI2QA web UI at https://ai2qa.com/agents

2. Login with your token:

   ai2qa-agent login <your-token>

3. Start in cloud mode:

   ai2qa-agent start --cloud

The agent will connect to AI2QA cloud and be available for running test runs from the web interface. This enables testing on internal applications behind VPNs using your local browser session.

Available Tools

navigate_page

Navigate to a URL or perform navigation actions.

{
  "url": "https://example.com",
  "type": "goto"  // goto, reload, back, forward
}

click

Click on an element by selector or ref.

{
  "selector": "button#submit"
}

fill

Fill an input field with text.

{
  "selector": "input[name='email']",
  "value": "[email protected]"
}

hover

Hover over an element.

{
  "selector": ".menu-trigger"
}

press_key

Press a keyboard key.

{
  "key": "Enter",
  "modifiers": ["Control"]
}

take_screenshot

Capture a screenshot.

{
  "fullPage": true,
  "format": "png"
}

take_snapshot

Get accessibility tree/DOM snapshot for AI analysis.

{
  "verbose": true,
  "mode": "accessibility"
}

wait_for

Wait for element, text, or duration.

{
  "selector": ".loaded",
  "state": "visible",
  "timeout": 5000
}

evaluate

Execute JavaScript in page context.

{
  "script": "document.title"
}

Development

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

# Lint
npm run lint

Architecture

┌─────────────────────────────────────────────────────────┐
│                    AI2QA Local Agent                     │
│                                                          │
│  ┌─────────────┐    ┌──────────────┐    ┌────────────┐  │
│  │   Stdio     │    │  MCP Server  │    │ WebSocket  │  │
│  │  Transport  │───►│  (9 tools)   │◄───│ Transport  │  │
│  └─────────────┘    └──────┬───────┘    └────────────┘  │
│        ▲                   │                   ▲        │
│        │                   ▼                   │        │
│  [Claude Code]      ┌──────────────┐    [AI2QA Cloud]   │
│  [Cursor]           │  Playwright  │                    │
│                     │  CDP Bridge  │                    │
│                     └──────┬───────┘                    │
└────────────────────────────┼────────────────────────────┘
                             │
                             ▼
┌────────────────────────────────────────────────────────┐
│  Chrome (--remote-debugging-port=9222)                  │
│  [Already logged into VPN, SSO, internal apps]         │
└────────────────────────────────────────────────────────┘

License

MIT