letsbe-mcp-browser/CLAUDE.md

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

# 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