@certscore/mcp 0.2.6 → 0.2.11

package/README.md

@@ -2,7 +2,7 @@
 
 CertScore MCP exposes a focused Model Context Protocol server for CertScore Pulse workflows.
 
-Status: public developer preview. Version 0.2.6 is available as a Homebrew/npm stdio server and as a hosted OAuth-protected Streamable HTTP service. Local WC01 development uses `pnpm mcp:certscore`.
+Status: public developer preview. Version 0.2.11 is prepared for the hosted Streamable HTTP service and the next deterministic Homebrew release. Local WC01 development uses `pnpm mcp:certscore`.
 
 Public docs:
 
@@ -14,11 +14,12 @@ Public docs:
 ## Tools
 
 - `create_scan` - Deprecated compatibility alias of scan_site. Use scan_site for new integrations. Returns completed-limited no-go disposition and reason-specific guidance when applicable.
-- `scan_site` - Start or reuse a CertScore public-web scan. Completed no-go scans return completed_limited status, structured reason-specific guidance, and timing when available.
+- `scan_site` - Recommended first call. Starts or reuses a public-web scan, reports freshness and anonymous quota decisions, and waits up to 45 seconds by default. If still running, use get_scan_status; otherwise use get_scan_bundle. Completed no-go scans retain completed_limited status and reason-specific guidance.
 - `get_scan` - Retrieve the API v2 public-safe scan resource, including completed-limited no-go disposition, reason-specific guidance, and timing when available.
 - `get_scan_status` - Retrieve terminal status, including completed_limited no-go disposition and reason-specific guidance. Pass jobId only before a stable scanId is available.
 - `get_report` - Retrieve a summary Pulse report, including customer-safe no-go messaging when coverage is completed-limited. Use get_evidence for the larger bounded packet.
 - `get_evidence` - Retrieve the bounded structured Evidence JSON packet for a stable scan ID. Excludes raw cookie values, raw bodies, sensitive payloads, full DOM, and unredacted query values.
+- `get_scan_bundle` - Recommended second call after scan_site. Returns the canonical scan state, compact report summary, findings, bounded evidence summary, and pre-consent inventory in one agent-friendly response.
 - `export_findings` - Return structured findings plus completed-limited no-go disposition and guidance for downstream review or ticketing workflows.
 - `list_findings` - List API v2 public-safe findings already projected for a scan.
 - `get_pre_consent_cookies_trackers` - Retrieve the public-safe Cookies & Trackers (Pre-consent) report table as compact JSON for a scan.
@@ -59,6 +60,15 @@ https://certscore.ai/.well-known/oauth-authorization-server
 
 The hosted service uses OAuth authorization code with PKCE. Default read access requests `scan:read mcp`; support-gated scan creation additionally requests `scan:create`. The same tool implementation and output contracts power stdio and hosted transports.
 
+For low-volume agent discovery without account or OAuth setup, use the unauthenticated endpoint:
+
+```text
+https://mcp.certscore.ai/mcp/anonymous
+```
+
+It exposes the same public-safe tool surface and preserves the existing limit of 10 new scans per requester IP per UTC day. Reusing an
+eligible recent result does not consume the quota. Use the OAuth endpoint or a scoped API key for higher-volume workflows.
+
 ## Configuration
 
 Install with Homebrew on macOS:
@@ -124,9 +134,22 @@ Stdio API keys use `pulse:read` and `mcp`; creating scans additionally requires
 certscore-mcp --version
 certscore-mcp --help
 CERTSCORE_API_KEY=... certscore-mcp doctor
