@cookiecrumbs-eu/mcp 0.7.0

package/dist/mcp/src/tools.js

@@ -0,0 +1,650 @@
+/**
+ * The tool table. One place that says, for every tool, what it is called, whether it reads or
+ * writes, which token scope it needs and how it runs — the dashboard's tool/scope matrix is
+ * generated from `TOOL_MATRIX` below, so the documentation cannot drift from the server.
+ *
+ * Two rules run through the whole file:
+ *   1. a tool is only advertised when the token carries a scope that allows it (contracts.md:
+ *      "write tools are advertised only when the token carries the scope" — we apply the same
+ *      rule to reads, because a tool that always fails is worse than one that is absent);
+ *   2. every write is two-step: `confirm:false` (the default) renders a unified diff plus the
+ *      lint result and changes nothing; `confirm:true` performs it.
+ *
+ * This file holds the phase-6 core (banner, scans, findings, rules, logs). Everything a site's
+ * configuration consists of beyond the banner draft lives in tools-config.ts; `TOOLS` at the
+ * bottom is the union the server registers.
+ */
+import { z } from 'zod';
+import { lintConfig } from "../../config/src/index.js";
+import { citationsFor, rulesFor, ruleById, searchRules, RULE_TOPICS, NOT_LEGAL_ADVICE } from "../../config/src/rules.js";
+import { CliError } from "../../cli/src/errors.js";
+import { jsonDiff, diffStats, mergePatch } from "./diff.js";
+import { MCP_TOOL_MATRIX, meta } from "./matrix.js";
+import { CONFIG_TOOLS } from "./tools-config.js";
+import { ENV, allSites, citationBlock, dryRun, envOf, findingsOf, jsonBlock, latestCompletedScan, lintLines, recentScans, renderRule, resolveSite, topicsForCategory, } from "./shared.js";
+export { toolAllowed, resolveSite } from "./shared.js";
+// --- the tools -------------------------------------------------------------
+const CORE_TOOLS = [
+    {
+        name: 'list_sites',
+        ...meta('list_sites'),
+        description: 'Every site this token can see, with its environments and public keys.',
+        inputSchema: {},
+        readOnlyHint: true,
+        async run(ctx) {
+            const sites = await allSites(ctx);
+            if (!sites.length)
+                return 'This token can see no sites.';
+            return sites
+                .map((s) => {
+                const envs = (s.environments ?? []).map((e) => `${e.name}=${e.public_key}`).join(', ');
+                return `- ${s.primary_domain}  ${s.name ? `(${s.name})` : ''}\n  id: ${s.id}\n  environments: ${envs || '—'}`;
+            })
+                .join('\n');
+        },
+    },
+    {
+        name: 'get_site',
+        ...meta('get_site'),
+        description: 'One site with its environments, languages and current version pointers.',
+        inputSchema: { site: z.string().optional().describe('site id, primary domain or name') },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            return jsonBlock(await ctx.api.site(id));
+        },
+    },
+    {
+        name: 'get_banner',
+        ...meta('get_banner'),
+        description: 'The current draft for an environment, the live version it would replace, and the legal lint of the draft.',
+        inputSchema: { site: z.string().optional(), env: ENV.optional().describe('production (default) or preview') },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const env = envOf(ctx, args.env);
+            const draft = await ctx.api.getDraft(id, env);
+            const versions = await ctx.api.versions(id).catch(() => []);
+            const live = versions.filter((v) => (v.environment ?? 'production') === env).sort((a, b) => b.number - a.number)[0] ?? null;
+            const lint = draft.lint ?? lintConfig(draft.config);
+            return [
+                `Site ${id} · environment ${env}`,
+                live ? `Live version: v${live.number} (${live.note ?? 'no note'}${live.channel ? `, via ${live.channel}` : ''}${live.actor_label ? `, ${live.actor_label}` : ''})` : 'Live version: none published yet',
+                `Draft updated: ${draft.updated_at}`,
+                '',
+                lintLines(lint),
+                '',
+                'Draft configuration:',
+                jsonBlock(draft.config),
+            ].join('\n');
+        },
+    },
+    {
+        name: 'get_compliance_status',
+        ...meta('get_compliance_status'),
+        description: 'The open compliance issues of a site with the rule each one rests on. There is no score and never will be one.',
+        inputSchema: { site: z.string().optional(), status: z.enum(['open', 'resolved', 'suppressed', 'all']).optional() },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const status = typeof args.status === 'string' ? args.status : 'open';
+            const body = await ctx.api.request('GET', `/sites/${id}/issues`, { query: { status } });
+            const items = body.items ?? [];
+            if (!items.length)
+                return `No ${status} compliance issues for site ${id}.\n\n${NOT_LEGAL_ADVICE}`;
+            const out = [`${items.length} ${status} issue(s) for site ${id}. There is no compliance score — each issue stands on its own rule.`, ''];
+            for (const i of items) {
+                const code = String(i.code);
+                out.push(`## ${code} — ${i.severity}`);
+                const rule = i.rule;
+                if (rule?.title)
+                    out.push(rule.title);
+                if (rule?.summary)
+                    out.push(rule.summary);
+                if (i.evidence)
+                    out.push(`Evidence: ${JSON.stringify(i.evidence)}`);
+                out.push(citationBlock([code], { limit: 4 }).trimStart());
+                out.push('');
+            }
+            return out.join('\n');
+        },
+    },
+    {
+        name: 'scan_site',
+        ...meta('scan_site'),
+        description: 'Queue a scan of the site. Optionally wait for it to finish (up to `wait` seconds) and return the summary.',
+        inputSchema: {
+            site: z.string().optional(),
+            env: ENV.optional(),
+            states: z.array(z.enum(['no_interaction', 'reject_all', 'accept_all'])).optional(),
+            page_cap: z.number().int().min(1).max(5000).optional(),
+            wait: z.number().int().min(0).max(600).optional().describe('seconds to wait for completion; 0 = return immediately'),
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const scan = await ctx.api.createScan(id, {
+                env: envOf(ctx, args.env),
+                states: args.states ?? undefined,
+                page_cap: args.page_cap ?? undefined,
+            });
+            const wait = typeof args.wait === 'number' ? args.wait : 0;
+            if (!wait)
+                return `Scan ${scan.id} queued (status ${scan.status}). Poll with get_scan.`;
+            const deadline = Date.now() + wait * 1000;
+            let current = scan;
+            while (Date.now() < deadline && !['completed', 'failed', 'cancelled'].includes(current.status)) {
+                await new Promise((r) => setTimeout(r, 3000));
+                current = await ctx.api.scan(scan.id);
+            }
+            return `Scan ${current.id}: ${current.status}\n${jsonBlock(current.summary ?? current.progress ?? {})}`;
+        },
+    },
+    {
+        name: 'get_scan',
+        ...meta('get_scan'),
+        description: 'Status, progress and summary of one scan.',
+        inputSchema: { scan_id: z.string().describe('scan uuid') },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            return jsonBlock(await ctx.api.scan(String(args.scan_id)));
+        },
+    },
+    {
+        name: 'list_findings',
+        ...meta('list_findings'),
+        description: 'Findings of a scan (defaults to the latest completed scan of the site). Tabs: all, preconsent, unknown.',
+        inputSchema: {
+            site: z.string().optional(),
+            scan_id: z.string().optional(),
+            tab: z.enum(['all', 'preconsent', 'unknown']).optional(),
+            limit: z.number().int().min(1).max(500).optional(),
+        },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            let scanId = typeof args.scan_id === 'string' ? args.scan_id : null;
+            if (!scanId) {
+                const site = await resolveSite(ctx, args.site);
+                const scan = await latestCompletedScan(ctx, site);
+                if (!scan)
+                    return `No scans for site ${site} yet — run scan_site first.`;
+                scanId = String(scan.id);
+            }
+            const tab = (typeof args.tab === 'string' ? args.tab : 'all');
+            const limit = typeof args.limit === 'number' ? args.limit : 100;
+            const { findings } = await findingsOf(ctx, scanId, tab);
+            if (!findings.length)
+                return `Scan ${scanId}: no findings in tab "${tab}".`;
+            const rows = findings.slice(0, limit).map((f) => {
+                const flag = f.loaded_pre_consent ? ' PRE-CONSENT' : '';
+                return `- ${f.kind} ${f.name} @ ${f.host} [${f.party}] → ${f.suggested_category ?? 'unclassified'} (${f.classification_source ?? 'no source'}, status ${f.status}, severity ${f.severity})${flag}`;
+            });
+            return [`Scan ${scanId} · tab ${tab} · ${findings.length} finding(s)${findings.length > limit ? ` (showing ${limit})` : ''}`, ...rows].join('\n');
+        },
+    },
+    {
+        name: 'explain_classification',
+        ...meta('explain_classification'),
+        description: 'Why one cookie, script or request carries the category it does: the matched tracker database row with its source and licence, the pattern that matched, the regime rule applied, and the citation. Unclassified findings are reported as unclassified — never guessed.',
+        inputSchema: {
+            site: z.string().optional(),
+            cookie: z.string().optional().describe('cookie / storage key / script name, e.g. "_fbp"'),
+            finding: z.string().optional().describe('finding_key or finding id, if you have it'),
+            scan_id: z.string().optional(),
+            env: ENV.optional(),
+        },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const site = await resolveSite(ctx, args.site);
+            const needle = String(args.cookie ?? args.finding ?? '').trim();
+            if (!needle)
+                throw new CliError('usage', 'Pass `cookie` (a cookie / script / storage name) or `finding` (a finding_key or id).', 2);
+            // Which scans to look in: the one that was asked for, or the recent completed ones
+            // newest first. A cookie can be absent from the newest scan (a different start URL, a
+            // shallower crawl) and still be a real observation of this site — we say which scan it
+            // came from rather than pretending it is not there or inventing it.
+            let scanIds;
+            if (typeof args.scan_id === 'string' && args.scan_id) {
+                scanIds = [args.scan_id];
+            }
+            else {
+                const recent = await recentScans(ctx, site);
+                if (!recent.length)
+                    return `No scans for site ${site} yet — run scan_site first.`;
+                scanIds = recent.slice(0, 5).map((s) => String(s.id));
+            }
+            const lower = needle.toLowerCase();
+            const pick = (findings) => findings.find((f) => String(f.finding_key ?? '') === needle || String(f.id ?? '') === needle) ??
+                findings.find((f) => String(f.name ?? '').toLowerCase() === lower) ??
+                findings.find((f) => String(f.name ?? '').toLowerCase().startsWith(lower)) ??
+                findings.find((f) => String(f.host ?? '').toLowerCase().includes(lower));
+            let hit;
+            let scanId = scanIds[0];
+            const seenNames = new Set();
+            for (const id of scanIds) {
+                const { findings } = await findingsOf(ctx, id, 'all');
+                for (const f of findings)
+                    seenNames.add(String(f.name ?? ''));
+                const found = pick(findings);
+                if (found) {
+                    hit = found;
+                    scanId = id;
+                    break;
+                }
+            }
+            if (!hit) {
+                const names = [...seenNames].sort().slice(0, 40);
+                return `No finding matching "${needle}" in the ${scanIds.length} most recent scan(s) of site ${site} (${scanIds.join(', ')}). They observed: ${names.join(', ') || 'nothing'}.`;
+            }
+            const cls = hit.attrs?.classification;
+            const head = [
+                `# ${hit.kind} \`${hit.name}\` on ${hit.host} (${hit.party} party)`,
+                `Scan ${scanId} · finding_key \`${hit.finding_key}\` · status ${hit.status} · severity ${hit.severity}` +
+                    (hit.loaded_pre_consent ? ' · **loaded before consent**' : ''),
+                '',
+            ];
+            if (!cls || !hit.suggested_category) {
+                return [
+                    ...head,
+                    'This finding is **unclassified**. Nothing in the tracker database or in this site’s services matched it, so CookieCrumbs has no category for it and will not invent one.',
+                    '',
+                    'Until it is classified it is blocked in opt-in regimes when strict blocking is on, and it is reported as `unclassified_tracker`.',
+                    citationBlock(['unclassified_tracker'], { limit: 4 }),
+                ].join('\n');
+            }
+            const t = cls.tracker ?? {};
+            const p = cls.pattern;
+            const s = cls.service;
+            const category = String(cls.suggested_category ?? hit.suggested_category);
+            const out = [
+                ...head,
+                `## Category: ${category}`,
+                `Decided by: ${cls.matched_via ?? cls.classification_source} (classification_source \`${cls.classification_source}\`, confidence ${cls.confidence ?? hit.confidence ?? '—'})`,
+                '',
+                '## The tracker database row this came from',
+                `  provider:        ${t.provider_name ?? '—'} (${t.provider_domain ?? '—'})`,
+                `  default category:${' '} ${t.default_category ?? '—'}`,
+                `  tracker_db id:   ${t.id ?? '—'}   added in tracker DB version ${t.version_added ?? '—'}`,
+                `  source:          ${t.source ?? '—'}${t.source_ref ? ` (${t.source_ref})` : ''}`,
+                `  licence:         ${t.licence ?? '—'}`,
+                `  DB confidence:   ${t.db_confidence ?? '—'}`,
+                `  privacy policy:  ${t.privacy_url ?? '—'}`,
+                `  Consent Mode:    ${Array.isArray(t.gcm_mapping) ? t.gcm_mapping.join(', ') : '—'}`,
+                t.descriptions && typeof t.descriptions === 'object' ? `  description:     ${t.descriptions.en ?? ''}` : '',
+                '',
+                '## The pattern that matched',
+                p
+                    ? `  tracker_patterns row ${p.id}: kind=${p.kind}, pattern=\`${p.pattern}\`, match_type=${p.match_type}${p.lifetime_hint_seconds ? `, lifetime hint ${p.lifetime_hint_seconds}s` : ''}`
+                    : '  No tracker_patterns row matched this finding directly (see the service below).',
+                s ? `  Matched through the site service “${s.name}” (${s.status}, source ${s.source}, legal basis ${s.legal_basis}, category ${s.category_key}).` : '',
+                '',
+                '## The regime rule applied',
+                category === 'necessary'
+                    ? '  A strictly-necessary item is never gated: it may be set before any choice, in every regime.'
+                    : `  Under an opt-in regime (eu_optin, uk_pecr, ch_fadp strict, br_lgpd, ca_qc) nothing in category "${category}" may be stored or read before the visitor gives consent; under us_optout it is granted by default and denied as soon as a Global Privacy Control signal is seen${category === 'marketing' ? ' (marketing is treated as sale/share/targeted advertising)' : ''}.` +
+                        (hit.loaded_pre_consent
+                            ? '\n  This finding was observed **before** the visitor made a choice, which is why it is reported as `preconsent_tracker`.'
+                            : '\n  In this scan it was not observed before the choice, so it is not reported as `preconsent_tracker`.'),
+                citationBlock(['preconsent_tracker'], { topics: topicsForCategory(category), limit: 5 }),
+            ];
+            return out.filter((l) => l !== '').join('\n');
+        },
+    },
+    {
+        name: 'check_first_layer',
+        ...meta('check_first_layer'),
+        description: 'Run the shared legal lint over the current draft and report what the first layer offers: Accept all / Reject all parity, pre-ticked categories, the re-open control and the closing-counts-as-refusal text. Every finding carries its citation.',
+        inputSchema: { site: z.string().optional(), env: ENV.optional() },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const env = envOf(ctx, args.env);
+            const draft = await ctx.api.getDraft(id, env);
+            const cfg = draft.config;
+            const lint = lintConfig(cfg);
+            const facts = [];
+            const codes = new Set(lint.issues.map((i) => i.code));
+            facts.push(`layout: ${cfg.layout}${cfg.layout === 'headless' ? ' — the runtime renders nothing; your own UI must carry Accept all, Reject all and settings with equal prominence' : ''}`);
+            const preTicked = (cfg.categories ?? []).filter((c) => c.key !== 'necessary' && c.default).map((c) => c.key);
+            facts.push(`categories on by default (other than necessary): ${preTicked.length ? preTicked.join(', ') : 'none'}`);
+            if (preTicked.length)
+                codes.add('default_on_non_necessary');
+            facts.push(`re-open control: ${cfg.behaviour?.reopen_control ?? '—'}`);
+            if (!['floating', 'link'].includes(String(cfg.behaviour?.reopen_control)))
+                codes.add('reopen_disabled');
+            facts.push(`closing the banner counts as a refusal: ${cfg.behaviour?.implied_dismiss ? 'yes — the banner must say so' : 'no'}`);
+            if (cfg.behaviour?.implied_dismiss)
+                codes.add('implied_dismiss_text_missing');
+            facts.push(`Accept all and Reject all share one button style in the runtime, so first-layer parity is a theme question: text ${cfg.theme?.text} on ${cfg.theme?.background}, button ${cfg.theme?.button_text} on ${cfg.theme?.button}.`);
+            codes.add('reject_not_layer1');
+            return [
+                `First-layer check for site ${id} · environment ${env}`,
+                '',
+                ...facts.map((f) => `- ${f}`),
+                '',
+                lintLines(lint),
+                citationBlock([...codes], { limit: 8 }),
+            ].join('\n');
+        },
+    },
+    {
+        name: 'rules_reference',
+        ...meta('rules_reference'),
+        description: 'The shared citation knowledge base: EDPB cookie banner taskforce paragraphs, CNIL, ICO, GDPR/ePrivacy articles, TCF policies, Quebec Law 25 and the US opt-out regulations. Filter by topic, by issue code or by free text. Entries whose exact wording could not be verified carry no quote.',
+        inputSchema: {
+            topic: z.string().optional().describe(`one of: ${RULE_TOPICS.join(', ')}`),
+            issue: z.string().optional().describe('a compliance issue code or a lint code'),
+            id: z.string().optional().describe('a rule id'),
+            query: z.string().optional().describe('free text'),
+        },
+        readOnlyHint: true,
+        async run(_ctx, args) {
+            let hits;
+            if (typeof args.id === 'string' && args.id) {
+                const one = ruleById(args.id);
+                if (!one)
+                    return `No rule with id "${args.id}". Topics: ${RULE_TOPICS.join(', ')}.`;
+                hits = [one];
+            }
+            else if (typeof args.topic === 'string' && args.topic) {
+                hits = rulesFor(args.topic);
+                if (!hits.length)
+                    return `No rules for topic "${args.topic}". Topics: ${RULE_TOPICS.join(', ')}.`;
+            }
+            else if (typeof args.issue === 'string' && args.issue) {
+                hits = citationsFor(args.issue);
+                if (!hits.length)
+                    return `No rules filed against "${args.issue}".`;
+            }
+            else if (typeof args.query === 'string' && args.query) {
+                hits = searchRules(args.query);
+                if (!hits.length)
+                    return `Nothing matches "${args.query}".`;
+            }
+            else {
+                hits = searchRules('');
+            }
+            return [...hits.map(renderRule), '', NOT_LEGAL_ADVICE].join('\n\n');
+        },
+    },
+    {
+        name: 'get_declaration',
+        ...meta('get_declaration'),
+        description: 'The current cookie declaration of a site as JSON, HTML or Markdown.',
+        inputSchema: { site: z.string().optional(), lang: z.string().optional(), format: z.enum(['json', 'html', 'md']).optional() },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const format = (typeof args.format === 'string' ? args.format : 'md');
+            const lang = typeof args.lang === 'string' ? args.lang : undefined;
+            return ctx.api.declaration(id, format, lang);
+        },
+    },
+    {
+        name: 'list_versions',
+        ...meta('list_versions'),
+        description: 'The immutable version timeline of a site: number, environment, note, channel and who published it.',
+        inputSchema: { site: z.string().optional(), env: ENV.optional(), limit: z.number().int().min(1).max(200).optional() },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const env = typeof args.env === 'string' ? args.env : null;
+            const limit = typeof args.limit === 'number' ? args.limit : 25;
+            const versions = (await ctx.api.versions(id))
+                .filter((v) => !env || (v.environment ?? 'production') === env)
+                .sort((a, b) => b.number - a.number)
+                .slice(0, limit);
+            if (!versions.length)
+                return `Site ${id} has no published versions${env ? ` in ${env}` : ''}.`;
+            return versions
+                .map((v) => `- v${v.number} [${v.environment ?? 'production'}] ${v.published_at ?? v.created_at ?? ''} ${v.material || v.material_change ? '(material)' : ''}\n    note: ${v.note ?? '—'}\n    via ${v.channel ?? '—'}${v.actor_label ? ` · ${v.actor_label}` : ''}  id ${v.id}`)
+                .join('\n');
+        },
+    },
+    {
+        name: 'logs_summary',
+        ...meta('logs_summary'),
+        description: 'Aggregated consent figures from the daily roll-ups. Never returns subject-level rows.',
+        inputSchema: {
+            site: z.string().optional(),
+            from: z.string().optional().describe('YYYY-MM-DD'),
+            to: z.string().optional().describe('YYYY-MM-DD'),
+            env: ENV.optional(),
+            dimension: z.enum(['region', 'country', 'device', 'language', 'version', 'layout']).optional(),
+        },
+        readOnlyHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const today = new Date();
+            const iso = (d) => d.toISOString().slice(0, 10);
+            const to = typeof args.to === 'string' ? args.to : iso(today);
+            const from = typeof args.from === 'string' ? args.from : iso(new Date(today.getTime() - 29 * 86400000));
+            try {
+                const body = await ctx.api.request('GET', `/sites/${id}/analytics/daily`, {
+                    query: { from, to, env: envOf(ctx, args.env), dimension: typeof args.dimension === 'string' ? args.dimension : undefined },
+                });
+                return [`Consent summary for site ${id}, ${from} → ${to} (aggregates only — no subject rows are ever returned).`, jsonBlock(body)].join('\n');
+            }
+            catch (e) {
+                if (e instanceof CliError && (e.status === 404 || e.status === 405)) {
+                    return `The analytics roll-up route \`GET /v1/sites/:id/analytics/daily\` is not available on this gateway yet, so no summary can be produced. Nothing was read.`;
+                }
+                throw e;
+            }
+        },
+    },
+    {
+        name: 'logs_export',
+        ...meta('logs_export'),
+        description: 'Create a consent log export and return the export id and the signed download URL. Subject rows are never returned inline — download the artefact yourself if you need it.',
+        inputSchema: {
+            site: z.string().optional(),
+            from: z.string().optional().describe('YYYY-MM-DD'),
+            to: z.string().optional().describe('YYYY-MM-DD'),
+            format: z.enum(['jsonl', 'csv', 'bundle']).optional(),
+            env: ENV.optional(),
+            wait: z.number().int().min(0).max(300).optional().describe('seconds to wait for the job to finish (default 60)'),
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const format = (typeof args.format === 'string' ? args.format : 'jsonl');
+            const kind = format === 'csv' ? 'consent_csv' : format === 'bundle' ? 'audit_bundle' : 'consent_jsonl';
+            const job = await ctx.api.createExport(id, {
+                kind: kind,
+                from: typeof args.from === 'string' ? args.from : undefined,
+                to: typeof args.to === 'string' ? args.to : undefined,
+                env: envOf(ctx, args.env),
+            });
+            const wait = typeof args.wait === 'number' ? args.wait : 60;
+            const deadline = Date.now() + wait * 1000;
+            let current = job;
+            while (Date.now() < deadline && !['completed', 'failed', 'expired'].includes(current.status)) {
+                await new Promise((r) => setTimeout(r, 2000));
+                current = await ctx.api.exportJob(job.id);
+            }
+            const url = ctx.api.url(`/exports/${current.id}/download`);
+            return [
+                `Export ${current.id} — status ${current.status}, kind ${current.kind}.`,
+                current.record_count != null ? `Records: ${current.record_count}` : '',
+                current.sha256 ? `SHA-256: ${current.sha256}` : '',
+                current.expires_at ? `Expires: ${current.expires_at}` : '',
+                '',
+                current.status === 'completed'
+                    ? `Download (send the same bearer token):\n  ${url}`
+                    : `Not finished yet. Re-run this tool or fetch ${url} once the job completes.`,
+                '',
+                'No consent record is returned through this tool — only the export id and its URL.',
+            ]
+                .filter(Boolean)
+                .join('\n');
+        },
+    },
+    // --- write tools: advertised only when the token carries the scope --------
+    {
+        name: 'classify_tracker',
+        ...meta('classify_tracker'),
+        description: 'Move a service into a different consent category. `confirm:false` (default) shows the diff and the effect; `confirm:true` writes it. Requires PATCH /v1/services/:id on the gateway.',
+        inputSchema: {
+            site: z.string().optional(),
+            service: z.string().describe('service id, or the service / provider name as shown by get_compliance_status'),
+            category: z.string().describe('target category key, e.g. marketing, analytics, functional, necessary'),
+            legal_basis: z.enum(['consent', 'legitimate_interest', 'contract', 'legal_obligation']).optional(),
+            justification: z.string().optional(),
+            confirm: z.boolean().optional().describe('false (default) = dry run'),
+        },
+        readOnlyHint: false,
+        destructiveHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const body = await ctx.api.request('GET', `/sites/${id}/services`);
+            const services = body.items ?? [];
+            const ref = String(args.service);
+            const svc = services.find((s) => String(s.id) === ref) ??
+                services.find((s) => String(s.name ?? '').toLowerCase() === ref.toLowerCase()) ??
+                services.find((s) => String(s.provider_name ?? '').toLowerCase() === ref.toLowerCase());
+            if (!svc)
+                return `No service matches "${ref}". Site ${id} has: ${services.map((s) => `${s.name} (${s.id})`).join(', ') || 'none'}.`;
+            const patch = { category_key: String(args.category) };
+            if (typeof args.legal_basis === 'string')
+                patch.legal_basis = args.legal_basis;
+            if (typeof args.justification === 'string')
+                patch.justification = args.justification;
+            const after = mergePatch(svc, patch);
+            const diff = jsonDiff(svc, after, `service ${svc.id} (current)`, `service ${svc.id} (proposed)`);
+            if (args.confirm !== true) {
+                return dryRun(`Would move “${svc.name}” from category "${svc.category_key}" to "${args.category}".`, diff, null, [
+                    '',
+                    `Effect: every finding attributed to this service is re-categorised on the next scan, and the cookie declaration changes accordingly.`,
+                    citationBlock(['unclassified_tracker'], { limit: 4 }),
+                ]);
+            }
+            try {
+                const updated = await ctx.api.request('PATCH', `/services/${svc.id}`, { body: patch });
+                return `Service ${svc.id} updated.\n${jsonBlock(updated)}`;
+            }
+            catch (e) {
+                if (e instanceof CliError && (e.status === 404 || e.status === 405)) {
+                    return `Nothing was changed: this gateway does not expose \`PATCH /v1/services/:id\` yet, so the confirmed write cannot be made from MCP. Change the category in the dashboard under Site → Services, or upgrade the gateway.`;
+                }
+                throw e;
+            }
+        },
+    },
+    {
+        name: 'update_banner',
+        ...meta('update_banner'),
+        description: 'Apply an RFC 7386 JSON Merge Patch to the banner draft. `confirm:false` (default) returns the unified diff and the lint of the result; `confirm:true` saves the draft. It never publishes — use push_config for that.',
+        inputSchema: {
+            site: z.string().optional(),
+            env: ENV.optional(),
+            patch: z.record(z.unknown()).describe('JSON Merge Patch: null removes a key, arrays and scalars replace'),
+            confirm: z.boolean().optional(),
+        },
+        readOnlyHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const env = envOf(ctx, args.env);
+            const draft = await ctx.api.getDraft(id, env);
+            const next = mergePatch(draft.config, args.patch);
+            const diff = jsonDiff(draft.config, next, `draft ${env} (current)`, `draft ${env} (patched)`);
+            const lint = await ctx.api.validate(id, next).catch(() => lintConfig(next));
+            if (args.confirm !== true) {
+                const stats = diffStats(draft.config, next);
+                return dryRun(`Would patch the ${env} draft of site ${id} (+${stats.added}/-${stats.removed} lines).`, diff, lint, [
+                    '',
+                    'The draft is not published by this tool — publishing is a separate, audited step (push_config).',
+                    citationBlock(lint.issues.map((i) => i.code), { limit: 6 }),
+                ]);
+            }
+            const saved = await ctx.api.putDraft(id, env, next, draft.updated_at);
+            return [`Draft saved for site ${id} (${env}) at ${saved.updated_at}. Nothing is live until it is published.`, lintLines(saved.lint ?? lint)].join('\n');
+        },
+    },
+    {
+        name: 'push_config',
+        ...meta('push_config'),
+        description: 'Replace the draft with a full BannerConfig and publish it as a new immutable version. `confirm:false` (default) returns the unified diff against what is live plus the lint result and publishes nothing; `confirm:true` saves the draft and publishes. The audit trail records it as via MCP with this token’s name.',
+        inputSchema: {
+            site: z.string().optional(),
+            env: ENV.optional(),
+            config: z.record(z.unknown()).describe('the full BannerConfig — push merges nothing'),
+            note: z.string().optional().describe('change note, required for a confirmed publish'),
+            material: z.boolean().optional().describe('true if visitors must be asked again'),
+            confirm: z.boolean().optional(),
+        },
+        readOnlyHint: false,
+        destructiveHint: false,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const env = envOf(ctx, args.env);
+            const next = args.config;
+            const draft = await ctx.api.getDraft(id, env);
+            const lint = await ctx.api.validate(id, next).catch(() => lintConfig(next));
+            const diff = jsonDiff(draft.config, next, `draft ${env} (current)`, `draft ${env} (proposed)`);
+            if (args.confirm !== true) {
+                const stats = diffStats(draft.config, next);
+                const blocking = lint.issues.filter((i) => i.severity === 'error');
+                return dryRun(`Would publish a new ${env} version of site ${id} (+${stats.added}/-${stats.removed} lines).`, diff, lint, [
+                    '',
+                    blocking.length ? `This would be REJECTED: ${blocking.length} blocking lint error(s) — publish_config refuses errors.` : 'No blocking lint errors.',
+                    args.material === true ? 'Marked material: every visitor is asked again.' : 'Not marked material.',
+                    citationBlock(lint.issues.map((i) => i.code), { limit: 6 }),
+                ]);
+            }
+            if (!args.note)
+                throw new CliError('usage', 'A confirmed publish needs a `note` — it is written into the version and into the audit trail.', 2);
+            await ctx.api.putDraft(id, env, next, draft.updated_at);
+            const version = await ctx.api.publish(id, { env, note: String(args.note), material: args.material === true });
+            return [
+                `Published v${version.number} of site ${id} (${env}).`,
+                `note: ${version.note ?? ''}`,
+                `channel: ${version.channel ?? 'mcp'}${version.actor_label ? ` · ${version.actor_label}` : ''}`,
+                `version id: ${version.id}`,
+                '',
+                lintLines(lint),
+            ].join('\n');
+        },
+    },
+    {
+        name: 'rollback_version',
+        ...meta('rollback_version'),
+        description: 'Restore a published version as a new version. `confirm:false` (default) shows the unified diff between what is live and the target plus the lint of the target; `confirm:true` performs the rollback.',
+        inputSchema: {
+            site: z.string().optional(),
+            env: ENV.optional(),
+            number: z.number().int().min(1).describe('the version number to restore'),
+            confirm: z.boolean().optional(),
+        },
+        readOnlyHint: false,
+        destructiveHint: true,
+        async run(ctx, args) {
+            const id = await resolveSite(ctx, args.site);
+            const env = envOf(ctx, args.env);
+            const number = Number(args.number);
+            const versions = (await ctx.api.versions(id)).filter((v) => (v.environment ?? 'production') === env);
+            const target = versions.find((v) => v.number === number);
+            if (!target)
+                return `Site ${id} has no v${number} in ${env}. Available: ${versions.map((v) => `v${v.number}`).join(', ') || 'none'}.`;
+            const live = [...versions].sort((a, b) => b.number - a.number)[0] ?? null;
+            const targetFull = await ctx.api.version(target.id);
+            const liveFull = live ? await ctx.api.version(live.id) : null;
+            const diff = jsonDiff(liveFull?.config ?? {}, targetFull.config ?? {}, `live v${live?.number ?? '—'}`, `target v${number}`);
+            const lint = lintConfig(targetFull.config ?? {});
+            if (args.confirm !== true) {
+                return dryRun(`Would restore v${number} of site ${id} (${env}) as a new version v${(live?.number ?? number) + 1}.`, diff, lint, [
+                    '',
+                    'Rollback never rewrites history: it publishes the old configuration again under a new number.',
+                ]);
+            }
+            const created = await ctx.api.rollback(target.id, env);
+            return `Restored v${number} as v${created.number} of site ${id} (${env}). Version id ${created.id}.`;
+        },
+    },
+];
+/** Every tool the server can register: the phase-6 core plus the site-configuration tools. */
+export const TOOLS = [...CORE_TOOLS, ...CONFIG_TOOLS];
+/** name → definition. */
+export const TOOL_BY_NAME = new Map(TOOLS.map((t) => [t.name, t]));
+/** The tool/scope matrix the dashboard renders — the same table the tools above are built from. */
+export { MCP_TOOL_MATRIX as TOOL_MATRIX };