Page Capture

mcp-page-capture

mcp-page-capture is a Model Context Protocol (MCP) server that orchestrates headless Chromium via Puppeteer to capture pixel-perfect screenshots of arbitrary URLs. It is optimized for Copilot/MCP-enabled environments and can be embedded into automated workflows or run as a standalone developer tool.

Features

• 📸 High-fidelity screenshots powered by Puppeteer and headless Chromium
• ⚙️ LLM-optimized schema with minimal parameters exposed and sensible defaults
• 🔍 Structured DOM extraction with optional CSS selectors for AI-friendly consumption
• 📱 Device presets for mobile emulation (iPhone, iPad, Android, desktop)
• 🎯 6 simplified steps for LLM friendliness: viewport, wait, fill, click, scroll, screenshot
• 🤖 Smart defaults - screenshot auto-captured, field types auto-detected
• 🆕 Consistent parameters - target for elements, for for waiting, to for scrolling, device for viewport
• 🔄 Automatic retry with exponential backoff for transient failures
• 📊 Telemetry hooks for centralized observability and monitoring
• 💾 Pluggable storage backends (local filesystem, S3, memory)
• 🛡️ Structured logging plus defensive error handling for operational visibility
• 🔌 Launch via npm start, npm run dev, or as a long-lived MCP sidecar
• 🐳 Docker image with multi-platform support (amd64, arm64)

How It Works

1. The MCP transport boots a Node.js server and registers the captureScreenshot and extractDom tools.
2. Incoming tool invocations are validated against the relevant type definitions.
3. Puppeteer starts (or reuses) a Chromium instance, navigates to the requested URL, and either captures a screenshot or serializes the DOM according to the tool parameters.
4. The server returns structured content (images, text, DOM trees, metadata) to the caller or downstream workflow.

Requirements

• Node.js ≥ 18.x
• npm ≥ 9.x
• Chromium package download permissions (first run)
• Network access to the target URLs

🌟 LLM-Friendly Features

Simplified Schema (5-Star LLM Rating)

• ✅ Only 4 top-level parameters: url, steps, headers, validate
• ✅ Exactly 6 step types (no more, no less)
• ✅ Consistent parameter naming across all steps
• ✅ Automatic screenshot if omitted
• ✅ Smart field type detection
• ✅ Actionable error messages with recovery suggestions
• ✅ Single source of truth for all schemas
• ✅ Deprecation warnings for legacy parameters
• ✅ NEW: Validate mode for pre-flight step checking
• ✅ NEW: Step order enforcement with auto-correction
• ✅ NEW: Embedded LLM reference in MCP server instructions

Quick Start for LLMs

See LLM Quick Reference for the 6 primary step types and common patterns.

For advanced features, see Advanced Steps.

The 6 Step Types (Exactly 6, No More)

Step Order: Auto-fixed! viewport auto-moves to first, screenshot auto-added at end.

Composite Patterns (NEW)

High-level patterns that auto-expand to multiple steps:

// Login pattern
{
  "type": "login",
  "email": { "selector": "#email", "value": "user@example.com" },
  "password": { "selector": "#password", "value": "secret" },
  "submit": "button[type=submit]",
  "successIndicator": ".dashboard"
}

// Search pattern  
{
  "type": "search",
  "input": "#search-box",
  "query": "MCP protocol",
  "resultsIndicator": ".search-results"
}

Installation

From source (recommended during development)

git clone https://github.com/chasesaurabh/mcp-page-capture.git
npm install

From npm

# Run without installing globally
npx mcp-page-capture

# Or add it to your toolchain
npm install -g mcp-page-capture
mcp-page-capture

Running the server

npm install
npm run build
npm start

For hot reload while iterating locally, run npm run dev.

Why Docker?

• Guarantees a consistent Puppeteer + Chromium environment with all system libraries when teammates or CI run the server. No more "it works on my machine" mismatches.
• Provides a ready-to-deploy container image for hosting mcp-page-capture as a sidecar/service on Kubernetes, ECS, Fly.io, etc.

If you need those guarantees, build and run via:

docker build -t mcp-page-capture .
docker run --rm -it mcp-page-capture

Otherwise you can keep using the standard npm scripts locally.

IDE MCP configuration

{
  "mcpServers": {
    "page-capture": {
      "command": "node",
      "args": ["dist/cli.js"]
    }
  }
}

Note: You may need to use the full path to dist/cli.js or node depending on your working directory and Node.js module resolution configuration.

Programmatic usage

If you want to embed the server inside another Node.js process, import the helpers exposed by the package:

import { startMcpPageCaptureServer } from "mcp-page-capture";

await startMcpPageCaptureServer();
// Optionally pass a custom Transport implementation if you don't want stdio.

Usage

Tool invocation examples

Basic Screenshot

{
  "tool": "captureScreenshot",
  "params": {
    "url": "https://example.com"
  }
}

Note: A screenshot is automatically captured at the end if no explicit screenshot step is provided.

Search with Fill Step (Recommended)

The fill step auto-detects field types and handles text inputs, selects, checkboxes, and radio buttons.

{
  "tool": "captureScreenshot",
  "params": {
    "url": "https://example.com",
    "steps": [
      { "type": "fill", "target": "#search", "value": "MCP protocol", "submit": true },
      { "type": "wait", "for": ".search-results" },
      { "type": "screenshot" }
    ]
  }
}

Login Form Example

{
  "tool": "captureScreenshot",
  "params": {
    "url": "https://example.com/login",
    "steps": [
      { "type": "wait", "for": "#login-form" },
      { "type": "fill", "target": "#email", "value": "user@example.com" },
      { "type": "fill", "target": "#password", "value": "secretpassword" },
      { "type": "fill", "target": "#remember-me", "value": "true" },
      { "type": "click", "target": "button[type=submit]", "waitFor": ".dashboard" },
      { "type": "screenshot" }
    ]
  }
}

Full Page Screenshot

{
  "tool": "captureScreenshot",
  "params": {
    "url": "https://docs.modelcontextprotocol.io",
    "steps": [
      { "type": "screenshot", "fullPage": true }
    ]
  }
}

With Authentication and Cookies

{
  "tool": "captureScreenshot",
  "params": {
    "url": "https://example.com/dashboard",
    "headers": {
      "authorization": "Bearer dev-token"
    },
    "steps": [
      {
        "type": "cookie",
        "action": "set",
        "name": "session",
        "value": "abc123",
        "path": "/secure"
      },
      { "type": "screenshot" }
    ]
  }
}

Extract DOM Content

{
  "tool": "extractDom",
  "params": {
    "url": "https://docs.modelcontextprotocol.io",
    "selector": "main article"
  }
}

Mobile Device Emulation

{
  "tool": "captureScreenshot",
  "params": {
    "url": "https://example.com",
    "steps": [
      { "type": "viewport", "device": "ipad-pro" },
      { "type": "scroll", "to": "#main-content" },
      { "type": "screenshot" }
    ]
  }
}

Step Types

6 Primary Steps (LLM-Exposed)

These are the only steps exposed to LLMs. They cover 95%+ of use cases:

Validate Mode (NEW)

Use validate: true to check steps before execution:

{
  "tool": "captureScreenshot",
  "params": {
    "url": "https://example.com",
    "steps": [
      { "type": "fill", "target": "#email", "value": "test@example.com" },
      { "type": "click", "target": "button" }
    ],
    "validate": true
  }
}

Returns validation analysis including:

• Errors: Missing required parameters
• Warnings: Step order issues (e.g., viewport not first)
• Suggestions: Recommended improvements (e.g., add waitFor to click)
• Step analysis: Per-step status and notes

Deprecated Steps (Legacy Support Only)

These work at runtime but are not exposed in the LLM schema. Use the 6 primary steps instead:

Internal Steps (Not Exposed)

These are for power users only and are not documented in the tool schema:

type, hover, cookie, storage, evaluate, keypress, focus, blur, clear, upload, submit

Legacy Parameter Support

For backward compatibility, these parameters work at runtime but are not exposed in the LLM schema:

Deprecation warnings are logged when legacy parameters are used.

Example response

{
  "content": [
    {
      "type": "text",
      "text": "mcp-page-capture screenshot\nURL: https://example.com\nCaptured: 2025-12-13T08:30:12.713Z\nFull page: false\nViewport: 1280x720\nDocument: 1280x2000\nScroll position: (0, 0)\nSize: 45.2 KB\nSteps executed: 5"
    },
    {
      "type": "image",
      "mimeType": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgA..."
    }
  ]
}

## Supported options

### `captureScreenshot`
- `url` (string, required): Fully-qualified URL to capture
- `headers` (object, optional): Key/value map of HTTP headers to send with the initial page navigation
- `cookies` (array, optional): List of cookies to set before navigation. Each cookie supports `name`, `value`, and optional `url`, `domain`, `path`, `secure`, `httpOnly`, `sameSite`, and `expires` (Unix timestamp, sec

…