@cookiecrumbs-eu/mcp 0.7.0

package/dist/mcp/src/server.js

@@ -0,0 +1,171 @@
+/**
+ * The MCP server itself.
+ *
+ * Start-up order:
+ *   1. resolve the token (COOKIECRUMBS_TOKEN, else the CLI credentials file);
+ *   2. `GET /v1/me` to learn the scopes, the organisation and any site/environment restriction;
+ *   3. register only the tools those scopes allow — write tools disappear entirely for a
+ *      read-only token — plus the three resources.
+ *
+ * When there is no token, or /me fails, the server still starts and still advertises the
+ * tools, but every call answers with what to do about it. A stdio server has nowhere to run a
+ * device flow, so it never tries.
+ */
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { lintConfig } from "../../config/src/index.js";
+import { CliError } from "../../cli/src/errors.js";
+import { McpApi, sanitiseClient } from "./client.js";
+import { loginInstructions, resolveCredentials } from "./auth.js";
+import { TOOLS, TOOL_MATRIX, resolveSite, toolAllowed } from "./tools.js";
+export const SERVER_NAME = 'cookiecrumbs';
+export const SERVER_VERSION = '0.7.0';
+const text = (s) => ({ content: [{ type: 'text', text: s }] });
+const failure = (s) => ({ content: [{ type: 'text', text: s }], isError: true });
+/** RFC 9457 problem+json → something an agent can act on. */
+export function describeError(e) {
+    if (e instanceof CliError) {
+        const lines = [`${e.code}: ${e.detail}`];
+        if (e.status)
+            lines.push(`HTTP ${e.status}`);
+        if (e.status === 401)
+            lines.push('The token is missing, revoked or expired. Create a new one in the dashboard (Developers → MCP and CLI) or run `npx cookiecrumbs login`, then restart this server.');
+        if (e.status === 403)
+            lines.push('The token does not carry the scope this call needs. Issue a token with the required scope.');
+        if (e.status === 402)
+            lines.push('The workspace plan does not include this feature.');
+        if (e.status === 422 && e.extra?.lint)
+            lines.push(`Lint: ${JSON.stringify(e.extra.lint)}`);
+        if (e.status === 429)
+            lines.push('Rate limited (600 requests per minute per token). Retry in a moment.');
+        return lines.join('\n');
+    }
+    return e instanceof Error ? `${e.name}: ${e.message}` : String(e);
+}
+export async function buildServer(opts = {}) {
+    const env = opts.env ?? process.env;
+    const resolved = resolveCredentials(env);
+    const token = opts.token !== undefined ? opts.token : resolved.token;
+    // MCP_CLIENT wins; otherwise the name the MCP client sends in `initialize`.
+    let clientName = env.MCP_CLIENT?.trim() || null;
+    let initialiseName = null;
+    const currentClient = () => sanitiseClient(clientName ?? initialiseName ?? 'unknown');
+    const api = opts.api ?? new McpApi(resolved.api, token, currentClient);
+    let me = opts.me ?? null;
+    let authError = null;
+    if (!token) {
+        authError = loginInstructions();
+    }
+    else if (!me) {
+        try {
+            me = await api.me();
+        }
+        catch (e) {
+            authError = `Could not verify the token against ${resolved.api}.\n\n${describeError(e)}`;
+        }
+    }
+    const scopes = new Set(me?.token?.scopes ?? []);
+    const ctx = {
+        api,
+        me,
+        scopes,
+        siteId: me?.token?.site_id ?? null,
+        environment: me?.token?.environment ?? null,
+        sites: null,
+    };
+    // Without a working token we cannot know the scopes, so we advertise everything and let each
+    // call explain what to do — better than an empty, silent server.
+    const advertised = authError ? TOOLS : TOOLS.filter((t) => toolAllowed(t, scopes));
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        capabilities: { tools: {}, resources: {} },
+        instructions: instructionsFor(me, advertised, authError),
+    });
+    for (const def of advertised) {
+        server.registerTool(def.name, {
+            title: def.title,
+            description: def.kind === 'write' ? `${def.description}\n\nTwo-step: call with confirm:false (default) first and show the diff to the user.` : def.description,
+            inputSchema: def.inputSchema,
+            annotations: {
+                title: def.title,
+                readOnlyHint: def.readOnlyHint,
+                destructiveHint: def.destructiveHint ?? false,
+                idempotentHint: def.kind === 'read',
+                openWorldHint: true,
+            },
+        }, async (args) => {
+            if (authError && def.scopes.length)
+                return failure(authError);
+            try {
+                return text(await def.run(ctx, args ?? {}));
+            }
+            catch (e) {
+                return failure(describeError(e));
+            }
+        });
+    }
+    registerResources(server, ctx, () => authError);
+    return {
+        server,
+        ctx,
+        advertised,
+        scopes,
+        authError,
+        setClientName(name) {
+            initialiseName = name?.trim() || null;
+        },
+    };
+}
+function instructionsFor(me, advertised, authError) {
+    const lines = [
+        'CookieCrumbs — consent banner, hosted scans, consent logs and the compliance rules reference.',
+        '',
+        'House rules:',
+        '  • Every write tool is two-step. Call it with confirm:false first, show the unified diff and the',
+        '    lint result to the person you are working with, and only then call it again with confirm:true.',
+        '  • Nothing here is legal advice. Quote the citations; do not paraphrase them into advice.',
+        '  • No tool ever returns subject-level consent records. logs_export returns an id and a URL.',
+    ];
+    if (authError) {
+        lines.push('', 'No usable token yet:', authError);
+    }
+    else if (me) {
+        lines.push('', `Token: ${me.token?.name ?? '—'} (${me.token?.kind ?? '—'})  scopes: ${(me.token?.scopes ?? []).join(', ') || 'none'}`, me.token?.site_id ? `Restricted to site ${me.token.site_id}${me.token.environment ? ` / ${me.token.environment}` : ''}.` : 'Not restricted to one site.', `Workspace: ${me.org?.name ?? me.org?.slug ?? me.org?.id ?? '—'} (plan ${me.org?.plan ?? '—'})`, `Tools available with these scopes: ${advertised.map((t) => t.name).join(', ')}`);
+    }
+    return lines.join('\n');
+}
+function registerResources(server, ctx, authError) {
+    const guard = async (fn) => {
+        const err = authError();
+        if (err)
+            return err;
+        try {
+            return await fn();
+        }
+        catch (e) {
+            return describeError(e);
+        }
+    };
+    server.registerResource('site-config', new ResourceTemplate('cookiecrumbs://sites/{siteId}/config', { list: undefined }), { title: 'Banner configuration', description: 'The production draft configuration of a site, with its legal lint.', mimeType: 'application/json' }, async (uri, vars) => {
+        const body = await guard(async () => {
+            const id = await resolveSite(ctx, String(vars.siteId));
+            const draft = await ctx.api.getDraft(id, ctx.environment === 'preview' ? 'preview' : 'production');
+            return JSON.stringify({ site_id: id, updated_at: draft.updated_at, lint: draft.lint ?? lintConfig(draft.config), config: draft.config }, null, 2);
+        });
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: body }] };
+    });
+    server.registerResource('site-declaration', new ResourceTemplate('cookiecrumbs://sites/{siteId}/declaration', { list: undefined }), { title: 'Cookie declaration', description: 'The current cookie declaration of a site as Markdown.', mimeType: 'text/markdown' }, async (uri, vars) => {
+        const body = await guard(async () => {
+            const id = await resolveSite(ctx, String(vars.siteId));
+            return ctx.api.declaration(id, 'md');
+        });
+        return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: body }] };
+    });
+    server.registerResource('site-issues', new ResourceTemplate('cookiecrumbs://sites/{siteId}/issues', { list: undefined }), { title: 'Compliance issues', description: 'Open compliance issues of a site with the rule each one rests on.', mimeType: 'application/json' }, async (uri, vars) => {
+        const body = await guard(async () => {
+            const id = await resolveSite(ctx, String(vars.siteId));
+            const res = await ctx.api.request('GET', `/sites/${id}/issues`, { query: { status: 'open' } });
+            return JSON.stringify({ site_id: id, note: 'This is not a legal assessment.', issues: res.items ?? [] }, null, 2);
+        });
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: body }] };
+    });
+}
+export { TOOL_MATRIX, TOOLS };

