@wcag-checkr/mcp 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+# @wcag-checkr/mcp
+
+**Model Context Protocol** server for wcagcheckr. Lets LLM-IDEs drive accessibility audits, verify forensic receipts, and look up tier features via tool-use.
+
+## Why this matters
+
+axe DevTools shipped an MCP server in 2026 (paid tier). We ship one for free, with one extra: it audits across our 108-state matrix (hover/focus/dark/RTL/breakpoints), so the LLM gets findings competitors' single-state audits would miss.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `audit_url` | Run a multi-state accessibility audit on a URL. Returns structured findings (JSON / SARIF / JUnit). |
+| `verify_receipt` | Independently verify a wcagcheckr forensic-anchor receipt's ed25519 signature against the published public key. |
+| `get_tier_config` | Fetch the per-product tier feature flags. |
+
+## Install
+
+```bash
+npm install -g @wcag-checkr/mcp @wcag-checkr/ci
+npx playwright install chromium
+```
+
+## Use with Claude Code
+
+Add to `~/.claude/mcp.json` (or use `claude mcp add` if available in your version):
+
+```json
+{
+  "mcpServers": {
+    "wcagcheckr": {
+      "command": "wcagcheckr-mcp"
+    }
+  }
+}
+```
+
+Then in any conversation:
+
+> "Audit https://staging.example.com for accessibility issues."
+
+Claude will call `audit_url` and return findings, ready for fix-it discussion.
+
+## Use with Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "wcagcheckr": {
+      "command": "wcagcheckr-mcp"
+    }
+  }
+}
+```
+
+## Use with Continue
+
+Add to your Continue config under `mcpServers`:
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "wcagcheckr",
+      "command": "wcagcheckr-mcp"
+    }
+  ]
+}
+```
+
+## Environment variables
+
+| Var | Default | Purpose |
+|---|---|---|
+| `WCAGCHECKR_SERVER_URL` | `https://api.wcagcheckr.com` | Override the server base URL (e.g. for self-hosted instance) |
+| `WCAGCHECKR_PRODUCT_SLUG` | `wcagcheckr` | Override the product slug |
+| `WCAGCHECKR_CI_PATH` | bundled | Override the path to the CI runner (used by `audit_url`) |
+
+## Examples — what an LLM can do with this
+
+**Auditing a deployment preview**
+> User: "Audit my Vercel preview at https://my-site-pr-42.vercel.app — fail the build if there are any serious violations."
+>
+> Claude calls `audit_url` with `threshold: serious`, gets back JSON, summarizes findings, and tells the user the exit code mapping.
+
+**Validating a forensic receipt**
+> User: *pastes a forensic-log entry copied from a defense bundle*
+>
+> "Is this receipt actually from wcagcheckr?"
+>
+> Claude calls `verify_receipt`, gets a "✓ valid signature" response, explains what was verified (and what wasn't — i.e., directs the user to `openssl ts -verify` for the TSA token).
+
+**Tier-feature questions**
+> User: "Does the Solo plan include forensic anchoring?"
+>
+> Claude calls `get_tier_config`, finds `features.forensicAnchoring: true` for the solo plan, answers.
+
+## Limitations (v0)
+
+- `audit_url` shells out to `@wcag-checkr/ci` which spawns Chromium with the loaded extension. Heavy — single audits take 15-60s. Don't expect sub-second response.
+- `verify_receipt` only verifies our ed25519 signature. Full RFC 3161 timestamp verification against FreeTSA's CA chain is intentionally out of scope (use `openssl ts -verify` for that — see `https://api.wcagcheckr.com/verify` for openssl-command instructions tailored to a specific receipt).
+- No streaming. Audits report results when done, not incrementally.
+
+## License
+
+UNLICENSED until commercial release. See `wcagcheckr.com/license`.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@wcag-checkr/mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Model Context Protocol server for wcagcheckr. Lets LLM-IDEs (Claude Code, Cursor, Continue, etc.) drive accessibility audits, verify forensic receipts, and look up tier features programmatically. Same audit engine as the Chrome extension and CI runner.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "wcagcheckr-mcp.mjs",
+  "bin": {
+    "wcagcheckr-mcp": "./wcagcheckr-mcp.mjs"
+  },
+  "files": [
+    "wcagcheckr-mcp.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@wcag-checkr/ci": "^0.1.0"
+  },
+  "homepage": "https://wcagcheckr.com",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "accessibility",
+    "a11y",
+    "wcag",
+    "audit",
+    "claude",
+    "cursor",
+    "ai-tools"
+  ]
+}

