MCP 服务器

pursr-mcp

Enables AI assistants to capture screenshots, run visual diffs, accessibility audits, and batch sweep plans for web pages via MCP tools.

README

<img src="assets/social-preview.svg" alt="pursr - visual QA, audit, and MCP for the browser" width="100%">

<h1 align="center">pursr</h1>

Visual QA, audit, and MCP for the browser. Capture - sweep - diff - audit - repeat - from the CLI, an MCP server, or as a library.

<a href="#install">Install</a> · <a href="#30-seconds">30 seconds</a> · <a href="#cli">CLI</a> · <a href="#mcp-server">MCP</a> · <a href="#library-api">Library</a> · <a href="#plugins">Plugins</a> · <a href="#roadmap">Roadmap</a>

Why pursr?

Most teams need five separate tools to do visual QA: a screenshot CLI, a regression diff runner, an accessibility auditor, a way to share captures with an AI assistant, and a way to turn all of that into a PDF report for stakeholders. pursr is all five - built as a single Node.js package with:

A unified CLI (pursr) for every capture, diff, sweep, and audit.
An MCP stdio server (pursr-mcp) so Claude Code, Cursor, and Continue can take screenshots, run sweeps, and inspect prior captures as MCP resources.
A library with 34 named exports and 18 subpath modules, so you can embed it in your own tooling.
A plugin system for custom viewports, sweep ops, and capture hooks.
PDF reports + AI diff summaries built in - render a sweep to a styled PDF or ask a vision LLM to describe the regression in plain language.
Zero browser bundled - drives your system Chrome via Playwright. No 200 MB Chromium download.

Install

npm install pursr
npm install --save-dev playwright-core   # peer dep - bring your own Chrome

Then verify:

pursr viewports         # list 10+ registered viewport presets
pursr probe https://example.com   # health check

30 seconds

# 1. Capture a screenshot with overlays
pursr shoot https://example.com shot.png \
  --preset desktop-1280 --grid --grid-tile 64

# 2. Save it as a visual baseline
pursr baseline save myapp shot.png home --url https://example.com

# 3. Next time you run, compare against the baseline
pursr diff https://example.com \
  ~/.pursr/baselines/myapp/<id>/home.png \
  diff.png

# 4. Or: run a batched sweep + a11y audit + parallel workers
pursr sweep ./plan.json   # see plans/ for an example

Features

Feature	Description	CLI flag
Multi-viewport capture	10+ presets (mobile, tablet, desktop, ultrawide)	`--preset mobile-375`
Layered states	entity / terrain / hud / ui isolation	`--layer entity`
Animation freeze	pause CSS/JS animations for stable frames	`--no-animation`
Cursor overlay	pointer / grab / grabbing / crosshair	`--cursor crosshair`
Grid overlay	spacing guides, custom color + tile size	`--grid --grid-tile 64`
Camera control	zoom + pan via mouse wheel/drag	`--zoom 1.5 --panX 200`
Frame timeline	N captures at intervalMs for animations	`pursr frames <url> 8 200`
Hover capture	text=/role=/aria=/placeholder= matchers	`pursr hover <url> "text=Login"`
Pixel diff	`pixelmatch` against any reference PNG	`pursr diff <url> <ref>`
Visual baselines	save / approve / diff with stable IDs	`pursr baseline save ...`
Parallel sweep	opt-in worker pool across independent steps	`{ "parallel": 4 }`
Accessibility audit	axe-core WCAG 2.1 AA + highlighted screenshot	`pursr audit <url>`
DOM snapshot	serialized HTML + computed styles + selector map	`pursr dom <url>`
Sweep plans	JSON-driven batch with per-step ops	`pursr sweep plan.json`
HTML report	dark-themed grid of every capture + meta	auto-generated `index.html`
CI output	JUnit XML, GitHub Actions annotations, Markdown	written on every sweep
Auto-heal selectors	fallback chain + named matchers	`["text=Login", "#login"]`
HAR capture	HAR 1.2 spec, written next to your shot	`--har ./req.har.json`
Auth state	Playwright storageState, reuse logged-in sessions	`--auth-state admin`
Plugins	custom viewports, sweep ops, before/after hooks	`pursr-plugin-*`
MCP server	7 tools + resources/list & resources/read for Claude/Cursor	`npx pursr-mcp`
PDF report	render sweep.json to a styled, embedded-PNG A4 PDF	`pursr report --sweep ./sweep.json`
AI diff summary	vision LLM describes the diff in plain language	`pursr diff ... --ai`

CLI

# Health check
pursr probe https://example.com

# Screenshot (simple)
pursr shot https://example.com ./out/shot.png

