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 | Default |
|---|---|---|---|
| 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; }