@cookiecrumbs-eu/mcp 0.7.0

package/dist/config/src/webhooks.js

@@ -0,0 +1,309 @@
+// Standard Webhooks (https://www.standardwebhooks.com) — the one implementation shared by the
+// cc-worker dispatcher, the CLI (`cookiecrumbs verify-webhook`), the sample receiver in
+// docs/platform/samples/webhook-receiver.mjs and the tests.
+//
+//   webhook-id:        the delivery id (public.webhook_deliveries.id)
+//   webhook-timestamp: unix seconds
+//   webhook-signature: `v1,<base64>` (space separated when several keys are valid)
+//
+// The signature is HMAC-SHA256 over `${id}.${timestamp}.${body}`, keyed with the *raw bytes* of the
+// secret: a `whsec_`-prefixed secret is the base64 of those bytes, anything else is used as UTF-8.
+//
+// No imports: SHA-256, HMAC and base64 are implemented here so the module runs unchanged in Node,
+// Deno, the edge runtime and the browser, and so a customer can copy the verifier into any project.
+export const WEBHOOK_SIGNATURE_VERSION = "v1";
+/** Standard Webhooks recommends five minutes of clock tolerance. */
+export const WEBHOOK_TOLERANCE_SECONDS = 300;
+export const WEBHOOK_SECRET_PREFIX = "whsec_";
+export const WEBHOOK_ID_HEADER = "webhook-id";
+export const WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+export const WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+// ---------------------------------------------------------------------------
+// SHA-256
+// ---------------------------------------------------------------------------
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotr = (x, n) => ((x >>> n) | (x << (32 - n))) >>> 0;
+/** SHA-256 of `data`, as 32 bytes. */
+export function sha256(data) {
+    const h = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const len = data.length;
+    const padded = new Uint8Array((((len + 8) >> 6) + 1) * 64);
+    padded.set(data);
+    padded[len] = 0x80;
+    const view = new DataView(padded.buffer);
+    // length in bits, as a 64-bit big-endian number
+    view.setUint32(padded.length - 8, Math.floor(len / 0x20000000) >>> 0);
+    view.setUint32(padded.length - 4, ((len % 0x20000000) * 8) >>> 0);
+    const w = new Uint32Array(64);
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = view.getUint32(off + i * 4);
+        for (let i = 16; i < 64; i++) {
+            const x = w[i - 15];
+            const y = w[i - 2];
+            const s0 = (rotr(x, 7) ^ rotr(x, 18) ^ (x >>> 3)) >>> 0;
+            const s1 = (rotr(y, 17) ^ rotr(y, 19) ^ (y >>> 10)) >>> 0;
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) >>> 0;
+        }
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let hh = h[7];
+        for (let i = 0; i < 64; i++) {
+            const s1 = (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) >>> 0;
+            const ch = ((e & f) ^ (~e & g)) >>> 0;
+            const t1 = (hh + s1 + ch + K[i] + w[i]) >>> 0;
+            const s0 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) >>> 0;
+            const maj = ((a & b) ^ (a & c) ^ (b & c)) >>> 0;
+            const t2 = (s0 + maj) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + hh) >>> 0;
+    }
+    const out = new Uint8Array(32);
+    const ov = new DataView(out.buffer);
+    for (let i = 0; i < 8; i++)
+        ov.setUint32(i * 4, h[i]);
+    return out;
+}
+/** HMAC-SHA256 (RFC 2104), as 32 bytes. */
+export function hmacSha256(key, message) {
+    const block = new Uint8Array(64);
+    if (key.length > 64)
+        block.set(sha256(key));
+    else
+        block.set(key);
+    const inner = new Uint8Array(64 + message.length);
+    const outer = new Uint8Array(64 + 32);
+    for (let i = 0; i < 64; i++) {
+        inner[i] = block[i] ^ 0x36;
+        outer[i] = block[i] ^ 0x5c;
+    }
+    inner.set(message, 64);
+    outer.set(sha256(inner), 64);
+    return sha256(outer);
+}
+// ---------------------------------------------------------------------------
+// base64 / utf-8 / hex helpers (no Buffer, no atob)
+// ---------------------------------------------------------------------------
+const B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+export function toBase64(bytes) {
+    let out = "";
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = bytes[i + 1];
+        const b2 = bytes[i + 2];
+        out += B64[b0 >> 2];
+        out += B64[((b0 & 3) << 4) | ((b1 ?? 0) >> 4)];
+        out += b1 === undefined ? "=" : B64[((b1 & 15) << 2) | ((b2 ?? 0) >> 6)];
+        out += b2 === undefined ? "=" : B64[b2 & 63];
+    }
+    return out;
+}
+export function fromBase64(text) {
+    const clean = text.replace(/[\s=]/g, "").replace(/-/g, "+").replace(/_/g, "/");
+    const out = new Uint8Array(Math.floor((clean.length * 6) / 8));
+    let acc = 0;
+    let bits = 0;
+    let n = 0;
+    for (const ch of clean) {
+        const v = B64.indexOf(ch);
+        if (v < 0)
+            throw new Error("invalid base64");
+        acc = (acc << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[n++] = (acc >> bits) & 0xff;
+        }
+    }
+    return out.subarray(0, n);
+}
+export const toHex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+const utf8 = (s) => new TextEncoder().encode(s);
+/** Length-independent, value-constant-time comparison of two ASCII strings. */
+export function timingSafeEqual(a, b) {
+    const x = utf8(a);
+    const y = utf8(b);
+    let diff = x.length ^ y.length;
+    const n = Math.max(x.length, y.length);
+    for (let i = 0; i < n; i++)
+        diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+    return diff === 0;
+}
+// ---------------------------------------------------------------------------
+// Secrets
+// ---------------------------------------------------------------------------
+/** The HMAC key of a secret: base64 body for `whsec_…`, raw UTF-8 otherwise. */
+export function webhookSecretKey(secret) {
+    const s = (secret ?? "").trim();
+    if (!s)
+        throw new Error("webhook secret is empty");
+    return s.startsWith(WEBHOOK_SECRET_PREFIX) ? fromBase64(s.slice(WEBHOOK_SECRET_PREFIX.length)) : utf8(s);
+}
+/**
+ * A new `whsec_` + base64(32 random bytes) secret. Uses the platform CSPRNG; throws when the runtime
+ * has none (the database generates the real secrets — this exists for tests and local receivers).
+ */
+export function generateWebhookSecret(bytes = 32) {
+    const c = globalThis.crypto;
+    if (!c?.getRandomValues)
+        throw new Error("no CSPRNG available in this runtime");
+    return WEBHOOK_SECRET_PREFIX + toBase64(c.getRandomValues(new Uint8Array(bytes)));
+}
+function unixSeconds(t) {
+    if (t === undefined || t === null || t === "")
+        return String(Math.floor(Date.now() / 1000));
+    if (t instanceof Date)
+        return String(Math.floor(t.getTime() / 1000));
+    const n = typeof t === "number" ? t : Number(t);
+    if (!Number.isFinite(n))
+        throw new Error(`invalid timestamp: ${String(t)}`);
+    // Anything past the year 33658 in seconds is really milliseconds.
+    return String(Math.floor(n > 1e12 ? n / 1000 : n));
+}
+export function signWebhook(input) {
+    const id = String(input.id ?? "");
+    if (!id)
+        throw new Error("webhook id is required");
+    const timestamp = unixSeconds(input.timestamp);
+    const body = input.body ?? "";
+    const signedContent = `${id}.${timestamp}.${body}`;
+    const mac = hmacSha256(webhookSecretKey(input.secret), utf8(signedContent));
+    const signature = `${WEBHOOK_SIGNATURE_VERSION},${toBase64(mac)}`;
+    return {
+        id,
+        timestamp,
+        signature,
+        signedContent,
+        headers: {
+            "content-type": "application/json; charset=utf-8",
+            [WEBHOOK_ID_HEADER]: id,
+            [WEBHOOK_TIMESTAMP_HEADER]: timestamp,
+            [WEBHOOK_SIGNATURE_HEADER]: signature,
+        },
+    };
+}
+function headerValue(headers, name) {
+    if (!headers)
+        return null;
+    const anyH = headers;
+    if (typeof anyH.get === "function") {
+        const v = anyH.get(name);
+        return v == null ? null : String(v);
+    }
+    const rec = headers;
+    for (const key of Object.keys(rec)) {
+        if (key.toLowerCase() !== name)
+            continue;
+        const v = rec[key];
+        if (v == null)
+            return null;
+        return Array.isArray(v) ? (v.length ? String(v[0]) : null) : String(v);
+    }
+    return null;
+}
+/**
+ * Verifies a Standard Webhooks request. Returns a result object rather than throwing so a receiver
+ * can log the reason and answer 400 without a try/catch.
+ */
+export function verifyWebhook(input) {
+    const id = headerValue(input.headers, WEBHOOK_ID_HEADER);
+    const ts = headerValue(input.headers, WEBHOOK_TIMESTAMP_HEADER);
+    const sigHeader = headerValue(input.headers, WEBHOOK_SIGNATURE_HEADER);
+    if (!id)
+        return { ok: false, reason: "missing_id", message: `No ${WEBHOOK_ID_HEADER} header.` };
+    if (!ts)
+        return { ok: false, reason: "missing_timestamp", message: `No ${WEBHOOK_TIMESTAMP_HEADER} header.` };
+    if (!sigHeader)
+        return { ok: false, reason: "missing_signature", message: `No ${WEBHOOK_SIGNATURE_HEADER} header.` };
+    const seconds = Number(ts);
+    if (!Number.isFinite(seconds) || !/^\d{1,15}$/.test(ts.trim())) {
+        return { ok: false, reason: "invalid_timestamp", message: `${WEBHOOK_TIMESTAMP_HEADER} must be unix seconds.` };
+    }
+    const tolerance = input.toleranceSeconds ?? WEBHOOK_TOLERANCE_SECONDS;
+    if (tolerance > 0) {
+        const nowSeconds = Math.floor((input.now ?? Date.now()) / 1000);
+        if (seconds < nowSeconds - tolerance) {
+            return { ok: false, reason: "timestamp_too_old", message: `Timestamp is ${nowSeconds - seconds} s old (tolerance ${tolerance} s).` };
+        }
+        if (seconds > nowSeconds + tolerance) {
+            return { ok: false, reason: "timestamp_too_new", message: `Timestamp is ${seconds - nowSeconds} s in the future (tolerance ${tolerance} s).` };
+        }
+    }
+    let expected;
+    try {
+        const mac = hmacSha256(webhookSecretKey(input.secret), utf8(`${id}.${ts}.${input.body ?? ""}`));
+        expected = toBase64(mac);
+    }
+    catch (e) {
+        return { ok: false, reason: "invalid_secret", message: e.message };
+    }
+    const parts = sigHeader.split(/\s+/).filter(Boolean);
+    let sawV1 = false;
+    let matched = false;
+    for (const part of parts) {
+        const comma = part.indexOf(",");
+        if (comma < 0)
+            continue;
+        if (part.slice(0, comma) !== WEBHOOK_SIGNATURE_VERSION)
+            continue;
+        sawV1 = true;
+        // No early exit: every v1 candidate is compared so the timing does not leak which one matched.
+        if (timingSafeEqual(part.slice(comma + 1), expected))
+            matched = true;
+    }
+    if (!sawV1)
+        return { ok: false, reason: "no_v1_signature", message: `${WEBHOOK_SIGNATURE_HEADER} carries no v1 signature.` };
+    if (!matched)
+        return { ok: false, reason: "signature_mismatch", message: "The v1 signature does not match the body." };
+    return { ok: true, id, timestamp: seconds, signature: `${WEBHOOK_SIGNATURE_VERSION},${expected}` };
+}
+/** The 12 CookieCrumbs event types (mirrors private.webhook_event_types() in migration 0036). */
+export const WEBHOOK_EVENT_TYPES = [
+    "scan.completed",
+    "scan.failed",
+    "tracker.new",
+    "issue.opened",
+    "issue.resolved",
+    "alert.raised",
+    "config.published",
+    "version.promoted",
+    "export.completed",
+    "declaration.updated",
+    "install.broken",
+    "plan.changed",
+];
+export function isWebhookEnvelope(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    return typeof v.id === "string" && typeof v.type === "string" && typeof v.created_at === "string" && typeof v.org_id === "string" && "data" in v;
+}