# Rich capture: viewport preset + cursor + grid
pursr shoot https://example.com \
  --preset desktop-1280 \
  --cursor crosshair \
  --grid --grid-tile 64

# Isolate a layer
pursr layer https://example.com entity

# Animation timeline
pursr frames https://example.com 8 200 ./frames/

# Hover an element
pursr hover https://example.com "text=Login"

# Pixel diff vs reference
pursr diff https://example.com ./ref.png ./out/diff.png

# Batched plan
pursr sweep ./plan.json

# Accessibility audit
pursr audit https://example.com --tags wcag2a,wcag2aa

# DOM + selector map snapshot
pursr dom https://example.com

# HAR capture during a shoot
pursr shoot https://example.com shot.png --har ./req.har.json

# Auth state reuse
pursr shoot https://my.app/dashboard shot.png \
  --auth-state admin --auth-project myapp

# Visual baselines
pursr baseline save myapp shot.png home --url https://example.com
pursr baseline list myapp
pursr baseline approve myapp ./new.png home --url https://example.com

# Plan validation
pursr validate ./plan.json

Subcommands

Subcommand	Purpose
`probe`	Health check (HTTP status, page title)
`shot` / `full`	Viewport / full-page screenshot
`eval`	Execute JS in the page, return result
`click` / `type` / `wait` / `seq`	Interaction primitives
`diff`	Pixel-level diff vs a reference PNG
`viewports`	List all registered viewport presets
`shoot`	Rich capture (overlays, freeze, camera, plugins)
`layer`	Capture one isolated layer (entity/hud/ui/terrain)
`frames`	N-frame animation timeline at interval
`hover`	Hover state capture
`sweep`	Batched capture plan -> HTML report + CI output
`audit`	axe-core WCAG accessibility audit + highlighted screenshot
`dom` / `dom-snapshot`	Serialized DOM + CSS selectors + XPath + bounding rects
`every-viewport`	Capture once per preset in parallel (3-wide pool)
`baseline`	save / list / approve / show visual baselines
`auth`	save / load / list / delete Playwright storageState
`validate`	Validate a sweep plan JSON without running it

MCP Server

pursr-mcp exposes every capability as MCP tools over stdio - works with Claude Code, Cursor, Continue, and any MCP host.

npx pursr-mcp
# or with verbose logging:
npx pursr-mcp --verbose

Exposed Tools

Tool	Description
`pursr_shoot`	Rich screenshot capture (viewport, grid, layer, cursor, camera, animation freeze, HAR)
`pursr_diff`	Pixel-diff a URL against a reference PNG
`pursr_sweep`	Execute a batch sweep plan
`pursr_frames`	Capture an N-frame animation timeline
`pursr_probe`	Health-check a URL
`pursr_audit`	axe-core WCAG audit + highlighted screenshot
`pursr_dom_snapshot`	Full DOM + selector map snapshot

Exposed Resources

URI	Description
`pursr://shoot/<url	preset>`
`pursr://sweep/<plan-name>`	Last sweep summary JSON (application/json)

Resources are persisted to ~/.pursr/mcp/mcp-index.json (override with PURSR_MCP_STATE).

Visual Regression Baselines

pursr baseline save myapp ./out/shoot.png home --url https://my.app
pursr baseline approve myapp ./out/shoot.png home --url https://my.app
pursr baseline list myapp
pursr baseline show myapp home --url https://my.app

Baselines live under ~/.pursr/baselines/<project>/<id>/<step>.png + manifest.json. Override with PURSR_BASELINES_DIR. The id is a 16-char SHA1 prefix of url|viewport|flags so re-running a sweep maps to the same slot deterministically.

import { diffKey, saveBaseline, loadBaseline } from "pursr/baseline";
const id = diffKey({ url: "https://my.app", viewport: { width: 1280, height: 800, dpr: 1 }, flags: { preset: "desktop-1280" } });
saveBaseline({ project: "myapp", id, step: "home", png: "./shot.png", meta: { url: "https://my.app" } });

Sweep Plan Validation

pursr validate ./plan.json
# { "valid": false, "errors": ["steps[2].frames.count: must be a number between 1 and 120"] }

Catches: empty steps, unknown ops, out-of-range numbers, duplicate names, missing required fields. pursr sweep runs the same validator before executing - fail-fast.

{
  "name": "homepage-matrix",
  "base": "https://example.com",
  "parallel": 4,
  "steps": [
    { "name": "baseline",   "shoot":  { "preset": "desktop-1280" } },
    { "name": "grid-64",    "shoot":  { "preset": "desktop-1280", "grid": true, "grid-tile": 64 } },
    { "name": "tablet",     "shoot":  { "preset": "tablet-768" } },
    { "name": "mobile",     "shoot":  { "preset": "mobile-375" } },
    { "name": "hover-cta",  "hover":  { "selector": ["text=Get started", "a.btn-primary"] } },
    { "name": "audit",      "audit":  { "tags": "wcag2a,wcag2aa" } },
    { "name": "diff",       "diff":   { "ref": "baseline" } }
  ]
}

