@certscore/mcp 0.2.15 → 0.2.16

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.15 reserves the first compact finding and evidence digest before optional detail inside small byte budgets, returns typed validation details, and makes every omission recoverable. Local WC01 development uses `pnpm mcp:certscore`.
+Status: public developer preview. Version 0.2.16 makes confirmed Reject Path outcomes explicit through typed verdict and intentional-termination metadata, direct MCP TextContent, and separately scoped coverage limitations. Local WC01 development uses `pnpm mcp:certscore`.
 
 Public docs:
 
@@ -10,6 +10,8 @@ Public docs:
 - https://certscore.ai/developers/quickstart
 - https://certscore.ai/developers/reference
 - https://certscore.ai/api-pulse
+- [MCP Light installation and agent reference](../../docs/mcp-light-install.md)
+- [MCP Light marketplace workflow assets](../../docs/mcp-light-marketplace-assets.md)
 
 ## Light MCP — no authentication: start here
 
@@ -23,7 +25,9 @@ Authentication: None
 Tools: certscore_scan_site, certscore_get_scan_status, certscore_get_scan_bundle
 ```
 
-No signup, API key, bearer token, browser login, or OAuth is required. Light allows 20 new scans per requester IP per UTC day. Reused eligible results do not consume quota.
+No signup, API key, bearer token, browser login, or OAuth is required. Light allows up to 50 genuinely new scans per UTC day across the public Light surface and up to 5 per rolling 10 minutes, with additional IP/provider safeguards. Reused eligible results do not consume quota.
+
+Light is a free website privacy scanner and cookie checker for public websites. It can return canonical evidence and findings for pre-consent cookies and storage, trackers and vendors, cookie banners, CMP and consent controls, privacy-policy and transparency surfaces, GDPR/ePrivacy and CCPA/CPRA review signals, and HTTPS/TLS transport observations. Typical uses include release privacy preflight, public vendor-domain review, landing-page tracker inspection, audit triage, and evidence collection before human privacy review.
 
 Codex setup:
 
@@ -49,7 +53,7 @@ Canonical Light workflow:
 8. If truncated, follow `recommendedNextAction` or increase `maxBytes`.
 9. Summarize findings together with coverage limitations and the report URL.
 
-Recommended bundle budgets are `maxBytes=5000` for `summary`, `maxBytes=8000` for `findings`, `maxBytes=8000` for `evidence`, and `maxBytes=12000` or higher for `full`. A 5,000-byte response may intentionally omit optional sections while still returning a compact finding or evidence reference when available. Inspect `actualBytes`, `truncated`, `omittedSections`, `nextRecommendedMaxBytes`, and returned report or evidence content URLs.
+Recommended bundle budgets are `maxBytes=5000` for `summary`, `maxBytes=8000` for `findings`, `maxBytes=8000` for `evidence`, and `maxBytes=12000` to `25000` for `full`. MCP Light applies a 25,000-byte response ceiling so results remain within practical client limits; larger requested budgets are reported but clamped. At the 5,000-byte floor, compact core finding rows take priority over optional inventory and duplicate envelope fields. When repeated per-finding URLs are omitted, `evidenceUrlTemplate` points to `contentUrls.findings` and the returned finding ID so the same canonical evidence endpoint remains derivable. Inspect `canonicalFindingsComplete`, `requestedMaxBytes`, `effectiveMaxBytes`, `responseCeilingBytes`, `actualBytes`, `fullPayloadBytes`, `truncated`, `omittedSections`, `nextRecommendedMaxBytes`, and returned report or evidence content URLs. When `canonicalFindingsComplete` is true, retry only if omitted envelope detail is needed.
 
 Verification prompt:
 
@@ -59,11 +63,13 @@ Success means the tool list contains exactly the three Light tools, no authoriza
 
 CertScore results are automated observations from a public-web scan. No-go, not-observed, and limited-coverage results are not proof of compliance, absence of risk, or legal status. Review the retained evidence and applicable context before relying on a finding.
 
+Scans describe observable behavior at a point in time. Public sites may behave differently on later visits or in another execution context. CertScore findings and the CertScore score support human and agentic review; they are not legal advice, certification, or a compliance determination.
+
 ## Which MCP route should I use?
 
 | Route | Access | Best for |
 | --- | --- | --- |
-| Light MCP — no authentication | No account, API key, bearer token, browser login, or OAuth; three tools; 20 new scans per requester IP per UTC day | First-time users, testing, and discovery |
+| Light MCP — no authentication | No account, API key, bearer token, browser login, or OAuth; three tools; up to 50 new scans per UTC day across Light and 5 per rolling 10 minutes; eligible reuse is free | First-time users, testing, and discovery |
 | Hosted MCP — OAuth | Hosted Streamable HTTP with OAuth scopes, higher volume, history, and approved advanced tools | Production, team, and managed remote clients |
 | Local MCP — scoped API key | Local stdio with a scoped key and tools allowed by its scopes | Backend, local, and controlled automation workflows |
 
@@ -75,18 +81,24 @@ MCP scan-resource reads use the same weighted, rolling policy as the direct Cert
 
 ## Tools
 
-- `certscore_scan_site` - First call. Starts or reuses a public-web scan and waits up to 45 seconds by default. If status is queued, running, or finalizing, retain scanId and poll certscore_get_scan_status using only that scanId. Stop polling at completed, completed_limited, failed, expired, or rate_limited. For usable completion, call certscore_get_scan_bundle. No-go and limited coverage are observations, never proof of compliance.
+- `certscore_scan_site` - Use CertScore.ai to scan a public website for observable privacy and consent signals, including pre-consent cookies and browser storage, third-party trackers, consent-banner and CMP behavior, TLS/transport security, privacy-policy disclosures, GDPR/ePrivacy transparency findings, and applicable CCPA/CPRA review signals. Starts or reuses a public-web scan with a 25-second total tool-call budget by default; scan creation time is deducted from completion waiting. If status is queued, running, or finalizing, retain scanId and poll certscore_get_scan_status using only that scanId. Stop polling at completed, completed_limited, failed, expired, or rate_limited. For usable completion, call certscore_get_scan_bundle. No-go and limited coverage are observations, never proof of compliance.
 - `certscore_get_scan` - Retrieve the API v2 public-safe scan resource, including completed-limited no-go disposition, reason-specific guidance, and timing when available.
-- `certscore_get_scan_status` - Poll with only the stable scanId returned by certscore_scan_site. Active responses include phase, heartbeat, estimated progress, stalled state, and retry delay. Terminal responses include the canonical score, risk, coverage, timestamps, report URL, and an explicit next action. Stop polling at any terminal status.
-- `certscore_get_report` - Retrieve a summary Pulse report, including customer-safe no-go messaging when coverage is completed-limited. Use certscore_get_evidence for the larger bounded packet.
-- `certscore_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.
-- `certscore_get_scan_bundle` - Call after completed or completed_limited status. summary returns the canonical overview without finding bodies; findings reserves space for compact findings; evidence reserves findings plus bounded evidence digests and references; full adds all available bounded sections. Every response declares detail and byte-budget metadata, omittedSections, retrieval URLs, and nextRecommendedMaxBytes when truncated. Never interpret no-go, not-observed, or limited coverage as proof of compliance.
+- `certscore_get_scan_status` - Poll with only the stable scanId returned by certscore_scan_site. Active responses include phase, heartbeat, estimated progress, stalled state, retry delay, and canonical scan provenance when available. Terminal responses include the CertScore score, risk, coverage, execution region (scanFrom), timestamps, report URL, and an explicit next action. For a reused or retrieved existing scan, use only persisted scanFrom and timestamps; never infer its original region from the current request, the user's location, or a default. Report unavailable provenance as unavailable. Stop polling at any terminal status.
+- `certscore_get_report` - Focused follow-up: retrieve a bounded Pulse report with high-signal TextContent and typed structuredContent, including customer-safe no-go messaging. For broad privacy questions, use certscore_get_scan_bundle first because it combines canonical findings, limitations, and pre-consent rows without redundant calls.
+- `certscore_get_evidence` - Focused follow-up: retrieve a bounded public-safe evidence packet with a concise TextContent digest and typed structuredContent. For broad privacy questions, use certscore_get_scan_bundle first. Excludes raw cookie values, raw bodies, sensitive payloads, full DOM, and unredacted query values.
+- `certscore_get_scan_bundle` - Call after completed or completed_limited status. Every usable completed bundle returns a self-contained concise TextContent digest plus matching structuredContent, including canonical execution region (scanFrom) and timestamps when available. For a reused or retrieved existing scan, use only persisted scanFrom and timestamps; never infer its original region from the current request, the user's location, or a default, and report unavailable provenance as unavailable. The default summary includes the canonical report overview, up to five compact public-safe projected findings across the scan's observed domains, and bounded row-level pre-consent cookie/tracker evidence; detail=findings increases the default finding allowance, evidence adds bounded evidence digests and references, and full adds all available bounded sections. MCP Light applies a 25000-byte response ceiling so full results remain transport-safe; use returned content URLs when the complete requested tier exceeds it. At the 5000-byte floor, core finding rows take priority over optional inventory and duplicate envelope fields; evidenceUrlTemplate may replace repeated per-finding URLs while preserving their canonical derivation from contentUrls.findings and findingId. Every response declares finding and evidence total/returned/truncated counts, canonicalFindingsComplete, requested and effective byte budgets, the response ceiling, omittedSections, retrieval URLs, and nextRecommendedMaxBytes when the complete tier fits the ceiling. When canonicalFindingsComplete is true, retry only if omitted envelope detail is needed. Enumerate only returned observations and projected findings. Post-refusal observation may intentionally stop as soon as qualifying non-essential activity or a retained consent-signal contradiction is observed. A confirmed observation with termination.kind=evidence_satisfied is positive evidence for the returned observation, not an inconclusive Reject Path result; keep any coverageLimitations scoped to additional behavior or persistence that was not measured. Treat criticality, priority, and confidence as CertScore metadata; regulatory review lenses are non-determinative CertScore review context, not legal severity, legal exposure, or a compliance determination. Missing consent-action evidence does not establish Accept, Reject, or Decline behavior. Do not extrapolate observed embeds, vendors, or requests into unobserved cookies, fingerprinting, tracking, or processing. The CertScore score covers observable scan signals only; do not infer unobserved technologies or legal compliance status, and never interpret no-go, not-observed, or limited coverage as proof of compliance.
+
+  Post-refusal observation may intentionally stop after the first qualifying non-essential activity or retained consent-signal contradiction. A confirmed observation with `termination.kind=evidence_satisfied` is positive evidence for the returned observation, not an inconclusive Reject Path result. `coverageLimitations` describe only additional behavior or persistence that was not measured.
 - `certscore_export_findings` - Return structured findings plus completed-limited no-go disposition and guidance for downstream review or ticketing workflows.