package/dist/mcp/src/auth.js

@@ -0,0 +1,40 @@
+/**
+ * Where the token comes from.
+ *
+ * `COOKIECRUMBS_TOKEN` wins; otherwise we read the CLI's stored credentials
+ * (`%APPDATA%/cookiecrumbs/credentials.json` on Windows, `~/.config/cookiecrumbs/…`
+ * elsewhere) through the CLI's own `resolveToken()` — one credential store, not two.
+ *
+ * There is deliberately **no** device flow here: a stdio MCP server has no terminal to print
+ * a user code to and no browser to open, so an unauthenticated start-up returns instructions
+ * instead of blocking on a poll loop.
+ */
+import { credentialsPath, resolveToken } from "../../cli/src/auth.js";
+import { DEFAULT_API } from "./client.js";
+export function resolveCredentials(env = process.env) {
+    const { token, source, creds } = resolveToken();
+    const api = (env.COOKIECRUMBS_API ?? creds?.api ?? DEFAULT_API).trim();
+    return { token, source, api, credentials: creds ?? null };
+}
+export const LOGIN_INSTRUCTIONS = [
+    'No CookieCrumbs API token is available, so this server cannot talk to the API yet.',
+    '',
+    'Pick one of these, then restart the MCP server so it can re-read the token:',
+    '',
+    '  1. Log in once with the CLI (opens the dashboard device page in your browser):',
+    '',
+    '       npx cookiecrumbs login',
+    '',
+    `     The token is stored at ${'${credentials}'} and this server reads it from there.`,
+    '',
+    '  2. Or create a machine token in the dashboard under',
+    '     Workspace → Developers → MCP and CLI, and put it in the environment:',
+    '',
+    '       COOKIECRUMBS_TOKEN=cc_live_…',
+    '',
+    'A device login cannot be run from inside this server: stdio has no terminal to show the',
+    'user code on and no browser to open.',
+].join('\n');
+export function loginInstructions() {
+    return LOGIN_INSTRUCTIONS.replace('${credentials}', credentialsPath());
+}