HAR Capture

pursr shoot https://example.com shot.png --har ./out/req.har.json

import { startHarCapture, stopHarCapture, writeHar } from "pursr/har";
const state = await startHarCapture(page);
await page.goto(url);
const har = stopHarCapture(page);
await writeHar(har, "./out/req.har.json");

Output is HAR 1.2 spec - pipe to har-cli, perf-tools, or any visualizer.

Auth State

pursr auth save myapp admin --from ./playwright-state.json
pursr shoot https://my.app/dashboard shot.png --auth-state admin --auth-project myapp
pursr auth list myapp
pursr auth load myapp admin --out ./round-trip.json
pursr auth delete myapp admin

States live in ~/.pursr/auth/<project>/<name>.json (override with PURSR_AUTH_DIR). The on-disk format is the standard Playwright storageState shape: { cookies, origins }.

Parallel Sweep

Add parallel: N to your plan to run steps concurrently in a worker pool:

{
  "name": "matrix",
  "base": "https://my.app",
  "parallel": 4,
  "steps": [
    { "name": "home",    "shoot": { "preset": "desktop-1280" } },
    { "name": "pricing", "shoot": { "preset": "desktop-1280" } },
    { "name": "docs",    "shoot": { "preset": "desktop-1280" } }
  ]
}

Steps run in a shared browser context; results are still ordered by index in the summary. Defaults to serial (parallel: 1) - opt in only when steps are independent.

Accessibility Audit

pursr audit https://example.com --tags wcag2a,wcag2aa
# Writes: audit.json, audit-summary.md, audit-highlighted.png

Injects axe-core, runs a configurable tag set (wcag2a, wcag2aa, wcag21a, wcag21aa, best-practice), and overlays a red outline on every violating node with the rule id as a label. The summary Markdown includes per-rule failure snippets.

DOM Snapshot

pursr dom https://example.com
# Writes: dom-snapshot-<ts>.dom.json

Captures serialized HTML, computed CSS for every visible element, and a selector map (id, role, accessible name, text, xpath, css selector, viewport-relative rect). Great for regression diffing without re-running a browser.

CI Output

Every sweep writes three sidecar artifacts alongside sweep.json:

sweep.junit.xml - JUnit XML for Jenkins / GitLab / CircleCI
sweep.github.json - GitHub Actions annotation file
sweep.md - Human-readable Markdown summary with diffs + failures

Library API

import {
  runProbe, runShot, runShoot, runSweep, runDiff, runAudit,
  captureDomSnapshot, resolveHealedSelector,
  saveBaseline, diffKey,
  startHarCapture, stopHarCapture, writeHar,
  loadAuthState,
  PursrMCPServer, loadMcpConfig,
  validateSweepPlan,
  listResources, readResource,
  listViewports, resolveViewport, VIEWPORTS,
  loadPlugins, registerPlugin, getSweepOp,
  VERSION,
} from "pursr";

Subpath exports

import { resolveLocator } from "pursr/selector";
import { launch } from "pursr/runway";
import { parseFlags, asNum } from "pursr/util";
import { overlayGrid } from "pursr/overlays";
import { captureDomSnapshot } from "pursr/dom-snapshot";
import { runAudit } from "pursr/plugin-audit";
import { resolveHealedSelector } from "pursr/selector-heal";
import { writeCiOutput } from "pursr/ci-output";
import { diffKey, saveBaseline, loadBaseline } from "pursr/baseline";
import { validateSweepPlan } from "pursr/sweep-schema";
import { startHarCapture, stopHarCapture } from "pursr/har";
import { saveAuthState, loadAuthState } from "pursr/auth";
import { listResources, readResource } from "pursr/mcp-resources";
import { PursrMCPServer } from "pursr/mcp";

Plugins

A plugin is a plain ES module that exports a default object:

// plugins/my-plugin.js
export default {
  name: "my-plugin",
  viewport: { "my-laptop": { width: 1440, height: 900, dpr: 2, label: "MBP 14" } },
  sweepOp: {
    lighthouse: async (ctx, opts) => { /* ... */ },
  },
  beforeShoot: async (ctx) => { /* mutate ctx.flags / ctx.viewport */ },
  afterShoot:  async (ctx, meta) => { /* augment sidecar */ },
  flagHelp:    { "my-flag": "what it does" },
};

Plugins are auto-loaded from plugins/ (built-in) or via --plugin <path>.

