@certscore/mcp 0.2.20 → 0.2.22

package/dist/server.js

@@ -1,8 +1,13 @@
+import { registerAdoptionFeatures, EXAMPLE_SCAN_ID } from "./adoption.js";
+import { withResponseGuidance } from "./response-guidance.js";
+import { randomUUID } from "node:crypto";
+import { captureMcpResponse, withResponseCapture } from "./response-capture.js";
+import { z } from "zod";
 import { captureMcpCallerInput } from "@website-signal-risk-scanner/shared/dist/mcp-caller-input.js";
-import { CertScoreClient } from "@certscore/sdk";
-import { certScoreMcpToolContracts, isCanonicalScanId } from "@certscore/api-contracts";
+import { CertScoreClient, CertScoreError } from "@certscore/sdk";
+import { certScoreMcpToolContracts, isCanonicalScanId, reportEvidencePageSchema } from "@certscore/api-contracts";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { sanitizeMcpTaskContext } from "@website-signal-risk-scanner/shared/dist/mcp-product-context.js";
 import { CERTSCORE_MCP_VERSION } from "./version.js";
 import { boundEvidencePacket, buildScanBundle, exportFindings, findingListText, limitPreConsentRows, markdownReportText, MAX_EVIDENCE_PACKET_CHARS, normalizeDetail, normalizeFormat, paginateFindingList, preConsentInventoryText, pulseReportText, scanBundleText, scanSiteText, scanStatusText, toInvalidArgumentsToolError, toInvalidScanIdToolError, toToolError, toToolResult, withMcpAgentGuidance, withMcpScanProvenanceGuidance } from "./tools.js";
