@certscore/mcp 0.2.12 → 0.2.16

package/dist/server.js

@@ -1,10 +1,64 @@
-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, scanIdFromStatus, toToolError, toToolResult } from "./tools.js";
-let createScanDeprecationWarningPrinted = false;
-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, scanStatusText, toInvalidArgumentsToolError, toInvalidScanIdToolError, toToolError, toToolResult, withMcpAgentGuidance, withMcpScanProvenanceGuidance } from "./tools.js";
+const DEFAULT_MCP_SCAN_TOOL_BUDGET_MS = 25_000;
+const MAX_MCP_SCAN_TOOL_BUDGET_MS = 45_000;
+const MCP_SCAN_TOOL_RESPONSE_RESERVE_MS = 1_000;
+const LIGHT_MCP_BUNDLE_RESPONSE_CEILING_BYTES = 25_000;
+export function resolveMcpScanSiteWaitBudget(input) {
+    const totalBudgetMs = Math.min(input.maxWaitSeconds ? input.maxWaitSeconds * 1_000 : DEFAULT_MCP_SCAN_TOOL_BUDGET_MS, MAX_MCP_SCAN_TOOL_BUDGET_MS);
+    const elapsedMs = Math.max(0, input.nowMs - input.startedAtMs);
+    return {
+        elapsedMs,
+        remainingWaitMs: Math.max(0, totalBudgetMs - elapsedMs - MCP_SCAN_TOOL_RESPONSE_RESERVE_MS),
+        responseReserveMs: MCP_SCAN_TOOL_RESPONSE_RESERVE_MS,
+        totalBudgetMs,
+    };
+}
+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) {
+    if (!substitution)
+        return undefined;
+    const status = typeof value.status === "string" ? ` Status=${value.status}.` : "";
+    const scanId = typeof value.scanId === "string" ? ` ScanId=${value.scanId}.` : "";
+    return `${substitution.message}${status}${scanId} Full result and substitution provenance are in structuredContent.`;
+}
+async function retryTransientOriginFailure(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const retryable = error instanceof Error && "status" in error && [502, 503, 504].includes(Number(error.status));
+        if (!retryable) {
+            throw error;
+        }
+        return operation();
+    }
+}
 function scanCreationMetadata(value) {
     return {
         executionMode: value.executionMode,
@@ -32,99 +86,291 @@ 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
     });
-    const lightTools = new Set(["scan_site", "get_scan_status", "get_scan_bundle"]);
+    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 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);
-    };
-    async function createPulseScanTool(input) {
-        const result = await client.submitScan(input.url, {
-            detail: normalizeDetail(input.detail),
-            format: normalizeFormat(input.format),
-            freshness: input.freshness ?? "latest",
-            scanFrom: input.scanFrom
-        });
-        return {
-            type: "certscore_mcp_scan_created",
-            status: result.status,
-            jobId: result.jobId ?? null,
-            scanId: result.scanId ?? result.scan_id ?? null,
-            completed: result.completed ?? false,
-            statusUrl: result.statusUrl ?? result.nextCheckUrl ?? null,
-            resultUrl: result.resultUrl ?? null,
-            reportUrl: result.reportUrl ?? null,
-            pulse: result.pulse ?? null,
-            resultDisposition: result.resultDisposition ?? result.pulse?.resultDisposition ?? null,
-            noGo: result.noGo ?? result.pulse?.noGo ?? null
-        };
-    }
-    registerTool("create_scan", toolContract("create_scan"), async (input) => {
-        try {
-            if (!createScanDeprecationWarningPrinted) {
-                createScanDeprecationWarningPrinted = true;
-                console.error("[certscore-mcp] create_scan is deprecated in the 0.2.x line. Use scan_site for new integrations.");
+        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;
             }
-            return toToolResult(await createPulseScanTool(input));
-        }
-        catch (error) {
-            return toToolError(error);
-        }
-    });
-    registerTool("scan_site", toolContract("scan_site"), async (input) => {
+            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, extra) => {
+        const toolStartedAtMs = Date.now();
+        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(created);
+                const guided = withExampleDomainDemo(withMcpAgentGuidance(created), demoSubstitution);
+                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
             }
+            const waitBudget = resolveMcpScanSiteWaitBudget({
+                maxWaitSeconds: input.maxWaitSeconds,
+                nowMs: Date.now(),
+                startedAtMs: toolStartedAtMs,
+            });
+            if (waitBudget.remainingWaitMs === 0) {
+                console.warn(JSON.stringify({
+                    event: "mcp.certscore_scan_site.wait_budget_consumed",
+                    jobId: created.jobId ?? null,
+                    scanId: created.scanId ?? created.scan_id ?? null,
+                    status: created.status ?? null,
+                    ...waitBudget,
+                }));
+                const guided = withExampleDomainDemo(withMcpAgentGuidance(created), demoSubstitution);
+                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
+            }
+            const waitAbortController = new AbortController();
+            const waitAbortTimer = setTimeout(() => waitAbortController.abort(), waitBudget.remainingWaitMs);
             try {
+                const internalMcpOperation = { operation: "scan_site_wait", scanId: created.scanId ?? created.scan_id ?? created.jobId };
                 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)
+                    maxWaitMs: waitBudget.remainingWaitMs,
+                    internalMcpOperation,
+                    signal: waitAbortController.signal,
                 });
