<p align="center"><img src="assets/fathom-header-banner.svg" alt="Fathom Works — impeccable-mcp" width="100%"></p>

# `$ impeccable-mcp`

**Checks a web page for common design mistakes and tells your AI assistant what it found.** It uses [impeccable](https://github.com/pbakaus/impeccable)'s 59 fixed rules in a headless Chrome browser (one with no window), so no AI model or API key is needed for the check itself.

**In plain terms:** this is for people who use an AI assistant to build websites. The assistant can ask this service to look at a page and report layout, color and accessibility problems.

*A [Fathom Works](https://github.com/Jemplayer82) project.*

## `[ quick start ]`

Run the service in Docker. It listens on port 8000 and needs a secret token that you make up.

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

Point your MCP client (MCP = a plug-in standard that lets an AI assistant use a tool) at this address:

```
http://localhost:8000/mcp
```
Send the header `Authorization: Bearer <IMPECCABLE_MCP_TOKEN>`.

## `[ usage ]`

Your assistant can call four tools. You normally just ask it to check a page.

| Tool | Needs a browser | What it does |
|---|---|---|
| `scan_url` | yes | Opens a URL and returns findings, grouped as `slop` (signs of AI-made design) or `quality` (accessibility and design issues). Accepts optional `headers` / `cookies` for pages that need a login. |
| `scan_html` | no | Checks raw HTML/CSS text. Use it on markup before it is saved to disk. |
| `screenshot` | yes | Returns a PNG picture of the page. |
| `list_rules` | no | Lists every rule with its id, name, category and description. |

> **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.

By default `scan_url` and `screenshot` refuse addresses on your own network (RFC1918, loopback and link-local targets). This stops a tricked assistant from probing your home or office network. Set `IMPECCABLE_ALLOW_PRIVATE=1` only if you need to scan an internal site. Details are in [docs/how-it-works.md](docs/how-it-works.md).

## `[ configuration ]`

Set these as environment variables on the container.

| Variable | Required | What it does |
|---|---|---|
| `IMPECCABLE_MCP_TOKEN` | Yes | Bearer token clients must send. Server refuses to start if unset. |
| `PORT` | No | Listen port inside the container. Default `8000`. |
| `IMPECCABLE_ALLOW_PRIVATE` | No | Set to `1` to allow scans of RFC1918/loopback/link-local targets. Default off. |
| `MAX_CONCURRENCY` | No | Max concurrent browser-backed scans. Default `2`. |
| `BROWSER_IDLE_TIMEOUT_MS` | No | Close the idle browser after this long with no scans. Default `300000` (5 min). |

## `[ docs ]`

- [docs/docker-compose.md](docs/docker-compose.md) — run it with Docker Compose
- [docs/how-it-works.md](docs/how-it-works.md) — design notes and the private-target guard
- [impeccable](https://github.com/pbakaus/impeccable) — the rule engine (don't file issues/PRs there from this project; see `CONTRIBUTING.md`)
- [gsd-browser-mcp](https://github.com/Jemplayer82/gsd-browser-mcp) — the sibling MCP this repo's transport, auth, and Dockerfile pattern were cloned from
- [Impeccable Chrome extension](https://chromewebstore.google.com/detail/impeccable/bdkgmiklpdmaojlpflclinlofgjfpabf) — same rules, for a person looking at DevTools directly. This server is for agents.

## `[ license ]`

Apache License 2.0 — see `LICENSE`.

<img src="assets/fathom-footer-banner.svg" alt="Fathom Works — sound the depths before you set a course" width="100%">