@@ -202,11 +207,21 @@ export function projectMcpToolInvocationObservation(input) {
     const error = result.error && typeof result.error === "object" && !Array.isArray(result.error)
         ? result.error
         : null;
-    const errorCode = boundedTelemetryToken(error?.code ?? result.errorCode, 100);
+    const completedNoGo = result.status === "completed_limited"
+        && result.resultDisposition === "no_go";
+    // A completed no-go is a usable terminal scan result. Agent guidance embeds
+    // its reason-specific remedy in `error`, but the MCP tool call itself
+    // succeeded and must not be counted as a transport or invocation failure.
+    const errorCode = completedNoGo
+        ? null
+        : boundedTelemetryToken(error?.code ?? result.errorCode, 100);
     const rateLimited = errorCode === "rate_limited" || result.status === "rate_limited";
-    const isError = Boolean(input.result?.isError) || Boolean(error);
+    const isError = !completedNoGo
+        && (Boolean(input.result?.isError) || Boolean(error));
     const outcome = rateLimited ? "rate_limited" : isError ? "error" : "success";
-    const resultScanId = boundedTelemetryToken(result.scanId ?? result.scan_id ?? result.jobId, 128);
+    const scan = result.type === "certscore_domain_latest_scan" && result.scan && typeof result.scan === "object"
+        ? result.scan : result;
+    const resultScanId = boundedTelemetryToken(scan.scanId ?? scan.scan_id ?? scan.jobId, 128);
     const inputScanId = boundedTelemetryToken(args.scanId, 128);
     const requestedResource = requestedTelemetryResource(args);
     const targetHostname = input.toolName === "certscore_scan_site"
@@ -239,11 +254,12 @@ export function projectMcpToolInvocationObservation(input) {
         scanDecision,
         scanFrom: args.scanFrom === "eu_de" || args.scanFrom === "eu_ie" || args.scanFrom === "california"
             ? args.scanFrom
-            : result.scanFrom === "eu_de" || result.scanFrom === "eu_ie" || result.scanFrom === "california"
-                ? result.scanFrom
+            : scan.scanFrom === "eu_de" || scan.scanFrom === "eu_ie" || scan.scanFrom === "california"
+                ? scan.scanFrom
                 : null,
-        scanId: resultScanId ?? inputScanId,
-        scanStatus: boundedTelemetryToken(result.status, 64),
+        scanId: outcome === "error" && ["invalid_scan_id", "invalid_arguments", "invalid_url", "unknown_tool"].includes(errorCode ?? "")
+            ? null : resultScanId ?? inputScanId,
+        scanStatus: boundedTelemetryToken(scan.status ?? scan.scanStatus, 64),
         targetHostname,
         toolName: input.toolName,
         transportOutcome: isError ? "mcp_error" : "mcp_result",
@@ -278,8 +294,8 @@ function observeToolInvocation(observer, observation, requestContext) {
     });
 }
 export function createCertScoreMcpServer(options = {}) {
-    const createClient = (forwardedClientIp, anonymousRequesterSession) => new CertScoreClient({
-        apiKey: options.apiKey,
+    const createClient = (forwardedClientIp, anonymousRequesterSession, apiKey = options.apiKey) => new CertScoreClient({
+        apiKey,
         baseUrl: options.baseUrl,
         clientName: "mcp",
         forwardedClientIp,
@@ -289,24 +305,72 @@ export function createCertScoreMcpServer(options = {}) {
         timeout: options.timeout
     });
     const client = createClient(options.forwardedClientIp, options.resolveAnonymousRequesterSession?.());
-    const clientForRequest = (extra) => options.resolveForwardedClientIp
-        ? createClient(options.resolveForwardedClientIp(extra.requestInfo?.headers ?? {}), options.resolveAnonymousRequesterSession?.())
-        : client;
+    const clientForRequest = (extra) => {
+        if (!options.resolveApiKey && !options.resolveForwardedClientIp)
+            return client;
+        const apiKey = options.resolveApiKey ? options.resolveApiKey() : options.apiKey;
+        if (options.resolveApiKey && !apiKey?.trim()) {
+            throw new Error("Validated MCP request credential is unavailable.");
+        }
+        return createClient(options.resolveForwardedClientIp ? options.resolveForwardedClientIp(extra.requestInfo?.headers ?? {}) : options.forwardedClientIp, options.resolveAnonymousRequesterSession?.(), apiKey);
+    };
     const server = new McpServer({
         name: "certscore",
         version: CERTSCORE_MCP_VERSION
+    }, {
+        instructions: JSON.stringify({
+            setup: {
+                route: options.toolProfile === "light" ? "light" : options.grantedOAuthScopes ? "hosted_oauth" : options.anonymousSurface ? "anonymous" : "scoped_api_key",
+                scopesGranted: options.grantedOAuthScopes ?? null,
+                createAllowedByScope: options.grantedOAuthScopes ? options.grantedOAuthScopes.includes("scan:create") : null,
+                resources: options.toolProfile === "light" ? [] : ["certscore://connection", "certscore://project-instructions", "certscore://reconnect", "certscore://example-report"],
+                prompts: options.toolProfile === "light" ? [] : ["certscore_launch_review", "certscore_compare_scans", "certscore_remediation_checklist"],
+                quotaRemaining: null,
+                quotaNote: "Remaining allowance is not loaded at handshake. Scan creation enforces current workspace and requester limits; inspect quota errors rather than assuming a fresh allowance.",
+                recommendedNextTool: options.grantedOAuthScopes && !options.grantedOAuthScopes.includes("scan:create") ? "certscore_get_latest_domain_scan" : "certscore_scan_site",
+                sequence: ["certscore_scan_site", "certscore_get_scan_status", "certscore_get_scan_bundle"],
+                guidance: options.toolProfile === "light"
+                    ? "Light supports eligible public scans, not workspace history. For workspace access connect https://mcp.certscore.ai/mcp using OAuth. Reuse an existing Hosted OAuth connection rather than adding duplicate names."
+                    : "Start a scan, poll only while active at the returned interval, then fetch its bundle. If scan:create is missing, reauthorize with scan:read scan:create mcp. Reuse existing endpoint installations; client names are labels, not verified identities."
+            }
+        })
     });
+    if (options.toolProfile !== "light")
+        registerAdoptionFeatures(server, async () => {
+            try {
+                return await clientForRequest({}).getConnectionStatus();
+            }
+            catch (error) {
+                if (error instanceof CertScoreError && error.status === 401)
+                    return { authenticated: false, status: "reconnect_required", quota: null, nextAction: "Read certscore://reconnect and reconnect the existing Hosted OAuth connector. Do not share tokens." };
+                return { authenticated: null, status: "check_unavailable", quota: null, nextAction: "Retry the connection check. If your host reports expired or revoked access, read certscore://reconnect. Do not assume a failed check means quota is available." };
+            }
+        }, async () => {
+            try {
+                const exampleClient = clientForRequest({});
+                const [report, metadata] = await Promise.all([exampleClient.getScanPulse(EXAMPLE_SCAN_ID), exampleClient.getScanResource(EXAMPLE_SCAN_ID)]);
+                return { originalCompletedAt: metadata.completedAt ?? null, coverage: metadata.coverage, status: metadata.status, example: true, label: "Retained example, not a current scan of your website", scanId: EXAMPLE_SCAN_ID,
+                    reportUrl: `https://certscore.ai/scan/${EXAMPLE_SCAN_ID}`,
+                    report: JSON.stringify(report).length <= 30000 ? report : null,
+                    note: "Use original timestamps and coverage from the report. If omitted here for size, open the report URL. No new scan was created." };
+            }
+            catch {
+                return { example: true, available: false, scanId: EXAMPLE_SCAN_ID, nextAction: "The retained example is unavailable. Do not create a replacement scan automatically." };
+            }
+        });
     const sdkCreateToolError = server.createToolError.bind(server);
     server.createToolError = (message) => message.includes("Input validation error:")
         ? toInvalidArgumentsToolError(message)
         : sdkCreateToolError(message);
-    const lightTools = new Set(["certscore_scan_site", "certscore_get_scan_status", "certscore_get_scan_bundle"]);
+    const registeredToolNames = new Set();
+    const lightTools = new Set(["certscore_scan_site", "certscore_get_scan_status", "certscore_get_scan_bundle", "certscore_get_report_evidence_page"]);
     const scanIdTools = new Set([
         "certscore_explain_finding",
         "certscore_export_findings",
         "certscore_get_evidence",
         "certscore_get_pre_consent_cookies_trackers",
         "certscore_get_report",
+        "certscore_get_report_evidence_page",
         "certscore_get_scan",
         "certscore_get_scan_bundle",
         "certscore_get_scan_status",
@@ -321,17 +385,51 @@ export function createCertScoreMcpServer(options = {}) {
             return registerRequest(schema, handler);
         return registerRequest(CallToolRequestSchema, async (request, extra) => {
             const startedAt = Date.now();
+            const requestId = options.resolveRequestId?.() ?? randomUUID();
             const name = request.params.name;
+            if (options.onToolInvocationStarted) {
+                void Promise.resolve().then(() => options.onToolInvocationStarted({ requestId, toolName: name, startedAt: new Date(startedAt).toISOString() }))
+                    .catch(() => console.error("[certscore-mcp] request-start observation failed"));
+            }
             const args = request.params.arguments ?? {};
-            const known = certScoreMcpToolContracts.some(tool => tool.name === name)
-                && (options.toolProfile !== "light" || lightTools.has(name));
+            const taskContext = sanitizeMcpTaskContext(args.taskContext);
+            const forwardedRequest = name === "certscore_scan_site" && args.taskContext !== undefined && !taskContext
+                ? {
+                    ...request,
+                    params: {
+                        ...request.params,
+                        arguments: Object.fromEntries(Object.entries(args).filter(([key]) => key !== "taskContext")),
+                    },
+                }
+                : request;
+            const known = registeredToolNames.has(name);
             let result;
+            let protocolFailure;
             try {
-                result = await handler(request, extra);
+                if (!known) {
+                    result = { isError: true, structuredContent: { error: { code: "unknown_tool" } } };
+                    const availableTools = [...registeredToolNames];
+                    const recommendedNextAction = "Refresh the available tools using your MCP client's tool discovery (tools/list), then call a supported tool.";
+                    throw withResponseCapture(new McpError(ErrorCode.InvalidParams, `This tool is unavailable on this endpoint. ${recommendedNextAction} Available tools: ${availableTools.join(", ")}.`, { code: "unknown_tool", retryable: false, recommendedNextAction, availableTools }), { message: `This tool is unavailable on this endpoint. ${recommendedNextAction} Available tools: ${availableTools.join(", ")}.`, recommendedNextAction });
+                }
+                const contract = certScoreMcpToolContracts.find(candidate => candidate.name === name);
+                const validation = z.object(contract.inputSchema).safeParse(forwardedRequest.params.arguments ?? {});
+                result = validation.success
+                    ? await handler(forwardedRequest, extra)
+                    : toInvalidArgumentsToolError(`Input validation error: tool ${name}`, {
+                        tool: name,
+                        issues: validation.error.issues.map(issue => ({
+                            // Only schema-owned top-level names; never echo values or dynamic keys.
+                            field: typeof issue.path[0] === "string" && Object.hasOwn(contract.inputSchema, issue.path[0]) ? issue.path[0] : "arguments",
+                            code: issue.code,
+                            ...(issue.code === "invalid_type" && issue.received === "undefined" ? { required: true } : {}),
+                        })).filter((issue, index, issues) => issues.findIndex(other => other.field === issue.field) === index).slice(0, 8),
+                    });
                 return result;
             }
             catch (error) {
-                result = { isError: true, structuredContent: { error: { code: "handler_exception" } } };
+                protocolFailure = error;
+                result ??= { isError: true, structuredContent: { error: { code: "handler_exception" } } };
                 throw error;
             }
             finally {
@@ -343,14 +441,16 @@ export function createCertScoreMcpServer(options = {}) {
                         observation.errorCode = "protocol_error";
                     const payload = telemetryResultRecord(result);
                     const metadata = payload.mcpMetadata;
-                    const taskContext = sanitizeMcpTaskContext(args.taskContext);
                     observeToolInvocation(options.onToolInvocation, {
                         ...observation,
+                        requestId,
+                        timing: { startedAt: new Date(startedAt).toISOString(), responseGeneratedAt: new Date().toISOString() },
                         captureBasis: "protocol_request",
-                        callerInput: captureMcpCallerInput(args, request.params._meta),
+                        callerInput: captureMcpCallerInput(args, request.params._meta, { expanded: process.env.MCP_EXPANDED_CALLER_INPUT_ENABLED === "1" }),
                         ...(taskContext ? { taskContext } : {}),
                         response: {
-                            bytes: Math.min(10_000_000, Buffer.byteLength(JSON.stringify(result ?? null))),
+                            summary: captureMcpResponse(result, protocolFailure),
+                            bytes: protocolFailure ? null : Math.min(10_000_000, Buffer.byteLength(JSON.stringify(result ?? null))),
                             truncated: typeof metadata?.truncated === "boolean" ? metadata.truncated : null,
                             ...(typeof metadata?.effectiveMaxBytes === "number" ? { effectiveMaxBytes: metadata.effectiveMaxBytes } : {}),
                         },
@@ -372,20 +472,32 @@ export function createCertScoreMcpServer(options = {}) {
             const scanId = input && typeof input === "object" && !Array.isArray(input)
                 ? input.scanId : null;
             return scanIdTools.has(name) && !isCanonicalScanId(scanId)
-                ? toInvalidScanIdToolError() : typedHandler(input, extra);
+                ? toInvalidScanIdToolError() : withResponseGuidance(name, input, await typedHandler(input, extra));
         });
+        registeredToolNames.add(name);
     };
+    registerTool("certscore_get_connection_status", toolContract("certscore_get_connection_status"), async (_input, extra) => {
+        try {
+            const status = await clientForRequest(extra).getConnectionStatus();
+            return toToolResult(status, JSON.stringify(status));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
     registerTool("certscore_scan_site", toolContract("certscore_scan_site"), async (input, extra) => {
         const toolStartedAtMs = Date.now();
         const creationStartedAtMs = toolStartedAtMs;
         const client = clientForRequest(extra);
         const demoSubstitution = exampleDomainDemoSubstitution(input.url, options.exampleDomainDemoUrl);
         const effectiveUrl = demoSubstitution?.effectiveUrl ?? input.url;
+        let creationCompleted = false;
         try {
             const created = await client.scans.create(effectiveUrl, {
                 freshness: input.freshness ?? "latest",
                 scanFrom: input.scanFrom
             });
+            creationCompleted = true;
             console.log(JSON.stringify({
                 event: "mcp.certscore_scan_site.creation_completed",
                 durationMs: Date.now() - creationStartedAtMs,
@@ -394,6 +506,8 @@ export function createCertScoreMcpServer(options = {}) {
                 reused: created.reused === true,
                 status: created.status ?? null,
             }));
+            let retainedPreviewWaitMs = 0;
+            let retainedInternalReadCount = 0;
             let initialResult = created;
             const stableScanId = typeof created.scanId === "string" && created.scanId
                 ? created.scanId
@@ -445,6 +559,8 @@ export function createCertScoreMcpServer(options = {}) {
                         scanId: stableScanId,
                     }));
                 }
+                retainedPreviewWaitMs = Date.now() - previewWaitStartedAtMs;
+                retainedInternalReadCount = internalReadCount;
                 console.log(JSON.stringify({
                     event: "mcp.certscore_scan_site.preview_wait_completed",
                     durationMs: Date.now() - previewWaitStartedAtMs,
@@ -456,7 +572,11 @@ export function createCertScoreMcpServer(options = {}) {
                 }));
             }
             const guided = withExampleDomainDemo(withMcpAgentGuidance(initialResult, "unknown", "scan_creation"), demoSubstitution);
-            return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
+            const toolResult = toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
+            return options.toolProfile === "light" ? withResponseCapture(toolResult, {
+                firstResult: ["completed", "completed_limited"].includes(initialResult.status) ? "completed" : ["failed", "expired"].includes(initialResult.status) ? "failed" : hasPreConsentPreview(initialResult) ? "preview" : activeScan(initialResult) ? "queued" : "unknown",
+                previewWaitMs: retainedPreviewWaitMs, internalReadCount: retainedInternalReadCount,
+            }) : toolResult;
         }
         catch (error) {
             console.warn(JSON.stringify({
@@ -464,10 +584,11 @@ export function createCertScoreMcpServer(options = {}) {
                 durationMs: Date.now() - creationStartedAtMs,
                 errorName: error instanceof Error ? error.name : "UnknownError",
             }));
-            return toToolError(error);
+            return toToolError(error, { scanCreation: !creationCompleted });
         }
     });
-    registerTool("certscore_get_scan", toolContract("certscore_get_scan"), async ({ scanId }) => {
+    registerTool("certscore_get_scan", toolContract("certscore_get_scan"), async ({ scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             return toToolResult(await client.scans.get(scanId));
         }
@@ -491,7 +612,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_report", toolContract("certscore_get_report"), async ({ scanId, detail, format }) => {
+    registerTool("certscore_get_report", toolContract("certscore_get_report"), async ({ scanId, detail, format }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const normalizedFormat = normalizeFormat(format);
             const result = normalizedFormat === "markdown"
@@ -518,7 +640,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_evidence", toolContract("certscore_get_evidence"), async ({ scanId }) => {
+    registerTool("certscore_get_evidence", toolContract("certscore_get_evidence"), async ({ scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const bounded = boundEvidencePacket(await client.getScan(scanId, { detail: "evidence", format: "json" }), MAX_EVIDENCE_PACKET_CHARS - 2_500);
             const guided = withMcpAgentGuidance(bounded, "existing_scan_retrieved");
@@ -528,6 +651,15 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
+    registerTool("certscore_get_report_evidence_page", toolContract("certscore_get_report_evidence_page"), async ({ scanId, cursor }, extra) => {
+        try {
+            const page = reportEvidencePageSchema.parse(await clientForRequest(extra).getReportEvidencePage(scanId, { cursor, timeout: 30_000, internalMcpOperation: { operation: "scan_bundle", scanId } }));
+            return toToolResult(page, `Report evidence for ${scanId}: ${page.pagination.offset + 1}–${page.pagination.offset + page.pagination.returned} of ${page.pagination.total} entries. ${page.pagination.complete ? "Export complete; preserve report coverage limitations." : `Continue with certscore_get_report_evidence_page using scanId and cursor ${page.pagination.nextCursor}.`} Evidence values are in structuredContent.entries. ${page.download ? `Full report JSON: ${page.download.url} (${page.download.bytes} bytes). ${page.download.instructions}` : ""} ${page.reportUrl}`);
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
     registerTool("certscore_get_scan_bundle", toolContract("certscore_get_scan_bundle"), async ({ scanId, detail = "summary", maxBytes, maxFindings, maxPreConsentRows }, extra) => {
         const client = clientForRequest(extra);
         try {
@@ -553,7 +685,7 @@ export function createCertScoreMcpServer(options = {}) {
                     responseCeilingBytes,
                     scan
                 });
-                return toToolResult(bundle, scanBundleText(bundle));
+                return toToolResult(bundle, scanBundleText(bundle, { lightTrialCta: options.toolProfile === "light" }));
             }
             const includeEvidence = detail === "evidence" || detail === "full";
             const reportDetail = detail === "full" ? "full" : includeEvidence ? "evidence" : "summary";
@@ -578,13 +710,14 @@ export function createCertScoreMcpServer(options = {}) {
                 responseCeilingBytes,
                 scan
             });
-            return toToolResult(bundle, scanBundleText(bundle));
+            return toToolResult(bundle, scanBundleText(bundle, { lightTrialCta: options.toolProfile === "light" }));
         }
         catch (error) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_export_findings", toolContract("certscore_export_findings"), async ({ scanId }) => {
+    registerTool("certscore_export_findings", toolContract("certscore_export_findings"), async ({ scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const report = await client.getScan(scanId, { detail: "full", format: "json" });
             const guided = withMcpAgentGuidance(exportFindings(report), "existing_scan_retrieved");
@@ -594,7 +727,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_list_findings", toolContract("certscore_list_findings"), async ({ limit, offset, scanId }) => {
+    registerTool("certscore_list_findings", toolContract("certscore_list_findings"), async ({ limit, offset, scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const guided = withMcpAgentGuidance(paginateFindingList(await client.findings.list(scanId), { limit, offset }), "existing_scan_retrieved");
             return toToolResult(guided, findingListText(guided));
@@ -603,7 +737,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_pre_consent_cookies_trackers", toolContract("certscore_get_pre_consent_cookies_trackers"), async ({ maxRows, scanId }) => {
+    registerTool("certscore_get_pre_consent_cookies_trackers", toolContract("certscore_get_pre_consent_cookies_trackers"), async ({ maxRows, scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const guided = withMcpAgentGuidance(limitPreConsentRows(await client.scans.preConsentCookiesTrackers(scanId), { maxRows }), "existing_scan_retrieved");
             return toToolResult(guided, preConsentInventoryText(guided));
@@ -612,7 +747,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_explain_finding", toolContract("certscore_explain_finding"), async ({ scanId, findingId }) => {
+    registerTool("certscore_explain_finding", toolContract("certscore_explain_finding"), async ({ scanId, findingId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             return toToolResult(await client.findings.explain(scanId, findingId));
         }
@@ -620,7 +756,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_latest_domain_scan", toolContract("certscore_get_latest_domain_scan"), async ({ domain, scanFrom }) => {
+    registerTool("certscore_get_latest_domain_scan", toolContract("certscore_get_latest_domain_scan"), async ({ domain, scanFrom }, extra) => {
+        const client = clientForRequest(extra);
         try {
             return toToolResult(await client.domains.latest(domain, { scanFrom }));
         }
@@ -628,7 +765,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_latest_domain_pre_consent_cookies_trackers", toolContract("certscore_get_latest_domain_pre_consent_cookies_trackers"), async ({ domain, maxRows, scanFrom }) => {
+    registerTool("certscore_get_latest_domain_pre_consent_cookies_trackers", toolContract("certscore_get_latest_domain_pre_consent_cookies_trackers"), async ({ domain, maxRows, scanFrom }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const guided = withMcpAgentGuidance(limitPreConsentRows(await client.domains.latestPreConsentCookiesTrackers(domain, { scanFrom }), { maxRows }), "existing_scan_retrieved");
             return toToolResult(guided, preConsentInventoryText(guided));
@@ -638,5 +776,12 @@ export function createCertScoreMcpServer(options = {}) {
         }
     });
     server.server.setRequestHandler = registerRequest;
+    // Reconnecting hosts may retain a tool catalog from an older release.
+    // Announce the current catalog once the new session has initialized.
+    server.server.oninitialized = () => {
+        void server.server.sendToolListChanged().catch(() => {
+            // A host without a notification channel can still call tools/list normally.
+        });
+    };
     return server;
 }

package/dist/tools.d.ts

@@ -13,8 +13,17 @@ type ActionableError = {
     mcpCode?: number;
 };
 export declare function toToolResult(payload: unknown, text?: string): CallToolResult;
-export declare function toToolError(error: unknown): CallToolResult;
-export declare function toInvalidArgumentsToolError(errorMessage: string): CallToolResult;
+export declare function toToolError(error: unknown, context?: {
+    scanCreation?: boolean;
+}): CallToolResult;
+export declare function toInvalidArgumentsToolError(errorMessage: string, validation?: {
+    tool: string;
+    issues: {
+        field: string;
+        code: string;
+        required?: boolean;
+    }[];
+}): CallToolResult;
 export declare function toInvalidScanIdToolError(): CallToolResult;
 export declare function withMcpAgentGuidance<T extends Record<string, any>>(value: T, fallbackProvenanceMode?: ScanProvenanceMode, pollGuidanceContext?: McpPollGuidanceContext): T & {
     error: ActionableError | null;
@@ -39,6 +48,10 @@ export declare function scanIdFromPulse(report: PulseResult): string | null;
 export declare function findingsFromReport(report: PulseResult): TopFinding[];
 export declare function exportFindings(report: PulseResult): {
     type: string;
+    exportVersion: string;
+    exportedAt: string;
+    returnedFindingCount: number;
+    completeness: string;
     scanId: string | null;
     domain: string | null;
     summary: import("packages/certscore-sdk/dist/types.js").PulseSummary | null;
@@ -71,7 +84,9 @@ export declare function findingListText(value: Record<string, any>, label?: stri
 export declare function preConsentInventoryText(value: Record<string, any>): string;
 export declare function pulseReportText(value: Record<string, any>, label?: string): string;
 export declare function markdownReportText(value: Record<string, any>): string;
-export declare function scanBundleText(bundle: Record<string, any>): string;
+export declare function scanBundleText(bundle: Record<string, any>, options?: {
+    lightTrialCta?: boolean;
+}): string;
 export declare function buildScanBundle(input: {
     detail?: "summary" | "findings" | "evidence" | "full";
     evidence?: PulseResult | null;

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}