87 lines
2.5 KiB
Markdown
87 lines
2.5 KiB
Markdown
# 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
|