package/dist/mcp/src/client.js

@@ -0,0 +1,44 @@
+/**
+ * The REST client the MCP tools talk through.
+ *
+ * It is the CLI's `Api` (packages/cli/src/api.ts) — same typed routes, same RFC 9457
+ * problem+json mapping, same `X-Request-Id` — with one difference: the
+ * `X-CookieCrumbs-Client` header reads `mcp/<client>` instead of `cli/<version>`, so the
+ * gateway writes `channel='mcp'` and the audit rows read "via MCP".
+ *
+ * The client name is read live on every request: the process may learn it from the MCP
+ * `initialize` params after start-up.
+ */
+import { Api } from "../../cli/src/api.js";
+import { CliError } from "../../cli/src/errors.js";
+export const DEFAULT_API = 'https://api.cookiecrumbs.eu';
+/** MCP client identifiers end up in audit rows: keep them short and boring. */
+export function sanitiseClient(raw) {
+    const s = (raw ?? '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+    return s.slice(0, 40) || 'unknown';
+}
+export class McpApi extends Api {
+    constructor(base, token, clientName) {
+        super(base, token, '0');
+        Object.defineProperty(this, 'client', {
+            configurable: true,
+            enumerable: true,
+            get: () => `mcp/${sanitiseClient(clientName())}`,
+        });
+    }
+}
+export { CliError };
+/** Extra routes the MCP server needs that the CLI client does not expose yet. */
+export function servicesUrl(site) {
+    return `/sites/${site}/services`;
+}
+/**
+ * `PATCH /v1/services/:id` and `GET /v1/sites/:id/analytics/daily` are phase-6 REST additions
+ * owned by other tracks. When they are not deployed yet the gateway answers 404/405; we turn
+ * that into a message the agent can act on instead of a raw problem document.
+ */
+export function isRouteMissing(err) {
+    if (!(err instanceof CliError))
+        return false;
+    return (err.status === 404 || err.status === 405) && /not.?found|no.?route|method/i.test(err.detail ?? '');
+}

package/dist/mcp/src/diff.js

@@ -0,0 +1,134 @@
+/**
+ * Unified diff rendering for the two-step write tools.
+ *
+ * Every write tool with `confirm:false` must show the agent exactly what would change, and a
+ * dotted-path list is not enough to review a banner configuration — so we render a real
+ * unified diff over a deterministic pretty-printed JSON serialisation (object keys sorted,
+ * arrays left in order because array order is meaningful in a BannerConfig).
+ */
+/** Deterministic pretty JSON: keys sorted at every level, two-space indent, no trailing space. */
+export function stableJson(value, indent = 2) {
+    return JSON.stringify(sortDeep(value), null, indent);
+}
+function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value).sort())
+            out[k] = sortDeep(value[k]);
+        return out;
+    }
+    return value;
+}
+/** Longest common subsequence table over two line arrays (configs are small; O(n·m) is fine). */
+function lcs(a, b) {
+    const table = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    return table;
+}
+export function diffLines(a, b) {
+    const table = lcs(a, b);
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        if (a[i] === b[j]) {
+            ops.push({ op: ' ', line: a[i] });
+            i++;
+            j++;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1]) {
+            ops.push({ op: '-', line: a[i] });
+            i++;
+        }
+        else {
+            ops.push({ op: '+', line: b[j] });
+            j++;
+        }
+    }
+    while (i < a.length)
+        ops.push({ op: '-', line: a[i++] });
+    while (j < b.length)
+        ops.push({ op: '+', line: b[j++] });
+    return ops;
+}
+/**
+ * A unified diff with `context` lines of context. Returns '' when the two sides are identical,
+ * so callers can say "nothing would change" instead of printing an empty diff.
+ */
+export function unifiedDiff(before, after, opts = {}) {
+    const context = opts.context ?? 3;
+    const a = before.split('\n');
+    const b = after.split('\n');
+    const ops = diffLines(a, b);
+    if (!ops.some((o) => o.op !== ' '))
+        return '';
+    // Mark which context lines to keep around each change.
+    const keep = new Array(ops.length).fill(false);
+    ops.forEach((o, idx) => {
+        if (o.op === ' ')
+            return;
+        for (let k = Math.max(0, idx - context); k <= Math.min(ops.length - 1, idx + context); k++)
+            keep[k] = true;
+    });
+    const hunks = [];
+    let aLine = 1;
+    let bLine = 1;
+    let current = null;
+    ops.forEach((o, idx) => {
+        if (keep[idx]) {
+            if (!current)
+                current = { aStart: aLine, aLines: 0, bStart: bLine, bLines: 0, lines: [] };
+            current.lines.push(o.op + o.line);
+            if (o.op !== '+')
+                current.aLines++;
+            if (o.op !== '-')
+                current.bLines++;
+        }
+        else if (current) {
+            hunks.push(current);
+            current = null;
+        }
+        if (o.op !== '+')
+            aLine++;
+        if (o.op !== '-')
+            bLine++;
+    });
+    if (current)
+        hunks.push(current);
+    const head = [`--- ${opts.fromLabel ?? 'before'}`, `+++ ${opts.toLabel ?? 'after'}`];
+    const body = hunks.map((h) => [`@@ -${h.aStart},${h.aLines} +${h.bStart},${h.bLines} @@`, ...h.lines].join('\n'));
+    return [...head, ...body].join('\n');
+}
+/** Unified diff of two JSON values, rendered from the deterministic serialisation. */
+export function jsonDiff(before, after, fromLabel, toLabel) {
+    return unifiedDiff(stableJson(before), stableJson(after), { fromLabel, toLabel });
+}
+/** `3 changed, 1 added, 0 removed` — the one-line headline above the diff. */
+export function diffStats(before, after) {
+    const ops = diffLines(stableJson(before).split('\n'), stableJson(after).split('\n'));
+    const added = ops.filter((o) => o.op === '+').length;
+    const removed = ops.filter((o) => o.op === '-').length;
+    return { added, removed, changed: added > 0 || removed > 0 };
+}
+/**
+ * RFC 7386 JSON Merge Patch — the `update_banner` patch format. `null` removes a key;
+ * arrays and scalars replace wholesale.
+ */
+export function mergePatch(target, patch) {
+    if (patch === null || typeof patch !== 'object' || Array.isArray(patch))
+        return patch;
+    const base = target && typeof target === 'object' && !Array.isArray(target) ? { ...target } : {};
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === null)
+            delete base[k];
+        else
+            base[k] = mergePatch(base[k], v);
+    }
+    return base;
+}

