brosh - Browser Screenshot Capture

A modular Python tool for capturing intelligent, scrolling screenshots of webpages using Playwright's async API. Designed for AI integration with semantic section detection, HTML extraction, and automatic Markdown conversion.

What This Does

brosh captures full-page screenshots by intelligently scrolling through webpages, detecting content boundaries, and organizing output by semantic sections. It provides both CLI and MCP server interfaces for AI tool integration.

Installation

```bash

Install from PyPI

pip install brosh

Or install in development mode

pip install -e .

Install Playwright browsers (required)

playwright install

```

Core Capabilities

1. Intelligent Screenshot Capture

2. Browser Management

3. Content Extraction

Usage Instructions

CLI Usage

```bash

Basic screenshot capture

brosh shot "https://example.com"

High-resolution capture with custom viewport

brosh --app chrome --width 1920 --height 1080 shot "https://example.com" --format png --scale 100

With HTML extraction

brosh shot "https://example.com" --html

Start browser in debug mode for manual inspection

brosh --app chrome run

Custom scroll behavior

brosh shot "https://example.com" --scroll_step 80 --pause 2

```

MCP Server Mode (for AI Integration)

```bash

Start MCP server

brosh mcp

Or use dedicated command

brosh-mcp

```

Python API

**Synchronous (for CLI scripts):**

```python

from brosh import capture_webpage

result = capture_webpage(

"https://example.com",

scale=50,

format="png"

)

Returns: {"path/to/screenshot.png": {"selector": "body", "text": "..."}}

```

**Asynchronous (for MCP/async apps):**

```python

from brosh import capture_webpage_async

async def main():

result = await capture_webpage_async(

"https://example.com",

html=True

)

# Returns same format with optional "html" field

```

Key Parameters

Module Structure

```

src/brosh/

├── api.py # Public sync/async APIs

├── cli.py # Fire-based CLI interface

├── tool.py # Main BrowserScreenshotTool orchestrator

├── browser.py # BrowserManager (detection, launch, connection)

├── capture.py # CaptureManager (scrolling, section detection)

├── image.py # ImageProcessor (scaling, APNG creation)

├── models.py # Data models and enums

├── mcp.py # FastMCP server for AI integration

├── texthtml.py # DOMProcessor (HTML compression, Markdown)

└── __main__.py # CLI entry point

```

Development Workflow

After making Python changes, run quality checks:

```bash

uzpy run .

fd -e py -x autoflake {}

fd -e py -x pyupgrade --py312-plus {}

fd -e py -x ruff check --output-format=github --fix --unsafe-fixes {}

fd -e py -x ruff format --respect-gitignore --target-version py312 {}

python -m pytest

```

Important Constraints

1. **Browser Support**: Chrome/Edge recommended; Safari macOS-only; Firefox not supported

2. **Scroll Overlap**: Must be between 10-200% for proper section stitching

3. **Debug Ports**: Each browser type has fixed port assignment

4. **Async Context**: MCP server uses async API to avoid asyncio issues

Output Organization

Screenshots are organized by:

Use Cases

Notes