@icjia/contrastcap 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Illinois Criminal Justice Information Authority (ICJIA)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# @icjia/contrastcap
+
+**MCP server for automated WCAG contrast auditing via pixel-level analysis.**
+
+`contrastcap` resolves the "needs review" gap that axe-core and SiteImprove leave behind. When text sits over a complex background (gradient, image, semi-transparent overlay), axe can't determine the rendered contrast ratio from the DOM alone and marks the element `incomplete`. `contrastcap` loads the page in headless Chromium, screenshots the element region with the text hidden, samples actual rendered pixels, and returns a decisive pass / fail / warning with a concrete hex color suggestion for failures.
+
+Built for the same triage workflow as `@icjia/lightcap` and `@icjia/viewcap` — stdio transport, ESM, minimal token footprint, `get_status` tool, `publish.sh`.
+
+---
+
+## Install
+
+```bash
+pnpm install
+# Playwright's Chromium is fetched automatically via postinstall.
+# If that fails (offline, CI), run manually:
+pnpm exec playwright install chromium
+```
+
+Requires Node 20+.
+
+## Claude Desktop / Claude Code configuration
+
+Add to `claude_desktop_config.json` (or your IDE's MCP config):
+
+```json
+{
+  "mcpServers": {
+    "contrastcap": {
+      "command": "npx",
+      "args": ["-y", "@icjia/contrastcap"]
+    }
+  }
+}
+```
+
+Or, pointing at a local checkout:
+
+```json
+{
+  "mcpServers": {
+    "contrastcap": {
+      "command": "node",
+      "args": ["/absolute/path/to/contrastcap-mcp/src/server.js"]
+    }
+  }
+}
+```
+
+Restart Claude to pick up the new server.
+
+---
+
+## Tools
+
+All four tools default to **WCAG AA**. `AAA` must be explicitly requested via `level: "AAA"`.
+
+### `get_contrast_summary`
+
+Counts only — the cheapest token footprint. Use this first to decide whether a full audit is warranted.
+
+```json
+{ "url": "https://example.com/about" }
+```
+
+Returns:
+
+```json
+{
+  "url": "https://example.com/about",
+  "timestamp": "2026-04-13T14:30:00Z",
+  "wcag_level": "AA",
+  "counts": {
+    "total_elements_checked": 52,
+    "pass": 47,
+    "fail": 3,
+    "warning": 2,
+    "skipped": 0
+  }
+}
+```
+
+### `check_page_contrast`
+
+Full page audit. Returns detail for failures and warnings only — passing elements are counted, not itemized.
+
+```json
+{ "url": "https://example.com/about", "level": "AA" }
+```
+
+Returns:
+
+```json
+{
+  "url": "...",
+  "timestamp": "...",
+  "wcag_level": "AA",
+  "summary": { "total": 52, "pass": 47, "fail": 3, "warning": 2, "skipped": 0 },
+  "failures": [
+    {
+      "selector": "nav.main-nav > ul > li:nth-child(3) > a",
+      "text": "Grant Opportunities",
+      "ratio": 3.21,
+      "required": 4.5,
+      "level": "AA",
+      "fontSize": "14px",
+      "fontWeight": "400",
+      "isLargeText": false,
+      "foreground": "#6c757d",
+      "background": "#e9ecef",
+      "backgroundSource": "pixel-sample",
+      "suggestion": "#595f64"
+    }
+  ],
+  "warnings": [
+    {
+      "selector": ".hero-banner h1",
+      "text": "Criminal Justice Information…",
+      "ratio": 4.62,
+      "required": 4.5,
+      "level": "AA",
+      "foreground": "#ffffff",
+      "background": "#5a7a91",
+      "backgroundSource": "pixel-sample-over-image",
+      "note": "Ratio within 0.3 of threshold — marginal. Background sampled from gradient or image — may vary at other positions."
+    }
+  ]
+}
+```
+
+**Suggestion format is always hex** (e.g. `"#595f64"`). The caller formats prose.
+
+### `check_element_contrast`
+
+Single-element check. Use this to verify a fix without re-running the full page audit.
+
+```json
+{
+  "url": "http://localhost:3000/about",
+  "selector": "nav.main-nav > ul > li:nth-child(3) > a"
+}
+```
+
+Returns a single-element object with `pass: true|false`, the measured `ratio`, `foreground`, `background`, and a `suggestion` hex if failing.
+
+### `get_status`
+
+Server + axe-core + Playwright versions, plus a non-blocking npm update check.
+
+---
+
+## How it works
+
+1. Playwright navigates to the URL (30s timeout, `networkidle` fallback to `load`).
+2. The server re-validates `page.url()` against the SSRF denylist (redirect guard).
+3. axe-core is injected via `page.evaluate` and run with `color-contrast` only. Its `violations` (definite failures) and `passes` (definite passes) are trusted as-is.
+4. For every `incomplete` (needs-review) node:
+   - Scroll into view
+   - Read computed `color`, `fontSize` (always resolved to px), `fontWeight`
+   - Save the element's prior inline `color`, set it to `transparent`, screenshot the bounding box, then restore
+   - Decode pixels via `sharp`, sample on a 5×3 grid
+   - If per-channel stddev > 15, treat as gradient/image and use worst-case pixel (darkest on light text, lightest on dark text)
+   - Otherwise take the median per channel
+   - Compute the WCAG 2.1 ratio and compare against the required threshold
+5. For failures, compute a hex color suggestion via 16-iteration HSL-lightness binary search in both directions; return whichever candidate has the smaller `|ΔL|` from the original foreground.
+6. Passes bump the `pass` count. Marginal passes or high-variance backgrounds are flagged as warnings, not failures.
+
+### Limits & timeouts
+
+| Scope | Limit |
+|-------|-------|
+| Page navigation | 30 s |
+| Per-element pixel sampling | 5 s (skipped on timeout, audit continues) |
+| Total audit | 120 s (returns `Audit timed out`) |
+| Max elements pixel-sampled per page | 200 |
+| Concurrent audits per process | 2 (queue-full error beyond that) |
+
+### What's out of scope (v1)
+
+- Authenticated pages (no cookie/session handling)
+- Multi-page crawling (use `a11yscan` for that)
+- Focus/hover state contrast
+- Dark-mode toggling
+- Non-text contrast (UI components, graphical objects)
+- Elements inside shadow DOM or cross-origin iframes (counted under `skipped`)
+- PDF contrast
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `CONTRASTCAP_NAV_TIMEOUT` | `30000` | Page navigation timeout (ms) |
+| `CONTRASTCAP_ELEMENT_TIMEOUT` | `5000` | Per-element pixel sampling timeout (ms) |
+| `CONTRASTCAP_AUDIT_TIMEOUT` | `120000` | Total audit cap (ms) |
+| `CONTRASTCAP_LEVEL` | `AA` | Default WCAG level (`AA` or `AAA`) |
+| `CONTRASTCAP_MAX_ELEMENTS` | `200` | Max elements to pixel-sample per page |
+| `CONTRASTCAP_MAX_CONCURRENT` | `2` | Max concurrent audits per process |
+| `CONTRASTCAP_VIEWPORT_WIDTH` | `1280` | Chromium viewport width |
+| `CONTRASTCAP_VIEWPORT_HEIGHT` | `800` | Chromium viewport height |
+
+---
+
+## CLI
+
+The package also exposes a CLI for local use without an MCP client:
+
+```bash
+npx @icjia/contrastcap summary  https://example.com/about
+npx @icjia/contrastcap page     https://example.com/about --level AAA
+npx @icjia/contrastcap element  http://localhost:3000 'nav a'
+npx @icjia/contrastcap status
+```
+
+With no subcommand, the binary starts the MCP server on stdio.
+
+---
+
+## Publishing
+
+`./publish.sh` mirrors the pattern used by `@icjia/lightcap` and `@icjia/viewcap`:
+
+```bash
+./publish.sh              # bump patch version and publish (default)
+./publish.sh minor        # bump minor version and publish
+./publish.sh major        # bump major version and publish
+./publish.sh --dry-run    # dry run only, no publish
+```
+
+First-time publish is auto-detected (no existing version on npm) — the current `package.json` version is used as-is. Subsequent releases bump + tag + push.
+
+---
+
+## Security
+
+- Scheme allowlist: `http:` and `https:` only. `file:`, `javascript:`, `data:`, `ftp:` etc. are rejected with a generic `Blocked URL scheme` error.
+- Cloud-metadata hostnames blocked: `169.254.169.254`, `metadata.google.internal`, `metadata.azure.com`, `0.0.0.0`.
+- IP-prefix denylist (DNS-resolved): IPv4 link-local (`169.254.`), IPv6 unique-local (`fd00:`), link-local (`fe80:`), unspecified (`::`). DNS-resolution failures fail closed.
+- Post-navigation re-check: after `page.goto` settles, `page.url()` is re-validated before any pixel sampling.
+- Generic error messages — no filesystem paths or stack traces are returned to MCP clients.
+- No file writes. Screenshots are in-memory buffers consumed by `sharp` and discarded.
+
+Private / localhost IPs are **allowed** by design — the primary use case is auditing dev servers.
+
+---
+
+## License
+
+MIT © 2026 Illinois Criminal Justice Information Authority (ICJIA)

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@icjia/contrastcap",
+  "version": "0.1.0",
+  "description": "MCP server for automated WCAG contrast auditing via pixel-level analysis — resolves axe-core 'needs review' items by sampling actual rendered pixels in headless Chromium",
+  "type": "module",
+  "main": "src/server.js",
+  "bin": {
+    "contrastcap": "src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node --test test/*.test.js",
+    "postinstall": "node -e \"try { require('child_process').execSync('playwright install chromium', { stdio: 'inherit' }) } catch (e) { console.error('[contrastcap] playwright install chromium failed:', e.message); process.exit(0) }\""
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "accessibility",
+    "wcag",
+    "contrast",
+    "axe-core",
+    "playwright",
+    "claude",
+    "a11y"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ICJIA/contrastcap-mcp.git"
+  },
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "axe-core": "^4.10.0",
+    "commander": "^14.0.3",
+    "playwright": "^1.49.0",
+    "sharp": "^0.34.0",
+    "zod": "^4.3.6"
+  }
+}