+CERTSCORE_API_KEY=... certscore-mcp doctor --check-auth
 ```
 
-The doctor command checks binary startup, version output, Node.js runtime compatibility, the configured CertScore base URL, API v2 health, and API key presence. It does not print secrets, create scans, or inspect raw scanner artifacts. There is no dedicated public auth-check endpoint; verify credentials with a real MCP tool call such as `scan_site` after the client is connected.
+The doctor command checks binary startup, version output, Node.js runtime compatibility, the configured CertScore base URL, API v2 health, and API key presence. Add `--check-auth` to validate the credential against `/api/v2/auth/check` without creating a scan. It does not print secrets or inspect raw scanner artifacts.
+
+## No-account agent scan path
+
+Agents that cannot create an account or configure OAuth can use the public API v2 scan path without an `Authorization` header:
+
+```bash
+curl -X POST https://certscore.ai/api/v2/scans \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://example.com","freshness":"latest","scanFrom":"eu_ie"}'
+```
+
+New anonymous scans are limited to 10 per requester IP per UTC day. Reusing an eligible recent result does not consume the quota. Poll the returned status resource, then retrieve findings or evidence. Use OAuth or a scoped API key for repeated or higher-volume workflows.
 
 ## MCP Client Examples
 
@@ -198,14 +221,16 @@ Local repo config for contributors:
 
 ## Agent Workflow
 
-1. Call `scan_site` with a public URL.
-2. If it returns a `jobId`, call `get_scan_status` until the scan completes.
-3. Call `get_scan` with the stable `scanId`.
-4. Call `list_findings` to route structured findings into review workflows.
-5. Call `get_evidence` when a reviewer or agent needs the larger bounded evidence packet.
-6. Call `get_pre_consent_cookies_trackers` when the user asks for Cookies & Trackers (Pre-consent) table data as JSON.
-7. Call `explain_finding` when a reviewer needs evidence and caveats for a specific finding.
-8. Call `get_latest_domain_scan` or `get_latest_domain_pre_consent_cookies_trackers` when the user asks for latest eligible public data for a domain.
+1. Call `scan_site` with a public URL. It normally returns the completed scan resource in the same tool call.
+2. Only if it returns a non-terminal job, call `get_scan_status` using the stable `scanId` until completion.
+3. Call `get_scan_bundle` for the normal compact review handoff.
+4. Call `get_report`, `get_evidence`, `list_findings`, or `get_pre_consent_cookies_trackers` only when the task needs a dedicated view.
+5. Call `explain_finding` when a reviewer needs evidence and caveats for a specific finding.
+6. Call `get_latest_domain_scan` or `get_latest_domain_pre_consent_cookies_trackers` when the user asks for latest eligible public data for a domain.
+
+`scan_site` reports whether the result was reused, why the freshness decision was made, whether anonymous quota was consumed, the remaining daily allowance, the UTC reset time, and the recommended next tool.
+
+With `freshness: "latest"`, CertScore reuses an eligible scan completed within the last 24 hours for the same normalized target and scan region. A reusable result must have completed usable page coverage and must not be an early-loss, no-page, or otherwise non-reusable limited result. Reuse does not consume anonymous quota. `freshnessDecision` states whether a recent result was reused or a new scan was queued; `reusedScanAgeSeconds` reports the reused result's age.
 
 ```json
 {

package/dist/certscore-mcp.mjs

@@ -15386,6 +15386,9 @@ var StdioServerTransport = class {
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
+// ../certscore-sdk/dist/client.js
+import { createHmac } from "node:crypto";
+
 // ../certscore-sdk/dist/errors.js
 var CertScoreError = class extends Error {
   status;
@@ -15587,6 +15590,9 @@ function isStatus(body) {
 var CertScoreClient = class {
   apiKey;
   baseUrl;
+  clientName;
+  forwardedClientIp;
+  anonymousRequesterSecret;
   timeout;
   scans;
   findings;
@@ -15596,6 +15602,9 @@ var CertScoreClient = class {
   constructor(options = {}) {
     this.apiKey = options.apiKey;
     this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    this.clientName = options.clientName ?? "sdk";
+    this.forwardedClientIp = options.forwardedClientIp?.trim() || void 0;
+    this.anonymousRequesterSecret = options.anonymousRequesterSecret?.trim() || void 0;
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
     this.scans = {
       create: (url2, scanOptions) => this.createScanResource(url2, scanOptions),
@@ -16002,7 +16011,8 @@ var CertScoreClient = class {
   }
   headers(jsonBody = false) {
     const headers = {
-      Accept: "application/json, text/markdown;q=0.9"
+      Accept: "application/json, text/markdown;q=0.9",
+      "X-CertScore-Client": this.clientName
     };
     if (jsonBody) {
       headers["Content-Type"] = "application/json; charset=utf-8";
@@ -16010,6 +16020,17 @@ var CertScoreClient = class {
     if (this.apiKey) {
       headers.Authorization = `Bearer ${this.apiKey}`;
     }
+    if (this.forwardedClientIp && !this.apiKey) {
+      headers["X-Forwarded-For"] = this.forwardedClientIp;
+      if (this.anonymousRequesterSecret) {
+        const timestamp = String(Math.floor(Date.now() / 1e3));
+        const message = `${timestamp}.${this.forwardedClientIp}`;
+        const proof = createHmac("sha256", this.anonymousRequesterSecret).update(message).digest("base64url");
+        headers["X-CertScore-Anonymous-Requester-IP"] = this.forwardedClientIp;
+        headers["X-CertScore-Anonymous-Requester-Timestamp"] = timestamp;
+        headers["X-CertScore-Anonymous-Requester-Proof"] = proof;
+      }
+    }
     return headers;
   }
   url(path) {
@@ -20253,6 +20274,14 @@ var pulseStatusSchema = external_exports2.object({
   resultUrl: external_exports2.string().nullable().optional(),
   reportUrl: external_exports2.string().nullable().optional(),
   retryAfterSeconds: external_exports2.number().int().nullable().optional(),
+  recovery: external_exports2.object({
+    alternateRegionAttempted: external_exports2.literal(true),
+    fallbackScanFrom: external_exports2.string(),
+    noGoReason: external_exports2.string(),
+    primaryScanFrom: external_exports2.string(),
+    primaryScanId: external_exports2.string(),
+    claimedAt: external_exports2.string()
+  }).passthrough().optional(),
   capabilities: pulseCapabilitiesSchema.optional(),
   agentInterpretation: pulseAgentInterpretationSchema.optional(),
   disclaimer: external_exports2.string().optional()
@@ -20295,6 +20324,17 @@ var apiV2PreConsentInventoryKindSchema = external_exports2.enum(["cookie", "trac
 var apiV2PreConsentInventoryPhaseSchema = external_exports2.literal("pre_consent");
 var apiV2PreConsentInventoryPrioritySchema = external_exports2.enum(["high", "medium", "review_needed", "contextual", "unknown"]);
 var apiV2PreConsentInventoryConfidenceSchema = external_exports2.enum(["high", "medium", "low", "unknown"]);
+var apiV2ScanCreationMetadataShape = {
+  executionMode: external_exports2.enum(["new_scan", "reused_scan"]).optional(),
+  reused: external_exports2.boolean().optional(),
+  reusedScanAgeSeconds: external_exports2.number().int().min(0).nullable().optional(),
+  freshnessDecision: external_exports2.string().optional(),
+  quotaConsumed: external_exports2.boolean().optional(),
+  anonymousQuotaLimit: external_exports2.number().int().min(0).nullable().optional(),
+  anonymousQuotaRemaining: external_exports2.number().int().min(0).nullable().optional(),
+  anonymousQuotaResetAt: external_exports2.string().nullable().optional(),
+  recommendedNextTool: external_exports2.enum(["get_scan_status", "get_scan_bundle"]).optional()
+};
 var apiV2LinksSchema = external_exports2.object({
   self: external_exports2.string().optional(),
   status: external_exports2.string().optional(),
@@ -20312,7 +20352,8 @@ var apiV2ErrorSchema = external_exports2.object({
     retryAfterSeconds: external_exports2.number().int().nullable().optional()
   }).passthrough(),
   links: apiV2LinksSchema.optional(),
-  disclaimer: external_exports2.string().optional()
+  disclaimer: external_exports2.string().optional(),
+  ...apiV2ScanCreationMetadataShape
 }).passthrough();
 var apiV2CreateScanRequestSchema = external_exports2.object({
   url: external_exports2.string().min(1),
@@ -20337,7 +20378,8 @@ var apiV2ScanJobSchema = external_exports2.object({
   lastUpdatedAt: external_exports2.string().optional(),
   retryAfterSeconds: external_exports2.number().int().nullable().optional(),
   links: apiV2LinksSchema.optional(),
-  disclaimer: external_exports2.string().optional()
+  disclaimer: external_exports2.string().optional(),
+  ...apiV2ScanCreationMetadataShape
 }).passthrough();
 var apiV2ScanResourceSchema = external_exports2.object({
   type: external_exports2.literal("certscore_scan"),
@@ -20526,6 +20568,13 @@ var mcpCreateScanInputSchema = {
   freshness: mcpPulseFreshnessSchema.optional().describe("Use latest to reuse recent scans or refresh to request a new scan when eligible."),
   scanFrom: mcpScanFromSchema.optional().describe("Optional scan execution context for newly queued scans.")
 };
+var mcpScanSiteInputSchema = {
+  url: mcpCreateScanInputSchema.url,
+  freshness: mcpCreateScanInputSchema.freshness,
+  scanFrom: mcpCreateScanInputSchema.scanFrom,
+  waitForCompletion: external_exports2.boolean().optional().describe("Wait for a completed scan resource in this tool call. Defaults to true. Set false only for an explicitly asynchronous workflow."),
+  maxWaitSeconds: external_exports2.number().int().min(1).max(45).optional().describe("Maximum time to wait before returning the still-running job. Defaults to 45 seconds; never turns an active scan into an error.")
+};
 var mcpGetScanStatusInputSchema = {
   jobId: external_exports2.string().min(1).optional().describe("Pulse job ID for a just-created scan that has not yet returned a scanId."),
   scanId: external_exports2.string().min(1).optional().describe("Preferred stable CertScore scan ID for API v2 scan status.")
@@ -20541,6 +20590,11 @@ var mcpGetReportInputSchema = {
 var mcpGetEvidenceInputSchema = {
   scanId: external_exports2.string().min(1).describe("Stable CertScore scan ID.")
 };
+var mcpGetScanBundleInputSchema = {
+  scanId: external_exports2.string().min(1).describe("Stable CertScore scan ID."),
+  maxFindings: external_exports2.number().int().min(1).max(50).optional().describe("Maximum compact findings to return. Defaults to 20."),
+  maxPreConsentRows: external_exports2.number().int().min(1).max(50).optional().describe("Maximum pre-consent inventory rows to return. Defaults to 20.")
+};
 var mcpExportFindingsInputSchema = {
   scanId: external_exports2.string().min(1).describe("Stable CertScore scan ID.")
 };
@@ -20634,6 +20688,21 @@ var mcpReportOutputSchema = external_exports2.object({
   noGo: scanNoGoResultSchema.optional(),
   value: external_exports2.string().optional()
 }).passthrough();
+var mcpScanBundleOutputSchema = external_exports2.object({
+  type: external_exports2.literal("certscore_scan_bundle"),
+  scanId: external_exports2.string(),
+  status: apiV2ScanStatusSchema,
+  resultDisposition: scanResultDispositionSchema.nullable().optional(),
+  noGo: scanNoGoResultSchema.nullable().optional(),
+  scan: apiV2ScanResourceSchema,
+  summary: external_exports2.unknown().nullable(),
+  findings: external_exports2.array(external_exports2.unknown()),
+  evidenceSummary: external_exports2.unknown().nullable(),
+  preConsentCookiesTrackers: external_exports2.unknown().nullable(),
+  links: external_exports2.record(external_exports2.string()).optional(),
+  recommendedNextTool: external_exports2.string().nullable(),
+  disclaimer: external_exports2.string().nullable()
+}).passthrough();
 var mcpFindingsExportOutputSchema = external_exports2.object({
   type: external_exports2.literal("certscore_mcp_findings_export"),
   scanId: external_exports2.string().nullable(),
@@ -20676,7 +20745,7 @@ var mcpPreConsentCookiesTrackersOutputSchema = apiV2PreConsentCookiesTrackersSch
 var certScoreMcpToolContracts = [
   {
     name: "create_scan",
-    title: "Create CertScore Pulse scan",
+    title: "Deprecated \u2014 Create CertScore Pulse scan",
     description: "Deprecated compatibility alias of scan_site. Use scan_site for new integrations. Returns completed-limited no-go disposition and reason-specific guidance when applicable.",
     inputSchema: mcpCreateScanInputSchema,
     outputSchema: mcpCreateScanOutputSchema,
@@ -20685,8 +20754,8 @@ var certScoreMcpToolContracts = [
   {
     name: "scan_site",
     title: "Scan site",
-    description: "Start or reuse a CertScore public-web scan. Completed no-go scans return completed_limited status, structured reason-specific guidance, and timing when available.",
-    inputSchema: mcpCreateScanInputSchema,
+    description: "Recommended first call. Starts or reuses a public-web scan, reports freshness and anonymous quota decisions, and waits up to 45 seconds by default. If still running, use get_scan_status; otherwise use get_scan_bundle. Completed no-go scans retain completed_limited status and reason-specific guidance.",
+    inputSchema: mcpScanSiteInputSchema,
     outputSchema: mcpScanSiteOutputSchema,
     annotations: scanCreationAnnotations
   },
@@ -20722,6 +20791,14 @@ var certScoreMcpToolContracts = [
     outputSchema: pulseResponseSchema,
     annotations: readOnlyOpenWorldAnnotations
   },
+  {
+    name: "get_scan_bundle",
+    title: "Get compact CertScore scan bundle",
+    description: "Recommended second call after scan_site. Returns the canonical scan state, compact report summary, findings, bounded evidence summary, and pre-consent inventory in one agent-friendly response.",
+    inputSchema: mcpGetScanBundleInputSchema,
+    outputSchema: mcpScanBundleOutputSchema,
+    annotations: readOnlyOpenWorldAnnotations
+  },
   {
     name: "export_findings",
     title: "Export CertScore findings",
@@ -32665,28 +32742,23 @@ function toToolResult(payload) {
   };
 }
 function toToolError(error2) {
-  if (error2 instanceof CertScoreError) {
-    return {
-      ...toToolResult({
-        error: {
-          name: error2.name,
-          message: error2.message,
-          status: error2.status,
-          code: error2.code,
-          retryAfterSeconds: "retryAfterSeconds" in error2 ? error2.retryAfterSeconds : void 0,
-          responseBody: truncateErrorResponseBody(error2.responseBody)
-        }
-      }),
-      isError: true
-    };
-  }
+  const payload = error2 instanceof CertScoreError ? {
+    error: {
+      name: error2.name,
+      message: error2.message,
+      status: error2.status,
+      code: error2.code,
+      retryAfterSeconds: "retryAfterSeconds" in error2 ? error2.retryAfterSeconds : void 0,
+      responseBody: truncateErrorResponseBody(error2.responseBody)
+    }
+  } : {
+    error: {
+      name: error2 instanceof Error ? error2.name : "Error",
+      message: error2 instanceof Error ? error2.message : "Unknown CertScore MCP error."
+    }
+  };
   return {
-    ...toToolResult({
-      error: {
-        name: error2 instanceof Error ? error2.name : "Error",
-        message: error2 instanceof Error ? error2.message : "Unknown CertScore MCP error."
-      }
-    }),
+    content: [{ type: "text", text: JSON.stringify(payload) }],
     isError: true
   };
 }
@@ -32939,6 +33011,71 @@ function limitPreConsentRows(payload, options = {}) {
     }
   };
 }
+function buildScanBundle(input) {
+  const maxFindings = Math.min(50, Math.max(1, input.maxFindings ?? 20));
+  const maxPreConsentRows = Math.min(50, Math.max(1, input.maxPreConsentRows ?? 20));
+  const evidence = input.evidence;
+  const report = input.report;
+  const findings = Array.isArray(input.findings.findings) ? input.findings.findings.slice(0, maxFindings) : [];
+  const preConsentRows = Array.isArray(input.preConsentCookiesTrackers.rows) ? input.preConsentCookiesTrackers.rows.slice(0, maxPreConsentRows) : [];
+  const links = {
+    ...input.scan.links ?? {},
+    ...report.links && typeof report.links === "object" && !Array.isArray(report.links) ? report.links : {}
+  };
+  return {
+    type: "certscore_scan_bundle",
+    scanId: input.scan.scanId,
+    status: input.scan.status,
+    resultDisposition: input.scan.resultDisposition ?? null,
+    noGo: input.scan.noGo ?? null,
+    scan: input.scan,
+    summary: {
+      summary: report.summary ?? null,
+      executiveSummary: report.executiveSummary ?? null,
+      counts: report.counts ?? null,
+      coverage: report.coverage ?? input.scan.coverage ?? null,
+      agentInterpretation: report.agentInterpretation ?? null
+    },
+    findings,
+    findingsMetadata: {
+      shown: findings.length,
+      total: Array.isArray(input.findings.findings) ? input.findings.findings.length : 0,
+      truncated: Array.isArray(input.findings.findings) && input.findings.findings.length > findings.length
+    },
+    evidenceSummary: {
+      evidenceSafetyNotes: evidence.evidenceSafetyNotes ?? null,
+      projectionDiagnostics: evidence.projectionDiagnostics ?? null,
+      projectedFindings: compactEvidenceValue(evidence.projectedFindings ?? [], {
+        arrayItems: maxFindings,
+        depth: 5,
+        objectKeys: 40,
+        stringChars: 1e3
+      }),
+      coverageDiagnostics: compactEvidenceValue(evidence.coverageDiagnostics ?? null, {
+        arrayItems: 20,
+        depth: 5,
+        objectKeys: 40,
+        stringChars: 1e3
+      }),
+      policySurfaceCoverage: compactEvidenceValue(evidence.policySurfaceCoverage ?? null, {
+        arrayItems: 20,
+        depth: 5,
+        objectKeys: 40,
+        stringChars: 1e3
+      })
+    },
+    preConsentCookiesTrackers: {
+      summary: input.preConsentCookiesTrackers.summary,
+      rows: preConsentRows,
+      shown: preConsentRows.length,
+      total: Array.isArray(input.preConsentCookiesTrackers.rows) ? input.preConsentCookiesTrackers.rows.length : 0,
+      truncated: Array.isArray(input.preConsentCookiesTrackers.rows) && input.preConsentCookiesTrackers.rows.length > preConsentRows.length
+    },
+    links,
+    recommendedNextTool: findings.length > 0 ? "explain_finding" : null,
+    disclaimer: input.scan.disclaimer ?? input.report.disclaimer ?? null
+  };
+}
 function explainFinding(report, findingId) {
   const finding = findingsFromReport(report).find((candidate) => candidate.id === findingId);
   if (!finding) {
@@ -32976,6 +33113,19 @@ function explainFinding(report, findingId) {
 
 // src/server.ts
 var createScanDeprecationWarningPrinted = false;
+var DEFAULT_MCP_SCAN_WAIT_MS = 45e3;
+function scanCreationMetadata(value) {
+  return {
+    executionMode: value.executionMode,
+    reused: value.reused,
+    reusedScanAgeSeconds: value.reusedScanAgeSeconds,
+    freshnessDecision: value.freshnessDecision,
+    quotaConsumed: value.quotaConsumed,
+    anonymousQuotaLimit: value.anonymousQuotaLimit,
+    anonymousQuotaRemaining: value.anonymousQuotaRemaining,
+    anonymousQuotaResetAt: value.anonymousQuotaResetAt
+  };
+}
 function toolContract(name) {
   const contract = certScoreMcpToolContracts.find((candidate) => candidate.name === name);
   if (!contract) {
@@ -32993,6 +33143,9 @@ function createCertScoreMcpServer(options = {}) {
   const client = new CertScoreClient({
     apiKey: options.apiKey,
     baseUrl: options.baseUrl,
+    clientName: "mcp",
+    forwardedClientIp: options.forwardedClientIp,
+    anonymousRequesterSecret: options.anonymousRequesterSecret,
     timeout: options.timeout
   });
   const server = new McpServer({
@@ -33028,7 +33181,7 @@ function createCertScoreMcpServer(options = {}) {
       try {
         if (!createScanDeprecationWarningPrinted) {
           createScanDeprecationWarningPrinted = true;
-          console.error("[certscore-mcp] create_scan is deprecated and will be removed in 0.2.0. Use scan_site.");
+          console.error("[certscore-mcp] create_scan is deprecated in the 0.2.x line. Use scan_site for new integrations.");
         }
         return toToolResult(await createPulseScanTool(input));
       } catch (error2) {
@@ -33041,12 +33194,36 @@ function createCertScoreMcpServer(options = {}) {
     toolContract("scan_site"),
     async (input) => {
       try {
-        return toToolResult(
-          await client.scans.create(input.url, {
-            freshness: input.freshness ?? "latest",
-            scanFrom: input.scanFrom
-          })
-        );
+        const created = await client.scans.create(input.url, {
+          freshness: input.freshness ?? "latest",
+          scanFrom: input.scanFrom
+        });
+        if (input.waitForCompletion === false || created.type === "certscore_scan") {
+          return toToolResult(created);
+        }
+        try {
+          const completed = await client.scans.wait(created, {
+            maxWaitMs: Math.min(input.maxWaitSeconds ? input.maxWaitSeconds * 1e3 : DEFAULT_MCP_SCAN_WAIT_MS, DEFAULT_MCP_SCAN_WAIT_MS)
+          });
+          return toToolResult({
+            ...completed,
+            ...scanCreationMetadata(created),
+            recommendedNextTool: "get_scan_bundle"
+          });
+        } catch (error2) {
+          if (!(error2 instanceof CertScoreTimeoutError)) {
+            throw error2;
+          }
+          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);
+        }
       } catch (error2) {
         return toToolError(error2);
       }
@@ -33069,7 +33246,27 @@ function createCertScoreMcpServer(options = {}) {
     async ({ jobId, scanId }) => {
       try {
         if (scanId) {
-          return toToolResult(await client.scans.status(scanId));
+          const status2 = await client.scans.status(scanId);
+          const needsTerminalHydration = status2.status === "completed" || status2.status === "completed_limited";
+          if (needsTerminalHydration) {
+            try {
+              const scan = await client.scans.get(scanId);
+              return toToolResult({
+                ...status2,
+                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 {
+            }
+          }
+          return toToolResult(status2);
         }
         if (!jobId) {
           return toToolResult({
@@ -33119,6 +33316,32 @@ function createCertScoreMcpServer(options = {}) {
       }
     }
   );
+  registerTool(
+    "get_scan_bundle",
+    toolContract("get_scan_bundle"),
+    async ({ scanId, maxFindings, maxPreConsentRows }) => {
+      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)
+        ]);
+        return toToolResult(buildScanBundle({
+          evidence,
+          findings,
+          maxFindings,
+          maxPreConsentRows,
+          preConsentCookiesTrackers,
+          report,
+          scan
+        }));
+      } catch (error2) {
+        return toToolError(error2);
+      }
+    }
+  );
   registerTool(
     "export_findings",
     toolContract("export_findings"),
@@ -33218,12 +33441,13 @@ async function main() {
       "",
       "Usage:",
       "  certscore-mcp",
-      "  certscore-mcp doctor"
+      "  certscore-mcp doctor",
+      "  certscore-mcp doctor --check-auth"
     ].join("\n"));
     return;
   }
   if (process.argv.includes("doctor")) {
-    const result = await getCertScoreMcpDoctorReport();
+    const result = await getCertScoreMcpDoctorReport({ checkAuth: process.argv.includes("--check-auth") });
     console.log(result.lines.join("\n"));
     process.exitCode = result.exitCode;
     return;
@@ -33279,10 +33503,41 @@ async function getCertScoreMcpDoctorReport(options = {}) {
   }
   if (env.CERTSCORE_API_KEY?.trim()) {
     lines.push("[ok] CERTSCORE_API_KEY is present");
-    lines.push("[info] No dedicated auth-check endpoint is exposed; verify credentials with a real MCP tool call such as scan_site.");
+    if (options.checkAuth) {
+      if (!healthUrl) {
+        lines.push("[error] Cannot check credentials until CERTSCORE_BASE_URL is valid");
+        exitCode = 1;
+      } else {
+        const authUrl = new URL("/api/v2/auth/check", healthUrl.origin);
+        try {
+          const response = await fetchImpl(authUrl, {
+            headers: {
+              accept: "application/json",
+              authorization: `Bearer ${env.CERTSCORE_API_KEY.trim()}`
+            },
+            signal: AbortSignal.timeout(1e4)
+          });
+          if (response.ok) {
+            lines.push(`[ok] API key authenticated at ${authUrl.href}`);
+          } else {
+            lines.push(`[error] API key rejected with HTTP ${response.status} at ${authUrl.href}`);
+            exitCode = 1;
+          }
+        } catch (error2) {
+          const message = error2 instanceof Error && error2.message ? error2.message : "request failed";
+          lines.push(`[error] API key check failed at ${authUrl.href}: ${message}`);
+          exitCode = 1;
+        }
+      }
+    } else {
+      lines.push("[info] Run certscore-mcp doctor --check-auth to verify the credential without creating a scan.");
+    }
   } else {
     lines.push("[warn] CERTSCORE_API_KEY is not set");
-    lines.push("[info] Set CERTSCORE_API_KEY before connecting an MCP client or calling authenticated tools.");
+    lines.push(options.checkAuth ? "[error] --check-auth requires CERTSCORE_API_KEY." : "[info] Set CERTSCORE_API_KEY before connecting an MCP client or calling authenticated tools.");
+    if (options.checkAuth) {
+      exitCode = 1;
+    }
   }
   lines.push("CertScore outputs are automated public-web observations for review, not legal advice, certification, or a compliance determination.");
   return { exitCode, lines };

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { createCertScoreMcpServer } from "./server.js";
 export { explainFinding, exportFindings, findingsFromReport } from "./tools.js";
 export { CERTSCORE_MCP_VERSION } from "./version.js";
 export interface CertScoreMcpDoctorOptions {
+    checkAuth?: boolean;
     env?: Record<string, string | undefined>;
     fetch?: typeof fetch;
     nodeVersion?: string;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAMrD,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA+CD,wBAAsB,2BAA2B,CAAC,OAAO,GAAE,yBAA8B;;;GA0DxF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAMrD,MAAM,WAAW,yBAAyB;IACxC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAgDD,wBAAsB,2BAA2B,CAAC,OAAO,GAAE,yBAA8B;;;GAyFxF"}

package/dist/index.js

@@ -34,12 +34,13 @@ async function main() {
             "",
             "Usage:",
             "  certscore-mcp",
-            "  certscore-mcp doctor"
+            "  certscore-mcp doctor",
+            "  certscore-mcp doctor --check-auth"
         ].join("\n"));
         return;
     }
     if (process.argv.includes("doctor")) {
-        const result = await getCertScoreMcpDoctorReport();
+        const result = await getCertScoreMcpDoctorReport({ checkAuth: process.argv.includes("--check-auth") });
         console.log(result.lines.join("\n"));
         process.exitCode = result.exitCode;
         return;
@@ -99,11 +100,46 @@ export async function getCertScoreMcpDoctorReport(options = {}) {
     }
     if (env.CERTSCORE_API_KEY?.trim()) {
         lines.push("[ok] CERTSCORE_API_KEY is present");
-        lines.push("[info] No dedicated auth-check endpoint is exposed; verify credentials with a real MCP tool call such as scan_site.");
+        if (options.checkAuth) {
+            if (!healthUrl) {
+                lines.push("[error] Cannot check credentials until CERTSCORE_BASE_URL is valid");
+                exitCode = 1;
+            }
+            else {
+                const authUrl = new URL("/api/v2/auth/check", healthUrl.origin);
+                try {
+                    const response = await fetchImpl(authUrl, {
+                        headers: {
+                            accept: "application/json",
+                            authorization: `Bearer ${env.CERTSCORE_API_KEY.trim()}`
+                        },
+                        signal: AbortSignal.timeout(10_000)
+                    });
+                    if (response.ok) {
+                        lines.push(`[ok] API key authenticated at ${authUrl.href}`);
+                    }
+                    else {
+                        lines.push(`[error] API key rejected with HTTP ${response.status} at ${authUrl.href}`);
+                        exitCode = 1;
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error && error.message ? error.message : "request failed";
+                    lines.push(`[error] API key check failed at ${authUrl.href}: ${message}`);
+                    exitCode = 1;
+                }
+            }
+        }
+        else {
+            lines.push("[info] Run certscore-mcp doctor --check-auth to verify the credential without creating a scan.");
+        }
     }
     else {
         lines.push("[warn] CERTSCORE_API_KEY is not set");
-        lines.push("[info] Set CERTSCORE_API_KEY before connecting an MCP client or calling authenticated tools.");
+        lines.push(options.checkAuth ? "[error] --check-auth requires CERTSCORE_API_KEY." : "[info] Set CERTSCORE_API_KEY before connecting an MCP client or calling authenticated tools.");
+        if (options.checkAuth) {
+            exitCode = 1;
+        }
     }
     lines.push("CertScore outputs are automated public-web observations for review, not legal advice, certification, or a compliance determination.");
     return { exitCode, lines };

package/dist/server.d.ts

@@ -2,6 +2,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export interface CertScoreMcpOptions {
     apiKey?: string;
     baseUrl?: string;
+    forwardedClientIp?: string | null;
+    anonymousRequesterSecret?: string | null;
     timeout?: number;
 }
 export declare function createCertScoreMcpServer(options?: CertScoreMcpOptions): McpServer;

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,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqCD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,aAwNzE"}
+{"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;CAClB;AAsDD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,aAoSzE"}

package/dist/server.js

@@ -1,9 +1,22 @@
-import { CertScoreClient } from "@certscore/sdk";
+import { CertScoreClient, CertScoreTimeoutError } from "@certscore/sdk";
 import { certScoreMcpToolContracts } from "@certscore/api-contracts";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CERTSCORE_MCP_VERSION } from "./version.js";
-import { boundEvidencePacket, exportFindings, limitPreConsentRows, normalizeDetail, normalizeFormat, paginateFindingList, scanIdFromStatus, toToolError, toToolResult } from "./tools.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;
+function scanCreationMetadata(value) {
+    return {
+        executionMode: value.executionMode,
+        reused: value.reused,
+        reusedScanAgeSeconds: value.reusedScanAgeSeconds,
+        freshnessDecision: value.freshnessDecision,
+        quotaConsumed: value.quotaConsumed,
+        anonymousQuotaLimit: value.anonymousQuotaLimit,
+        anonymousQuotaRemaining: value.anonymousQuotaRemaining,
+        anonymousQuotaResetAt: value.anonymousQuotaResetAt
+    };
+}
 function toolContract(name) {
     const contract = certScoreMcpToolContracts.find((candidate) => candidate.name === name);
     if (!contract) {
@@ -21,6 +34,9 @@ export function createCertScoreMcpServer(options = {}) {
     const client = new CertScoreClient({
         apiKey: options.apiKey,
         baseUrl: options.baseUrl,
+        clientName: "mcp",
+        forwardedClientIp: options.forwardedClientIp,
+        anonymousRequesterSecret: options.anonymousRequesterSecret,
         timeout: options.timeout
     });
     const server = new McpServer({
@@ -53,7 +69,7 @@ export function createCertScoreMcpServer(options = {}) {
         try {
             if (!createScanDeprecationWarningPrinted) {
                 createScanDeprecationWarningPrinted = true;
-                console.error("[certscore-mcp] create_scan is deprecated and will be removed in 0.2.0. Use scan_site.");
+                console.error("[certscore-mcp] create_scan is deprecated in the 0.2.x line. Use scan_site for new integrations.");
             }
             return toToolResult(await createPulseScanTool(input));
         }
@@ -63,10 +79,37 @@ export function createCertScoreMcpServer(options = {}) {
     });
     registerTool("scan_site", toolContract("scan_site"), async (input) => {
         try {
-            return toToolResult(await client.scans.create(input.url, {
+            const created = await client.scans.create(input.url, {
                 freshness: input.freshness ?? "latest",
                 scanFrom: input.scanFrom
-            }));
+            });
+            if (input.waitForCompletion === false || created.type === "certscore_scan") {
+                return toToolResult(created);
+            }
+            try {
+                const completed = await client.scans.wait(created, {
+                    maxWaitMs: Math.min(input.maxWaitSeconds ? input.maxWaitSeconds * 1_000 : DEFAULT_MCP_SCAN_WAIT_MS, DEFAULT_MCP_SCAN_WAIT_MS)
+                });
+                return toToolResult({
+                    ...completed,
+                    ...scanCreationMetadata(created),
+                    recommendedNextTool: "get_scan_bundle"
+                });
+            }
+            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);
+            }
         }
         catch (error) {
             return toToolError(error);
@@ -83,7 +126,30 @@ export function createCertScoreMcpServer(options = {}) {
     registerTool("get_scan_status", toolContract("get_scan_status"), async ({ jobId, scanId }) => {
         try {
             if (scanId) {
-                return toToolResult(await client.scans.status(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({
@@ -129,6 +195,29 @@ export function createCertScoreMcpServer(options = {}) {
             return toToolError(error);
         }
     });
+    registerTool("get_scan_bundle", toolContract("get_scan_bundle"), async ({ scanId, maxFindings, maxPreConsentRows }) => {
+        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)
+            ]);
+            return toToolResult(buildScanBundle({
+                evidence,
+                findings,
+                maxFindings,
+                maxPreConsentRows,
+                preConsentCookiesTrackers,
+                report,
+                scan
+            }));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
     registerTool("export_findings", toolContract("export_findings"), async ({ scanId }) => {
         try {
             const report = await client.getScan(scanId, { detail: "full", format: "json" });

package/dist/tools.d.ts

@@ -1,5 +1,5 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { type JobStatus, type PulseDetail, type PulseFormat, type PulseResult, type TopFinding } from "@certscore/sdk";
+import { type FindingList, type JobStatus, type PreConsentCookiesTrackers, type PulseDetail, type PulseFormat, type PulseResult, type ScanResource, type TopFinding } from "@certscore/sdk";
 export declare const MAX_EVIDENCE_PACKET_CHARS = 250000;
 export declare function toToolResult(payload: unknown): CallToolResult;
 export declare function toToolError(error: unknown): CallToolResult;
@@ -37,6 +37,69 @@ export declare function paginateFindingList<T extends Record<string, unknown>>(p
 export declare function limitPreConsentRows<T extends Record<string, unknown>>(payload: T, options?: {
     maxRows?: number;
 }): T;
+export declare function buildScanBundle(input: {
+    evidence: PulseResult;
+    findings: FindingList;
+    maxFindings?: number;
+    maxPreConsentRows?: number;
+    preConsentCookiesTrackers: PreConsentCookiesTrackers;
+    report: PulseResult;
+    scan: ScanResource;
+}): {
+    type: string;
+    scanId: string;
+    status: import("packages/certscore-sdk/dist/types.js").PulseJobStatus;
+    resultDisposition: "no_go" | null;
+    noGo: import("@certscore/sdk").ScanNoGoResult | null;
+    scan: ScanResource;
+    summary: {
+        summary: {} | null;
+        executiveSummary: {} | null;
+        counts: {} | null;
+        coverage: {} | null;
+        agentInterpretation: {} | null;
+    };
+    findings: import("packages/certscore-sdk/dist/types.js").FindingSummary[];
+    findingsMetadata: {
+        shown: number;
+        total: number;
+        truncated: boolean;
+    };
+    evidenceSummary: {
+        evidenceSafetyNotes: {} | null;
+        projectionDiagnostics: {} | null;
+        projectedFindings: unknown;
+        coverageDiagnostics: unknown;
+        policySurfaceCoverage: unknown;
+    };
+    preConsentCookiesTrackers: {
+        summary: {
+            [key: string]: unknown;
+            rowCount: number;
+            trackerCount: number;
+            cookieCount: number;
+            requestCount: number;
+            totalRowCount?: number;
+            truncated?: boolean;
+        };
+        rows: import("packages/certscore-sdk/dist/types.js").PreConsentCookiesTrackersRow[];
+        shown: number;
+        total: number;
+        truncated: boolean;
+    };
+    links: {
+        [key: string]: string | undefined;
+        self?: string;
+        status?: string;
+        findings?: string;
+        pulse?: string;
+        report?: string;
+        latestDomainScan?: string;
+        docs?: string;
+    };
+    recommendedNextTool: string | null;
+    disclaimer: string | null;
+};
 export declare function explainFinding(report: PulseResult, findingId: string): {
     type: string;
     scanId: string | null;

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAkB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGvI,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAKjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAa7D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAyB1D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,kBAAkB,SAA4B,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0C9H;AA6ID,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAE5E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAE5E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,iBAEjD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,iBAGlD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,EAAE,CAQpE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW;;;;;;;;;;;;;;;;;;;;EAsBjD;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,OAAO,EAAE,CAAC,EACV,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,CAAC,CAoBH;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,OAAO,EAAE,CAAC,EACV,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,CAAC,CAiBH;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCpE"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAkB,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,yBAAyB,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAG5M,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAKjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAa7D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA0B1D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,kBAAkB,SAA4B,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0C9H;AA6ID,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAE5E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAE5E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,iBAEjD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,iBAGlD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,EAAE,CAQpE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW;;;;;;;;;;;;;;;;;;;;EAsBjD;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,OAAO,EAAE,CAAC,EACV,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,CAAC,CAoBH;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,OAAO,EAAE,CAAC,EACV,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,CAAC,CAiBH;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,QAAQ,EAAE,WAAW,CAAC;IACtB,QAAQ,EAAE,WAAW,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yBAAyB,EAAE,yBAAyB,CAAC;IACrD,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;CACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmEA;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCpE"}

package/dist/tools.js

@@ -19,28 +19,28 @@ export function toToolResult(payload) {
     };
 }
 export function toToolError(error) {
-    if (error instanceof CertScoreError) {
-        return {
-            ...toToolResult({
-                error: {
-                    name: error.name,
-                    message: error.message,
-                    status: error.status,
-                    code: error.code,
-                    retryAfterSeconds: "retryAfterSeconds" in error ? error.retryAfterSeconds : undefined,
-                    responseBody: truncateErrorResponseBody(error.responseBody)
-                }
-            }),
-            isError: true
-        };
-    }
-    return {
-        ...toToolResult({
+    const payload = error instanceof CertScoreError
+        ? {
+            error: {
+                name: error.name,
+                message: error.message,
+                status: error.status,
+                code: error.code,
+                retryAfterSeconds: "retryAfterSeconds" in error ? error.retryAfterSeconds : undefined,
+                responseBody: truncateErrorResponseBody(error.responseBody)
+            }
+        }
+        : {
             error: {
                 name: error instanceof Error ? error.name : "Error",
                 message: error instanceof Error ? error.message : "Unknown CertScore MCP error."
             }
-        }),
+        };
+    // MCP validates structuredContent against the tool's success output schema,
+    // including for isError results. Keep errors in text content so a bounded
+    // error envelope cannot be rejected as an invalid success resource.
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload) }],
         isError: true
     };
 }
@@ -297,6 +297,73 @@ export function limitPreConsentRows(payload, options = {}) {
         }
     };
 }
+export function buildScanBundle(input) {
+    const maxFindings = Math.min(50, Math.max(1, input.maxFindings ?? 20));
+    const maxPreConsentRows = Math.min(50, Math.max(1, input.maxPreConsentRows ?? 20));
+    const evidence = input.evidence;
+    const report = input.report;
+    const findings = Array.isArray(input.findings.findings) ? input.findings.findings.slice(0, maxFindings) : [];
+    const preConsentRows = Array.isArray(input.preConsentCookiesTrackers.rows)
+        ? input.preConsentCookiesTrackers.rows.slice(0, maxPreConsentRows)
+        : [];
+    const links = {
+        ...(input.scan.links ?? {}),
+        ...(report.links && typeof report.links === "object" && !Array.isArray(report.links) ? report.links : {})
+    };
+    return {
+        type: "certscore_scan_bundle",
+        scanId: input.scan.scanId,
+        status: input.scan.status,
+        resultDisposition: input.scan.resultDisposition ?? null,
+        noGo: input.scan.noGo ?? null,
+        scan: input.scan,
+        summary: {
+            summary: report.summary ?? null,
+            executiveSummary: report.executiveSummary ?? null,
+            counts: report.counts ?? null,
+            coverage: report.coverage ?? input.scan.coverage ?? null,
+            agentInterpretation: report.agentInterpretation ?? null
+        },
+        findings,
+        findingsMetadata: {
+            shown: findings.length,
+            total: Array.isArray(input.findings.findings) ? input.findings.findings.length : 0,
+            truncated: Array.isArray(input.findings.findings) && input.findings.findings.length > findings.length
+        },
+        evidenceSummary: {
+            evidenceSafetyNotes: evidence.evidenceSafetyNotes ?? null,
+            projectionDiagnostics: evidence.projectionDiagnostics ?? null,
+            projectedFindings: compactEvidenceValue(evidence.projectedFindings ?? [], {
+                arrayItems: maxFindings,
+                depth: 5,
+                objectKeys: 40,
+                stringChars: 1_000
+            }),
+            coverageDiagnostics: compactEvidenceValue(evidence.coverageDiagnostics ?? null, {
+                arrayItems: 20,
+                depth: 5,
+                objectKeys: 40,
+                stringChars: 1_000
+            }),
+            policySurfaceCoverage: compactEvidenceValue(evidence.policySurfaceCoverage ?? null, {
+                arrayItems: 20,
+                depth: 5,
+                objectKeys: 40,
+                stringChars: 1_000
+            })
+        },
+        preConsentCookiesTrackers: {
+            summary: input.preConsentCookiesTrackers.summary,
+            rows: preConsentRows,
+            shown: preConsentRows.length,
+            total: Array.isArray(input.preConsentCookiesTrackers.rows) ? input.preConsentCookiesTrackers.rows.length : 0,
+            truncated: Array.isArray(input.preConsentCookiesTrackers.rows) && input.preConsentCookiesTrackers.rows.length > preConsentRows.length
+        },
+        links,
+        recommendedNextTool: findings.length > 0 ? "explain_finding" : null,
+        disclaimer: input.scan.disclaimer ?? input.report.disclaimer ?? null
+    };
+}
 export function explainFinding(report, findingId) {
     const finding = findingsFromReport(report).find((candidate) => candidate.id === findingId);
     if (!finding) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@certscore/mcp",
-  "version": "0.2.6",
+  "version": "0.2.11",
   "mcpName": "ai.certscore/mcp",
   "private": false,
   "description": "MCP server for CertScore public website risk-signal workflows.",

package/server.json

@@ -7,13 +7,13 @@
     "url": "https://github.com/ergoveritas1-alt/certscore.ai",
     "source": "github"
   },
-  "version": "0.2.6",
+  "version": "0.2.11",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@certscore/mcp",
-      "version": "0.2.6",
+      "version": "0.2.11",
       "transport": {
         "type": "stdio"
       },