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

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:

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

{
  "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:

{
  "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:

node index.js --config config.json

Or simply (uses default config.json):

node index.js

2. Using CLI Arguments

Quick single URL capture:

node index.js --url https://example.com --width 1920 --height 1080

Multiple viewports:

node index.js \
  --url https://example.com \
  --width 1920 --height 1080 \
  --width 375 --height 667 \
  --output ./my-snapshots

Multiple URLs:

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

{
  "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:

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

{
  "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

{
  "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

{
  "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:

npm install puppeteer --legacy-peer-deps

Or set environment variable:

set PUPPETEER_SKIP_DOWNLOAD=true
npm install

Timeout Errors

If pages take long to load, increase the wait time:

{
  "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)