-- `certscore_list_findings` - List API v2 public-safe findings already projected for a scan.
-- `certscore_get_pre_consent_cookies_trackers` - Retrieve the public-safe Cookies & Trackers (Pre-consent) report table as compact JSON for a scan.
+- `certscore_list_findings` - Focused follow-up: list bounded API v2 public-safe findings already projected by the canonical pipeline, with matching high-signal TextContent and typed structuredContent. For broad privacy questions, use certscore_get_scan_bundle first.
+- `certscore_get_pre_consent_cookies_trackers` - Focused follow-up: retrieve bounded row-level public-safe pre-consent cookie/tracker evidence with matching TextContent and typed structuredContent. For a new broad request such as checking a site for pre-consent tracking, use certscore_scan_site then certscore_get_scan_bundle first.
 - `certscore_explain_finding` - Explain one projected finding with public evidence, caveats, reviewer next steps, and reason-specific no-go context when applicable.
 - `certscore_get_latest_domain_scan` - Retrieve the latest eligible API v2 public-safe scan for a domain.
-- `certscore_get_latest_domain_pre_consent_cookies_trackers` - Retrieve the public-safe Cookies & Trackers (Pre-consent) table from the latest eligible scan for a domain.
+
+Status provenance fields remain distinct: `provenance.retrievalMode` describes the current read, `provenance.creationDecision` reports the retained original new/reused decision or `unknown`, and `provenance.scanAgeSeconds` reports numeric age when available. A scan-ID lookup alone never proves reuse.
+
+At tight bundle budgets, short canonical `nextStep` actions remain only when they fit without displacing a finding. Longer actions and evidence detail remain available through the returned canonical URLs or a larger complete tier.
+- `certscore_get_latest_domain_pre_consent_cookies_trackers` - Focused follow-up: retrieve bounded row-level public-safe pre-consent cookie/tracker evidence from the latest eligible scan for a domain, with matching TextContent and typed structuredContent. For a broad current-site review, use certscore_scan_site then certscore_get_scan_bundle first.
 
 The initial MCP surface intentionally does not include account scan browsing or scan comparison tools.
 
