compare_screenshots

Compare visual changes between two URLs by capturing screenshots at identical viewport sizes, calculating difference percentages, and verifying UI modifications.

Instructions

Before/after visual comparison. Captures screenshots of two URLs at the same viewport size, returns BOTH images for visual comparison, and calculates a difference percentage. Use this to verify UI changes, compare staging vs production, or check before/after states of a redesign.

Input Schema

TableJSON Schema

Name	Required	Description
`urlA`	Yes	First URL — the 'before' state (e.g., http://localhost:3000)
`urlB`	Yes	Second URL — the 'after' state (e.g., http://localhost:3001)
`width`	No	Viewport width in pixels
`height`	No	Viewport height in pixels

Implementation Reference

src/tools/compare.ts:101-124 (handler)

The compareScreenshots function implements the logic for comparing two URLs visually.

export async function compareScreenshots(
  urlA: string,
  urlB: string,
  options?: { readonly width?: number; readonly height?: number }
): Promise<ComparisonResult> {
  const width = options?.width ?? 1440;
  const height = options?.height ?? 900;

  const screenshotA = await captureUrlScreenshot(urlA, width, height);
  const screenshotB = await captureUrlScreenshot(urlB, width, height);

  const differencePercent = calculateBase64DifferencePercent(
    screenshotA.base64,
    screenshotB.base64
  );

  return {
    screenshotA,
    screenshotB,
    differencePercent,
    urlA,
    urlB,
  };
}

src/tools/compare.ts:5-20 (schema)

Type definitions for the comparison screenshot and result.

export interface ComparisonScreenshot {
  readonly base64: string;
  readonly mimeType: "image/png";
  readonly width: number;
  readonly height: number;
  readonly url: string;
  readonly timestamp: string;
}

export interface ComparisonResult {
  readonly screenshotA: ComparisonScreenshot;
  readonly screenshotB: ComparisonScreenshot;
  readonly differencePercent: number;
  readonly urlA: string;
  readonly urlB: string;
}

src/server.ts:404-412 (registration)

The compare_screenshots tool is registered here with its input schema definition.

server.tool(
  "compare_screenshots",
  "Before/after visual comparison. Captures screenshots of two URLs at the same viewport size, returns BOTH images for visual comparison, and calculates a difference percentage. Use this to verify UI changes, compare staging vs production, or check before/after states of a redesign.",
  {
    urlA: z.string().url().describe("First URL — the 'before' state (e.g., http://localhost:3000)"),
    urlB: z.string().url().describe("Second URL — the 'after' state (e.g., http://localhost:3001)"),
    width: z.number().optional().default(1440).describe("Viewport width in pixels"),
    height: z.number().optional().default(900).describe("Viewport height in pixels"),
  },

src/tools/compare.ts:29-53 (helper)

Helper function to calculate the percentage difference between two base64 strings.

function calculateBase64DifferencePercent(
  base64A: string,
  base64B: string
): number {
  if (base64A === base64B) {
    return 0;
  }

  const maxLength = Math.max(base64A.length, base64B.length);

  if (maxLength === 0) {
    return 0;
  }

  let differingCharacters = 0;

  for (let i = 0; i < maxLength; i++) {
    if (base64A[i] !== base64B[i]) {
      differingCharacters++;
    }
  }

  const rawPercent = (differingCharacters / maxLength) * 100;
  return Math.round(rawPercent * 100) / 100;
}

mcp-uimax