# Titan MCP - Unified Browser Automation Protocol

A unified Model Context Protocol (MCP) that connects AI agents to multiple browser automation tools.

## Overview

Titan MCP provides a unified interface for AI agents to control web browsers using multiple backends:
- **Selenium** - Traditional browser automation
- **Playwright** - Modern Chromium automation
- **Puppeteer** - Node.js browser control
- **Browser-Use** - AI-powered browser interactions

## Installation

```bash
# Clone the repository
git clone https://github.com/mrhavens/titan-mcp.git
cd titan-mcp

# Install Python dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Install Node.js dependencies
npm install

# Configure
cp config/mcp.yaml.example config/mcp.yaml
# Edit mcp.yaml with your settings
```

## Configuration

Edit `config/mcp.yaml`:

```yaml
browsers:
  chromium:
    enabled: true
    headless: false
    viewport: { width: 1920, height: 1080 }
  
  firefox:
    enabled: false
    headless: true

  webkit:
    enabled: false

automation:
  selenium:
    implicit_wait: 10
    page_load_timeout: 30
    
  playwright:
    slow_mo: 0
    accept_downloads: true
    
  browser_use:
    max_steps: 100
    headless: false

agents:
  openclaw:
    gateway: "ws://192.168.1.64:18789"
    token: "your-gateway-token"
    
  # Connect to witness-zero agents
  witness_zero:
    ollama: "http://192.168.1.64:11434"
```

## Usage

### Starting the MCP Server

```bash
# Start MCP server
python3 mcp_server.py

# Or with custom config
python3 mcp_server.py --config config/mcp.yaml
```

### Connecting to AI Agents

The MCP exposes WebSocket and HTTP endpoints for agent connections:

```python
# Example: Connect OpenClaw agent
import websocket

ws = websocket.create_connection("ws://localhost:8765/agent")
ws.send('{"action": "navigate", "url": "https://example.com"}')
```

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/browse` | POST | Navigate to URL with optional actions |
| `/screenshot` | GET | Take screenshot of current page |
| `/execute` | POST | Execute JavaScript in browser |
| `/fill` | POST | Fill form fields |
| `/click` | POST | Click elements |
| `/ws/agent` | WS | WebSocket for agent commands |

## Available Browsers

| Browser | Status | Command |
|---------|--------|---------|
| Chrome | ✅ Installed | `google-chrome` |
| Firefox | ✅ Installed | `firefox` |
| Chromium | ✅ Installed | `chromium-browser` |
| Edge | ✅ Installed | `microsoft-edge` |
| Opera | ⚠️ Install issues | - |

## Text Browsers (Fallback)

| Browser | Command |
|---------|---------|
| Lynx | `lynx` |
| Links2 | `links2` |
| W3m | `w3m` |

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    AI Agents                            │
│  (OpenClaw, Claude, GPT, Ollama, etc.)               │
└──────────────────────┬──────────────────────────────────┘
                       │ WebSocket / HTTP
                       ▼
┌─────────────────────────────────────────────────────────┐
│                   Titan MCP Server                        │
│  ┌──────────────┬──────────────┬──────────────┐         │
│  │   Selenium   │  Playwright  │  Puppeteer   │         │
│  └──────────────┴──────────────┴──────────────┘         │
│  ┌──────────────┬──────────────┐                         │
│  │ Browser-Use │  Text Mode  │                         │
│  └──────────────┴──────────────┘                         │
└──────────────────────┬──────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────┐
│                    Browsers                              │
│  Chrome | Firefox | Chromium | Edge | Opera            │
└─────────────────────────────────────────────────────────┘
```

## Environment Variables

```bash
# Ollama (local models)
OLLAMA_HOST=http://192.168.1.64:11434

# OpenClaw Gateway
OPENCLAW_GATEWAY=ws://192.168.1.64:18789
OPENCLAW_TOKEN=your-token

# Browser settings
BROWSER_HEADLESS=false
BROWSER_TIMEOUT=30
```

## Examples

### Navigate and Screenshot

```python
import requests

# Navigate to URL
response = requests.post("http://localhost:8765/browse", json={
    "action": "navigate",
    "url": "https://github.com/mrhavens",
    "wait_for": "networkidle"
})

# Take screenshot
screenshot = requests.get("http://localhost:8765/screenshot")
with open("screenshot.png", "wb") as f:
    f.write(screenshot.content)
```

### Execute JavaScript

```python
response = requests.post("http://localhost:8765/execute", json={
    "script": "document.title = 'Hello from Titan MCP'",
    "return_value": "document.title"
})
```

## KAIROS Integration

This MCP integrates with the KAIROS ADAMON system for autonomous agent coordination.

### Phase Lock Testing

```bash
# Run phase lock test with 7 agents
python3 scripts/phase_lock_test.py
```

## License

MIT

## Author

Mark Havens / Titan Root Havens