@certscore/mcp 0.2.16 → 0.2.18

package/README.md

@@ -1,21 +1,36 @@
-# CertScore MCP
+# CertScore.ai MCP Light
 
-CertScore MCP exposes a focused Model Context Protocol server for CertScore Pulse workflows.
+**No-auth website privacy scans for MCP clients.** Give an agent a public URL and retrieve evidence-backed observations about cookies and storage, trackers and vendors, consent controls, privacy-policy surfaces, and HTTPS/TLS signals.
 
-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`.
+CertScore.ai MCP Light is live in the [GitHub MCP Registry](https://github.com/mcp/ai.certscore/mcp-light) as `ai.certscore/mcp-light`. It exposes exactly three tools and requires no signup, API key, bearer token, browser login, or OAuth.
 
-Public docs:
+| | |
+| --- | --- |
+| Endpoint | `https://mcp.certscore.ai/mcp/light` |
+| Transport | Streamable HTTP |
+| Authentication | None |
+| Tools | `certscore_scan_site` → `certscore_get_scan_status` → `certscore_get_scan_bundle` |
+| Current hosted version | `0.2.18` |
 
-- https://certscore.ai/developers/mcp
-- 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)
+[Start with MCP Light](https://certscore.ai/mcp/light?utm_source=github&utm_medium=mcp_registry&utm_campaign=github_mcp_registry_launch) · [Install in Cursor](https://cursor.com/link/mcp/install?name=CertScore.ai&config=eyJ1cmwiOiJodHRwczovL21jcC5jZXJ0c2NvcmUuYWkvbWNwL2xpZ2h0In0%3D) · [Read the installation reference](../../docs/mcp-light-install.md)
+
+## Try it in about a minute
+
+Add the public endpoint to Codex:
+
+```bash
+codex mcp add certscore --url https://mcp.certscore.ai/mcp/light
+```
+
+Then ask:
+
+> Scan https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html. Continue through the returned scan lifecycle, retrieve the completed findings bundle, and summarize the score, risk level, findings, evidence links, coverage limitations, and report URL. State whether the result was new or reused. Treat the results as automated public-web observations, not legal advice or certification.
+
+ErgoVeritas is a stable, owned canary with intentional test signals. For an ordinary review, substitute any public HTTP or HTTPS URL you are authorized to assess.
 
 ## Light MCP — no authentication: start here
 
-Light is the anonymous, no-auth Streamable HTTP endpoint for first-time and low-volume agent workflows:
+Light is the anonymous Streamable HTTP endpoint for first-time and low-volume agent workflows:
 
 ```text
 Light:
@@ -25,33 +40,26 @@ 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 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 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.
+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, the jurisdiction-neutral GPC comparison, Accept and Reject Path post-action observations or explicit limitations, 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:
+Detailed first-run prompt:
 
-```bash
-codex mcp add certscore --url https://mcp.certscore.ai/mcp/light
-```
-
-First-run Codex prompt:
-
-> Scan https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html. If certscore_scan_site returns a queued, running, or finalizing result, retain the returned scanId and poll certscore_get_scan_status using scanId only. If certscore_scan_site returns a retryable error without a scanId, wait for retryAfterSeconds and retry certscore_scan_site; do not call certscore_get_scan_status until a scanId exists. Once the scan reaches a terminal status, call certscore_get_scan_bundle with detail=findings and maxBytes=8000. Summarize whether the result was new or reused, the score, risk level, findings, evidence links, coverage limitations, and report URL. Explain truncation or omitted sections when present. Treat results as automated public-web observations, not legal conclusions, certifications, or compliance determinations.
-
-ErgoVeritas is a stable, owned canary site suited to demonstrating the complete scan, status, and bundle flow. Its pages intentionally contain test signals; users may substitute their own public HTTP or HTTPS URL for production-like testing.
+> Scan https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html. If certscore_scan_site includes preConsentPreview, treat it as a partial preview and continue the workflow. Distinguish captured totals from bounded returned identities; use trackingVendorCount for non-operational tracking vendors and keep operationalVendors separate. Do not compare the compatibility preview trackerCount with the completed inventory's broader trackerCount. Never report preview counts as final totals. If certscore_scan_site returns a queued, running, or finalizing result, retain the returned scanId and poll certscore_get_scan_status using scanId only. If certscore_scan_site returns a retryable error without a scanId, wait for retryAfterSeconds and retry certscore_scan_site; do not call certscore_get_scan_status until a scanId exists. Once the scan reaches a terminal status, call certscore_get_scan_bundle with detail=findings and maxBytes=8000. Summarize whether the result was new or reused, the score, risk level, findings, evidence links, coverage limitations, and report URL. Explain truncation or omitted sections when present. Treat results as automated public-web observations, not legal conclusions, certifications, or compliance determinations.
 
 Canonical Light workflow:
 
 1. Call `certscore_scan_site` with a public URL.
 2. If a retryable error has no `scanId`, wait `retryAfterSeconds` and retry `certscore_scan_site`.
-3. If the result is queued, running, or finalizing, retain `scanId`.
-4. Poll `certscore_get_scan_status` using `scanId` only. Never poll until `scanId` exists.
-5. Stop polling at a terminal status, then call `certscore_get_scan_bundle`.
-6. Use `detail=findings` for a compact finding review.
-7. Use `detail=evidence` for evidence digests and references.
-8. If truncated, follow `recommendedNextAction` or increase `maxBytes`.
-9. Summarize findings together with coverage limitations and the report URL.
+3. If `preConsentPreview` is present, it is a partial preview of checkpoint passive observations. Its counts are partial, not the full scan tally; never report them as final totals. It contains no canonical findings or score and does not replace the completed bundle.
+4. If the result is queued, running, or finalizing, retain `scanId`.
+5. Poll `certscore_get_scan_status` using `scanId` only. Never poll until `scanId` exists.
+6. Stop polling at any terminal status. At `completed` or `completed_limited`, call `certscore_get_scan_bundle` before reporting full scan results, and use its final returned tally, canonical findings, and limitations; for other terminal states, follow the returned error guidance.
+7. Use `detail=findings` for a compact finding review.
+8. Use `detail=evidence` for evidence digests and references.
+9. If truncated, follow `recommendedNextAction` or increase `maxBytes`.
+10. 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` 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.
 
@@ -79,14 +87,18 @@ The full/authenticated Streamable HTTP endpoint is `https://mcp.certscore.ai/mcp
 
 MCP scan-resource reads use the same weighted, rolling policy as the direct CertScore API. Hosted MCP rejects an over-limit composite call before internal fan-out; local MCP receives the same protection from the underlying API. Poll only active status resources, stop at a terminal status, do not repeatedly retrieve terminal scan resources, and honor `Retry-After` before retrying. The current limits and weights are published at https://certscore.ai/developers/reference#read-rate-limits and in the `x-certscore-read-rate-policy` extension of the public OpenAPI documents.
 
-## Tools
+## Authenticated and local MCP tool reference
+
+The sections below document the broader authenticated and local package surfaces. They do not change the GitHub-listed Light contract, which exposes only `certscore_scan_site`, `certscore_get_scan_status`, and `certscore_get_scan_bundle`.
+
+- `certscore_scan_site` - Creates a public-website privacy scan or reuses an eligible recent completed scan. Coverage includes pre-consent storage, trackers, consent and CMP signals, privacy-policy disclosures, transport security, and GDPR/ePrivacy or CCPA/CPRA review signals. The response contains a stable scanId, lifecycle status, retry timing, and sometimes a bounded preliminary preConsentPreview; preliminary data contains no final findings or score. Results are automated public-web observations, not legal advice, certification, or a compliance determination. Tool and workflow documentation: https://certscore.ai/developers/mcp.
 
-- `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.
+  Workflow note: a new scan may include `preConsentPreview` when the runtime lane completes or reaches its six-second checkpoint. The preview separates captured totals from bounded returned identities. `trackingVendorCount` excludes infrastructure, security, and consent-management vendors, which appear in `operationalVendors`; the compatibility preview count is not comparable to the completed inventory's broader `trackerCount`. Continue with `certscore_get_scan_status`, never poll in parallel, and never resubmit `certscore_scan_site` while the scan is active. Then call `certscore_get_scan_bundle` at completed or completed_limited.
 - `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, 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_scan_status` - Returns lifecycle status for a stable CertScore scanId. Active responses include phase, heartbeat, estimated progress, retryAfterSeconds, and sometimes a bounded preliminary preConsentPreview. Terminal responses include completion status, CertScore score and risk metadata when available, coverage, persisted execution region and timestamps, report URL, and a next-action field. Preliminary observations are distinct from completed findings.
 - `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.
+- `certscore_get_scan_bundle` - Returns the completed or completed-limited CertScore evidence bundle for a stable scanId as concise TextContent and matching structuredContent. Available sections include the canonical report overview, bounded projected findings, pre-consent cookie and tracker evidence, coverage limitations, persisted execution provenance, and retrieval URLs. Detail tiers and byte budgets control the bounded response, with explicit returned, total, truncated, and omitted-section metadata. Accept and Reject Path content is present only for confirmed, evidence-qualified post-action observations; unsupported or inconclusive outcomes remain neutral coverage limitations. Results are automated public-web observations, not legal advice, certification, or a compliance determination.
 
   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.
@@ -318,15 +330,15 @@ Local repo config for contributors:
 
 ## Agent Workflow
 
-1. Call `certscore_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 `certscore_get_scan_status` using the stable `scanId` until completion.
+1. Call `certscore_scan_site` with a public URL. A reused eligible result may be completed immediately; a new scan returns its stable `scanId` and may return a partial preview when the runtime lane completes or reaches its six-second checkpoint.
+2. If `preConsentPreview` is present, distinguish captured totals from bounded returned identities. Use `trackingVendorCount` for non-operational tracking vendors and keep `operationalVendors` separate; do not compare the compatibility preview `trackerCount` with the completed inventory's broader `trackerCount`. It is not a finding, score, or terminal result.
 3. If status is `queued`, `running`, or `finalizing`, retain the returned `scanId` and poll `certscore_get_scan_status` using only that ID. Stop polling at `completed`, `completed_limited`, `failed`, `expired`, or `rate_limited`.
-4. For `completed` or `completed_limited`, call `certscore_get_scan_bundle` with its default `detail: "summary"`. Use `findings`, `evidence`, or `full` only when progressively deeper bounded context is required.
-5. Summarize the canonical score, risk, findings, coverage, limitations, report URL, and next action. Never treat no-go, not-observed, or limited coverage as proof of compliance.
+4. For `completed` or `completed_limited`, call `certscore_get_scan_bundle` with its default `detail: "summary"` before reporting full scan results. Use its final returned tally, canonical findings, and limitations. Use `findings`, `evidence`, or `full` only when progressively deeper bounded context is required.
+5. Summarize the canonical score, risk, findings, coverage, limitations, report URL, and next action. Never treat the preview, no-go, not-observed, or limited coverage as proof of compliance.
 
 Canonical first-run prompt:
 
-> Scan these public URLs. For each one, call certscore_scan_site. If status is queued, running, or finalizing, retain scanId and poll certscore_get_scan_status using only scanId. Stop polling at completed, completed_limited, failed, expired, or rate_limited. For completed or completed_limited scans, call certscore_get_scan_bundle with detail=findings. If truncated, follow recommendedNextAction or increase maxBytes. Report the canonical score, risk level, coverage, findings, limitations, report URL, and next action. Never treat no-go, not-observed, or limited coverage as proof of compliance.
+> Scan these public URLs. For each one, call certscore_scan_site. If preConsentPreview is present, treat it as a partial preview whose counts are checkpoint-only and partial, not the full scan tally; never report them as final totals, and continue the workflow. If status is queued, running, or finalizing, retain scanId and poll certscore_get_scan_status using only scanId. Stop polling at completed, completed_limited, failed, expired, or rate_limited. For completed or completed_limited scans, call certscore_get_scan_bundle with detail=findings before reporting full scan results. Use the bundle for the final returned tally, canonical findings, and limitations. If truncated, follow recommendedNextAction or increase maxBytes. Report the canonical score, risk level, coverage, findings, limitations, report URL, and next action. Never treat preConsentPreview, no-go, not-observed, or limited coverage as proof of compliance.
 4. Call `certscore_get_report`, `certscore_get_evidence`, `certscore_list_findings`, or `certscore_get_pre_consent_cookies_trackers` only when the task needs a dedicated view.
 5. Call `certscore_explain_finding` when a reviewer needs evidence and caveats for a specific finding.
 6. Call `certscore_get_latest_domain_scan` or `certscore_get_latest_domain_pre_consent_cookies_trackers` when the user asks for latest eligible public data for a domain.