# pixelgrade

pixelgrade lets you check whether the advertising
pixels on a page actually work, without opening a
browser yourself. Give it a landing page and it
grades the Meta, TikTok and OpenAI pixels it finds
there: whether they wait for cookie consent, whether
the same event fires twice, whether event IDs line
up between the browser and any server copy, and
whether the click IDs that ads append — `fbclid`
becoming `_fbc`, for example — are captured. When
something is wrong you get the finding, an
explanation, and a step-by-step guide for fixing it
on your platform.

The package itself checks nothing locally. It is a
thin bridge to the hosted pixel-check service: it
answers the tool list from a verbatim capture of
that service and forwards every tool call upstream,
returning the reply untouched. All four tools are
read-only. Checking reads a page you name; reading a
report, listing findings and reading a fix guide
change nothing, install nothing and touch no ad
account.

## Tools

- `check_page` — check a page's pixels and grade
  each one. Required: `url` (the page to check,
  usually the landing page the ads point to, 3 to
  2048 characters). Optional: `recheck` (start a
  fresh check instead of reusing a result from the
  last 24 hours; allowed once the last check is an
  hour old) and `wait_seconds` (0 to 45, default
  40; a check takes 20 to 60 seconds, and if it is
  still running you can poll with `get_report`).
  An EU browser visits the page twice so consent
  behaviour is exercised.
- `get_report` — read the result of an earlier
  check. Required: `report` (a report id such as
  `Ab3dE5fG7hJ9kL2m`, or the full report link,
  8 to 200 characters). Returns the status, a grade
  per pixel found, each problem with its explanation
  and fix-guide link, and a checklist. Reports are
  kept for 90 days.
- `list_findings` — list every problem a check can
  report. Takes no arguments. Each entry carries its
  id, severity, title and explanation, and whether a
  fix guide exists for it. Useful for learning the
  catalogue before you run a check.
- `get_fix_guide` — read the step-by-step fix guide
  (Markdown) for a problem. All arguments are
  optional: `issue_id` (a problem id from a report,
  for example `meta.fires_before_consent`), `platform`
  (for example `framer`, `shopify`, `webflow`,
  `wordpress`; when omitted or unknown the general
  version is returned) and `consent_tool` (one of
  `complianz`, `cookiebot`, `cookieyes`, `onetrust`,
  `usercentrics`; when given, the guide covers wiring
  the Meta, TikTok and OpenAI pixels to that consent
  tool). Setup guides are also available through
  `issue_id`, for example the Meta Conversions API,
  the TikTok Events API, and installing the OpenAI
  Pixel or its Conversions API.

## Configuration

- `ISPIXELWORKING_MCP_URL` (optional) — override the
  upstream endpoint. Defaults to
  `https://ispixelworking.com/mcp`. (The override
  hook is this rebuild's own labelled reconstruction.)
- `ISPIXELWORKING_API_KEY` (optional) — when set,
  every upstream request carries an
  `Authorization: Bearer <key>` header. When it is
  not set, no key header is sent. (The header name
  is pinned by the original's registry record, which
  declares a secret `Authorization` header; the
  record pins no package env name, so the Bearer
  form and forwarding the key from this env var are
  labelled reconstructions — the original surface
  was captured keyless.)

### Forwarding mechanics

On the first tool call the client opens a streamable
HTTP session upstream: a JSON-RPC `initialize`
request (protocolVersion `2025-03-26`, clientInfo
name `pixelgrade`), then a
`notifications/initialized` notification, then the
`tools/call` request carrying the caller's arguments
unchanged. When the upstream answers `initialize`
with an `Mcp-Session-Id` header, that value rides on
every later request of the session, which is reused
for the life of the process. Replies may arrive as
plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim,
including any `isError` flag the upstream sets.
Failures — a JSON-RPC error, a non-2xx status, an
unreadable response, or a request that cannot be
completed — come back as an `isError` result whose
text starts with `pixelgrade error:` (this rendering
is this rebuild's own labelled reconstruction).

## CLI

Each tool is also a subcommand taking one JSON
argument string:

```bash
npx @reneturcios/pixelgrade check_page '{"url":"https://example.com/landing"}'
npx @reneturcios/pixelgrade get_report '{"report":"Ab3dE5fG7hJ9kL2m"}'
npx @reneturcios/pixelgrade get_fix_guide '{"issue_id":"meta.fires_before_consent","platform":"shopify"}'
npx @reneturcios/pixelgrade list_findings '{}'
npx @reneturcios/pixelgrade --version
```

Exit codes: `0` on success, `1` on an `isError`
result, `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/pixelgrade mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "pixelgrade": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pixelgrade", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/pixelgrade
docker run --rm ghcr.io/cloudcorprecords/pixelgrade --version
```

The container's default command is `mcp`, so the first
form is a stdio MCP server; any other arguments reach
the CLI normally.

## Development

```bash
npm install
npm run build
npm test
npm run dev
```

The test suite runs entirely against a stubbed
JSON-RPC upstream — no live network calls.

## License

MIT — see `LICENSE`.