Docs

Getting started

Set up Pixel Not Perfect in three steps.

Step 1

Add the server to your MCP client

Any agent or editor that speaks MCP can use it. Needs Node.js 20 or later and Chrome or Chromium. Run this command, then choose which agents to add it to.

npx add-mcp @codeandfunction/pixelnotperfect --env "PIXELNOTPERFECT_ALLOWED_ROOTS=~/Designs" -g

Set PIXELNOTPERFECT_ALLOWED_ROOTS to the folders that hold your reference images and PDFs. To set it up by hand instead, add this to your MCP client's configuration:

{
  "mcpServers": {
    "pixelnotperfect": {
      "command": "npx",
      "args": ["-y", "@codeandfunction/pixelnotperfect"],
      "env": {
        "PIXELNOTPERFECT_ALLOWED_ROOTS": "~/Designs"
      }
    }
  }
}

Step 2

Ask your agent to compare

The agent renders, compares, fixes and repeats until the page is within threshold.

Compare http://localhost:3000/login with ~/Designs/login.png and fix the differences.

Step 3

Review with the extension

Ask for a visual review, open the page, and click Review this tab. The extension asks for access to that one site only. Needs Chrome 130 or later. Reviews work on HTTPS sites and on local HTTP sites (localhost, 127.0.0.1 and [::1]). If it can't find your agent, run:

npx @codeandfunction/pixelnotperfect install-native-host

Add to Chrome

Configuration

Set these in the env block of the server's entry in your MCP client. All are optional.

PIXELNOTPERFECT_ALLOWED_ROOTS

Extra folders the agent can read reference images and PDFs from, separated by commas. The agent can read every folder you list, so keep it narrow.

Default: Working and temporary folders

PIXELNOTPERFECT_CHROME_PATH

Path to the Chrome or Chromium program used to render pages.

Default: Detected

PIXELNOTPERFECT_DATA_DIR

Where reviews and comparison images are kept.

Default: A .pixelnotperfect folder in the system temporary folder

PIXELNOTPERFECT_REVIEW_PORT

Port of the local review server the extension talks to, from 0 to 65535.

Default: Any free port

PIXELNOTPERFECT_HOST_REGISTRATION

Set to off to stop the server connecting itself to the extension when it starts.

Default: On

Prompts

The server ships ready-made MCP prompts. Clients that support prompts list them, often as slash commands. The reference can be an image, a PDF or a URL.

`visual_diff`

Compares the page with the reference and reports what differs, without changing any code.

targetUrl / reference / selector / misMatchThreshold / pdfPage

`self_healing_ui`

Compares, proposes a fix plan for you to approve, applies it and compares again, until the page is within the threshold or the iterations run out.

targetUrl / reference / maxIterations / misMatchThreshold / selector / pdfPage

`visual_review`

Starts a visual review of the page and waits for the feedback you pin with the extension.

targetUrl