@certscore/mcp 0.2.21 → 0.2.23

package/dist/response-capture.d.ts

@@ -1,5 +1,8 @@
 import { type McpResponseSummary } from "@website-signal-risk-scanner/shared/dist/mcp-response-summary.js";
 type SafeMetadata = {
+    firstResult?: McpResponseSummary["firstResult"];
+    previewWaitMs?: number;
+    internalReadCount?: number;
     message?: string;
     recommendedNextAction?: string;
     upstream?: McpResponseSummary["upstream"];

package/dist/response-capture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response-capture.d.ts","sourceRoot":"","sources":["../src/response-capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,kEAAkE,CAAC;AAErI,KAAK,YAAY,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAA;CAAE,CAAC;AAEpH,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,GAAG,CAAC,CAG1F;AACD,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAGxF;AAGD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAsC/F"}
+{"version":3,"file":"response-capture.d.ts","sourceRoot":"","sources":["../src/response-capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,kEAAkE,CAAC;AAErI,KAAK,YAAY,GAAG;IAAE,WAAW,CAAC,EAAE,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAA;CAAE,CAAC;AAEzN,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,YAAY,GAAG,CAAC,CAG1F;AACD,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAGxF;AAGD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,OAAO,GAAG,kBAAkB,CA6D/F"}

package/dist/response-capture.js

@@ -2,7 +2,7 @@ import { mcpResponseSummarySchema } from "@website-signal-risk-scanner/shared/di
 const controlled = new WeakMap();
 /** Only call with template-owned text. Never mark upstream messages or caller values. */
 export function withResponseCapture(result, metadata) {
-    controlled.set(result, metadata);
+    controlled.set(result, { ...controlled.get(result), ...metadata });
     return result;
 }
 export function transferResponseCapture(payload, result) {
@@ -23,18 +23,43 @@ export function captureMcpResponse(result, protocolError) {
             catch { /* Markdown is never retained. */ }
         }
     }
+    const scan = payload.type === "certscore_domain_latest_scan" ? record(payload.scan) : payload;
+    const guidance = record(record(outer._meta)['ai.certscore/responseGuidance']);
+    const next = record(guidance.nextAction);
+    const actionCategories = ["poll_status", "get_bundle", "get_next_page", "create_if_requested", "summarize", "review_connection", "stop_review"];
+    const actionCategory = actionCategories.find(value => value === guidance.actionCategory);
+    const page = record(guidance.pagination);
+    const fm = record(payload.findingsMetadata), inventory = record(payload.preConsentCookiesTrackers), metadata = record(payload.mcpMetadata);
+    const counts = {};
+    for (const [key, value] of Object.entries({ findingsReturned: fm.returned, findingsTotal: fm.total, inventoryReturned: inventory.returned, inventoryTotal: inventory.total })) {
+        if (Number.isInteger(value) && value >= 0)
+            counts[key] = value;
+    }
+    if (Array.isArray(metadata.omittedSections))
+        counts.omittedSections = metadata.omittedSections.filter((v) => token(v)).slice(0, 12);
+    const quota = { limit: payload.anonymousQuotaLimit, remaining: payload.anonymousQuotaRemaining, resetAt: payload.anonymousQuotaResetAt };
     const protocol = record(protocolError);
     const error = protocolError ? record(protocol.data) : record(payload.error);
     const safe = controlled.get(protocolError ? protocol : outer) ?? {};
-    const retryAfterSeconds = Object.hasOwn(error, "retryAfterSeconds") ? error.retryAfterSeconds : payload.retryAfterSeconds;
+    const retryAfterSeconds = Object.hasOwn(error, "retryAfterSeconds") ? error.retryAfterSeconds : payload.retryAfterSeconds ?? next.retryAfterSeconds;
     const summary = {
         version: 1, captureBasis: "response_generated", templateVersion: "2026-09-11.1",
         kind: protocolError ? "protocol_error" : "tool_result", isError: protocolError ? true : outer.isError === true,
-        type: token(payload.type), status: token(payload.status), errorCode: token(error.code), reasonCode: token(error.reasonCode),
+        type: token(payload.type), status: token(scan.status ?? scan.scanStatus), errorCode: token(error.code), reasonCode: token(error.reasonCode),
         ...(Number.isInteger(protocolError ? protocol.code : error.mcpCode) ? { mcpCode: protocolError ? protocol.code : error.mcpCode } : {}),
         ...(typeof error.retryable === "boolean" ? { retryable: error.retryable } : {}),
         ...(retryAfterSeconds === null || Number.isInteger(retryAfterSeconds) && retryAfterSeconds >= 0 && retryAfterSeconds <= 86400 ? { retryAfterSeconds } : {}),
-        recommendedNextTool: payload.recommendedNextTool === null ? null : token(payload.recommendedNextTool),
+        recommendedNextTool: token(next.tool) ?? (payload.recommendedNextTool === null ? null : token(payload.recommendedNextTool)),
+        ...(actionCategory ? { actionCategory } : {}),
+        retryDisposition: !protocolError && outer.isError !== true && ["summarize", "get_bundle", "get_next_page", "create_if_requested", "review_connection"].includes(actionCategory ?? "") ? "not_needed" : actionCategory ? "follow_guidance" : "not_recorded",
+        scanAssociation: token(scan.scanId ?? scan.scan_id) ? "linked" : payload.type === "certscore_domain_latest_scan" && payload.scan === null ? "no_eligible_scan" : payload.type === "certscore_auth_check" ? "not_applicable" : "not_recorded",
+        ...(typeof (error.quotaConsumed ?? payload.quotaConsumed) === "boolean" ? { quotaConsumed: error.quotaConsumed ?? payload.quotaConsumed } : {}),
+        ...(typeof (error.scanStarted ?? payload.scanStarted) === "boolean" ? { scanStarted: error.scanStarted ?? payload.scanStarted } : {}),
+        ...(token(metadata.truncationReason) ? { omissionReason: token(metadata.truncationReason) } : {}),
+        ...(["new_scan", "reused_scan", "not_requested", "unknown"].includes(guidance.creationDecision) ? { creationDecision: guidance.creationDecision } : {}),
+        ...(typeof page.complete === "boolean" && (page.nextOffset === null || Number.isInteger(page.nextOffset) && page.nextOffset >= 0) ? { pagination: { complete: page.complete, nextOffset: page.nextOffset } } : {}),
+        ...(Number.isInteger(quota.limit) && quota.limit >= 0 && Number.isInteger(quota.remaining) && quota.remaining >= 0 && typeof quota.resetAt === "string" && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z$/.test(quota.resetAt) ? { anonymousCreationQuota: quota } : {}),
+        ...(Object.keys(counts).length ? { completeness: counts } : {}),
         ...safe,
         textOmitted: Boolean((protocolError ? protocol.message : error.message) && !safe.message || (error.recommendedNextAction || payload.recommendedNextAction) && !safe.recommendedNextAction),
         summaryTruncated: false,

package/dist/response-guidance.d.ts

@@ -0,0 +1,4 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** Presentation metadata only: never derive findings, eligibility or quota from observations. */
+export declare function withResponseGuidance(tool: string, input: unknown, result: CallToolResult, now?: number): CallToolResult;
+//# sourceMappingURL=response-guidance.d.ts.map

package/dist/response-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-guidance.d.ts","sourceRoot":"","sources":["../src/response-guidance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAuBzE,iGAAiG;AACjG,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,SAAa,GAAG,cAAc,CAqE3H"}

package/dist/response-guidance.js

@@ -0,0 +1,100 @@
+import { transferResponseCapture } from './response-capture.js';
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const string = (value) => typeof value === 'string' && value.trim() ? value.slice(0, 1000) : null;
+const toolPurposes = {
+    certscore_get_connection_status: "Check current access and quota without creating a scan.",
+    certscore_scan_site: 'Start the requested public-website scan; latest may reuse an eligible result, refresh requests a new scan.',
+    certscore_get_scan: 'Read one scan’s identity, lifecycle and overview without starting another scan.',
+    certscore_get_scan_status: 'Check whether a scan is ready; follow the polling interval instead of repeatedly fetching reports.',
+    certscore_get_report_evidence_page: 'Retrieve the complete report projection in bounded pages, preserving observation limitations.',
+    certscore_get_report: 'Read the report in JSON or Markdown for the requested level of detail.',
+    certscore_get_evidence: 'Inspect retained supporting evidence when the report summary is insufficient.',
+    certscore_get_scan_bundle: 'Use this as the main completed-scan summary: score, findings, evidence and pre-consent inventory together.',
+    certscore_export_findings: 'Export the returned canonical findings for downstream review or processing.',
+    certscore_list_findings: 'Browse canonical findings in pages; use their exact IDs for explanations.',
+    certscore_get_pre_consent_cookies_trackers: 'Inspect observed pre-consent inventory for this exact scan; unknown purpose is not proof of non-essential use.',
+    certscore_explain_finding: 'Explain one returned finding and its reviewer action, grounded in retained evidence.',
+    certscore_get_latest_domain_scan: 'Find an existing eligible domain scan before requesting new work when freshness is not required.',
+    certscore_get_latest_domain_pre_consent_cookies_trackers: 'Read pre-consent inventory from the latest eligible domain scan without starting a new scan.',
+};
+/** Presentation metadata only: never derive findings, eligibility or quota from observations. */
+export function withResponseGuidance(tool, input, result, now = Date.now()) {
+    if (result.isError || !result.structuredContent)
+        return result;
+    const args = record(input), payload = record(result.structuredContent);
+    const scan = payload.scan === null ? {} : Object.keys(record(payload.scan)).length ? record(payload.scan) : payload;
+    const summary = record(scan.summary), provenance = record(scan.provenance);
+    const noGo = scan.resultDisposition === 'no_go' || payload.resultDisposition === 'no_go';
+    const scanId = string(scan.scanId) ?? string(scan.scan_id) ?? string(args.scanId);
+    const status = string(scan.status);
+    const completedAt = string(scan.completedAt);
+    const parsedTime = completedAt ? Date.parse(completedAt) : NaN;
+    const ageSeconds = Number.isFinite(parsedTime) && parsedTime <= now ? Math.floor((now - parsedTime) / 1000) : null;
+    const isCreation = tool === 'certscore_scan_site';
+    const active = ['queued', 'running', 'finalizing'].includes(status ?? '');
+    const ready = ['completed', 'completed_limited'].includes(status ?? '');
+    const pagination = record(payload.pagination);
+    const hasMore = pagination.truncated === true || pagination.complete === false;
+    const nextOffset = hasMore && Number.isInteger(pagination.offset) && Number.isInteger(pagination.returned) && pagination.returned > 0
+        ? pagination.offset + pagination.returned : null;
+    let nextAction = { tool: null, arguments: null, instruction: 'Summarize the returned observations and coverage limitations.' };
+    if (tool === 'certscore_get_connection_status')
+        nextAction = { tool: null, arguments: null, instruction: string(record(payload.diagnostics).nextAction) ?? 'Review the connection diagnostics.' };
+    else if (noGo)
+        nextAction = { tool: null, arguments: null, instruction: string(scan.recommendedNextAction) ?? 'Review the retained no-go reason. Do not continue polling this scan.' };
+    else if (scanId && active)
+        nextAction = { tool: 'certscore_get_scan_status', arguments: { scanId }, retryAfterSeconds: scan.retryAfterSeconds ?? null, instruction: 'Wait for the returned polling interval before checking status.' };
+    else if (scanId && ready && payload.resultDisposition !== 'no_go' && ['certscore_scan_site', 'certscore_get_scan', 'certscore_get_scan_status', 'certscore_get_latest_domain_scan'].includes(tool))
+        nextAction = { tool: 'certscore_get_scan_bundle', arguments: { scanId }, instruction: 'Fetch the report bundle to summarize this completed scan.' };
+    else if (tool === 'certscore_get_report_evidence_page' && typeof pagination.nextCursor === 'string')
+        nextAction = { tool, arguments: { scanId, cursor: pagination.nextCursor }, instruction: 'Fetch the next report evidence page. Keep the same snapshot until export is complete.' };
+    else if (tool === 'certscore_list_findings' && nextOffset !== null)
+        nextAction = { tool, arguments: { scanId, offset: nextOffset, limit: pagination.limit }, instruction: 'Fetch the next page if more findings are needed.' };
+    else if (payload.scan === null)
+        nextAction = { tool: 'certscore_scan_site', arguments: null, instruction: 'No eligible retained scan was returned. Start a scan only if requested, using the intended public website URL.' };
+    else if (['failed', 'cancelled', 'canceled', 'no_go'].includes(status ?? '') || payload.resultDisposition === 'no_go')
+        nextAction = { tool: null, arguments: null, instruction: string(payload.recommendedNextAction) ?? 'Review the terminal error or no-go reason. Do not continue polling this scan.' };
+    const actionCategory = tool === 'certscore_get_connection_status' ? 'review_connection'
+        : nextAction.tool === 'certscore_get_scan_status' ? 'poll_status'
+            : nextAction.tool === 'certscore_get_scan_bundle' ? 'get_bundle'
+                : ['certscore_list_findings', 'certscore_get_report_evidence_page'].includes(String(nextAction.tool)) ? 'get_next_page'
+                    : nextAction.tool === 'certscore_scan_site' ? 'create_if_requested'
+                        : noGo || ['failed', 'cancelled', 'canceled', 'no_go'].includes(status ?? '') ? 'stop_review' : 'summarize';
+    const findingIds = (Array.isArray(payload.findings) ? payload.findings : Array.isArray(payload.topFindings) ? payload.topFindings : [])
+        .slice(0, 20).map((item) => string(record(item).id)).filter(Boolean);
+    if (tool === 'certscore_explain_finding' && string(payload.id))
+        findingIds.push(string(payload.id));
+    const guidance = {
+        version: 'certscore.mcp-response-guidance.v1', tool, purpose: toolPurposes[tool] ?? null, scanId, status,
+        score: typeof scan.score === 'number' ? scan.score : typeof summary.score === 'number' ? summary.score : null,
+        risk: string(scan.riskLevel) ?? string(summary.riskLevel) ?? string(scan.risk) ?? string(summary.risk),
+        coverage: string(scan.coverage) ?? string(record(scan.coverage).status),
+        reportUrl: string(scan.reportUrl) ?? string(record(scan.links).report),
+        retrieval: isCreation ? 'creation_response' : tool.includes('latest_domain') ? 'latest_eligible_domain_scan' : 'retained_result',
+        creationDecision: isCreation ? string(provenance.creationDecision) ?? (payload.reused === true ? 'reused_scan' : 'unknown') : 'not_requested',
+        quotaConsumed: typeof payload.quotaConsumed === 'boolean' ? payload.quotaConsumed : null,
+        completedAt, ageSeconds, scanFrom: string(scan.scanFrom), findingIds,
+        returnedRows: Array.isArray(payload.rows) ? payload.rows.length : Array.isArray(record(payload.preConsentCookiesTrackers).rows) ? payload.preConsentCookiesTrackers.rows.length : null,
+        evidenceLimits: { truncated: record(payload.evidenceMetadata).truncated ?? record(payload.mcpMetadata).truncated ?? null, total: record(payload.evidenceMetadata).total ?? null, returned: record(payload.evidenceMetadata).returned ?? null },
+        pagination: Object.keys(pagination).length ? { ...pagination, nextOffset, complete: !hasMore } : null,
+        optionalFollowUps: !noGo && !active && scanId && findingIds.length ? [
+            { tool: 'certscore_explain_finding', arguments: { scanId, findingId: findingIds[0] }, reason: 'Explain a returned finding using retained evidence.' },
+            { prompt: 'certscore_remediation_checklist', arguments: { scanId }, reason: 'Prepare a proposed checklist; do not claim remediation is verified.' }
+        ] : [],
+        nextAction, actionCategory,
+    };
+    // Keep full machine metadata; avoid repeating the entire envelope in model-visible text.
+    const compact = Object.fromEntries(Object.entries({
+        scanId, status, score: guidance.score, risk: guidance.risk, reportUrl: guidance.reportUrl,
+        quotaConsumed: guidance.quotaConsumed, nextAction,
+        ...(guidance.pagination ? { pagination: guidance.pagination } : {})
+    }).filter(([, value]) => value !== null));
+    const overview = `CertScore guidance: ${JSON.stringify(compact)}`;
+    const explanation = tool === 'certscore_explain_finding'
+        ? `\nFinding: ${JSON.stringify({ id: string(payload.id), observation: string(payload.evidenceSummary) ?? string(record(payload.evidence).summary), interpretation: string(payload.plainEnglish), reviewerAction: string(payload.nextStep) })}` : '';
+    return transferResponseCapture(result, {
+        ...result,
+        _meta: { ...result._meta, 'ai.certscore/responseGuidance': guidance },
+        content: [...result.content, { type: 'text', text: overview + explanation }],
+    });
+}

package/dist/server.d.ts

@@ -5,6 +5,10 @@ import { type RequestInfo } from "@modelcontextprotocol/sdk/types.js";
 import { type McpTaskContext } from "@website-signal-risk-scanner/shared/dist/mcp-product-context.js";
 export interface CertScoreMcpOptions {
     apiKey?: string;
+    /** Validated hosted OAuth scopes; never inferred from an unverified token. */
+    grantedOAuthScopes?: readonly string[];
+    /** Trusted host callback providing the current request's validated credential. */
+    resolveApiKey?: () => string;
     baseUrl?: string;
     forwardedClientIp?: string | null;
     resolveForwardedClientIp?: (headers: RequestInfo["headers"]) => string | null;
@@ -15,6 +19,7 @@ export interface CertScoreMcpOptions {
     toolProfile?: "full" | "light";
     initialPreConsentPreviewWaitMs?: number;
     exampleDomainDemoUrl?: string | null;
+    resolveRequestId?: () => string | undefined;
     onToolInvocationStarted?: (input: {
         requestId: string;
         toolName: string;

package/dist/server.d.ts.map

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

package/dist/server.js

@@ -1,9 +1,11 @@
+import { registerAdoptionFeatures, EXAMPLE_SCAN_ID } from "./adoption.js";
+import { withResponseGuidance } from "./response-guidance.js";
 import { randomUUID } from "node:crypto";
 import { captureMcpResponse, withResponseCapture } from "./response-capture.js";
 import { z } from "zod";
 import { captureMcpCallerInput } from "@website-signal-risk-scanner/shared/dist/mcp-caller-input.js";
-import { CertScoreClient } from "@certscore/sdk";
-import { certScoreMcpToolContracts, isCanonicalScanId } from "@certscore/api-contracts";
+import { CertScoreClient, CertScoreError } from "@certscore/sdk";
+import { certScoreMcpToolContracts, isCanonicalScanId, reportEvidencePageSchema } from "@certscore/api-contracts";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CallToolRequestSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { sanitizeMcpTaskContext } from "@website-signal-risk-scanner/shared/dist/mcp-product-context.js";
@@ -217,7 +219,9 @@ export function projectMcpToolInvocationObservation(input) {
     const isError = !completedNoGo
         && (Boolean(input.result?.isError) || Boolean(error));
     const outcome = rateLimited ? "rate_limited" : isError ? "error" : "success";
-    const resultScanId = boundedTelemetryToken(result.scanId ?? result.scan_id ?? result.jobId, 128);
+    const scan = result.type === "certscore_domain_latest_scan" && result.scan && typeof result.scan === "object"
+        ? result.scan : result;
+    const resultScanId = boundedTelemetryToken(scan.scanId ?? scan.scan_id ?? scan.jobId, 128);
     const inputScanId = boundedTelemetryToken(args.scanId, 128);
     const requestedResource = requestedTelemetryResource(args);
     const targetHostname = input.toolName === "certscore_scan_site"
@@ -250,12 +254,12 @@ export function projectMcpToolInvocationObservation(input) {
         scanDecision,
         scanFrom: args.scanFrom === "eu_de" || args.scanFrom === "eu_ie" || args.scanFrom === "california"
             ? args.scanFrom
-            : result.scanFrom === "eu_de" || result.scanFrom === "eu_ie" || result.scanFrom === "california"
-                ? result.scanFrom
+            : scan.scanFrom === "eu_de" || scan.scanFrom === "eu_ie" || scan.scanFrom === "california"
+                ? scan.scanFrom
                 : null,
         scanId: outcome === "error" && ["invalid_scan_id", "invalid_arguments", "invalid_url", "unknown_tool"].includes(errorCode ?? "")
             ? null : resultScanId ?? inputScanId,
-        scanStatus: boundedTelemetryToken(result.status, 64),
+        scanStatus: boundedTelemetryToken(scan.status ?? scan.scanStatus, 64),
         targetHostname,
         toolName: input.toolName,
         transportOutcome: isError ? "mcp_error" : "mcp_result",
@@ -290,8 +294,8 @@ function observeToolInvocation(observer, observation, requestContext) {
     });
 }
 export function createCertScoreMcpServer(options = {}) {
-    const createClient = (forwardedClientIp, anonymousRequesterSession) => new CertScoreClient({
-        apiKey: options.apiKey,
+    const createClient = (forwardedClientIp, anonymousRequesterSession, apiKey = options.apiKey) => new CertScoreClient({
+        apiKey,
         baseUrl: options.baseUrl,
         clientName: "mcp",
         forwardedClientIp,
@@ -301,25 +305,72 @@ export function createCertScoreMcpServer(options = {}) {
         timeout: options.timeout
     });
     const client = createClient(options.forwardedClientIp, options.resolveAnonymousRequesterSession?.());
-    const clientForRequest = (extra) => options.resolveForwardedClientIp
-        ? createClient(options.resolveForwardedClientIp(extra.requestInfo?.headers ?? {}), options.resolveAnonymousRequesterSession?.())
-        : client;
+    const clientForRequest = (extra) => {
+        if (!options.resolveApiKey && !options.resolveForwardedClientIp)
+            return client;
+        const apiKey = options.resolveApiKey ? options.resolveApiKey() : options.apiKey;
+        if (options.resolveApiKey && !apiKey?.trim()) {
+            throw new Error("Validated MCP request credential is unavailable.");
+        }
+        return createClient(options.resolveForwardedClientIp ? options.resolveForwardedClientIp(extra.requestInfo?.headers ?? {}) : options.forwardedClientIp, options.resolveAnonymousRequesterSession?.(), apiKey);
+    };
     const server = new McpServer({
         name: "certscore",
         version: CERTSCORE_MCP_VERSION
+    }, {
+        instructions: JSON.stringify({
+            setup: {
+                route: options.toolProfile === "light" ? "light" : options.grantedOAuthScopes ? "hosted_oauth" : options.anonymousSurface ? "anonymous" : "scoped_api_key",
+                scopesGranted: options.grantedOAuthScopes ?? null,
+                createAllowedByScope: options.grantedOAuthScopes ? options.grantedOAuthScopes.includes("scan:create") : null,
+                resources: options.toolProfile === "light" ? [] : ["certscore://connection", "certscore://project-instructions", "certscore://reconnect", "certscore://example-report"],
+                prompts: options.toolProfile === "light" ? [] : ["certscore_launch_review", "certscore_compare_scans", "certscore_remediation_checklist"],
+                quotaRemaining: null,
+                quotaNote: "Remaining allowance is not loaded at handshake. Scan creation enforces current workspace and requester limits; inspect quota errors rather than assuming a fresh allowance.",
+                recommendedNextTool: options.grantedOAuthScopes && !options.grantedOAuthScopes.includes("scan:create") ? "certscore_get_latest_domain_scan" : "certscore_scan_site",
+                sequence: ["certscore_scan_site", "certscore_get_scan_status", "certscore_get_scan_bundle"],
+                guidance: options.toolProfile === "light"
+                    ? "Light supports eligible public scans, not workspace history. For workspace access connect https://mcp.certscore.ai/mcp using OAuth. Reuse an existing Hosted OAuth connection rather than adding duplicate names."
+                    : "Start a scan, poll only while active at the returned interval, then fetch its bundle. If scan:create is missing, reauthorize with scan:read scan:create mcp. Reuse existing endpoint installations; client names are labels, not verified identities."
+            }
+        })
     });
+    if (options.toolProfile !== "light")
+        registerAdoptionFeatures(server, async () => {
+            try {
+                return await clientForRequest({}).getConnectionStatus();
+            }
+            catch (error) {
+                if (error instanceof CertScoreError && error.status === 401)
+                    return { authenticated: false, status: "reconnect_required", quota: null, nextAction: "Read certscore://reconnect and reconnect the existing Hosted OAuth connector. Do not share tokens." };
+                return { authenticated: null, status: "check_unavailable", quota: null, nextAction: "Retry the connection check. If your host reports expired or revoked access, read certscore://reconnect. Do not assume a failed check means quota is available." };
+            }
+        }, async () => {
+            try {
+                const exampleClient = clientForRequest({});
+                const [report, metadata] = await Promise.all([exampleClient.getScanPulse(EXAMPLE_SCAN_ID), exampleClient.getScanResource(EXAMPLE_SCAN_ID)]);
+                return { originalCompletedAt: metadata.completedAt ?? null, coverage: metadata.coverage, status: metadata.status, example: true, label: "Retained example, not a current scan of your website", scanId: EXAMPLE_SCAN_ID,
+                    reportUrl: `https://certscore.ai/scan/${EXAMPLE_SCAN_ID}`,
+                    report: JSON.stringify(report).length <= 30000 ? report : null,
+                    note: "Use original timestamps and coverage from the report. If omitted here for size, open the report URL. No new scan was created." };
+            }
+            catch {
+                return { example: true, available: false, scanId: EXAMPLE_SCAN_ID, nextAction: "The retained example is unavailable. Do not create a replacement scan automatically." };
+            }
+        });
     const sdkCreateToolError = server.createToolError.bind(server);
     server.createToolError = (message) => message.includes("Input validation error:")
         ? toInvalidArgumentsToolError(message)
         : sdkCreateToolError(message);
     const registeredToolNames = new Set();
-    const lightTools = new Set(["certscore_scan_site", "certscore_get_scan_status", "certscore_get_scan_bundle"]);
+    const lightTools = new Set(["certscore_scan_site", "certscore_get_scan_status", "certscore_get_scan_bundle", "certscore_get_report_evidence_page"]);
     const scanIdTools = new Set([
         "certscore_explain_finding",
         "certscore_export_findings",
         "certscore_get_evidence",
         "certscore_get_pre_consent_cookies_trackers",
         "certscore_get_report",
+        "certscore_get_report_evidence_page",
         "certscore_get_scan",
         "certscore_get_scan_bundle",
         "certscore_get_scan_status",
@@ -334,7 +385,7 @@ export function createCertScoreMcpServer(options = {}) {
             return registerRequest(schema, handler);
         return registerRequest(CallToolRequestSchema, async (request, extra) => {
             const startedAt = Date.now();
-            const requestId = randomUUID();
+            const requestId = options.resolveRequestId?.() ?? randomUUID();
             const name = request.params.name;
             if (options.onToolInvocationStarted) {
                 void Promise.resolve().then(() => options.onToolInvocationStarted({ requestId, toolName: name, startedAt: new Date(startedAt).toISOString() }))
@@ -395,7 +446,7 @@ export function createCertScoreMcpServer(options = {}) {
                         requestId,
                         timing: { startedAt: new Date(startedAt).toISOString(), responseGeneratedAt: new Date().toISOString() },
                         captureBasis: "protocol_request",
-                        callerInput: captureMcpCallerInput(args, request.params._meta),
+                        callerInput: captureMcpCallerInput(args, request.params._meta, { expanded: process.env.MCP_EXPANDED_CALLER_INPUT_ENABLED === "1" }),
                         ...(taskContext ? { taskContext } : {}),
                         response: {
                             summary: captureMcpResponse(result, protocolFailure),
@@ -421,10 +472,19 @@ export function createCertScoreMcpServer(options = {}) {
             const scanId = input && typeof input === "object" && !Array.isArray(input)
                 ? input.scanId : null;
             return scanIdTools.has(name) && !isCanonicalScanId(scanId)
-                ? toInvalidScanIdToolError() : typedHandler(input, extra);
+                ? toInvalidScanIdToolError() : withResponseGuidance(name, input, await typedHandler(input, extra));
         });
         registeredToolNames.add(name);
     };
+    registerTool("certscore_get_connection_status", toolContract("certscore_get_connection_status"), async (_input, extra) => {
+        try {
+            const status = await clientForRequest(extra).getConnectionStatus();
+            return toToolResult(status, JSON.stringify(status));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
     registerTool("certscore_scan_site", toolContract("certscore_scan_site"), async (input, extra) => {
         const toolStartedAtMs = Date.now();
         const creationStartedAtMs = toolStartedAtMs;
@@ -446,6 +506,8 @@ export function createCertScoreMcpServer(options = {}) {
                 reused: created.reused === true,
                 status: created.status ?? null,
             }));
+            let retainedPreviewWaitMs = 0;
+            let retainedInternalReadCount = 0;
             let initialResult = created;
             const stableScanId = typeof created.scanId === "string" && created.scanId
                 ? created.scanId
@@ -497,6 +559,8 @@ export function createCertScoreMcpServer(options = {}) {
                         scanId: stableScanId,
                     }));
                 }
+                retainedPreviewWaitMs = Date.now() - previewWaitStartedAtMs;
+                retainedInternalReadCount = internalReadCount;
                 console.log(JSON.stringify({
                     event: "mcp.certscore_scan_site.preview_wait_completed",
                     durationMs: Date.now() - previewWaitStartedAtMs,
@@ -508,7 +572,11 @@ export function createCertScoreMcpServer(options = {}) {
                 }));
             }
             const guided = withExampleDomainDemo(withMcpAgentGuidance(initialResult, "unknown", "scan_creation"), demoSubstitution);
-            return toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
+            const toolResult = toToolResult(guided, exampleDomainDemoText(guided, demoSubstitution));
+            return options.toolProfile === "light" ? withResponseCapture(toolResult, {
+                firstResult: ["completed", "completed_limited"].includes(initialResult.status) ? "completed" : ["failed", "expired"].includes(initialResult.status) ? "failed" : hasPreConsentPreview(initialResult) ? "preview" : activeScan(initialResult) ? "queued" : "unknown",
+                previewWaitMs: retainedPreviewWaitMs, internalReadCount: retainedInternalReadCount,
+            }) : toolResult;
         }
         catch (error) {
             console.warn(JSON.stringify({
@@ -519,7 +587,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error, { scanCreation: !creationCompleted });
         }
     });
-    registerTool("certscore_get_scan", toolContract("certscore_get_scan"), async ({ scanId }) => {
+    registerTool("certscore_get_scan", toolContract("certscore_get_scan"), async ({ scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             return toToolResult(await client.scans.get(scanId));
         }
@@ -543,7 +612,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_report", toolContract("certscore_get_report"), async ({ scanId, detail, format }) => {
+    registerTool("certscore_get_report", toolContract("certscore_get_report"), async ({ scanId, detail, format }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const normalizedFormat = normalizeFormat(format);
             const result = normalizedFormat === "markdown"
@@ -570,7 +640,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_evidence", toolContract("certscore_get_evidence"), async ({ scanId }) => {
+    registerTool("certscore_get_evidence", toolContract("certscore_get_evidence"), async ({ scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const bounded = boundEvidencePacket(await client.getScan(scanId, { detail: "evidence", format: "json" }), MAX_EVIDENCE_PACKET_CHARS - 2_500);
             const guided = withMcpAgentGuidance(bounded, "existing_scan_retrieved");
@@ -580,6 +651,15 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
+    registerTool("certscore_get_report_evidence_page", toolContract("certscore_get_report_evidence_page"), async ({ scanId, cursor }, extra) => {
+        try {
+            const page = reportEvidencePageSchema.parse(await clientForRequest(extra).getReportEvidencePage(scanId, { cursor, timeout: 30_000, internalMcpOperation: { operation: "scan_bundle", scanId } }));
+            return toToolResult(page, `Report evidence for ${scanId}: ${page.pagination.offset + 1}–${page.pagination.offset + page.pagination.returned} of ${page.pagination.total} entries. ${page.pagination.complete ? "Export complete; preserve report coverage limitations." : `Continue with certscore_get_report_evidence_page using scanId and cursor ${page.pagination.nextCursor}.`} Evidence values are in structuredContent.entries. ${page.download ? `Full report JSON: ${page.download.url} (${page.download.bytes} bytes). ${page.download.instructions}` : ""} ${page.reportUrl}`);
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
     registerTool("certscore_get_scan_bundle", toolContract("certscore_get_scan_bundle"), async ({ scanId, detail = "summary", maxBytes, maxFindings, maxPreConsentRows }, extra) => {
         const client = clientForRequest(extra);
         try {
@@ -605,7 +685,7 @@ export function createCertScoreMcpServer(options = {}) {
                     responseCeilingBytes,
                     scan
                 });
-                return toToolResult(bundle, scanBundleText(bundle));
+                return toToolResult(bundle, scanBundleText(bundle, { lightTrialCta: options.toolProfile === "light" }));
             }
             const includeEvidence = detail === "evidence" || detail === "full";
             const reportDetail = detail === "full" ? "full" : includeEvidence ? "evidence" : "summary";
@@ -630,13 +710,14 @@ export function createCertScoreMcpServer(options = {}) {
                 responseCeilingBytes,
                 scan
             });
-            return toToolResult(bundle, scanBundleText(bundle));
+            return toToolResult(bundle, scanBundleText(bundle, { lightTrialCta: options.toolProfile === "light" }));
         }
         catch (error) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_export_findings", toolContract("certscore_export_findings"), async ({ scanId }) => {
+    registerTool("certscore_export_findings", toolContract("certscore_export_findings"), async ({ scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const report = await client.getScan(scanId, { detail: "full", format: "json" });
             const guided = withMcpAgentGuidance(exportFindings(report), "existing_scan_retrieved");
@@ -646,7 +727,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_list_findings", toolContract("certscore_list_findings"), async ({ limit, offset, scanId }) => {
+    registerTool("certscore_list_findings", toolContract("certscore_list_findings"), async ({ limit, offset, scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const guided = withMcpAgentGuidance(paginateFindingList(await client.findings.list(scanId), { limit, offset }), "existing_scan_retrieved");
             return toToolResult(guided, findingListText(guided));
@@ -655,7 +737,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_pre_consent_cookies_trackers", toolContract("certscore_get_pre_consent_cookies_trackers"), async ({ maxRows, scanId }) => {
+    registerTool("certscore_get_pre_consent_cookies_trackers", toolContract("certscore_get_pre_consent_cookies_trackers"), async ({ maxRows, scanId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const guided = withMcpAgentGuidance(limitPreConsentRows(await client.scans.preConsentCookiesTrackers(scanId), { maxRows }), "existing_scan_retrieved");
             return toToolResult(guided, preConsentInventoryText(guided));
@@ -664,7 +747,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_explain_finding", toolContract("certscore_explain_finding"), async ({ scanId, findingId }) => {
+    registerTool("certscore_explain_finding", toolContract("certscore_explain_finding"), async ({ scanId, findingId }, extra) => {
+        const client = clientForRequest(extra);
         try {
             return toToolResult(await client.findings.explain(scanId, findingId));
         }
@@ -672,7 +756,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_latest_domain_scan", toolContract("certscore_get_latest_domain_scan"), async ({ domain, scanFrom }) => {
+    registerTool("certscore_get_latest_domain_scan", toolContract("certscore_get_latest_domain_scan"), async ({ domain, scanFrom }, extra) => {
+        const client = clientForRequest(extra);
         try {
             return toToolResult(await client.domains.latest(domain, { scanFrom }));
         }
@@ -680,7 +765,8 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
-    registerTool("certscore_get_latest_domain_pre_consent_cookies_trackers", toolContract("certscore_get_latest_domain_pre_consent_cookies_trackers"), async ({ domain, maxRows, scanFrom }) => {
+    registerTool("certscore_get_latest_domain_pre_consent_cookies_trackers", toolContract("certscore_get_latest_domain_pre_consent_cookies_trackers"), async ({ domain, maxRows, scanFrom }, extra) => {
+        const client = clientForRequest(extra);
         try {
             const guided = withMcpAgentGuidance(limitPreConsentRows(await client.domains.latestPreConsentCookiesTrackers(domain, { scanFrom }), { maxRows }), "existing_scan_retrieved");
             return toToolResult(guided, preConsentInventoryText(guided));
@@ -690,5 +776,12 @@ export function createCertScoreMcpServer(options = {}) {
         }
     });
     server.server.setRequestHandler = registerRequest;
+    // Reconnecting hosts may retain a tool catalog from an older release.
+    // Announce the current catalog once the new session has initialized.
+    server.server.oninitialized = () => {
+        void server.server.sendToolListChanged().catch(() => {
+            // A host without a notification channel can still call tools/list normally.
+        });
+    };
     return server;
 }

package/dist/tools.d.ts

@@ -48,6 +48,10 @@ export declare function scanIdFromPulse(report: PulseResult): string | null;
 export declare function findingsFromReport(report: PulseResult): TopFinding[];
 export declare function exportFindings(report: PulseResult): {
     type: string;
+    exportVersion: string;
+    exportedAt: string;
+    returnedFindingCount: number;
+    completeness: string;
     scanId: string | null;
     domain: string | null;
     summary: import("packages/certscore-sdk/dist/types.js").PulseSummary | null;
@@ -80,7 +84,9 @@ export declare function findingListText(value: Record<string, any>, label?: stri
 export declare function preConsentInventoryText(value: Record<string, any>): string;
 export declare function pulseReportText(value: Record<string, any>, label?: string): string;
 export declare function markdownReportText(value: Record<string, any>): string;
-export declare function scanBundleText(bundle: Record<string, any>): string;
+export declare function scanBundleText(bundle: Record<string, any>, options?: {
+    lightTrialCta?: boolean;
+}): string;
 export declare function buildScanBundle(input: {
     detail?: "summary" | "findings" | "evidence" | "full";
     evidence?: PulseResult | null;

package/dist/tools.d.ts.map

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