package/src/browser.js

@@ -0,0 +1,58 @@
+import { chromium } from 'playwright';
+import { CONFIG, log } from './config.js';
+
+let _browser = null;
+let _launching = null;
+
+export async function getBrowser() {
+  if (_browser) return _browser;
+  if (_launching) return _launching;
+
+  _launching = chromium.launch({
+    headless: true,
+    args: [
+      '--disable-dev-shm-usage',
+      '--disable-gpu',
+      '--disable-extensions',
+      '--disable-background-networking',
+      '--no-first-run',
+      '--no-default-browser-check',
+      ...(process.platform === 'linux' ? ['--no-sandbox', '--disable-setuid-sandbox'] : []),
+    ],
+  }).then((b) => {
+    _browser = b;
+    _launching = null;
+    log('info', 'Chromium launched');
+    return b;
+  }).catch((err) => {
+    _launching = null;
+    throw err;
+  });
+
+  return _launching;
+}
+
+export async function closeBrowser() {
+  if (!_browser) return;
+  try { await _browser.close(); } catch { /* ignore */ }
+  _browser = null;
+}
+
+/**
+ * Open a fresh context + page, run `fn`, then tear it down.
+ * Context is disposable per call to avoid state leaks between audits.
+ */
+export async function withPage(fn) {
+  const browser = await getBrowser();
+  const context = await browser.newContext({
+    viewport: { width: CONFIG.VIEWPORT_WIDTH, height: CONFIG.VIEWPORT_HEIGHT },
+    deviceScaleFactor: 1, // pixel sampling needs CSS pixels, not retina
+    userAgent: CONFIG.USER_AGENT,
+  });
+  const page = await context.newPage();
+  try {
+    return await fn(page);
+  } finally {
+    await context.close().catch(() => { /* ignore */ });
+  }
+}

