mcp-design-comparison 0.1.0

package/AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+This file provides guidance to WARP (warp.dev) when working with code in this repository.
+
+## Project Overview
+
+This is an MCP (Model Context Protocol) server that exposes a single tool (`compare_design`) for comparing design screenshots with implementation screenshots using pixelmatch. The server communicates via stdio and is intended to be used by MCP clients like Claude Desktop.
+
+## Development Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript to dist/
+npm run build
+
+# Watch mode for development
+npm run watch
+```
+
+## Architecture
+
+### Single-file MCP Server (`src/index.ts`)
+
+The entire server is implemented in one file with three main components:
+
+1. **Image Processing Functions**:
+   - `loadPNG()`: Reads PNG files using pngjs
+   - `compareScreenshots()`: Core comparison logic using pixelmatch, returns metrics and diff image
+
+2. **MCP Server Setup**: 
+   - Uses `@modelcontextprotocol/sdk` with stdio transport
+   - Registers handlers for `ListToolsRequestSchema` and `CallToolRequestSchema`
+
+3. **Tool Implementation** (`compare_design`):
+   - Accepts two PNG paths, optional output path, and threshold (0-1)
+   - Returns text response with statistics + optional base64 image or saves to file
+   - Validates matching image dimensions before comparison
+
+### Key Constraints
+
+- Only PNG format is supported (via pngjs library)
+- Images must have identical dimensions
+- Server runs on stdio (not HTTP) - designed for local MCP client communication
+- Uses ES modules (`"type": "module"` in package.json)
+- TypeScript compilation uses `Node16` module resolution
+
+## Testing the Server
+
+There is no test framework yet. To test manually:
+
+1. Build the project: `npm run build`
+2. Configure an MCP client (e.g., Claude Desktop) to point to `dist/index.js`
+3. Use the `compare_design` tool with two PNG screenshots
+
+The server logs to stderr, so startup messages won't interfere with MCP stdio communication.

package/README.md

@@ -0,0 +1,114 @@
+# MCP Design Comparison Server
+
+An MCP (Model Context Protocol) server that allows LLMs to compare design screenshots with implementation screenshots using [pixelmatch](https://github.com/mapbox/pixelmatch). This tool helps identify visual discrepancies between design mockups and actual implementation.
+
+## Features
+
+- **Screenshot Comparison**: Compare two PNG images pixel-by-pixel
+- **Visual Diff Output**: Generate a highlighted diff image showing differences
+- **Detailed Metrics**: Get total pixels, different pixels, and percentage difference
+- **Configurable Threshold**: Adjust sensitivity of the comparison
+- **Base64 Support**: Return diff images as base64 or save to file
+
+## Installation
+
+### For End Users
+
+Install globally via npm:
+
+```bash
+npm install -g mcp-design-comparison
+```
+
+Or using npx (no installation required):
+
+```bash
+npx mcp-design-comparison
+```
+
+### For Development
+
+```bash
+git clone https://github.com/w01fgang/mcp-design-comparison.git
+cd mcp-design-comparison
+npm install
+npm run build
+```
+
+## Usage
+
+### As an MCP Server
+
+Add this server to your MCP client configuration. The server runs on stdio and provides a single tool:
+
+#### Tool: `compare_design`
+
+Compare a design screenshot with an implementation screenshot.
+
+**Parameters:**
+- `design_path` (string, required): Path to the design screenshot (PNG format)
+- `implementation_path` (string, required): Path to the implementation screenshot (PNG format)
+- `output_diff_path` (string, optional): Path to save the diff image. If not provided, the diff image will be returned as base64
+- `threshold` (number, optional): Matching threshold (0-1). Smaller values make the comparison more sensitive. Default is 0.1
+
+**Returns:**
+- Total number of pixels
+- Number of different pixels
+- Percentage difference
+- Diff image (as file or base64)
+
+### Configuration Example
+
+Add to your MCP settings file:
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "design-comparison": {
+      "command": "npx",
+      "args": ["-y", "mcp-design-comparison"]
+    }
+  }
+}
+```
+
+**Cursor** (`~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "design-comparison": {
+      "command": "npx",
+      "args": ["-y", "mcp-design-comparison"]
+    }
+  }
+}
+```
+
+After adding the configuration, restart Claude Desktop or Cursor.
+
+## How It Works
+
+1. Loads both PNG images into memory
+2. Validates that dimensions match
+3. Uses pixelmatch to compare pixel-by-pixel
+4. Generates a diff image highlighting differences in pink
+5. Returns statistics and the diff image
+
+## Example Use Cases
+
+- **Design QA**: Verify that implementation matches design mockups
+- **Regression Testing**: Compare screenshots before and after changes
+- **Cross-browser Testing**: Compare renders across different browsers
+- **Responsive Design**: Compare layouts at different breakpoints
+
+## Requirements
+
+- Node.js 18+
+- PNG images with matching dimensions
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import fs from "fs/promises";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+async function loadPNG(filePath) {
+    const data = await fs.readFile(filePath);
+    return PNG.sync.read(data);
+}
+async function compareScreenshots(designPath, implementationPath, outputDiffPath, threshold = 0.1) {
+    // Load both images
+    const design = await loadPNG(designPath);
+    const implementation = await loadPNG(implementationPath);
+    // Check if dimensions match
+    if (design.width !== implementation.width ||
+        design.height !== implementation.height) {
+        throw new Error(`Image dimensions don't match: design (${design.width}x${design.height}) vs implementation (${implementation.width}x${implementation.height})`);
+    }
+    // Create a diff image
+    const diff = new PNG({ width: design.width, height: design.height });
+    // Compare images using pixelmatch
+    const differentPixels = pixelmatch(design.data, implementation.data, diff.data, design.width, design.height, { threshold });
+    const totalPixels = design.width * design.height;
+    const differencePercentage = (differentPixels / totalPixels) * 100;
+    const result = {
+        totalPixels,
+        differentPixels,
+        differencePercentage,
+    };
+    // Save or encode diff image
+    if (outputDiffPath) {
+        await fs.writeFile(outputDiffPath, PNG.sync.write(diff));
+    }
+    else {
+        // Return base64 encoded diff image
+        const buffer = PNG.sync.write(diff);
+        result.diffImageBase64 = buffer.toString("base64");
+    }
+    return result;
+}
+// Create server instance
+const server = new Server({
+    name: "mcp-design-comparison",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "compare_design",
+                description: "Compare a design screenshot with an implementation screenshot using pixelmatch. Returns the number and percentage of different pixels, and optionally outputs a diff image highlighting the differences.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        design_path: {
+                            type: "string",
+                            description: "Path to the design screenshot (PNG format)",
+                        },
+                        implementation_path: {
+                            type: "string",
+                            description: "Path to the implementation screenshot (PNG format)",
+                        },
+                        output_diff_path: {
+                            type: "string",
+                            description: "Optional path to save the diff image. If not provided, the diff image will be returned as base64.",
+                        },
+                        threshold: {
+                            type: "number",
+                            description: "Matching threshold (0-1). Smaller values make the comparison more sensitive. Default is 0.1.",
+                            default: 0.1,
+                        },
+                    },
+                    required: ["design_path", "implementation_path"],
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name === "compare_design") {
+        const { design_path, implementation_path, output_diff_path, threshold = 0.1, } = request.params.arguments;
+        try {
+            const result = await compareScreenshots(design_path, implementation_path, output_diff_path, threshold);
+            let responseText = `Design Comparison Results:\n\n`;
+            responseText += `Total Pixels: ${result.totalPixels.toLocaleString()}\n`;
+            responseText += `Different Pixels: ${result.differentPixels.toLocaleString()}\n`;
+            responseText += `Difference: ${result.differencePercentage.toFixed(2)}%\n`;
+            if (output_diff_path) {
+                responseText += `\nDiff image saved to: ${output_diff_path}`;
+            }
+            const content = [
+                {
+                    type: "text",
+                    text: responseText,
+                },
+            ];
+            // If we have base64 image data, include it
+            if (result.diffImageBase64) {
+                content.push({
+                    type: "image",
+                    data: result.diffImageBase64,
+                    mimeType: "image/png",
+                });
+            }
+            return {
+                content,
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error comparing screenshots: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    throw new Error(`Unknown tool: ${request.params.name}`);
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Design Comparison Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "mcp-design-comparison",
+  "version": "0.1.0",
+  "description": "MCP server for comparing design screenshots with implementation using pixelmatch",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-design-comparison": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "design",
+    "comparison",
+    "screenshot",
+    "pixelmatch"
+  ],
+  "author": "wolf",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/w01fgang/mcp-design-comparison.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "pixelmatch": "^7.0.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pixelmatch": "^5.2.6",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5.7.0"
+  }
+}