package/dist/mcp/src/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * `cookiecrumbs-mcp` — the stdio entry point.
+ *
+ *   claude mcp add cookiecrumbs -- npx -y @cookiecrumbs-eu/mcp
+ *
+ * stdout belongs to the MCP protocol: every diagnostic goes to stderr.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+async function main() {
+    const built = await buildServer();
+    // The MCP client identifies itself in `initialize`; from then on every REST call carries
+    // `X-CookieCrumbs-Client: mcp/<that name>` unless MCP_CLIENT overrode it.
+    built.server.server.oninitialized = () => {
+        built.setClientName(built.server.server.getClientVersion()?.name);
+    };
+    await built.server.connect(new StdioServerTransport());
+    const scopes = [...built.scopes].join(', ') || 'none';
+    process.stderr.write(`${SERVER_NAME} mcp ${SERVER_VERSION} ready — ${built.advertised.length} tool(s); scopes: ${scopes}${built.authError ? ' (no usable token yet)' : ''}\n`);
+}
+main().catch((e) => {
+    process.stderr.write(`cookiecrumbs-mcp failed to start: ${e instanceof Error ? e.stack ?? e.message : String(e)}\n`);
+    process.exit(1);
+});

package/dist/mcp/src/matrix.js

@@ -0,0 +1,106 @@
+/**
+ * The tool/scope table — the single source of truth for what each MCP tool is called, whether
+ * it reads or writes, and which token scope it needs.
+ *
+ * `tools.ts` spreads these rows into the tool definitions it registers, so the server cannot
+ * advertise a tool under a different scope than this file says. The dashboard page
+ * `/w/:ws/developers/mcp` imports this module directly (`@cookiecrumbs-eu/mcp/matrix`) and renders
+ * the matrix from it — which is why this file has **no dependencies at all**: no zod, no node
+ * built-ins, nothing that would not survive a browser bundle.
+ */
+export const TOOL_META = {
+    list_sites: { kind: 'read', scopes: ['sites:read'], title: 'List sites', summary: 'Sites this token can see, with environments and public keys.' },
+    get_site: { kind: 'read', scopes: ['sites:read'], title: 'Get one site', summary: 'One site with its environments, languages and version pointers.' },
+    get_banner: { kind: 'read', scopes: ['banner:read'], title: 'Get the banner configuration', summary: 'Draft + live version + legal lint for an environment.' },
+    get_compliance_status: { kind: 'read', scopes: ['banner:read'], title: 'Open compliance issues with citations', summary: 'Open issues with the rule each one rests on. No score.' },
+    scan_site: { kind: 'read', scopes: ['scans:run'], title: 'Queue a hosted scan', summary: 'Queue a scan, optionally wait for the summary.' },
+    get_scan: { kind: 'read', scopes: ['scans:read'], title: 'Get a scan', summary: 'Status, progress and summary of one scan.' },
+    list_findings: { kind: 'read', scopes: ['scans:read'], title: 'List scan findings', summary: 'Findings per tab: all, pre-consent, unclassified.' },
+    explain_classification: { kind: 'read', scopes: ['scans:read'], title: 'Explain why something is classified the way it is', summary: 'The matched tracker DB row with its source and licence, the pattern, the regime rule and the citation.' },
+    check_first_layer: { kind: 'read', scopes: ['banner:read'], title: 'Check the first layer', summary: 'The shared legal lint plus what the first layer offers, with citations.' },
+    rules_reference: { kind: 'read', scopes: [], title: 'The rules reference', summary: 'EDPB, CNIL, ICO, GDPR/ePrivacy, TCF, Law 25, CCPA — quotes only where verified.' },
+    get_declaration: { kind: 'read', scopes: ['banner:read'], title: 'Get the cookie declaration', summary: 'The current declaration as JSON, HTML or Markdown.' },
+    list_versions: { kind: 'read', scopes: ['banner:read'], title: 'List published versions', summary: 'The immutable version timeline with channel and author.' },
+    logs_summary: { kind: 'read', scopes: ['analytics:read'], title: 'Consent log summary', summary: 'Aggregates from the daily roll-ups. Never subject rows.' },
+    logs_export: { kind: 'read', scopes: ['logs:export'], title: 'Export consent logs', summary: 'Returns an export id and the signed URL — never rows inline.' },
+    classify_tracker: { kind: 'write', scopes: ['banner:write'], title: 'Classify a tracker (two-step)', summary: 'Move a service into another consent category.' },
+    update_banner: { kind: 'write', scopes: ['banner:write'], title: 'Patch the banner draft (two-step)', summary: 'JSON Merge Patch onto the draft. Never publishes.' },
+    push_config: { kind: 'write', scopes: ['banner:publish', 'banner:write'], title: 'Push and publish a configuration (two-step)', summary: 'Replace the draft and publish a new immutable version.' },
+    rollback_version: { kind: 'write', scopes: ['banner:publish'], title: 'Restore an earlier version (two-step)', summary: 'Publish an old version again under a new number.' },
+    // ---- site configuration (tools-config.ts): everything the dashboard can change, from an agent ----
+    create_site: { kind: 'write', scopes: ['sites:write'], title: 'Create a site (two-step)', summary: 'A new site with both environments and a first draft.' },
+    update_site: { kind: 'write', scopes: ['sites:write'], title: 'Rename a site, set retention or settings (two-step)', summary: 'Name, consent-record retention, site settings.' },
+    list_domains: { kind: 'read', scopes: ['sites:read'], title: 'List domains', summary: 'Domains with verification state and the token to publish.' },
+    verify_domain: { kind: 'write', scopes: ['sites:write'], title: 'Request domain verification (two-step)', summary: 'Re-issue the DNS TXT / meta token; the worker checks it.' },
+    list_scans: { kind: 'read', scopes: ['scans:read'], title: 'List scans', summary: 'Recent scans with status, trigger and summary.' },
+    get_scan_diff: { kind: 'read', scopes: ['scans:read'], title: 'Scan diff', summary: 'What changed since the previous scan.' },
+    get_scan_schedule: { kind: 'read', scopes: ['scans:read'], title: 'Get the scan schedule', summary: 'Cadence, next run, page cap, states, crawl scope.' },
+    set_scan_schedule: { kind: 'write', scopes: ['scans:run'], title: 'Change the scan schedule (two-step)', summary: 'Cadence, pages, states, start URLs, patterns, robots, pause.' },
+    get_install_status: { kind: 'read', scopes: ['scans:read'], title: 'Install status', summary: 'The latest install checks: is cc.js on the page?' },
+    check_install: { kind: 'read', scopes: ['scans:run'], title: 'Queue an install check', summary: 'Queue a check of the page, optionally wait for the result.' },
+    list_alerts: { kind: 'read', scopes: ['scans:read'], title: 'List alerts', summary: 'The alert inbox, open by default.' },
+    acknowledge_alert: { kind: 'write', scopes: ['scans:run'], title: 'Acknowledge an alert (two-step)', summary: 'Mark an alert as seen.' },
+    resolve_alert: { kind: 'write', scopes: ['scans:run'], title: 'Resolve an alert (two-step)', summary: 'Close an alert.' },
+    list_services: { kind: 'read', scopes: ['banner:read'], title: 'List services', summary: 'Declared trackers with category, basis and patterns.' },
+    add_service: { kind: 'write', scopes: ['banner:write'], title: 'Add a service (two-step)', summary: 'Declare a tracker by hand.' },
+    update_service: { kind: 'write', scopes: ['banner:write'], title: 'Update a service (two-step)', summary: 'Patterns, provider, basis, status of a service.' },
+    delete_service: { kind: 'write', scopes: ['banner:write'], title: 'Delete a service (two-step, destructive)', summary: 'Remove a service; findings return to unclassified.' },
+    suppress_issue: { kind: 'write', scopes: ['banner:write'], title: 'Suppress a compliance issue (two-step)', summary: 'With a reason that becomes the record.' },
+    unsuppress_issue: { kind: 'write', scopes: ['banner:write'], title: 'Reopen a suppressed issue (two-step)', summary: 'Put a suppressed issue back to open.' },
+    promote_version: { kind: 'write', scopes: ['banner:publish'], title: 'Promote a preview version (two-step)', summary: 'Publish a preview version to production as it is.' },
+    list_templates: { kind: 'read', scopes: ['banner:read'], title: 'List templates', summary: 'Built-in and workspace banner templates.' },
+    get_template: { kind: 'read', scopes: ['banner:read'], title: 'Get a template', summary: 'One template with its full config.' },
+    apply_template: { kind: 'write', scopes: ['banner:write'], title: 'Apply a template (two-step)', summary: 'Copy template groups into site drafts; never publishes.' },
+    save_template: { kind: 'write', scopes: ['banner:write'], title: 'Save a workspace template (two-step)', summary: 'From a site draft or a config; feature shared_templates.' },
+    delete_template: { kind: 'write', scopes: ['banner:write'], title: 'Delete a workspace template (two-step, destructive)', summary: 'Built-ins are refused.' },
+    list_webhooks: { kind: 'read', scopes: ['sites:read'], title: 'List webhooks', summary: 'Endpoints with events and last delivery; never the secret.' },
+    create_webhook: { kind: 'write', scopes: ['sites:write'], title: 'Create a webhook (two-step)', summary: 'The signing secret is returned once.' },
+    update_webhook: { kind: 'write', scopes: ['sites:write'], title: 'Update a webhook (two-step)', summary: 'URL, events, description, enabled.' },
+    delete_webhook: { kind: 'write', scopes: ['sites:write'], title: 'Delete a webhook (two-step, destructive)', summary: 'Endpoint and delivery history.' },
+    list_alert_channels: { kind: 'read', scopes: ['sites:read'], title: 'List alert channels', summary: 'E-mail, Slack and webhook destinations with their rules.' },
+    create_alert_channel: { kind: 'write', scopes: ['sites:write'], title: 'Create an alert channel (two-step)', summary: 'E-mail, Slack incoming webhook or webhook; secret write-only.' },
+    update_alert_channel: { kind: 'write', scopes: ['sites:write'], title: 'Update an alert channel (two-step)', summary: 'Name, enabled, config, secret.' },
+    delete_alert_channel: { kind: 'write', scopes: ['sites:write'], title: 'Delete an alert channel (two-step, destructive)', summary: 'Channel and its rules.' },
+    get_usage: { kind: 'read', scopes: ['sites:read'], title: 'Usage meters', summary: 'Pageviews, sites, seats, consents, scan pages, exports.' },
+    list_export_destinations: { kind: 'read', scopes: ['sites:read'], title: 'List export destinations', summary: 'Customer-owned buckets; never the secret key.' },
+    list_export_schedules: { kind: 'read', scopes: ['logs:export'], title: 'List scheduled exports', summary: 'Recurring proof exports with next and last run.' },
+    create_export_schedule: { kind: 'write', scopes: ['logs:export'], title: 'Schedule an export (two-step)', summary: 'Recurring export to a destination; feature scheduled_exports.' },
+    update_export_schedule: { kind: 'write', scopes: ['logs:export'], title: 'Change a scheduled export (two-step)', summary: 'Kind, cadence, timing, destination, enabled.' },
+    delete_export_schedule: { kind: 'write', scopes: ['logs:export'], title: 'Delete a scheduled export (two-step, destructive)', summary: 'Delivered files stay in the bucket.' },
+};
+/** Spread into a tool definition so the registered tool and this table cannot disagree. */
+export function meta(name) {
+    return TOOL_META[name];
+}
+/** Row list for the dashboard, in the order the tools are registered. */
+export const MCP_TOOL_MATRIX = Object.keys(TOOL_META).map((name) => ({
+    name,
+    ...TOOL_META[name],
+    scopes: [...TOOL_META[name].scopes],
+    two_step: TOOL_META[name].kind === 'write',
+}));
+/** Every scope any tool can ask for, in a stable order. */
+export const MCP_SCOPES = [...new Set(MCP_TOOL_MATRIX.flatMap((t) => t.scopes))].sort();
+/** The install snippets shown on the dashboard and in the README — one definition, two surfaces. */
+export function installSnippets(apiBase) {
+    const api = apiBase ? `\n        "COOKIECRUMBS_API": "${apiBase}"` : '';
+    return {
+        claudeCode: 'claude mcp add cookiecrumbs -- npx -y @cookiecrumbs-eu/mcp',
+        cursor: `// .cursor/mcp.json
+{
+  "mcpServers": {
+    "cookiecrumbs": {
+      "command": "npx",
+      "args": ["-y", "@cookiecrumbs-eu/mcp"],
+      "env": {
+        "COOKIECRUMBS_TOKEN": "cc_live_…"${api ? ',' + api : ''}
+      }
+    }
+  }
+}`,
+        env: `# The server reads the token from the environment, or from the CLI credentials file
+# written by \`npx cookiecrumbs login\`. It never runs a device flow itself.
+export COOKIECRUMBS_TOKEN=cc_live_…${apiBase ? `\nexport COOKIECRUMBS_API=${apiBase}` : ''}`,
+        manual: 'npx -y @cookiecrumbs-eu/mcp   # stdio; add it to any MCP client that speaks stdio',
+    };
+}