package/dist/mcp/src/shared.js

@@ -0,0 +1,147 @@
+/**
+ * Helpers every tool file shares: the tool context and definition types, scope gating, site
+ * resolution (id / domain / name), lint and citation rendering, the dry-run block, and the scan
+ * lookups. tools.ts (the phase-6 core) and tools-config.ts (site configuration) both build on these.
+ */
+import { z } from 'zod';
+import { citationsFor, formatCitation, NOT_LEGAL_ADVICE } from "../../config/src/rules.js";
+import { CliError } from "../../cli/src/errors.js";
+import { stableJson } from "./diff.js";
+// --- small helpers ---------------------------------------------------------
+export const ENV = z.enum(['production', 'preview']);
+/** A tool is available when the token carries one of its scopes (or it needs none). */
+export function toolAllowed(def, scopes) {
+    return def.scopes.length === 0 || def.scopes.some((s) => scopes.has(s));
+}
+export function envOf(ctx, given) {
+    const v = typeof given === 'string' ? given : null;
+    if (v === 'production' || v === 'preview')
+        return v;
+    if (ctx.environment === 'production' || ctx.environment === 'preview')
+        return ctx.environment;
+    return 'production';
+}
+export async function allSites(ctx) {
+    if (!ctx.sites)
+        ctx.sites = await ctx.api.sites();
+    return ctx.sites;
+}
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Accept a site id, a primary domain or a name — agents rarely have the uuid to hand. */
+export async function resolveSite(ctx, ref) {
+    const raw = typeof ref === 'string' ? ref.trim() : '';
+    if (!raw) {
+        if (ctx.siteId)
+            return ctx.siteId;
+        const sites = await allSites(ctx);
+        if (sites.length === 1)
+            return sites[0].id;
+        throw new CliError('site_required', `Pass \`site\`. This token can see: ${sites.map((s) => `${s.primary_domain} (${s.id})`).join(', ') || 'no sites'}.`, 2);
+    }
+    if (UUID.test(raw))
+        return raw;
+    const sites = await allSites(ctx);
+    const needle = raw.toLowerCase().replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+    const hit = sites.find((s) => s.primary_domain?.toLowerCase() === needle) ??
+        sites.find((s) => s.name?.toLowerCase() === raw.toLowerCase()) ??
+        sites.find((s) => s.primary_domain?.toLowerCase().includes(needle));
+    if (!hit)
+        throw new CliError('not_found', `No site matches "${raw}". Known: ${sites.map((s) => s.primary_domain).join(', ') || 'none'}.`, 2);
+    return hit.id;
+}
+export function lintLines(lint) {
+    if (!lint)
+        return 'Lint: not available.';
+    const issues = lint.issues ?? [];
+    if (!issues.length)
+        return 'Lint: no issues.';
+    const order = { error: 0, warning: 1, info: 2 };
+    const sorted = [...issues].sort((a, b) => (order[a.severity] ?? 3) - (order[b.severity] ?? 3));
+    const head = `Lint: ${issues.filter((i) => i.severity === 'error').length} error(s), ${issues.filter((i) => i.severity === 'warning').length} warning(s), ${issues.filter((i) => i.severity === 'info').length} info.`;
+    return [head, ...sorted.map((i) => `  [${i.severity}] ${i.code} @ ${i.path}: ${i.message}`)].join('\n');
+}
+/**
+ * The citations behind a set of issue/lint codes. `topics` narrows a broad code to the part of
+ * the reference that actually bears on this case (a marketing cookie does not need the ICO's
+ * analytics exception), and `limit` keeps a tool answer readable. Entries with a verified quote
+ * come first — an entry we could not verify is still shown, but it is never dressed up.
+ */
+export function citationBlock(codes, opts = {}) {
+    const seen = new Map();
+    for (const c of codes)
+        for (const r of citationsFor(c))
+            seen.set(r.id, r);
+    let picked = [...seen.values()];
+    if (opts.topics?.length) {
+        const narrowed = picked.filter((r) => opts.topics.includes(r.topic));
+        if (narrowed.length)
+            picked = narrowed;
+    }
+    picked.sort((a, b) => Number(!a.quote) - Number(!b.quote));
+    if (opts.limit)
+        picked = picked.slice(0, opts.limit);
+    if (!picked.length)
+        return '';
+    const lines = ['', 'Citations:'];
+    for (const r of picked) {
+        lines.push(`  • ${formatCitation(r)}`);
+        if (r.quote)
+            lines.push(`      “${r.quote}”`);
+        else
+            lines.push(`      (no verified quotation on file) ${r.summary}`);
+    }
+    lines.push('', NOT_LEGAL_ADVICE);
+    return lines.join('\n');
+}
+/** Which corner of the reference bears on a category. */
+export function topicsForCategory(category) {
+    switch (category) {
+        case 'necessary':
+            return ['essential_cookies', 'prior_consent'];
+        case 'analytics':
+            return ['prior_consent', 'analytics', 'consent_definition'];
+        case 'marketing':
+            return ['prior_consent', 'legal_basis', 'consent_definition'];
+        default:
+            return ['prior_consent', 'consent_definition'];
+    }
+}
+export function renderRule(r) {
+    return [
+        `# ${r.id}  (topic: ${r.topic})`,
+        `Source:    ${r.source}`,
+        `URL:       ${r.source_url}`,
+        `Published: ${r.published}${r.paragraph ? `   Paragraph: ${r.paragraph}` : ''}`,
+        r.quote ? `Quote:     “${r.quote}”` : 'Quote:     — none on file; the wording of this source was not verified, so nothing is quoted.',
+        `Summary:   ${r.summary}`,
+        `Applies to: ${r.applies_to.join(', ')}`,
+    ].join('\n');
+}
+/** Dry-run block shared by every write tool. */
+export function dryRun(what, diff, lint, extra = []) {
+    const stats = diff ? '' : 'Nothing would change — the target already has this content.\n';
+    return [
+        `DRY RUN — nothing was changed. ${what}`,
+        '',
+        stats + (diff ? '```diff\n' + diff + '\n```' : ''),
+        '',
+        lintLines(lint),
+        ...extra,
+        '',
+        'Call the same tool again with `confirm: true` to apply it.',
+    ].join('\n');
+}
+export const jsonBlock = (v) => '```json\n' + stableJson(v) + '\n```';
+export async function recentScans(ctx, site) {
+    const res = await ctx.api.request('GET', `/sites/${site}/scans`, { query: { limit: 20 } });
+    const items = res?.items ?? [];
+    const completed = items.filter((s) => s.status === 'completed');
+    return completed.length ? completed : items;
+}
+export async function latestCompletedScan(ctx, site) {
+    return (await recentScans(ctx, site))[0] ?? null;
+}
+export async function findingsOf(ctx, scanId, tab) {
+    const body = await ctx.api.request('GET', `/scans/${scanId}/findings`, { query: { format: 'json', tab } });
+    return { findings: body.findings ?? [], scan: body.scan ?? {} };
+}