@@ -102,15 +114,19 @@ This applies to `certscore_scan_site` when it returns an API v2 scan resource or
 
 Completed Light results are canonical. `certscore_scan_site`, terminal `certscore_get_scan_status`, and `certscore_get_scan_bundle` return the same score, risk level, coverage, and timing fields. Scores include `scoreStatus`, `scoreVersion`, and `scoreUpdatedAt`; a scan remains `finalizing` until the persisted canonical report projection is ready, so a completed response always carries `scoreStatus: "final"`.
 
+The value is labeled `CertScore score`, never a compliance score. It covers observable public-web scan signals only. Clients must not infer technologies absent from the returned evidence, compare the value with a hypothetical compliant baseline, or infer legal compliance status.
+
 Every `failed`, `expired`, or `rate_limited` status includes a bounded `error` object with `code`, `message`, `retryable`, `retryAfterSeconds`, and `recommendedNextAction`.
 
 ## Light Bundle Detail and Byte Budgets
 
-Every bundle declares its selected `detail` mode. `summary` returns the overview, canonical result, coverage, limitations, counts, and report URL without finding bodies. `findings` reserves space for compact finding objects. `evidence` reserves findings plus bounded evidence digests and references. `full` adds every available section subject to the caller's byte budget.
+Every bundle declares its selected `detail` mode. `summary` returns the overview, canonical result, up to five compact projected finding objects, compact row-level pre-consent cookie/tracker evidence, coverage, limitations, counts, and report URL. This lets conversational MCP clients enumerate projected consent-control, CMP-context, transport, GDPR/ePrivacy transparency, social/media embed, accessibility, disclosure, and other returned review signals without needing a second tool; only categories actually present in canonical projections are returned. Findings and inventory sections each declare `total`, `returned`, and `truncated`. Each compact finding retains its public API v2 evidence anchor. Each inventory row includes cookie/tracker identity, cookie names where present, vendor, purpose, category, first-observed time, domains, evidence classification, and confidence. `findings` raises the default finding allowance to 20. `evidence` adds bounded evidence digests and references. `full` adds every available non-duplicated section subject to the effective byte budget; findings, top findings, and transport security are returned once in their canonical top-level bundle sections. When `fullPayloadBytes` exceeds the Light response ceiling, use the canonical content URLs instead of retrying above the ceiling.
 
