# Chrome DevTools MCP Helper

A powerful browser automation CLI built on Chrome DevTools Protocol with AI-optimized features and full parity with industry-leading browser automation tools.

## Features

- **Complete Browser Control**: Navigate, interact, and automate Chrome/Chromium browsers
- **AI-Optimized Snapshots**: Accessibility tree with deterministic element references (@e1, @e2, etc.)
- **Multiple Selector Types**: CSS selectors, XPath, refs, and semantic locators
- **Device Emulation**: Mobile/desktop device presets, custom viewports, geolocation
- **State Management**: Save and restore browser state (cookies, localStorage, sessionStorage)
- **Comprehensive Command Set**: 40+ commands for navigation, interaction, debugging
- **Session Isolation**: Multiple browser instances with separate user data directories

## Installation

```bash
# Install dependencies
bun install

# Build the project
bun run build

# Run the CLI
bun run src/cli.ts <command> [options]
```

## Quick Start

```bash
# Navigate to a URL
bun run src/cli.ts open https://example.com

# Take an AI-optimized snapshot with interactive elements only
bun run src/cli.ts snapshot -i --json

# Click an element using ref
bun run src/cli.ts click @e1

# Fill a form field
bun run src/cli.ts fill @e2 "user@example.com"

# Emulate iPhone 14
bun run src/cli.ts set-device "iPhone 14"

# Save browser state
bun run src/cli.ts state-save auth.json

# Take a screenshot
bun run src/cli.ts screenshot page.png
```

## Command Reference

### Navigation Commands

**Navigate to URL**
```bash
# Aliases: open, goto, navigate
bun run src/cli.ts open <url>
bun run src/cli.ts goto https://example.com --wait-until load
```

**Navigation Controls**
```bash
# Go back in history
bun run src/cli.ts back

# Go forward in history
bun run src/cli.ts forward

# Reload page (aliases: reload, refresh)
bun run src/cli.ts reload
bun run src/cli.ts reload --hard  # Force reload
```

**Tab Management**
```bash
# Create new tab (aliases: tab-new, new-page)
bun run src/cli.ts tab-new https://example.com

# List all tabs
bun run src/cli.ts tab-list

# Switch to tab by index
bun run src/cli.ts tab-switch 2

# Close tab
bun run src/cli.ts tab-close
```

### Element Interaction

**Snapshot - AI-Optimized Element Discovery**
```bash
# Get accessibility tree with refs
bun run src/cli.ts snapshot

# Interactive elements only
bun run src/cli.ts snapshot -i

# JSON output for AI agents
bun run src/cli.ts snapshot --json

# Compact view
bun run src/cli.ts snapshot -c
```

**Click Operations**
```bash
# Single click (supports refs and CSS selectors)
bun run src/cli.ts click @e1
bun run src/cli.ts click "button.submit"

# Double click (aliases: dblclick, double-click)
bun run src/cli.ts dblclick @e2
```

**Text Input**
```bash
# Fill input field (aliases: fill, type)
bun run src/cli.ts fill @e3 "test@example.com"
bun run src/cli.ts type "#email" "user@test.com"

# Press keyboard keys
bun run src/cli.ts press Enter
bun run src/cli.ts press "Ctrl+A"
```

**Element Focus and Hover**
```bash
# Focus element
bun run src/cli.ts focus @e4

# Hover over element
bun run src/cli.ts hover "nav .menu-item"
```

### Device Emulation

**Device Presets**
```bash
# Emulate device (aliases: emulate, set-device)
bun run src/cli.ts set-device "iPhone 14"
bun run src/cli.ts set-device "iPad Pro"
bun run src/cli.ts set-device "Pixel 5"
```

**Custom Viewport**
```bash
# Set viewport size (aliases: resize, set-viewport)
bun run src/cli.ts set-viewport 1920 1080
```

**Geolocation**
```bash
# Set geographic location
bun run src/cli.ts set-geo 37.7749 -122.4194  # San Francisco
```

**Media Queries**
```bash
# Set color scheme (dark/light)
bun run src/cli.ts set-media dark
bun run src/cli.ts set-media light
```

### Element Property Inspection

**Get Element Properties** (New command)
```bash
# Get element text
bun run src/cli.ts get --property text --selector @e1

# Get attribute value
bun run src/cli.ts get --property attr --selector @e2 --attr href

# Get computed property
bun run src/cli.ts get --property property --selector input.email --prop value

# JSON output for AI processing
bun run src/cli.ts get --property text --selector @e1 --json
```

**Typical Workflow:**
```bash
# 1. Take snapshot to find element refs
bun run src/cli.ts snapshot -i --json

# 2. Get text content from element
bun run src/cli.ts get --property text --selector @e1

# 3. Get attributes (links, form values, etc.)
bun run src/cli.ts get --property attr --selector @e3 --attr href --json
```

### State Management

**Save/Load Browser State**
```bash
# Save authentication state
bun run src/cli.ts state-save auth.json

# Restore saved state
bun run src/cli.ts state-load auth.json
```

The state file includes:
- Cookies
- localStorage
- sessionStorage
- Current URL

### Debugging & Output

