llms-full.txt

# snapgrab
> URL to screenshot + metadata. Claude Vision optimized. CLI / async Python / MCP.
Requires Python >= 3.11. Deps: playwright>=1.49, Pillow>=10.0, click>=8.0, rich>=13.0. MCP extra: fastmcp>=2.0.
```
pip install snapgrab              # core
pip install snapgrab[mcp]         # + MCP server
playwright install chromium       # required browser
```
## API
### `capture(url, **kwargs) -> CaptureResult`
Main entry point. `from snapgrab import capture`
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `url` | `str` | required | Target URL |
| `viewport` | `str \| tuple[int,int]` | `"desktop"` | `"desktop"` (1920x1080), `"tablet"` (768x1024), `"mobile"` (375x812), or `(w,h)` |
| `full_page` | `bool` | `False` | Capture entire scrollable page (auto-scrolls for lazy loading) |
| `format` | `str` | `"png"` | `"png"`, `"jpeg"`, `"pdf"` |
| `selector` | `str \| None` | `None` | CSS selector for element capture; falls back to full page |
| `wait` | `str \| float` | `"networkidle"` | `"networkidle"`, `"domcontentloaded"`, `"load"`, or seconds |
| `dark_mode` | `bool` | `False` | Force `prefers-color-scheme: dark` |
| `output_dir` | `str` | `"/tmp/snapgrab"` | Output directory (auto-created) |
| `quality` | `int \| None` | `None` | JPEG quality 0-100 (default 80 for jpeg, ignored otherwise) |
| `optimize_vision` | `bool` | `True` | Resize to 1568px max for Claude Vision |
| `headers` | `dict \| None` | `None` | Extra HTTP headers |
| `_manager` | `BrowserManager \| None` | `None` | Reuse existing browser (MCP/batch mode) |
Filename pattern: `{domain}_{viewport}_{YYYYMMDD_HHMMSS}.{format}`. Navigation timeout: 30s.
### `CaptureResult` (dataclass)
| Field | Type | Description |
|-------|------|-------------|
| `path` | `str` | Absolute path to screenshot |
| `format` | `str` | `"png"`, `"jpeg"`, `"pdf"` |
| `width`, `height` | `int` | Dimensions in pixels |
| `file_size` | `int` | Bytes |
| `metadata` | `CaptureMetadata` | Page metadata (see below) |
| `vision_tokens` | `int` | Estimated Claude Vision token cost |
| `vision_path` | `str` | Path to vision-optimized image (empty if same or PDF) |
| `processing_time_ms` | `float` | Capture time in ms |
### `CaptureMetadata` (dataclass)
Fields: `title`, `description`, `og_title`, `og_description`, `og_image`, `favicon_url` (all `str`), `status_code` (`int`), `content_type` (`str`), `url` (`str` — final URL after redirects).
### `estimate_vision_tokens(width: int, height: int) -> int`
From `snapgrab.vision`. Formula: downscale to 1568px max, then `(w * h) / 750`.
### `optimize_for_vision(image_path: str, output_path: str | None = None) -> str`
From `snapgrab.vision`. Resize to 1568px max (LANCZOS). Returns original path if already fits. Default output: `{stem}_vision.{ext}`.
### `BrowserManager`
From `snapgrab.browser`. Manages headless Chromium lifecycle.
- `new_page(viewport="desktop", dark_mode=False, extra_headers=None) -> Page` — new page in fresh context
- `close() -> None` — shutdown browser
- `get_manager() -> BrowserManager` / `close_manager() -> None` — module-level singleton helpers
### `extract_metadata(page, response=None) -> CaptureMetadata`
From `snapgrab.metadata`. Extracts metadata from a loaded Playwright page.
## MCP Server
Command: `snapgrab-mcp`. Transport: stdio. Three tools:
**`capture_screenshot`** — `(url, viewport="desktop", full_page=False, format="png", selector=None, wait="networkidle", dark_mode=False, optimize_vision=True)` Returns JSON: `{path, original_path, format, width, height, file_size, vision_tokens, processing_time_ms, metadata}`.
**`capture_comparison`** — `(url, viewports=["desktop","mobile"], full_page=False)` Returns JSON: `{url, captures: [{viewport, path, width, height, vision_tokens}], total_vision_tokens}`.
**`extract_page_metadata`** — `(url)` Returns JSON: CaptureMetadata fields.
Config:
```json
{"mcpServers": {"snapgrab": {"command": "snapgrab-mcp"}}}
```
Or with uvx: `{"mcpServers": {"snapgrab": {"command": "uvx", "args": ["snapgrab[mcp]", "snapgrab-mcp"]}}}`
## CLI
Entry point: `snapgrab` (or `python -m snapgrab`)
**`snapgrab url <URL>`** — capture screenshot
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--viewport` | `-v` | `desktop` | `desktop`, `tablet`, `mobile`, or `WxH` |
| `--full-page` | `-f` | off | Entire scrollable page |
| `--format` | | `png` | `png`, `jpeg`, `pdf` |
| `--selector` | `-s` | | CSS selector |
| `--wait` | `-w` | `networkidle` | Wait condition or seconds |
| `--dark-mode` | `-d` | off | Dark color scheme |
| `--output` | `-o` | `/tmp/snapgrab` | Output directory |
| `--quality` | `-q` | | JPEG quality 0-100 |
| `--no-optimize` | | off | Skip Vision optimization |
| `--json-output` | `-j` | off | JSON output |
**`snapgrab meta <URL>`** — metadata only (options: `-j`)
**`snapgrab --version`** — print version
## Examples
```python
# Basic capture
from snapgrab import capture
result = await capture("https://example.com")
print(result.path, result.vision_tokens)
```
```python
# Mobile dark mode + batch with BrowserManager reuse
from snapgrab.browser import BrowserManager
mgr = BrowserManager()
try:
    r1 = await capture("https://a.com", viewport="mobile", dark_mode=True, _manager=mgr)
    r2 = await capture("https://b.com", selector="article", _manager=mgr)
finally:
    await mgr.close()
```
```python
# Vision token estimation
from snapgrab.vision import estimate_vision_tokens, optimize_for_vision
tokens = estimate_vision_tokens(1920, 1080)  # ~2189 tokens
optimized = optimize_for_vision("/path/to/screenshot.png")
```
## Links
[GitHub](https://github.com/QuartzUnit/snapgrab) | [PyPI](https://pypi.org/project/snapgrab/) | [Issues](https://github.com/QuartzUnit/snapgrab/issues)