# CLAUDE.md - LetsBe MCP Browser Sidecar

## Purpose

This is the MCP Browser Sidecar - a Playwright browser automation service that provides an HTTP API for LLM-driven exploratory browser control.

Key features:
- Session-based browser management with domain allowlisting
- HTTP API for browser actions (navigate, click, type, screenshot, snapshot)
- Automatic session cleanup and resource limits
- Security via mandatory domain restrictions

## Tech Stack

- Python 3.11
- FastAPI for HTTP API
- Playwright for browser automation
- Pydantic for validation
- Docker with Playwright base image

## Project Structure

```
letsbe-mcp-browser/
  app/
    __init__.py
    config.py           # Settings from environment
    domain_filter.py    # URL/domain allowlist validation
    session_manager.py  # Browser session lifecycle
    playwright_client.py # Playwright browser management
    server.py           # FastAPI HTTP endpoints
  tests/
    test_domain_filter.py
    test_session_manager.py
  Dockerfile
  docker-compose.yml
  requirements.txt
  pytest.ini
```

## Development Commands

```bash
# Start the service
docker compose up --build

# Run tests locally
pip install -r requirements.txt
pytest -v

# API available at http://localhost:8931
```

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | /sessions | Create new browser session |
| GET | /sessions/{id}/status | Get session status |
| DELETE | /sessions/{id} | Close session |
| POST | /sessions/{id}/navigate | Navigate to URL |
| POST | /sessions/{id}/click | Click element |
| POST | /sessions/{id}/type | Type into element |
| POST | /sessions/{id}/wait | Wait for condition |
| POST | /sessions/{id}/screenshot | Take screenshot |
| POST | /sessions/{id}/snapshot | Get accessibility tree |
| GET | /health | Health check |
| GET | /metrics | Basic metrics |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| MAX_SESSIONS | 3 | Max concurrent sessions |
| IDLE_TIMEOUT_SECONDS | 300 | Session idle timeout |
| MAX_SESSION_LIFETIME_SECONDS | 1800 | Max session lifetime |
| MAX_ACTIONS_PER_SESSION | 50 | Max actions per session |
| LOG_LEVEL | INFO | Logging level |
| SCREENSHOTS_DIR | /screenshots | Screenshots directory |

## Security

- **Domain allowlist**: Every session requires `allowed_domains` at creation
- **Network filtering**: All requests blocked unless domain is in allowlist
- **Resource limits**: Max sessions, actions, and timeouts enforced
- **Session isolation**: Each session has its own browser context