browser-pilot/README.md

# 🚀 Browser Pilot

**Agentic Browser Control – wie im Screenshot: Side Panel Chat + MCP Server + eigenständige Browser-KI.**

Eine Chrome/Brave Extension die drei Dinge gleichzeitig kann:

1. **🗨️ In-Browser Agent (Side Panel)** – Chat-UI direkt im Browser, die KI steuert die Seite
2. **🔌 MCP Server** – externe KI-Clients (Claude Desktop, Cursor, du als Agent) können den Browser fernsteuern
3. **🛠️ Dev Tools** – JS Console, CSS Selector Tester, direkte Tool-Ausführung

![Architecture](https://img.shields.io/badge/MV3-Chrome%20Extension-blue) ![Zero Deps](https://img.shields.io/badge/Server-Zero%20Dependencies-green)

---

## 🏗️ Architektur

```
┌──────────────────────────────────────────────────────────────────────┐
│                         BROWSER (Chrome/Brave)                        │
│                                                                       │
│  ┌─────────────────────┐    ┌──────────────────────────────────────┐ │
│  │   Side Panel (UI)   │    │        Background Service Worker      │ │
│  │                     │    │                                        │ │
│  │  • Chat mit LLM     │◄──►│  • 22 Browser-Tools                   │ │
│  │  • Quick Actions    │    │  • WebSocket → MCP Server              │ │
│  │  • JS Console       │    │  • Message Router                      │ │
│  │  • Selector Test    │    │                                        │ │
│  └─────────────────────┘    └────────────────┬───────────────────────┘ │
│                                              │                         │
│  ┌─────────────────────┐                     │                         │
│  │   Content Script    │◄────────────────────┘                         │
│  │  (jede Seite)       │                                               │
│  │  • Console Capture  │                                               │
│  │  • Error Tracking   │                                               │
│  └─────────────────────┘                                               │
└──────────────────────────────────────────────────────────────────────┘
         ▲                              ▲
         │ LLM API                      │ WebSocket
         │ (OpenRouter/Ollama/etc)      │
         ▼                              ▼
┌─────────────────────┐      ┌─────────────────────────┐
│   LLM Provider      │      │   MCP Server (Node.js)  │
│   (dein Endpoint)   │      │   Port 9224             │
│                     │      │                         │
│   • OpenRouter      │      │   • HTTP MCP Protocol   │
│   • Ollama (lokal)  │      │   • WS Bridge           │
│   • Anthropic       │      │   • Zero Dependencies   │
│   • OpenAI          │      │                         │
│   • Custom          │      │   Clients:              │
└─────────────────────┘      │   • Claude Desktop      │
                             │   • Cursor              │
                             │   • Dieser Agent (du)   │
                             │   • Beliebiger MCP-Client│
                             └─────────────────────────┘
```

---

## ⚡ Quick Start

### 1. Extension installieren

```bash
# In Chrome/Brave:
# 1. chrome://extensions/ öffnen
# 2. Developer Mode aktivieren
# 3. "Load unpacked" → browser-pilot/ Ordner wählen
```

### 2. Side Panel nutzen (eigenständig im Browser)

1. Extension-Icon klicken → Side Panel öffnet sich
2. ⚙️ Settings → API Key + Endpoint konfigurieren
3. Lostippen: "Was steht auf dieser Seite?" oder "Klicke auf den Login-Button"

### 3. MCP Server starten (für externe KI-Anbindung)

```bash
cd browser-pilot/server
node index.js
```

### 4. In Claude Desktop / Cursor / etc. einbinden

```json
{
  "mcpServers": {
    "browser-pilot": {
      "type": "streamableHttp",
      "url": "http://127.0.0.1:9224/mcp"
    }
  }
}
```

---

## 🗨️ Side Panel Features

| Tab | Funktion |
|-----|----------|
| **Fragen** | Chat mit KI – stellt Fragen über die Seite, lässt Aufgaben ausführen |
| **Handeln** | Quick Actions: Screenshot, Seitentext, Links, Formulare, Zusammenfassung |
| **Dev** | JS Console (Ctrl+Enter), CSS Selector Tester mit Highlighting |

### Unterstützte LLM Provider

| Provider | Base URL | Modelle |
|----------|----------|---------|
| OpenRouter | `https://openrouter.ai/api/v1` | Alle (Claude, GPT, Gemini, ...) |
| Ollama | `http://localhost:11434/v1` | qwen2.5, llama3, mistral, ... |
| Anthropic | `https://api.anthropic.com/v1` | Claude Sonnet/Haiku/Opus |
| OpenAI | `https://api.openai.com/v1` | GPT-4o, o1, ... |
| Custom | Beliebig | Jeder OpenAI-kompatible Endpoint |

---

## 🔧 22 Browser-Tools

| Tool | Beschreibung |
|------|-------------|
| `browser_navigate` | Zu URL navigieren |
| `browser_go_back/forward` | History-Navigation |
| `browser_reload` | Seite neu laden |
| `browser_get_tabs` | Alle Tabs auflisten |
| `browser_switch_tab` | Tab wechseln |
| `browser_close_tab` | Tab schließen |
| `browser_screenshot` | Screenshot (base64 PNG) |
| `browser_get_page_info` | URL, Titel, Viewport, Scroll |
| `browser_get_text` | Textinhalt der Seite/Element |
| `browser_get_html` | HTML der Seite/Element |
| `browser_query_selector` | Elemente per CSS-Selektor |
| `browser_get_interactive_elements` | Alle klickbaren Elemente |
| `browser_click` | Element anklicken |
| `browser_type` | Text in Input eingeben |
| `browser_select` | Option in Select wählen |
| `browser_scroll` | Seite/Element scrollen |
| `browser_execute_js` | Beliebiges JavaScript ausführen |
| `browser_press_key` | Taste drücken (mit Modifiern) |
| `browser_wait` | Auf Element/Timeout warten |
| `browser_get_console_logs` | Console-Logs auslesen |
| `browser_highlight` | Element visuell hervorheben |

---

## 🔒 Compliance & Sicherheit

- **Eigene Endpoints** – du bestimmst welches LLM, welcher Server
- **Kein Cloud-Zwang** – funktioniert komplett offline mit Ollama
- **Kein Tracking** – null Telemetrie, null externe Calls (außer dein LLM)
- **Lokaler MCP Server** – bindet nur auf 127.0.0.1
- **Optional Auth Token** – `AUTH_TOKEN=xxx` Environment Variable
- **Zero Dependencies** – Server braucht kein `npm install`

---

## 📁 Projektstruktur

```
browser-pilot/
├── manifest.json           # Chrome MV3 Manifest
├── background.js           # Service Worker (Tools + WS Bridge)
├── content.js              # Content Script (Console Capture)
├── sidepanel.html          # Side Panel UI
├── sidepanel.css           # Styles (Dark Theme)
├── sidepanel.js            # Agent Loop + Chat Logic
├── icons/                  # Extension Icons
└── server/
    ├── index.js            # MCP Server (zero-dep, Node 18+)
    └── package.json
```

---

## 💡 Beispiele

### Im Side Panel:
```
"Fasse diese Seite zusammen"
"Fülle das Kontaktformular mit Testdaten aus"
"Finde alle Links die auf externe Seiten zeigen"
"Klicke auf 'Weiter' und warte bis die nächste Seite geladen ist"
"Sperre die Beobachtungsliste" (wie im Screenshot)
```

### Via MCP (Claude Desktop / dieser Agent):
```
Tool: browser_navigate → {"url": "https://servicenow.mercedes-benz.com"}
Tool: browser_get_interactive_elements → {}
Tool: browser_click → {"selector": "#resolve-btn"}
Tool: browser_screenshot → {}
```

---

## 🚀 Entwicklung

```bash
# Server im Watch-Mode:
cd server && node --watch index.js

# Extension: Dateien editieren → chrome://extensions/ → Reload
```

---

MIT License. Keine Abhängigkeiten. Dein Browser, dein LLM, deine Regeln. 🔥