-`mcpMetadata` always includes `requestedMaxBytes`, `actualBytes`, `truncated`, `truncationReason`, `omittedSections`, `nextRecommendedMaxBytes`, `omittedContentAvailableViaUrl`, and `contentUrls`. When the budget cannot retain a requested section, `recommendedNextAction` names the next useful byte limit or directs the agent to an available report/evidence URL.
+`TextContent` is capped at 8,000 characters and uses short plain-text lines instead of large tables or nested JSON. It presents canonical overview facts and projected findings before the row inventory so one evidence family cannot crowd out the rest. The full profile's structured bundle defaults to 50,000 bytes and accepts a caller-selected 5,000-200,000-byte bound. Light defaults to and applies a 25,000-byte response ceiling. If either representation must omit returned items, it states that explicitly and preserves totals and truncation metadata.
 
-Input-validation errors remain MCP `-32602` errors and also include structured `invalid_arguments` details with the affected field and a safe next action. Error results use concise text plus the same machine-readable `structuredContent`; successful results never duplicate the full structured payload in text.
+`mcpMetadata` always includes `requestedMaxBytes`, `effectiveMaxBytes`, `responseCeilingBytes`, `responseBudgetClamped`, `actualBytes`, `fullPayloadBytes`, `truncated`, `canonicalFindingsComplete`, `truncationReason`, `omittedSections`, `deduplicatedSections`, `nextRecommendedMaxBytes`, `omittedContentAvailableViaUrl`, and `contentUrls`. Under byte pressure, optional detail and inventory rows are reduced before compact core finding rows. `canonicalFindingsComplete` separates complete projected findings from a partially omitted envelope. `nextRecommendedMaxBytes` is the rounded size needed for the complete requested tier rather than an incremental retry step; when the complete tier exceeds the MCP ceiling, the response directs the agent to an available report/evidence URL.
+
+Input-validation errors remain MCP `-32602` errors and also include structured `invalid_arguments` details with the affected field and a safe next action. Error results use concise text plus machine-readable details. Successful results put the typed result in `structuredContent`; scan bundles also render a bounded row-level evidence summary in `TextContent` for client compatibility.
 
 The Light workflow is:
 