Architecture

src/
  index.js          - public library entry
  mcp.js            - MCP stdio server (JSON-RPC 2.0)
  shoot.js          - runShoot (overlays + camera + frame-stable)
  sweep.js          - runSweep (validated, parallel pool)
  diff.js           - pixelmatch wrapper
  plugin-audit.js   - axe-core injection + highlighted screenshot
  dom-snapshot.js   - full DOM + CSSOM + selector map
  selector-heal.js  - auto-heal chain resolver
  ci-output.js      - JUnit / GitHub / Markdown
  baseline.js       - visual regression storage
  har.js            - HAR 1.2 network capture
  auth.js           - Playwright storageState
  sweep-schema.js   - plan validator
  mcp-resources.js  - MCP resources adapter
  overlays.js       - page-side CSS overlays + camera
  runway.js         - Playwright launcher + system-Chrome detector
  viewport.js       - built-in viewport presets
  selector.js       - text=/role=/aria=/placeholder= parser
  plugin.js         - plugin registry + hook runner
  util.js           - flags, args, hashing, HTML escape, renderSweepHtml
  every-viewport.js - one shot per preset in parallel
  frames.js, hover.js, shot.js, eval.js, probe.js, interact.js

Development

git clone https://github.com/0xheycat/pursr
cd pursr
npm install
npm install --save-dev playwright-core
npm test

npm test runs 63 unit + integration tests (Node's built-in test runner, zero test deps). Coverage includes: viewport resolution, flag parsing, selector parsing, HTML escaping, hashing, baseline storage, sweep-plan validation, MCP resources, HAR 1.2 shape, auth state, and end-to-end CLI smoke tests.

src/           - 29 modules
test/          - 63 tests, 0 failures
plugins/       - 2 built-in plugins, auto-loaded

Roadmap

[x] Visual baselines (save / approve / diff)
[x] Sweep plan schema validation
[x] MCP resources (browse past captures from your AI host)
[x] HAR 1.2 capture
[x] Auth state (Playwright storageState)
[x] Parallel sweep workers
[x] Watch mode (pursr watch <url>)
[x] Component-level snapshot (pursr snap <selector>)
[x] PDF report export (pursr report --sweep)
[ ] Cloud output adapters (S3 / GCS)
[x] AI diff summary (vision model, --ai)

PDF Report (v0.6.0)

Turn any sweep summary into a styled, self-contained A4 PDF you can email, attach to a PR, or hand to a designer.

# 1. Run a sweep (writes sweep.json + index.html + per-step PNGs)
pursr sweep ./plans/marketing.json

# 2. Generate a PDF from the most recent sweep
pursr report --sweep ./out/sweep-marketing/sweep.json --out ./out/report.pdf

# Or: skip image embedding for a tiny text-only report
pursr report --sweep ./out/sweep-marketing/sweep.json --no-embed

The PDF includes a colored header (pursr brand magenta), a summary stat grid (steps / passed / failed / total time), and a per-step card with: status badge, op + duration + URL, the embedded capture PNG, diff stats, audit violation count, and any error message. Page numbers in the footer.

Library:

import { renderSweepPdf } from "pursr/report";
import { readFileSync } from "node:fs";

const summary = JSON.parse(readFileSync("./sweep.json", "utf8"));
const bytes = await renderSweepPdf(summary, { out: "./report.pdf" });
console.log("wrote", bytes.length, "bytes");

AI Diff Summary (v0.6.0)

Add --ai to pursr diff and a vision LLM describes the differences in plain language alongside the pixel-diff percentage. Perfect for triaging a regression without opening the PNG.

# Basic
pursr diff https://my.app ./ref.png ./out/diff.png --ai

# Custom model + endpoint + key (e.g. local llama.cpp, Codex proxy, OpenAI)
pursr diff https://my.app ./ref.png ./out/diff.png \
  --ai --ai-model gh/gpt-5.4 \
  --ai-base-url http://127.0.0.1:20128/v1 \
  --ai-api-key sk-...

The AI summary is written to <out>.ai.json (or alongside the current PNG) and is also attached to the diff result object as r.ai = { aiSummary, aiModel, aiElapsedMs, aiAt }.

Auth is picked up from these env vars (in order):

PURSR_AI_API_KEY  (preferred)
PURSOR_AI_API_KEY (legacy alias)
ANTHROPIC_AUTH_TOKEN
OPENAI_API_KEY

Base URL: PURSR_AI_BASE_URL (falls back to ANTHROPIC_BASE_URL then https://api.openai.com/v1). Model: PURSR_AI_MODEL (falls back to ANTHROPIC_DEFAULT_SONNET_MODEL then gpt-4o).