package/src/cli.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { readFileSync } from 'fs';
+import { execFile } from 'child_process';
+import { setVerbosity, CONFIG } from './config.js';
+import { closeBrowser } from './browser.js';
+import { checkPageContrast } from './tools/checkPageContrast.js';
+import { checkElementContrast } from './tools/checkElementContrast.js';
+import { getContrastSummary } from './tools/getContrastSummary.js';
+import { sanitizeError } from './utils/sanitizeError.js';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url)));
+
+program
+  .name('contrastcap')
+  .description('WCAG contrast auditor — pixel-level resolution of axe-core "needs review" items')
+  .version(pkg.version);
+
+program
+  .option('--verbose', 'Verbose logging')
+  .option('--quiet', 'Errors only');
+
+function applyGlobalOptions() {
+  const opts = program.opts();
+  if (opts.verbose) setVerbosity('verbose');
+  if (opts.quiet) setVerbosity('quiet');
+}
+
+function validLevel(v) {
+  return v === 'AAA' ? 'AAA' : 'AA';
+}
+
+async function runAndPrint(fn) {
+  try {
+    const result = await fn();
+    console.log(JSON.stringify(result, null, 2));
+  } catch (err) {
+    console.error(`Error: ${sanitizeError(err)}`);
+    process.exitCode = 1;
+  } finally {
+    await closeBrowser();
+  }
+}
+
+program
+  .command('summary <url>')
+  .description('Summary counts only (lowest token cost)')
+  .option('-l, --level <AA|AAA>', 'WCAG level', 'AA')
+  .action(async (url, opts) => {
+    applyGlobalOptions();
+    await runAndPrint(() => getContrastSummary({ url, level: validLevel(opts.level) }));
+  });
+
+program
+  .command('page <url>')
+  .description('Full page audit — failures and warnings with detail')
+  .option('-l, --level <AA|AAA>', 'WCAG level', 'AA')
+  .action(async (url, opts) => {
+    applyGlobalOptions();
+    await runAndPrint(() => checkPageContrast({ url, level: validLevel(opts.level) }));
+  });
+
+program
+  .command('element <url> <selector>')
+  .description('Check a single element by CSS selector')
+  .option('-l, --level <AA|AAA>', 'WCAG level', 'AA')
+  .action(async (url, selector, opts) => {
+    applyGlobalOptions();
+    await runAndPrint(() => checkElementContrast({ url, selector, level: validLevel(opts.level) }));
+  });
+
+program
+  .command('status')
+  .description('Show version info')
+  .action(async () => {
+    let axeVersion = 'unknown';
+    let playwrightVersion = 'unknown';
+    try {
+      axeVersion = JSON.parse(readFileSync(new URL('../node_modules/axe-core/package.json', import.meta.url))).version;
+    } catch { /* ignore */ }
+    try {
+      playwrightVersion = JSON.parse(readFileSync(new URL('../node_modules/playwright/package.json', import.meta.url))).version;
+    } catch { /* ignore */ }
+
+    let latest = 'unknown';
+    try {
+      latest = await new Promise((resolve, reject) => {
+        execFile('npm', ['view', '@icjia/contrastcap', 'version'], { timeout: 5000 }, (err, stdout) => {
+          if (err) reject(err);
+          else {
+            const raw = stdout.trim();
+            resolve(/^\d+\.\d+\.\d+/.test(raw) ? raw : 'unknown');
+          }
+        });
+      });
+    } catch { /* ignore */ }
+
+    const updateNote = (latest === 'unknown' || latest === pkg.version)
+      ? '(latest)'
+      : `(latest: v${latest} — update available)`;
+
+    console.log('contrastcap status');
+    console.log(`  Server:     @icjia/contrastcap v${pkg.version} ${updateNote}`);
+    console.log(`  axe-core:   v${axeVersion}`);
+    console.log(`  playwright: v${playwrightVersion}`);
+    console.log(`  Node:       v${process.versions.node}`);
+    console.log(`  Platform:   ${process.platform} ${process.arch}`);
+    console.log(`  Default:    WCAG ${CONFIG.DEFAULT_LEVEL}`);
+  });
+
+// Default: start the MCP server when invoked with no subcommand (the npx entry)
+const subcommands = ['summary', 'page', 'element', 'status', 'help'];
+const arg2 = process.argv[2];
+const isSubcommand = arg2 && (
+  subcommands.includes(arg2) ||
+  arg2 === '--help' || arg2 === '-h' ||
+  arg2 === '--version' || arg2 === '-V'
+);
+
+if (!arg2 || (!isSubcommand && arg2.startsWith('-'))) {
+  await import('./server.js');
+} else {
+  program.parse();
+}

