@certscore/mcp 0.2.15 → 0.2.16

package/dist/index.js

@@ -141,7 +141,7 @@ export async function getCertScoreMcpDoctorReport(options = {}) {
             exitCode = 1;
         }
     }
-    lines.push("CertScore outputs are automated public-web observations for review, not legal advice, certification, or a compliance determination.");
+    lines.push("CertScore outputs are automated public-web observations for human and agentic review, not legal advice, certification, or a compliance determination.");
     return { exitCode, lines };
 }
 function isMainModule() {

package/dist/server.d.ts

@@ -1,11 +1,53 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { RequestInfo } from "@modelcontextprotocol/sdk/types.js";
 export interface CertScoreMcpOptions {
     apiKey?: string;
     baseUrl?: string;
     forwardedClientIp?: string | null;
+    resolveForwardedClientIp?: (headers: RequestInfo["headers"]) => string | null;
+    resolveAnonymousRequesterSession?: () => string | null;
     anonymousRequesterSecret?: string | null;
+    anonymousSurface?: "mcp_light" | "mcp_anonymous" | null;
     timeout?: number;
     toolProfile?: "full" | "light";
+    exampleDomainDemoUrl?: string | null;
+    onToolInvocation?: (observation: McpToolInvocationObservation, requestContext: McpToolInvocationRequestContext) => void | Promise<void>;
 }
+export type McpToolInvocationRequestContext = {
+    headers: RequestInfo["headers"] | null;
+};
+export type McpToolInvocationObservation = {
+    durationMs: number;
+    errorCode: string | null;
+    freshness: "latest" | "refresh" | null;
+    isCanary: boolean;
+    outcome: "success" | "error" | "rate_limited";
+    quotaOutcome: "allowed" | "rate_limited";
+    requestedResource: string | null;
+    requestedResourceType: "url" | "domain" | "scan_id" | "job_id" | null;
+    scanDecision: "reused" | "new" | "unavailable" | "not_applicable";
+    scanFrom: "eu_de" | "eu_ie" | "california" | null;
+    scanId: string | null;
+    scanStatus: string | null;
+    targetHostname: string | null;
+    toolName: string;
+    transportOutcome: "mcp_result" | "mcp_error";
+};
+export declare function resolveMcpScanSiteWaitBudget(input: {
+    maxWaitSeconds?: number;
+    startedAtMs: number;
+    nowMs: number;
+}): {
+    elapsedMs: number;
+    remainingWaitMs: number;
+    responseReserveMs: number;
+    totalBudgetMs: number;
+};
+export declare function projectMcpToolInvocationObservation(input: {
+    args: unknown;
+    durationMs: number;
+    result: unknown;
+    toolName: string;
+}): McpToolInvocationObservation;
 export declare function createCertScoreMcpServer(options?: CertScoreMcpOptions): McpServer;
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC;AAyED,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,aAkSzE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAItE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,wBAAwB,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,IAAI,CAAC;IAC9E,gCAAgC,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACvD,wBAAwB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,gBAAgB,CAAC,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,gBAAgB,CAAC,EAAE,CACjB,WAAW,EAAE,4BAA4B,EACzC,cAAc,EAAE,+BAA+B,KAC5C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAID,MAAM,MAAM,+BAA+B,GAAG;IAC5C,OAAO,EAAE,WAAW,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC;CACxC,CAAC;AA4BF,MAAM,MAAM,4BAA4B,GAAG;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,SAAS,GAAG,OAAO,GAAG,cAAc,CAAC;IAC9C,YAAY,EAAE,SAAS,GAAG,cAAc,CAAC;IACzC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,qBAAqB,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC;IACtE,YAAY,EAAE,QAAQ,GAAG,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC;IAClE,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,IAAI,CAAC;IAClD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,YAAY,GAAG,WAAW,CAAC;CAC9C,CAAC;AAOF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;;;;;EAYA;AAoJD,wBAAgB,mCAAmC,CAAC,KAAK,EAAE;IACzD,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,4BAA4B,CAqD/B;AAkBD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,aA8XzE"}

package/dist/server.js

@@ -1,9 +1,52 @@
-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, 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();
@@ -43,15 +86,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,30 +250,100 @@ 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 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));
+                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(withMcpAgentGuidance({
+                const guided = withExampleDomainDemo(withMcpAgentGuidance({
                     ...completed,
                     ...scanCreationMetadata(created)
-                }));
+                }), demoSubstitution);
+                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
             }
             catch (error) {
                 const scanId = created.scanId ?? created.scan_id;
@@ -93,25 +352,18 @@ export function createCertScoreMcpServer(options = {}) {
                     errorName: error instanceof Error ? error.name : "UnknownError",
                     jobId: created.jobId ?? null,
                     scanId: scanId ?? null,
-                    status: created.status ?? null
+                    status: created.status ?? null,
+                    ...waitBudget,
                 }));
-                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.
-                    }
-                }
                 // 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));
+                const guided = withExampleDomainDemo(withMcpAgentGuidance(created), demoSubstitution);
+                return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
+            }
+            finally {
+                clearTimeout(waitAbortTimer);
             }
         }
         catch (error) {
@@ -126,41 +378,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 +406,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 +423,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 +490,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 +499,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 +508,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 +533,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);