Browser Agent

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

# Clone the repo and install locally
pip install -e .
playwright install chromium

2. Configuration

Create a .env file:

PROXY_URL=http://user:pass@host:port  # Optional for residential proxies
BROWSER_HEADLESS=false                # Recommended for local debugging

3. Run with MCP Inspector

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:

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:

{
  "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:

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].