-                return toToolResult({
+                const guided = withExampleDomainDemo(withMcpAgentGuidance({
                     ...completed,
-                    ...scanCreationMetadata(created),
-                    recommendedNextTool: "get_scan_bundle"
-                });
+                    ...scanCreationMetadata(created)
+                }), demoSubstitution);
+                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
             }
             catch (error) {
-                if (!(error instanceof CertScoreTimeoutError)) {
-                    throw error;
-                }
                 const scanId = created.scanId ?? created.scan_id;
-                if (scanId) {
-                    return toToolResult({
-                        ...(await client.scans.status(scanId)),
-                        ...scanCreationMetadata(created),
-                        recommendedNextTool: "get_scan_status"
-                    });
-                }
-                return toToolResult(created);
+                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,
+                    ...waitBudget,
+                }));
+                // 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.
+                const guided = withExampleDomainDemo(withMcpAgentGuidance(created), demoSubstitution);
+                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
+            }
+            finally {
+                clearTimeout(waitAbortTimer);
             }
         }
         catch (error) {
             return toToolError(error);
         }
     });
-    registerTool("get_scan", toolContract("get_scan"), async ({ scanId }) => {
+    registerTool("certscore_get_scan", toolContract("certscore_get_scan"), async ({ scanId }) => {
         try {
             return toToolResult(await client.scans.get(scanId));
         }
@@ -132,53 +378,23 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("get_scan_status", toolContract("get_scan_status"), async ({ jobId, scanId }) => {
+    registerTool("certscore_get_scan_status", toolContract("certscore_get_scan_status"), async ({ scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
-            if (scanId) {
-                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({
-                            ...status,
-                            type: "certscore_scan_job",
-                            status: scan.status,
-                            domain: scan.domain,
-                            resultDisposition: scan.resultDisposition,
-                            noGo: scan.noGo,
-                            startedAt: scan.startedAt,
-                            completedAt: scan.completedAt,
-                            scanTimeSeconds: scan.scanTimeSeconds,
-                            recommendedNextTool: "get_scan_bundle"
-                        });
-                    }
-                    catch {
-                        // Preserve the API status response if the terminal scan resource is
-                        // briefly unavailable during eventual-consistency windows.
-                    }
-                }
-                return toToolResult(status);
-            }
-            if (!jobId) {
-                return toToolResult({
-                    error: {
-                        name: "InvalidToolInput",
-                        message: "Provide either scanId for API v2 scan status or jobId for Pulse job status."
-                    }
-                });
-            }
-            const status = await client.getJobStatus(jobId);
-            return toToolResult({
+            const internalMcpOperation = { operation: "scan_status", scanId };
+            const status = await client.scans.status(scanId, { internalMcpOperation });
+            const guided = withMcpScanProvenanceGuidance({
                 ...status,
-                scanId: scanIdFromStatus(status)
-            });
+                jobId: undefined,
+                scanFrom: status.scanFrom ?? null
+            }, "existing_scan_retrieved");
+            return toToolResult(guided, scanStatusText(guided));
         }
         catch (error) {
             return toToolError(error);
         }
     });
-    registerTool("get_report", toolContract("get_report"), async ({ scanId, detail, format }) => {
+    registerTool("certscore_get_report", toolContract("certscore_get_report"), async ({ scanId, detail, format }) => {
         try {
             const normalizedFormat = normalizeFormat(format);
             const result = normalizedFormat === "markdown"
@@ -190,69 +406,116 @@ 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);
         }
     });
-    registerTool("get_evidence", toolContract("get_evidence"), async ({ scanId }) => {
+    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("get_scan_bundle", toolContract("get_scan_bundle"), async ({ scanId, 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, report, evidence, findings, preConsentCookiesTrackers] = await Promise.all([
-                client.scans.get(scanId),
-                client.getScan(scanId, { detail: "summary", format: "json" }),
-                client.getScan(scanId, { detail: "evidence", format: "json" }),
-                client.findings.list(scanId),
-                client.scans.preConsentCookiesTrackers(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") {
+                const bundle = buildScanBundle({
+                    detail,
+                    evidence: null,
+                    findings: { type: "certscore_finding_list", scanId, findings: [] },
+                    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", internalMcpOperation })),
+                retryTransientOriginFailure(() => client.findings.list(scanId, { internalMcpOperation })),
+                scan.status === "completed"
+                    ? retryTransientOriginFailure(() => client.scans.preConsentCookiesTrackers(scanId, { internalMcpOperation }))
+                    : Promise.resolve(null)
             ]);
-            return toToolResult(buildScanBundle({
+            const evidence = includeEvidence ? report : null;
+            const bundle = buildScanBundle({
+                detail,
                 evidence,
                 findings,
+                maxBytes: requestedMaxBytes,
                 maxFindings,
                 maxPreConsentRows,
                 preConsentCookiesTrackers,
                 report,
+                requestedMaxBytes,
+                responseCeilingBytes,
                 scan
-            }));
+            });
+            return toToolResult(bundle, scanBundleText(bundle));
         }
         catch (error) {
             return toToolError(error);
         }
     });
-    registerTool("export_findings", toolContract("export_findings"), async ({ scanId }) => {
+    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);
         }
     });
-    registerTool("list_findings", toolContract("list_findings"), async ({ limit, offset, scanId }) => {
+    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);
         }
     });
-    registerTool("get_pre_consent_cookies_trackers", toolContract("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 }) => {
         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);
         }
     });
-    registerTool("explain_finding", toolContract("explain_finding"), async ({ scanId, findingId }) => {
+    registerTool("certscore_explain_finding", toolContract("certscore_explain_finding"), async ({ scanId, findingId }) => {
         try {
             return toToolResult(await client.findings.explain(scanId, findingId));
         }
@@ -260,7 +523,7 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("get_latest_domain_scan", toolContract("get_latest_domain_scan"), async ({ domain, scanFrom }) => {
+    registerTool("certscore_get_latest_domain_scan", toolContract("certscore_get_latest_domain_scan"), async ({ domain, scanFrom }) => {
         try {
             return toToolResult(await client.domains.latest(domain, { scanFrom }));
         }
@@ -268,9 +531,10 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("get_latest_domain_pre_consent_cookies_trackers", toolContract("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 }) => {
         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);