# 🤖 AI Browser Agent MCP Server

A production-grade **Model Context Protocol (MCP)** server for autonomous web automation. 

Designed specifically for complex booking workflows (tickets, tours, hotels, transport), this server enables AI agents to browse, interact, and extract data like a human, bypassing common automation hurdles.

---

## 🔥 Key Problems Solved

- **The Hydration Race**: Modern SPAs (React/Next.js) often render elements that aren't interactive yet. Our server uses a `MutationObserver` to ensure the DOM is quiet and hydrated before every action.
- **Anti-Bot Evasion**: Built-in kernel-level stealth (Playwright Stealth), masked `navigator.webdriver`, and randomized human-like typing jitter.
- **Transparent Overlays**: Click traps and cookie banners often catch standard automation. Our "Smart Click" uses coordinate-based fallback to click the physically visible center of elements.
- **Brittle Selectors**: Instead of hardcoded scripts, we use a **Site Profile** system (YAML) that gives the LLM lightweight hints, allowing it to adapt to UI changes dynamically.

---

## 🛠️ Features

- 🛡️ **Stealth-First**: Masked fingerprints, residential-proxy support, and block detection.
- 📅 **3-Strategy Date Selection**: Adaptive handling of native inputs and complex custom calendar modals.
- 📁 **Declarative Site Profiles**: 15-line YAML configs for sites like GetYourGuide, Omio, and Trenitalia.
- 🗺️ **17 High-Level Tools**: Pre-built tools for session management, navigation, interaction, and data extraction.

---

## 🚀 Quick Start

### 1. Installation
```bash
# Clone the repo and install locally
pip install -e .
playwright install chromium
```

### 2. Configuration
Create a `.env` file:
```bash
PROXY_URL=http://user:pass@host:port  # Optional for residential proxies
BROWSER_HEADLESS=false                # Recommended for local debugging
```

### 3. Run with MCP Inspector
```bash
fastmcp dev server.py
```

---

## 🏗️ Integration Guide

### Use with LangGraph (Python)
Since this is an MCP-compliant server, you can dynamically load these tools into your LangGraph nodes:

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain.tools import tool

async def get_tools():
    server_params = StdioServerParameters(
        command="python",
        args=["PATH_TO_SERVER.py"]
    )
    # Use mcp.client to fetch and wrap tools for your StateGraph...
```

### Use with Claude Desktop
Add this to your `mcp_config.json`:
```json
{
  "mcpServers": {
    "browser-agent": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}
```

---

## ⚙️ Declarative Site Profiles
Add support for any website in seconds by creating a `.yaml` file in the `profiles/` directory:

```yaml
site: "example.com"
anti_bot: "DataDome"
cookie_banner:
  selector: "#accept-all"
  required: true
search_input: "input[type='search']"
session_hints: |
  Wait 2s after main navigation.
  Use coordinate clicks for the search button.
```

---

## 📂 Project Structure

- `browser/` : Core Playwright engine, stealth config, and stability logic.
- `tools/` : 17 MCP-standard tool definitions.
- `profiles/` : YAML site configurations.
- `server.py` : FastMCP entry point.

---

## 🛡️ License
MIT License. Created by [Your Name/GitHub].