@@ -119,7 +135,7 @@ The Light workflow is:
 3. If the result is queued, running, or finalizing, retain `scanId` and poll `certscore_get_scan_status` with only that ID.
 4. Stop polling at any terminal status. For `completed` or `completed_limited`, call `certscore_get_scan_bundle`.
 5. If the bundle is truncated, follow `recommendedNextAction`, increase `maxBytes`, or open a listed content URL.
-6. Summarize the canonical score, risk, findings, coverage, limitations, and report URL without treating no-go, not-observed, or limited coverage as proof of compliance.
+6. Summarize the CertScore score, risk, pre-consent rows, findings, coverage, limitations, and report URL without treating no-go, not-observed, or limited coverage as proof of compliance.
 
 ## Completed-Limited No-Go Results
 
@@ -140,7 +156,7 @@ https://mcp.certscore.ai/.well-known/oauth-protected-resource/mcp
 https://certscore.ai/.well-known/oauth-authorization-server
 ```
 
-The full 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.
+The full hosted service uses OAuth authorization code with PKCE. Default read access requests `scan:read mcp`. Active Trial workspaces connecting through Claude receive `scan:create` automatically, bounded to 20 genuinely new scans per hour and 100 per day per workspace; eligible recent-result reuse does not consume that allowance. Other clients continue to require an explicit scan-creation grant. 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:
 
@@ -207,7 +223,7 @@ CERTSCORE_REQUEST_TIMEOUT_MS=300000
 
 ## Local MCP — scoped API key access
 
-Stdio API keys use `pulse:read` and `mcp`; creating scans additionally requires `pulse:scan`. Hosted OAuth uses `scan:read` and `mcp`, with support-gated `scan:create`. Request scan-creation access by emailing `support@certscore.ai` with your organization, MCP client, expected workflow, expected request volume, and contact email.
+Stdio API keys use `pulse:read` and `mcp`; creating scans additionally requires `pulse:scan`. Hosted OAuth uses `scan:read` and `mcp`. Active Trial workspaces connecting through Claude receive bounded `scan:create` automatically; other clients can request scan-creation access by emailing `support@certscore.ai` with the organization, MCP client, expected workflow, expected request volume, and contact email.
 
 ## Verify Install
 
@@ -319,6 +335,8 @@ Canonical first-run prompt:
 
 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.
 
+Provenance keeps the current retrieval separate from the original creation decision. `retrievalMode=creation_response` means the result came from `certscore_scan_site`; `retrievalMode=scan_id_lookup` means a later tool fetched the retained scan by ID. `creationDecision` is `new_scan` or `reused_scan` only when the response retains that fact, and otherwise is `unknown`. Do not translate `scan_id_lookup` into a reused-scan claim. `scanAgeSeconds` reports a nonnegative age when a retained age or completion timestamp is available.
+
 ```json
 {
   "tool": "certscore_get_pre_consent_cookies_trackers",
@@ -339,7 +357,7 @@ With `freshness: "latest"`, CertScore reuses an eligible scan completed within t
 ```
 
 When summarizing table data, group rows by `vendor`, `purpose`, and `host` unless the user asks for row-level JSON.
-Treat MCP outputs as automated public-web observations for review. They are not legal advice, certification, or a compliance determination. MCP tools must not infer findings from raw labels, raw network events, missing data, or display-only context.
+Treat MCP outputs as automated public-web observations for human and agentic review. They are not legal advice, certification, or a compliance determination. MCP tools must not infer findings from raw labels, raw network events, missing data, or display-only context.
 
 ## Live Smoke
 
@@ -358,10 +376,10 @@ Without `CERTSCORE_API_KEY`, the smoke script exits successfully with a skip mes
 For the full production operator smoke, run from the WC01 repo:
 
 ```bash
-pnpm ops:smoke:mcp-production
+CERTSCORE_ALLOW_PAID_ECS_SMOKE=1 pnpm ops:smoke:mcp-cli-production
 ```
 
-This verifies the Homebrew-installed `certscore-mcp` command against live `https://certscore.ai`. It creates a short-lived preview key, stores only the hash in production through the approved ECS/Fargate path, checks required tools, requests a fresh EU-IR scan with `freshness: "refresh"` and `scanFrom: "eu_ie"`, requires non-empty findings and pre-consent cookies/trackers rows, runs `certscore_explain_finding`, and revokes the temporary key afterward. It exercises existing public-safe API/MCP projections only.
+This verifies the Homebrew-installed `certscore-mcp` command against live `https://certscore.ai`. It first requires the installed CLI version to match the workspace version, then creates a short-lived preview key, stores only the hash in production through the approved ECS/Fargate path, checks required tools, requires non-empty findings and pre-consent cookies/trackers rows, and revokes the temporary key afterward. The explicit cost opt-in is required because this separate CLI check starts one-off Fargate tasks. Use `pnpm ops:smoke:mcp-production` for the hosted, retained-scan, read-only canary.
 
 ## Troubleshooting
 
@@ -370,7 +388,7 @@ This verifies the Homebrew-installed `certscore-mcp` command against live `https
 - Missing scan ID: retry `certscore_scan_site` only when the error is retryable. Never call `certscore_get_scan_status` until `scanId` exists.
 - Rate limited: follow `retryAfterSeconds` and `recommendedNextAction`, wait for the returned UTC reset, or reuse an eligible result.
 - Reused result: report that the eligible prior scan was reused and quota was not consumed.
-- Truncated bundle: follow `nextRecommendedMaxBytes`, raise `maxBytes`, or open a returned report or evidence content URL.
+- Truncated bundle: first inspect `canonicalFindingsComplete`; when true, retry only for omitted envelope detail. Otherwise follow `nextRecommendedMaxBytes`, raise `maxBytes`, or open a returned report or evidence content URL.
 - Invalid URL: correct the field named by the structured `invalid_arguments` response and retry with a public HTTP or HTTPS URL.
 - Limited result versus failure: `completed_limited`, no-go, not-observed, and limited coverage are observations only, never proof of compliance. `failed`, `expired`, and connection errors are failures with retry guidance.
 - Command not found: run the Homebrew install again and confirm Homebrew's bin directory is on `PATH`.