**Screenshots**
```bash
# Take screenshot
bun run src/cli.ts screenshot page.png

# Full page screenshot
bun run src/cli.ts screenshot --full-page output.png
```

**Script Evaluation**
```bash
# Execute JavaScript in page context
bun run src/cli.ts eval "document.title"
bun run src/cli.ts eval "window.scrollTo(0, document.body.scrollHeight)"
```

**Console Messages**
```bash
# List console messages
bun run src/cli.ts console

# Get specific console message
bun run src/cli.ts console 0
```

### Chrome M144+ Remote Debugging

Chrome M144+ removed the HTTP discovery API (`/json/version`). Use the internal session debugging mode instead:

1. Open `chrome://inspect/#remote-debugging` in Chrome
2. Click **"Discover network targets"** and enable it
3. Run:

```bash
bun run src/cli.ts connect --auto
```

**Other Chromium browsers / pre-M144**

```bash
# Connect by port (Chrome must be running with --remote-debugging-port=9222)
bun run src/cli.ts connect 9222

# Connect to a remote host
bun run src/cli.ts connect --auto 192.168.1.10:9222
```

---

### Session Management

**User Data Directory**
```bash
# Use custom user data directory for session isolation
bun run src/cli.ts open https://example.com --user-data-dir=/tmp/session1
bun run src/cli.ts open https://example.com --user-data-dir=/tmp/session2
```

**Close Browser**
```bash
# Close the browser instance
bun run src/cli.ts close
```

## AI-Optimized Features

### Ref System

The snapshot command generates AI-friendly element references (@e1, @e2, etc.) that are deterministic and easy to use:

```bash
# 1. Take snapshot to discover elements
bun run src/cli.ts snapshot -i --json
# Output: {"elements": [{"ref": "@e1", "description": "button 'Submit'"}], "success": true}

# 2. Use refs in subsequent commands
bun run src/cli.ts click @e1
bun run src/cli.ts fill @e2 "user@example.com"
```

### JSON Output Mode

Many commands support `--json` flag for structured output perfect for AI agents:

```bash
bun run src/cli.ts snapshot --json
bun run src/cli.ts console --json
```

## Advanced Options

### Timeouts

```bash
# Set command timeout (in milliseconds)
bun run src/cli.ts open https://example.com --timeout=10000
```

### MCP Connection Type

```bash
# Use stdio (default)
bun run src/cli.ts open https://example.com --mcp-type=stdio

# Use HTTP
bun run src/cli.ts open https://example.com --mcp-type=http
```

### Debug Mode

```bash
# Enable debug output
DEBUG=1 bun run src/cli.ts open https://example.com
```

## Command Aliases Quick Reference

| Command | Aliases |
|---------|---------|
| navigate | open, goto |
| tab-new | new-page |
| tab-close | close-page |
| tab-list | list-pages |
| reload | refresh |
| dblclick | double-click |
| fill | type |
| snapshot | take-snapshot |
| emulate | set-device |
| resize | set-viewport |

## Architecture

This CLI is built on:
- **Chrome DevTools Protocol (CDP)**: Low-level browser automation protocol
- **MCP (Model Context Protocol)**: Integration layer for AI agents
- **Bun Runtime**: Fast TypeScript/JavaScript runtime
- **modality-ai**: AI-friendly browser automation toolkit

## Testing

```bash
# Run test suite
bun test

# Run with coverage
bun test --coverage

# Type checking
bun run build:types
```

## Use Cases

### Automated Testing
```bash
bun run src/cli.ts open https://app.example.com
bun run src/cli.ts fill "#username" "testuser"
bun run src/cli.ts fill "#password" "testpass"
bun run src/cli.ts click "button[type=submit]"
bun run src/cli.ts screenshot logged-in.png
```

### Web Scraping
```bash
bun run src/cli.ts open https://news.example.com
bun run src/cli.ts snapshot -i --json > elements.json
bun run src/cli.ts eval "document.querySelector('h1').textContent"
```

### Mobile Testing
```bash
bun run src/cli.ts set-device "iPhone 14"
bun run src/cli.ts open https://mobile.example.com
bun run src/cli.ts screenshot mobile-view.png
```

### AI Agent Automation
```bash
# AI-friendly workflow with refs
bun run src/cli.ts open https://example.com
bun run src/cli.ts snapshot -i --json | jq '.elements[] | select(.description | contains("Login"))'
bun run src/cli.ts click @e1
```

## Known Issues

### `get` Command Status
The `get` command has been implemented to support retrieving element properties, text content, and attributes (matching agent-browser API). However, the current version of the `chrome-devtools-mcp` server has a parameter validation issue with the `evaluate_script` tool that prevents full functionality.

**Status:** Ready for when chrome-devtools-mcp is updated to fix the parameter schema.

## Contributing

Contributions are welcome! Please ensure:
- All tests pass (`bun test`)
- Type checking succeeds (`bun run build:types`)
- Code follows existing patterns and style

## License

ISC

## Related Projects

- [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) - The underlying MCP server
- [agent-browser](https://github.com/vercel-labs/agent-browser) - Industry-leading browser automation CLI
- [Playwright](https://playwright.dev/) - Browser automation framework
- [Puppeteer](https://pptr.dev/) - Node.js library for Chrome/Chromium automation
