@certscore/mcp 0.2.15 → 0.2.17

package/dist/server.js

@@ -1,9 +1,41 @@
-import { CertScoreClient, CertScoreTimeoutError } from "@certscore/sdk";
-import { certScoreMcpToolContracts } from "@certscore/api-contracts";
+import { CertScoreClient } from "@certscore/sdk";
+import { certScoreMcpToolContracts, isCanonicalScanId } from "@certscore/api-contracts";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CERTSCORE_MCP_VERSION } from "./version.js";
-import { boundEvidencePacket, buildScanBundle, exportFindings, limitPreConsentRows, normalizeDetail, normalizeFormat, paginateFindingList, toInvalidArgumentsToolError, toToolError, toToolResult, withMcpAgentGuidance } from "./tools.js";
-const DEFAULT_MCP_SCAN_WAIT_MS = 45_000;
+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";
+const LIGHT_MCP_BUNDLE_RESPONSE_CEILING_BYTES = 25_000;
+const MCP_SCAN_SITE_TARGET_RESPONSE_MS = 11_000;
+const MCP_SCAN_SITE_TARGET_RESPONSE_RESERVE_MS = 250;
+const MCP_SCAN_SITE_PREVIEW_POLL_INTERVAL_MS = 750;
+const MCP_SCAN_SITE_MAX_PREVIEW_WAIT_MS = 10_000;
+function exampleDomainDemoSubstitution(requestedUrl, demoUrl) {
+    if (!demoUrl)
+        return null;
+    try {
+        const parsed = new URL(requestedUrl.includes("://") ? requestedUrl : `https://${requestedUrl}`);
+        const hostname = parsed.hostname.toLowerCase().replace(/\.$/, "");
+        const reserved = ["example.com", "example.net", "example.org"].some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
+        if (!reserved)
+            return null;
+        return {
+            requestedUrl,
+            effectiveUrl: demoUrl,
+            reason: "iana_example_domain",
+            message: "The requested IANA example domain is a documentation placeholder, so CertScore scanned its controlled demonstration site instead. Findings describe the effective URL, not the requested placeholder."
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function withExampleDomainDemo(value, substitution) {
+    return substitution ? { ...value, demoSubstitution: substitution } : value;
+}
+function exampleDomainDemoText(value, substitution) {
+    return scanSiteText(value, substitution
+        ? [`${substitution.message} Substitution provenance is in structuredContent.`]
+        : []);
+}
 async function retryTransientOriginFailure(operation) {
     try {
         return await operation();
@@ -30,6 +62,15 @@ function scanCreationMetadata(value) {
         upgradeMessage: value.upgradeMessage
     };
 }
+function activeScan(value) {
+    return value.status === "queued" || value.status === "running" || value.status === "finalizing";
+}
+function hasPreConsentPreview(value) {
+    return Boolean(value.preConsentPreview && typeof value.preConsentPreview === "object" && !Array.isArray(value.preConsentPreview));
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function toolContract(name) {
     const contract = certScoreMcpToolContracts.find((candidate) => candidate.name === name);
     if (!contract) {
@@ -43,15 +84,161 @@ function toolContract(name) {
         annotations: contract.annotations
     };
 }
+function boundedTelemetryToken(value, maxLength) {
+    return typeof value === "string" && /^[a-zA-Z0-9_.:-]+$/.test(value) && value.length <= maxLength
+        ? value
+        : null;
+}
+function telemetryResultRecord(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        return {};
+    const toolResult = result;
+    if (toolResult.structuredContent && typeof toolResult.structuredContent === "object" && !Array.isArray(toolResult.structuredContent)) {
+        return toolResult.structuredContent;
+    }
+    const firstText = Array.isArray(toolResult.content)
+        ? toolResult.content.find((item) => item && typeof item === "object" && item.type === "text")
+        : null;
+    if (!firstText || typeof firstText.text !== "string")
+        return {};
+    try {
+        const parsed = JSON.parse(firstText.text);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function telemetryHostname(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const parsed = new URL(value.includes("://") ? value : `https://${value}`);
+        return parsed.hostname.toLowerCase().replace(/\.$/, "").slice(0, 253) || null;
+    }
+    catch {
+        return null;
+    }
+}
+function telemetryUrl(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const parsed = new URL(value.includes("://") ? value : `https://${value}`);
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+            return null;
+        return parsed.origin.slice(0, 512);
+    }
+    catch {
+        return null;
+    }
+}
+function requestedTelemetryResource(args) {
+    const scanId = boundedTelemetryToken(args.scanId, 128);
+    if (scanId)
+        return { requestedResource: scanId, requestedResourceType: "scan_id" };
+    const jobId = boundedTelemetryToken(args.jobId, 128);
+    if (jobId)
+        return { requestedResource: jobId, requestedResourceType: "job_id" };
+    const url = telemetryUrl(args.url);
+    if (url)
+        return { requestedResource: url, requestedResourceType: "url" };
+    const domain = telemetryHostname(args.domain);
+    if (domain)
+        return { requestedResource: domain, requestedResourceType: "domain" };
+    return { requestedResource: null, requestedResourceType: null };
+}
+function isCertScoreCanaryUrl(value) {
+    if (typeof value !== "string")
+        return false;
+    try {
+        const parsed = new URL(/^https?:\/\//i.test(value) ? value : `https://${value}`);
+        return parsed.pathname.startsWith("/.well-known/certscore-canary/");
+    }
+    catch {
+        return false;
+    }
+}
+export function projectMcpToolInvocationObservation(input) {
+    const args = input.args && typeof input.args === "object" && !Array.isArray(input.args)
+        ? input.args
+        : {};
+    const result = telemetryResultRecord(input.result);
+    const error = result.error && typeof result.error === "object" && !Array.isArray(result.error)
+        ? result.error
+        : null;
+    const errorCode = boundedTelemetryToken(error?.code ?? result.errorCode, 100);
+    const rateLimited = errorCode === "rate_limited" || result.status === "rate_limited";
+    const isError = 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 inputScanId = boundedTelemetryToken(args.scanId, 128);
+    const requestedResource = requestedTelemetryResource(args);
+    const targetHostname = input.toolName === "certscore_scan_site"
+        ? telemetryHostname(args.url)
+        : input.toolName === "certscore_get_latest_domain_scan"
+            || input.toolName === "certscore_get_latest_domain_pre_consent_cookies_trackers"
+            ? telemetryHostname(args.domain)
+            : null;
+    const isCanary = isCertScoreCanaryUrl(args.url);
+    const executionMode = result.executionMode;
+    const scanDecision = input.toolName !== "certscore_scan_site"
+        ? "not_applicable"
+        : outcome !== "success"
+            ? "unavailable"
+            : result.reused === true || executionMode === "reused_scan"
+                ? "reused"
+                : result.reused === false || executionMode === "new_scan" || result.quotaConsumed === true
+                    ? "new"
+                    : "unavailable";
+    return {
+        durationMs: Math.max(0, Math.min(Math.round(input.durationMs), 3_600_000)),
+        errorCode: rateLimited ? "rate_limited" : errorCode,
+        freshness: args.freshness === "refresh" ? "refresh" : input.toolName === "certscore_scan_site" ? "latest" : null,
+        isCanary,
+        outcome,
+        quotaOutcome: rateLimited ? "rate_limited" : "allowed",
+        ...requestedResource,
+        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
+                : null,
+        scanId: resultScanId ?? inputScanId,
+        scanStatus: boundedTelemetryToken(result.status, 64),
+        targetHostname,
+        toolName: input.toolName,
+        transportOutcome: isError ? "mcp_error" : "mcp_result",
+    };
+}
+function observeToolInvocation(observer, observation, requestContext) {
+    if (!observer)
+        return;
+    queueMicrotask(() => {
+        Promise.resolve().then(() => observer(observation, requestContext)).catch((error) => {
+            console.error("[certscore-mcp] telemetry observer failed", {
+                errorName: error instanceof Error ? error.name : "UnknownError",
+                toolName: observation.toolName,
+            });
+        });
+    });
+}
 export function createCertScoreMcpServer(options = {}) {
-    const client = new CertScoreClient({
+    const createClient = (forwardedClientIp, anonymousRequesterSession) => new CertScoreClient({
         apiKey: options.apiKey,
         baseUrl: options.baseUrl,
         clientName: "mcp",
-        forwardedClientIp: options.forwardedClientIp,
+        forwardedClientIp,
         anonymousRequesterSecret: options.anonymousRequesterSecret,
+        anonymousSurface: options.anonymousSurface,
+        anonymousRequesterSession,
         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 server = new McpServer({
         name: "certscore",
         version: CERTSCORE_MCP_VERSION
@@ -61,60 +248,145 @@ export function createCertScoreMcpServer(options = {}) {
         ? toInvalidArgumentsToolError(message)
         : sdkCreateToolError(message);
     const lightTools = new Set(["certscore_scan_site", "certscore_get_scan_status", "certscore_get_scan_bundle"]);
+    const scanIdTools = new Set([
+        "certscore_explain_finding",
+        "certscore_export_findings",
+        "certscore_get_evidence",
+        "certscore_get_pre_consent_cookies_trackers",
+        "certscore_get_report",
+        "certscore_get_scan",
+        "certscore_get_scan_bundle",
+        "certscore_get_scan_status",
+        "certscore_list_findings",
+    ]);
     const registerMcpTool = server.registerTool.bind(server);
     const registerTool = (name, contract, handler) => {
         if (options.toolProfile === "light" && !lightTools.has(name)) {
             return;
         }
-        registerMcpTool(name, contract, handler);
+        const typedHandler = handler;
+        registerMcpTool(name, contract, async (input, extra) => {
+            const startedAt = Date.now();
+            try {
+                const scanId = input && typeof input === "object" && !Array.isArray(input)
+                    ? input.scanId
+                    : null;
+                const result = scanIdTools.has(name) && !isCanonicalScanId(scanId)
+                    ? toInvalidScanIdToolError()
+                    : await typedHandler(input, extra);
+                observeToolInvocation(options.onToolInvocation, projectMcpToolInvocationObservation({
+                    args: input,
+                    durationMs: Date.now() - startedAt,
+                    result,
+                    toolName: name,
+                }), { headers: extra.requestInfo?.headers ?? null });
+                return result;
+            }
+            catch (error) {
+                observeToolInvocation(options.onToolInvocation, {
+                    ...projectMcpToolInvocationObservation({
+                        args: input,
+                        durationMs: Date.now() - startedAt,
+                        result: { isError: true, structuredContent: { error: { code: "handler_exception" } } },
+                        toolName: name,
+                    }),
+                    errorCode: "handler_exception",
+                    outcome: "error",
+                    transportOutcome: "mcp_error",
+                }, { headers: extra.requestInfo?.headers ?? null });
+                throw error;
+            }
+        });
     };
-    registerTool("certscore_scan_site", toolContract("certscore_scan_site"), async (input) => {
+    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;
         try {
-            const created = await client.scans.create(input.url, {
+            const created = await client.scans.create(effectiveUrl, {
                 freshness: input.freshness ?? "latest",
                 scanFrom: input.scanFrom
             });
-            if (input.waitForCompletion === false || created.type === "certscore_scan") {
-                return toToolResult(withMcpAgentGuidance(created));
-            }
-            try {
-                const completed = await client.scans.wait(created, {
-                    maxWaitMs: Math.min(input.maxWaitSeconds ? input.maxWaitSeconds * 1_000 : DEFAULT_MCP_SCAN_WAIT_MS, DEFAULT_MCP_SCAN_WAIT_MS)
-                });
-                return toToolResult(withMcpAgentGuidance({
-                    ...completed,
-                    ...scanCreationMetadata(created)
-                }));
-            }
-            catch (error) {
-                const scanId = created.scanId ?? created.scan_id;
-                console.warn(JSON.stringify({
-                    event: "mcp.certscore_scan_site.wait_deferred",
-                    errorName: error instanceof Error ? error.name : "UnknownError",
-                    jobId: created.jobId ?? null,
-                    scanId: scanId ?? null,
-                    status: created.status ?? null
-                }));
-                if (error instanceof CertScoreTimeoutError && scanId) {
-                    try {
-                        return toToolResult(withMcpAgentGuidance({
-                            ...(await client.scans.status(scanId)),
-                            ...scanCreationMetadata(created)
-                        }));
-                    }
-                    catch {
-                        // Creation already succeeded. Preserve that stable identity when
-                        // the follow-up status read is briefly unavailable.
+            console.log(JSON.stringify({
+                event: "mcp.certscore_scan_site.creation_completed",
+                durationMs: Date.now() - creationStartedAtMs,
+                executionMode: created.executionMode ?? null,
+                hasScanId: Boolean(created.scanId ?? created.scan_id),
+                reused: created.reused === true,
+                status: created.status ?? null,
+            }));
+            let initialResult = created;
+            const stableScanId = typeof created.scanId === "string" && created.scanId
+                ? created.scanId
+                : typeof created.scan_id === "string" && created.scan_id
+                    ? created.scan_id
+                    : typeof created.jobId === "string" && created.jobId
+                        ? created.jobId
+                        : null;
+            const configuredPreviewWaitMs = options.toolProfile === "light"
+                ? Math.min(Math.max(0, options.initialPreConsentPreviewWaitMs ?? 10_000), MCP_SCAN_SITE_MAX_PREVIEW_WAIT_MS)
+                : 0;
+            const totalRemainingMs = Math.max(0, toolStartedAtMs + MCP_SCAN_SITE_TARGET_RESPONSE_MS - MCP_SCAN_SITE_TARGET_RESPONSE_RESERVE_MS - Date.now());
+            const previewWaitMs = Math.min(configuredPreviewWaitMs, totalRemainingMs);
+            if (stableScanId && previewWaitMs > 0 && activeScan(initialResult)) {
+                const previewWaitStartedAtMs = Date.now();
+                const previewDeadlineMs = previewWaitStartedAtMs + previewWaitMs;
+                let internalReadCount = 0;
+                try {
+                    while (Date.now() < previewDeadlineMs && activeScan(initialResult) && !hasPreConsentPreview(initialResult)) {
+                        await delay(Math.min(MCP_SCAN_SITE_PREVIEW_POLL_INTERVAL_MS, previewDeadlineMs - Date.now()));
+                        const requestRemainingMs = previewDeadlineMs - Date.now();
+                        if (requestRemainingMs <= 0)
+                            break;
+                        const waitAbortController = new AbortController();
+                        const waitAbortTimer = setTimeout(() => waitAbortController.abort(), requestRemainingMs);
+                        try {
+                            internalReadCount += 1;
+                            const status = await client.scans.status(stableScanId, {
+                                internalMcpOperation: { operation: "scan_site_wait", scanId: stableScanId },
+                                signal: waitAbortController.signal,
+                            });
+                            initialResult = {
+                                ...status,
+                                ...scanCreationMetadata(created),
+                            };
+                        }
+                        finally {
+                            clearTimeout(waitAbortTimer);
+                        }
                     }
                 }
-                // Waiting is a convenience layered on top of scan creation. Once the
-                // API has accepted a scan, never turn a transient polling or hydration
-                // failure into an identity-less tool error that encourages callers to
-                // submit a second, non-idempotent certscore_scan_site request.
-                return toToolResult(withMcpAgentGuidance(created));
+                catch (error) {
+                    console.warn(JSON.stringify({
+                        event: "mcp.certscore_scan_site.preview_wait_deferred",
+                        durationMs: Date.now() - previewWaitStartedAtMs,
+                        errorName: error instanceof Error ? error.name : "UnknownError",
+                        hasPreview: hasPreConsentPreview(initialResult),
+                        internalReadCount,
+                        scanId: stableScanId,
+                    }));
+                }
+                console.log(JSON.stringify({
+                    event: "mcp.certscore_scan_site.preview_wait_completed",
+                    durationMs: Date.now() - previewWaitStartedAtMs,
+                    hasPreview: hasPreConsentPreview(initialResult),
+                    internalReadCount,
+                    scanId: stableScanId,
+                    status: initialResult.status ?? null,
+                    totalDurationMs: Date.now() - toolStartedAtMs,
+                }));
             }
+            const guided = withExampleDomainDemo(withMcpAgentGuidance(initialResult, "unknown", "scan_creation"), demoSubstitution);
+            return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
         }
         catch (error) {
+            console.warn(JSON.stringify({
+                event: "mcp.certscore_scan_site.creation_failed",
+                durationMs: Date.now() - creationStartedAtMs,
+                errorName: error instanceof Error ? error.name : "UnknownError",
+            }));
             return toToolError(error);
         }
     });
@@ -126,41 +398,17 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_scan_status", toolContract("certscore_get_scan_status"), async ({ scanId }) => {
+    registerTool("certscore_get_scan_status", toolContract("certscore_get_scan_status"), async ({ scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
-            const status = await client.scans.status(scanId);
-            const needsTerminalHydration = status.status === "completed" || status.status === "completed_limited";
-            if (needsTerminalHydration) {
-                try {
-                    const scan = await client.scans.get(scanId);
-                    return toToolResult(withMcpAgentGuidance({
-                        ...status,
-                        type: "certscore_scan_job",
-                        status: scan.status,
-                        domain: scan.domain,
-                        url: scan.url ?? null,
-                        resultDisposition: scan.resultDisposition,
-                        noGo: scan.noGo,
-                        createdAt: scan.createdAt ?? null,
-                        startedAt: scan.startedAt,
-                        completedAt: scan.completedAt,
-                        scanTimeSeconds: scan.scanTimeSeconds,
-                        score: scan.score ?? null,
-                        scoreStatus: scan.scoreStatus,
-                        scoreVersion: scan.scoreVersion ?? null,
-                        scoreUpdatedAt: scan.scoreUpdatedAt ?? null,
-                        riskLevel: scan.riskLevel ?? null,
-                        coverage: scan.coverage ?? null,
-                        reportUrl: scan.links?.report ?? status.reportUrl ?? null,
-                        links: { ...status.links, ...scan.links }
-                    }));
-                }
-                catch {
-                    // Preserve the API status response if the terminal scan resource is
-                    // briefly unavailable during eventual-consistency windows.
-                }
-            }
-            return toToolResult(withMcpAgentGuidance(status));
+            const internalMcpOperation = { operation: "scan_status", scanId };
+            const status = await client.scans.status(scanId, { internalMcpOperation });
+            const guided = withMcpScanProvenanceGuidance({
+                ...status,
+                jobId: undefined,
+                scanFrom: status.scanFrom ?? null
+            }, "existing_scan_retrieved");
+            return toToolResult(guided, scanStatusText(guided));
         }
         catch (error) {
             return toToolError(error);
@@ -178,7 +426,16 @@ export function createCertScoreMcpServer(options = {}) {
                     detail: normalizeDetail(detail),
                     format: "json"
                 });
-            return toToolResult(result);
+            if (typeof result === "string") {
+                const guided = withMcpAgentGuidance({
+                    type: "certscore_pulse_markdown",
+                    scanId,
+                    value: result
+                }, "existing_scan_retrieved");
+                return toToolResult(guided, markdownReportText(guided));
+            }
+            const guided = withMcpAgentGuidance(result, "existing_scan_retrieved");
+            return toToolResult(guided, pulseReportText(guided));
         }
         catch (error) {
             return toToolError(error);
@@ -186,49 +443,65 @@ export function createCertScoreMcpServer(options = {}) {
     });
     registerTool("certscore_get_evidence", toolContract("certscore_get_evidence"), async ({ scanId }) => {
         try {
-            return toToolResult(boundEvidencePacket(await client.getScan(scanId, { detail: "evidence", format: "json" })));
+            const bounded = boundEvidencePacket(await client.getScan(scanId, { detail: "evidence", format: "json" }), MAX_EVIDENCE_PACKET_CHARS - 2_500);
+            const guided = withMcpAgentGuidance(bounded, "existing_scan_retrieved");
+            return toToolResult(guided, pulseReportText(guided, "CertScore evidence result"));
         }
         catch (error) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_scan_bundle", toolContract("certscore_get_scan_bundle"), async ({ scanId, detail = "summary", maxBytes, maxFindings, maxPreConsentRows }) => {
+    registerTool("certscore_get_scan_bundle", toolContract("certscore_get_scan_bundle"), async ({ scanId, detail = "summary", maxBytes, maxFindings, maxPreConsentRows }, extra) => {
+        const client = clientForRequest(extra);
         try {
-            const scan = await retryTransientOriginFailure(() => client.scans.get(scanId));
+            const responseCeilingBytes = options.toolProfile === "light"
+                ? LIGHT_MCP_BUNDLE_RESPONSE_CEILING_BYTES
+                : 200_000;
+            const requestedMaxBytes = maxBytes ?? (options.toolProfile === "light"
+                ? LIGHT_MCP_BUNDLE_RESPONSE_CEILING_BYTES
+                : 50_000);
+            const internalMcpOperation = { operation: "scan_bundle", scanId };
+            const scan = await retryTransientOriginFailure(() => client.scans.get(scanId, { internalMcpOperation }));
             if (scan.status === "completed_limited" && scan.resultDisposition === "no_go") {
-                return toToolResult(buildScanBundle({
+                const bundle = buildScanBundle({
                     detail,
                     evidence: null,
                     findings: { type: "certscore_finding_list", scanId, findings: [] },
-                    maxBytes,
+                    maxBytes: requestedMaxBytes,
                     maxFindings,
                     maxPreConsentRows,
                     preConsentCookiesTrackers: null,
                     report: null,
+                    requestedMaxBytes,
+                    responseCeilingBytes,
                     scan
-                }));
+                });
+                return toToolResult(bundle, scanBundleText(bundle));
             }
             const includeEvidence = detail === "evidence" || detail === "full";
             const reportDetail = detail === "full" ? "full" : includeEvidence ? "evidence" : "summary";
             const [report, findings, preConsentCookiesTrackers] = await Promise.all([
-                retryTransientOriginFailure(() => client.getScan(scanId, { detail: reportDetail, format: "json" })),
-                retryTransientOriginFailure(() => client.findings.list(scanId)),
-                includeEvidence
-                    ? retryTransientOriginFailure(() => client.scans.preConsentCookiesTrackers(scanId))
+                retryTransientOriginFailure(() => client.getScan(scanId, { detail: reportDetail, format: "json", internalMcpOperation })),
+                retryTransientOriginFailure(() => client.findings.list(scanId, { internalMcpOperation })),
+                scan.status === "completed"
+                    ? retryTransientOriginFailure(() => client.scans.preConsentCookiesTrackers(scanId, { internalMcpOperation }))
                     : Promise.resolve(null)
             ]);
             const evidence = includeEvidence ? report : null;
-            return toToolResult(buildScanBundle({
+            const bundle = buildScanBundle({
                 detail,
                 evidence,
                 findings,
-                maxBytes,
+                maxBytes: requestedMaxBytes,
                 maxFindings,
                 maxPreConsentRows,
                 preConsentCookiesTrackers,
                 report,
+                requestedMaxBytes,
+                responseCeilingBytes,
                 scan
-            }));
+            });
+            return toToolResult(bundle, scanBundleText(bundle));
         }
         catch (error) {
             return toToolError(error);
@@ -237,7 +510,8 @@ export function createCertScoreMcpServer(options = {}) {
     registerTool("certscore_export_findings", toolContract("certscore_export_findings"), async ({ scanId }) => {
         try {
             const report = await client.getScan(scanId, { detail: "full", format: "json" });
-            return toToolResult(exportFindings(report));
+            const guided = withMcpAgentGuidance(exportFindings(report), "existing_scan_retrieved");
+            return toToolResult(guided, findingListText(guided, "Exported canonical projected findings"));
         }
         catch (error) {
             return toToolError(error);
@@ -245,7 +519,8 @@ export function createCertScoreMcpServer(options = {}) {
     });
     registerTool("certscore_list_findings", toolContract("certscore_list_findings"), async ({ limit, offset, scanId }) => {
         try {
-            return toToolResult(paginateFindingList(await client.findings.list(scanId), { limit, offset }));
+            const guided = withMcpAgentGuidance(paginateFindingList(await client.findings.list(scanId), { limit, offset }), "existing_scan_retrieved");
+            return toToolResult(guided, findingListText(guided));
         }
         catch (error) {
             return toToolError(error);
@@ -253,7 +528,8 @@ export function createCertScoreMcpServer(options = {}) {
     });
     registerTool("certscore_get_pre_consent_cookies_trackers", toolContract("certscore_get_pre_consent_cookies_trackers"), async ({ maxRows, scanId }) => {
         try {
-            return toToolResult(limitPreConsentRows(await client.scans.preConsentCookiesTrackers(scanId), { maxRows }));
+            const guided = withMcpAgentGuidance(limitPreConsentRows(await client.scans.preConsentCookiesTrackers(scanId), { maxRows }), "existing_scan_retrieved");
+            return toToolResult(guided, preConsentInventoryText(guided));
         }
         catch (error) {
             return toToolError(error);
@@ -277,7 +553,8 @@ export function createCertScoreMcpServer(options = {}) {
     });
     registerTool("certscore_get_latest_domain_pre_consent_cookies_trackers", toolContract("certscore_get_latest_domain_pre_consent_cookies_trackers"), async ({ domain, maxRows, scanFrom }) => {
         try {
-            return toToolResult(limitPreConsentRows(await client.domains.latestPreConsentCookiesTrackers(domain, { scanFrom }), { maxRows }));
+            const guided = withMcpAgentGuidance(limitPreConsentRows(await client.domains.latestPreConsentCookiesTrackers(domain, { scanFrom }), { maxRows }), "existing_scan_retrieved");
+            return toToolResult(guided, preConsentInventoryText(guided));
         }
         catch (error) {
             return toToolError(error);

package/dist/tools.d.ts

@@ -1,6 +1,8 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { type FindingList, type JobStatus, type PreConsentCookiesTrackers, type PulseDetail, type PulseFormat, type PulseResult, type ScanResource, type TopFinding } from "@certscore/sdk";
 export declare const MAX_EVIDENCE_PACKET_CHARS = 250000;
+type McpPollGuidanceContext = "scan_creation" | "scan_status" | "upstream";
+type ScanProvenanceMode = "new_scan_started" | "existing_completed_scan_reused" | "existing_scan_retrieved" | "unknown";
 type ActionableError = {
     code: string;
     message: string;
@@ -10,10 +12,22 @@ type ActionableError = {
     field?: string;
     mcpCode?: number;
 };
-export declare function toToolResult(payload: unknown): CallToolResult;
+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 withMcpAgentGuidance<T extends Record<string, any>>(value: T): T & {
+export declare function toInvalidScanIdToolError(): CallToolResult;
+export declare function withMcpAgentGuidance<T extends Record<string, any>>(value: T, fallbackProvenanceMode?: ScanProvenanceMode, pollGuidanceContext?: McpPollGuidanceContext): T & {
+    error: ActionableError | null;
+    observationOnlyDisclaimer: string;
+};
+export declare function withMcpScanProvenanceGuidance(value: Record<string, any>, fallbackProvenanceMode: ScanProvenanceMode): {
+    interpretationGuidance: {
+        scoreLabel: "CertScore score";
+        observableSignalsOnly: true;
+        doNotInferUnobservedTechnologies: true;
+        doNotInferLegalComplianceStatus: true;
+        statement: string;
+    };
     error: ActionableError | null;
     observationOnlyDisclaimer: string;
 };
@@ -51,6 +65,13 @@ export declare function paginateFindingList<T extends Record<string, unknown>>(p
 export declare function limitPreConsentRows<T extends Record<string, unknown>>(payload: T, options?: {
     maxRows?: number;
 }): T;
+export declare function scanStatusText(value: Record<string, any>): string;
+export declare function scanSiteText(value: Record<string, any>, leadingLines?: string[]): string;
+export declare function findingListText(value: Record<string, any>, label?: string): string;
+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 buildScanBundle(input: {
     detail?: "summary" | "findings" | "evidence" | "full";
     evidence?: PulseResult | null;
@@ -60,6 +81,8 @@ export declare function buildScanBundle(input: {
     maxPreConsentRows?: number;
     preConsentCookiesTrackers?: PreConsentCookiesTrackers | null;
     report: PulseResult | null;
+    requestedMaxBytes?: number;
+    responseCeilingBytes?: number;
     scan: ScanResource;
 }): Record<string, any>;
 export declare function explainFinding(report: PulseResult, findingId: string): {