Content
# Browser Snapshot Agent
A powerful headless browser tool for capturing page snapshots at multiple configured window sizes, making visual debugging and responsive testing easy.
## Features
- 🚀 Headless browser automation using Puppeteer
- 📱 Configurable viewport sizes (mobile, tablet, desktop)
- 📸 Full page or viewport-only screenshots
- 🎯 Multiple URLs and viewports in a single run
- ⚙️ Flexible configuration via JSON or CLI arguments
- 📊 Detailed capture summary and error reporting
- 🏷️ Custom labels for viewports
- 🖼️ PNG or JPEG output formats
- ⏱️ Configurable wait times for dynamic content
- 🤖 **MCP (Model Context Protocol) Server** - Use with AI assistants like Claude
## Installation
```bash
cd browser-snapshot-agent
npm install
```
## Usage
### MCP Server Mode (Use with AI Assistants)
The Browser Snapshot Agent can run as an MCP (Model Context Protocol) server, allowing AI assistants like Claude to capture screenshots programmatically.
#### Setup
1. **Install dependencies:**
```bash
cd browser-snapshot-agent
npm install
```
2. **Configure your AI assistant** to use the MCP server. For Claude Desktop, add to your config file:
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"browser-snapshot": {
"command": "node",
"args": [
"C:\\path\\to\\browser-snapshot-agent\\mcp-server.js"
]
}
}
}
```
3. **Restart your AI assistant** to load the MCP server.
#### Available MCP Tools
Once configured, AI assistants can use these tools:
**1. `capture_snapshot`** - Capture a single screenshot
- Parameters: `url`, `width`, `height`, `label`, `outputDir`, `fullPage`, `waitTime`, `format`
- Example: *"Capture a screenshot of https://example.com at 1920x1080"*
**2. `capture_multiple_viewports`** - Capture across multiple viewport sizes
- Parameters: `url`, `viewports[]`, `outputDir`, `fullPage`, `waitTime`, `format`
- Example: *"Capture example.com at mobile, tablet, and desktop sizes"*
**3. `capture_responsive_set`** - Complete responsive test with common device sizes
- Parameters: `url`, `outputDir`, `fullPage`, `waitTime`
- Example: *"Run a full responsive test on https://mysite.com"*
**4. `capture_from_config`** - Use a configuration file
- Parameters: `configPath`
- Example: *"Capture screenshots using config.json"*
#### MCP Usage Examples
With the MCP server running, you can ask your AI assistant:
- *"Capture a screenshot of https://example.com at 1920x1080 resolution"*
- *"Take screenshots of https://mysite.com across mobile, tablet, and desktop viewports"*
- *"Run a complete responsive design test on https://myapp.com and save to ./test-snapshots"*
- *"Capture https://example.com at iPhone SE and iPhone 12 sizes"*
The AI assistant will use the MCP tools to execute these requests and return the file paths of the captured screenshots.
---
### Standalone CLI Mode
You can also use the agent directly from the command line:
#### 1. Using Configuration File (Recommended)
Create or modify `config.json`:
```json
{
"urls": [
"https://example.com",
"https://example.com/about"
],
"viewports": [
{
"width": 1920,
"height": 1080,
"label": "desktop-fullhd"
},
{
"width": 375,
"height": 667,
"label": "mobile-iphone-se"
}
],
"outputDir": "./snapshots",
"waitTime": 1000,
"fullPage": true,
"format": "png",
"quality": 90
}
```
Then run:
```bash
node index.js --config config.json
```
Or simply (uses default config.json):
```bash
node index.js
```
#### 2. Using CLI Arguments
Quick single URL capture:
```bash
node index.js --url https://example.com --width 1920 --height 1080
```
Multiple viewports:
```bash
node index.js \
--url https://example.com \
--width 1920 --height 1080 \
--width 375 --height 667 \
--output ./my-snapshots
```
Multiple URLs:
```bash
node index.js \
--url https://example.com \
--url https://example.com/about \
--width 1920 --height 1080
```
## Configuration Options
### Config File Properties
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `urls` | Array | Required | List of URLs to capture |
| `viewports` | Array | Required | Viewport configurations |
| `outputDir` | String | `./snapshots` | Output directory for screenshots |
| `waitTime` | Number | `1000` | Wait time (ms) after page load |
| `fullPage` | Boolean | `true` | Capture full page or viewport only |
| `format` | String | `png` | Image format: `png` or `jpeg` |
| `quality` | Number | `90` | JPEG quality (1-100) |
### Viewport Object
```json
{
"width": 1920,
"height": 1080,
"label": "desktop-fullhd"
}
```
- `width`: Viewport width in pixels
- `height`: Viewport height in pixels
- `label`: (Optional) Custom label for filename
### CLI Options
```
--config <path> Path to configuration file
--url <url> Single URL to capture (can be used multiple times)
--output <dir> Output directory for snapshots
--width <px> Viewport width (can be used multiple times)
--height <px> Viewport height (can be used multiple times)
--wait <ms> Wait time after page load
--format <type> Image format: png or jpeg
--quality <0-100> JPEG quality
--full-page Capture full page (default: true)
--no-full-page Capture viewport only
--help, -h Show help message
```
## Common Viewport Sizes
The default `config.json` includes these common sizes:
### Desktop
- **1920x1080** - Full HD Desktop
- **1366x768** - HD Desktop
### Tablet
- **768x1024** - iPad Portrait
- **1024x768** - iPad Landscape
### Mobile
- **375x667** - iPhone SE
- **390x844** - iPhone 12/13
- **414x896** - iPhone 11 Pro Max
- **360x640** - Android
## Output
Screenshots are saved with descriptive filenames:
```
{hostname}_{path}_{width}x{height}_{label}_{timestamp}.{format}
```
Example:
```
example_com__1920x1080_desktop-fullhd_2025-01-15T10-30-45.png
```
## Testing
Run the test script to verify installation:
```bash
npm test
```
This will capture test snapshots of example.com at desktop and mobile sizes.
## Use Cases
### Visual Regression Testing
Capture snapshots before and after changes to detect visual differences.
### Responsive Design Verification
Test how your site looks across different device sizes.
### Documentation
Generate screenshots for documentation or presentations.
### Quality Assurance
Automate visual checks as part of your QA process.
### Multi-page Testing
Capture all important pages in one batch for review.
## Advanced Examples
### Capture Specific Pages for Documentation
```json
{
"urls": [
"http://localhost:8080",
"http://localhost:8080/api-keys.html",
"http://localhost:8080/quick-start.html"
],
"viewports": [
{ "width": 1920, "height": 1080, "label": "docs-desktop" }
],
"outputDir": "./docs-screenshots",
"waitTime": 2000
}
```
### Mobile-First Testing
```json
{
"urls": ["https://myapp.com"],
"viewports": [
{ "width": 375, "height": 667, "label": "iphone-se" },
{ "width": 390, "height": 844, "label": "iphone-12" },
{ "width": 393, "height": 851, "label": "pixel-5" }
],
"fullPage": false,
"format": "jpeg",
"quality": 85
}
```
### High-Quality Screenshots for Marketing
```json
{
"urls": ["https://myproduct.com"],
"viewports": [
{ "width": 2560, "height": 1440, "label": "4k-desktop" }
],
"format": "png",
"waitTime": 3000,
"fullPage": true
}
```
## Troubleshooting
### Puppeteer Installation Issues
If you encounter issues installing Puppeteer on Windows:
```bash
npm install puppeteer --legacy-peer-deps
```
Or set environment variable:
```bash
set PUPPETEER_SKIP_DOWNLOAD=true
npm install
```
### Timeout Errors
If pages take long to load, increase the wait time:
```json
{
"waitTime": 5000
}
```
### Missing Content
If screenshots are capturing before content loads:
- Increase `waitTime`
- Ensure the page doesn't require authentication
- Check for JavaScript errors in the page
## License
MIT
## Author
Akhil Kumar (akhil@apralabs.com)
