$ impeccable-mcp

An MCP server wrapping impeccable's design-lint engine — headless Chrome plus 59 deterministic anti-pattern rules — so any agent can scan a URL and get back structured findings, no per-agent setup required. No LLM, no API key needed for the scan itself; the engine is pure detection.

[ what it does ]

• Takes impeccable's public library exports (detectUrl, detectHtml, ANTIPATTERNS, createBrowserDetector) — an official npm dependency, not a fork — and exposes them as MCP tools

• Runs one long-lived headless Chromium instance, each scan in its own incognito context

• Serves MCP over streamable HTTP on port 8000, same shape as gsd-browser-mcp

• Lets any MCP client (Claude Code, Fred, Billy, whatever's next) scan a website's design without local setup

Related MCP server: scribe-me

[ tools ]

Header/cookie values you pass to scan_url will appear in the calling agent's transcript. That's a deliberate tradeoff for reaching authenticated pages, not an oversight — see CONTRIBUTING.md. Don't pass anything you wouldn't want logged.

The private-target guard

scan_url and screenshot refuse RFC1918, loopback, and link-local targets by default. This service's whole job is "fetch whatever URL an agent hands it" — without the guard, a prompt-injected agent could turn it into a LAN port scanner or point it at Portainer/Home Assistant from inside the trusted network. Set IMPECCABLE_ALLOW_PRIVATE=1 only if you specifically need to scan an internal site and understand the tradeoff.

[ quick start ]

1. pull and run

$ docker run -d \
  -p 8000:8000 \
  --shm-size=512mb \
  -e IMPECCABLE_MCP_TOKEN=$(openssl rand -hex 32) \
  ghcr.io/jemplayer82/impeccable-mcp:latest

2. connect your mcp client

http://localhost:8000/mcp

with Authorization: Bearer <IMPECCABLE_MCP_TOKEN>.

[ docker compose ]

services:
  impeccable-mcp:
    image: ghcr.io/jemplayer82/impeccable-mcp:latest
    restart: unless-stopped
    shm_size: "512mb"
    mem_limit: 1536m
    init: true
    ports:
      - "8000:8000"
    environment:
      IMPECCABLE_MCP_TOKEN: your-token-here  # pragma: allowlist secret — doc placeholder
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8000/healthz"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

[ environment variables ]

[ how it works ]

A single Node/ESM process:

1. @modelcontextprotocol/sdk's StreamableHTTPServerTransport over raw node:http — stateless, a fresh server + transport per request, no session bookkeeping.

2. src/scan.mjs holds one Chromium via impeccable's createBrowserDetector, relaunching on crash and closing after BROWSER_IDLE_TIMEOUT_MS of inactivity. Each scan gets its own incognito browser context so headers/cookies from one call never leak into another.

3. Findings come back in impeccable's stable shape (antipattern, name, description, severity, category, snippet), grouped by category with a count summary.

impeccable itself needs no LLM and no API key — it's a deterministic rule engine. This server doesn't add one either; it's transport, auth, browser lifecycle, and a URL guard around a library.

[ related ]

• impeccable — the underlying detection engine (don't file issues/PRs there from this project; see CONTRIBUTING.md)

• gsd-browser-mcp — the sibling MCP this repo's transport, auth, and Dockerfile pattern were cloned from

• Impeccable Chrome extension — same rule engine, for a human looking at DevTools directly. This server exists for agents; the extension is still the right tool for eyeballing a page yourself.

[ license ]

Apache License 2.0 — see LICENSE.