package/wcagcheckr-mcp.mjs

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+// wcagcheckr — Model Context Protocol server.
+//
+// Exposes wcagcheckr capabilities as MCP tools so LLM-driven IDEs (Claude Code,
+// Cursor, Continue, etc.) can call them via tool-use. Same audit engine as the
+// Chrome extension and the CI npm package — this is just the JSON-RPC wrapper.
+//
+// Tools exposed:
+//   audit_url       — run a full-page audit on a URL, return structured findings
+//   verify_receipt  — verify a forensic receipt against our published public key
+//   get_tier_config — fetch the per-product tier feature flags
+//   list_violations — list violations from the most recent audit, filterable
+//
+// Transport: stdio (the MCP standard for local servers). Wired into Claude
+// Code via `~/.claude/mcp.json` or invoked directly by `claude mcp add` etc.
+//
+// See README.md for setup instructions per IDE.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolve, dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)));
+// CI runner — sibling package, or fall back to bundled
+const CI_RUNNER_PATH =
+  process.env.WCAGCHECKR_CI_PATH ??
+  resolve(ROOT, '..', 'cli', 'wcagcheckr-ci.mjs');
+
+const SERVER_BASE_URL = process.env.WCAGCHECKR_SERVER_URL ?? 'https://api.wcagcheckr.com';
+const PRODUCT_SLUG = process.env.WCAGCHECKR_PRODUCT_SLUG ?? 'wcagcheckr';
+
+const server = new Server(
+  {
+    name: 'wcagcheckr',
+    version: '0.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+// ─── Tool definitions ────────────────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: 'audit_url',
+    description:
+      'Run a wcagcheckr accessibility audit on a URL. Audits across the multi-state matrix (hover, focus, dark mode, RTL, breakpoints) and returns structured findings. Use this when the user asks to check accessibility of a page, find WCAG violations, or audit a deployment preview.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'Fully-qualified URL to audit. Must be reachable from the runner host.',
+        },
+        format: {
+          type: 'string',
+          enum: ['json', 'sarif', 'junit'],
+          description: 'Output format. Default: json.',
+        },
+        threshold: {
+          type: 'string',
+          enum: ['none', 'critical', 'serious', 'moderate', 'minor'],
+          description:
+            'Severity threshold for the success/failure assessment. Default: serious.',
+        },
+        timeout_ms: {
+          type: 'number',
+          description: 'Audit timeout in milliseconds. Default: 120000.',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'verify_receipt',
+    description:
+      'Independently verify a wcagcheckr forensic-anchor receipt. Confirms the ed25519 signature is valid against the published public key + the receipt fields are well-formed. Use this when a user provides a forensic receipt and wants to confirm authenticity (e.g., received as part of a defense bundle from a vendor).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        receipt: {
+          type: 'object',
+          description:
+            'The forensic-log entry containing { hash, componentId, pageUrl, capturedAt, receipt: { schemaVersion, anchoredAt, tsaName, rfc3161TokenBase64, serverSignatureBase64, serverKeyFingerprint } }.',
+        },
+        product_slug: {
+          type: 'string',
+          description: `Product slug. Default: ${PRODUCT_SLUG}.`,
+        },
+      },
+      required: ['receipt'],
+    },
+  },
+  {
+    name: 'get_tier_config',
+    description:
+      'Fetch the wcagcheckr per-tier feature flags for a product. Use this to answer questions about what each pricing tier (free / solo / team) includes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        product_slug: {
+          type: 'string',
+          description: `Product slug. Default: ${PRODUCT_SLUG}.`,
+        },
+      },
+    },
+  },
+];
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,
+}));
+
+// ─── Tool implementations ────────────────────────────────────────────────────
+
+async function auditUrl(args) {
+  const { url, format = 'json', threshold = 'serious', timeout_ms = 120_000 } = args;
+  if (!url) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required field: url' }] };
+  }
+  if (!existsSync(CI_RUNNER_PATH)) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: `wcagcheckr CI runner not found at ${CI_RUNNER_PATH}. Set WCAGCHECKR_CI_PATH or install @wcag-checkr/ci.`,
+        },
+      ],
+    };
+  }
+
+  return new Promise((resolveResult) => {
+    const args = [
+      CI_RUNNER_PATH,
+      'audit',
+      url,
+      '--format', format,
+      '--threshold', threshold,
+      '--timeout', String(timeout_ms),
+      '--quiet',
+    ];
+    const child = spawn(process.execPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+    child.stderr.on('data', (chunk) => (stderr += chunk.toString('utf8')));
+    child.on('error', (err) =>
+      resolveResult({
+        isError: true,
+        content: [{ type: 'text', text: `Failed to spawn auditor: ${err.message}` }],
+      }),
+    );
+    child.on('close', (code) => {
+      const summary = code === 0
+        ? `audit completed; ${threshold}-threshold not exceeded`
+        : code === 1
+          ? `audit completed; ${threshold}-threshold exceeded — failures detected`
+          : `audit runtime error (exit ${code})`;
+      resolveResult({
+        content: [
+          { type: 'text', text: summary },
+          { type: 'text', text: stdout },
+          ...(stderr ? [{ type: 'text', text: `stderr:\n${stderr}` }] : []),
+        ],
+      });
+    });
+  });
+}
+
+async function verifyReceipt(args) {
+  const { receipt: entry, product_slug = PRODUCT_SLUG } = args;
+  if (!entry || typeof entry !== 'object') {
+    return { isError: true, content: [{ type: 'text', text: 'Missing or invalid receipt object' }] };
+  }
+  const { hash, receipt } = entry;
+  if (!hash || !receipt) {
+    return {
+      isError: true,
+      content: [{ type: 'text', text: 'receipt must contain { hash, receipt: { ... } }' }],
+    };
+  }
+  if (receipt.schemaVersion !== 1) {
+    return {
+      content: [{ type: 'text', text: `Unsupported receipt schemaVersion: ${receipt.schemaVersion}` }],
+    };
+  }
+
+  // Fetch published public key
+  let pubKeyData;
+  try {
+    const res = await fetch(`${SERVER_BASE_URL}/v1/products/${product_slug}/forensic/public-key`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    pubKeyData = await res.json();
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Failed to fetch public key: ${err.message}` }],
+    };
+  }
+
+  if (pubKeyData.fingerprint !== receipt.serverKeyFingerprint) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Fingerprint mismatch — receipt was issued under a different (rotated) key. Receipt: ${receipt.serverKeyFingerprint?.slice(0, 16)}…  Currently published: ${pubKeyData.fingerprint?.slice(0, 16)}…`,
+        },
+      ],
+    };
+  }
+
+  // Verify ed25519 signature using Node's WebCrypto
+  const canonicalJson = (value) => {
+    if (value === null || typeof value !== 'object') return JSON.stringify(value);
+    if (Array.isArray(value)) return '[' + value.map(canonicalJson).join(',') + ']';
+    const keys = Object.keys(value).sort();
+    return '{' + keys.map((k) => JSON.stringify(k) + ':' + canonicalJson(value[k])).join(',') + '}';
+  };
+
+  const signedPayload = {
+    hash,
+    anchoredAt: receipt.anchoredAt,
+    tsaName: receipt.tsaName,
+    productSlug: product_slug,
+  };
+  const canonical = canonicalJson(signedPayload);
+  const canonicalBytes = new TextEncoder().encode(canonical);
+
+  const b64ToBytes = (b64) => {
+    const bin = Buffer.from(b64, 'base64');
+    return new Uint8Array(bin);
+  };
+
+  let pubKey;
+  try {
+    pubKey = await crypto.subtle.importKey(
+      'spki',
+      b64ToBytes(pubKeyData.publicKeyBase64),
+      { name: 'Ed25519' },
+      false,
+      ['verify'],
+    );
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Public-key import failed: ${err.message}` }] };
+  }
+
+  let sigValid;
+  try {
+    sigValid = await crypto.subtle.verify(
+      'Ed25519',
+      pubKey,
+      b64ToBytes(receipt.serverSignatureBase64),
+      canonicalBytes,
+    );
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Signature verification threw: ${err.message}` }] };
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: sigValid
+          ? `✓ Receipt is VALID. Server ed25519 signature verifies against the published key (fingerprint ${pubKeyData.fingerprint?.slice(0, 16)}…). The receipt was issued by the wcagcheckr server. Note: this verifies OUR signature only — full RFC 3161 timestamp verification against the TSA's CA chain (FreeTSA) is a separate step done via openssl ts -verify.`
+          : `✗ Receipt is INVALID. The server signature did NOT verify against the published key. Either the receipt was tampered with, or the entry's hash/anchoredAt/tsaName don't match what was originally signed.`,
+      },
+    ],
+  };
+}
+
+async function getTierConfig(args) {
+  const { product_slug = PRODUCT_SLUG } = args ?? {};
+  try {
+    const res = await fetch(`${SERVER_BASE_URL}/v1/products/${product_slug}/tier-config`);
+    if (!res.ok) {
+      return { content: [{ type: 'text', text: `tier-config HTTP ${res.status}` }] };
+    }
+    const json = await res.json();
+    return {
+      content: [
+        { type: 'text', text: JSON.stringify(json, null, 2) },
+      ],
+    };
+  } catch (err) {
+    return { content: [{ type: 'text', text: `Failed to fetch tier-config: ${err.message}` }] };
+  }
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+  switch (name) {
+    case 'audit_url':
+      return await auditUrl(args);
+    case 'verify_receipt':
+      return await verifyReceipt(args);
+    case 'get_tier_config':
+      return await getTierConfig(args);
+    default:
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+      };
+  }
+});
+
+// ─── Boot ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  // Stay alive — stdio transport handles its own lifecycle.
+}
+
+main().catch((err) => {
+  console.error('wcagcheckr MCP server failed:', err);
+  process.exit(1);
+});