package/src/config.js

@@ -0,0 +1,69 @@
+const envInt = (key, fallback) => {
+  const v = process.env[key];
+  if (!v) return fallback;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+
+const envEnum = (key, allowed, fallback) => {
+  const v = process.env[key];
+  return allowed.includes(v) ? v : fallback;
+};
+
+export const CONFIG = {
+  // Timeouts
+  NAV_TIMEOUT:      envInt('CONTRASTCAP_NAV_TIMEOUT', 30_000),
+  ELEMENT_TIMEOUT:  envInt('CONTRASTCAP_ELEMENT_TIMEOUT', 5_000),
+  AUDIT_TIMEOUT:    envInt('CONTRASTCAP_AUDIT_TIMEOUT', 120_000),
+
+  // Audit behavior
+  DEFAULT_LEVEL:    envEnum('CONTRASTCAP_LEVEL', ['AA', 'AAA'], 'AA'),
+  MAX_ELEMENTS:     envInt('CONTRASTCAP_MAX_ELEMENTS', 200),
+  MAX_CONCURRENT:   envInt('CONTRASTCAP_MAX_CONCURRENT', 2),
+
+  // Viewport
+  VIEWPORT_WIDTH:   envInt('CONTRASTCAP_VIEWPORT_WIDTH', 1280),
+  VIEWPORT_HEIGHT:  envInt('CONTRASTCAP_VIEWPORT_HEIGHT', 800),
+
+  // Input caps
+  MAX_URL_LENGTH:   2048,
+  SELECTOR_MAX_LEN: 1024,
+
+  // Warning heuristics
+  MARGINAL_DELTA:   0.3,   // ratio within this of threshold → warning, not fail
+  VARIANCE_STDDEV:  15,    // per-channel stddev above this → high variance
+
+  USER_AGENT: 'contrastcap-mcp/0.1 (WCAG contrast auditor)',
+
+  // SSRF denylist — mirrors lightcap.
+  BLOCKED_HOSTNAMES: [
+    '169.254.169.254',
+    'metadata.google.internal',
+    'metadata.azure.com',
+    '0.0.0.0',
+  ],
+  BLOCKED_IP_PREFIXES: [
+    '169.254.',                // IPv4 link-local (AWS IMDS)
+    'fd00:',                   // IPv6 unique-local
+    'fe80:',                   // IPv6 link-local
+    '::',                      // IPv6 unspecified/loopback-equivalent
+  ],
+  LOCALHOST_HOSTS: [
+    'localhost', '127.0.0.1', '::1', '[::1]',
+  ],
+};
+
+// ─── Logging ──────────────────────────────────────────────────────
+// Verbosity: 'quiet' = errors only, 'normal' = error+info, 'verbose' = +debug
+
+let verbosity = 'normal';
+
+export function setVerbosity(level) {
+  if (['quiet', 'normal', 'verbose'].includes(level)) verbosity = level;
+}
+
+export function log(level, msg) {
+  if (verbosity === 'quiet' && level !== 'error') return;
+  if (verbosity === 'normal' && level === 'debug') return;
+  console.error(`[contrastcap] ${msg}`);
+}

package/src/engine/axeRunner.js

@@ -0,0 +1,73 @@
+import axeCore from 'axe-core';
+
+const AXE_SOURCE = axeCore.source;
+
+/**
+ * Inject axe-core into the page and run the color-contrast rule only.
+ *
+ * Returns flattened arrays of nodes (not rules) for violations / incomplete / passes.
+ * Each node retains its original axe shape: { target, html, any, all, none, ... }.
+ *
+ * We trust axe's result for `violations` (definite failures with known colors)
+ * and `passes` (definite passes). Our job is to re-resolve every `incomplete`
+ * node via pixel sampling.
+ */
+export async function runContrastAudit(page) {
+  await page.evaluate((source) => {
+    // Guard against double-injection on re-runs
+    if (!window.axe) {
+      const s = document.createElement('script');
+      s.textContent = source;
+      document.head.appendChild(s);
+    }
+  }, AXE_SOURCE);
+
+  const results = await page.evaluate(async () => {
+    return await window.axe.run(document, {
+      runOnly: { type: 'rule', values: ['color-contrast'] },
+      resultTypes: ['violations', 'incomplete', 'passes'],
+    });
+  });
+
+  const nodesOf = (arr) => (arr || []).flatMap(rule => rule.nodes || []);
+
+  return {
+    violations: nodesOf(results.violations),
+    incomplete: nodesOf(results.incomplete),
+    passes:     nodesOf(results.passes),
+  };
+}
+
+/**
+ * Extract the first usable CSS selector from an axe node.
+ * axe sometimes returns nested selectors (shadow DOM, frames) — fall back to the
+ * first element of the path.
+ */
+export function selectorFromNode(node) {
+  if (!node || !node.target) return null;
+  const t = node.target[0];
+  if (typeof t === 'string') return t;
+  if (Array.isArray(t)) return t[0]; // nested context (shadow/iframe) — not reachable via page.$()
+  return null;
+}
+
+/**
+ * Pull axe's computed fg/bg (available on definite violations and many passes)
+ * from the standard `color-contrast` data shape.
+ */
+export function axeColors(node) {
+  const checks = [...(node.any || []), ...(node.all || []), ...(node.none || [])];
+  for (const c of checks) {
+    if (c?.data && (c.data.fgColor || c.data.bgColor)) {
+      return {
+        fgColor:          c.data.fgColor || null,
+        bgColor:          c.data.bgColor || null,
+        contrastRatio:    typeof c.data.contrastRatio === 'number' ? c.data.contrastRatio : null,
+        fontSize:         c.data.fontSize || null,
+        fontWeight:       c.data.fontWeight || null,
+        expectedContrastRatio: typeof c.data.expectedContrastRatio === 'number' ? c.data.expectedContrastRatio : null,
+      };
+    }
+  }
+  return null;
+}