CertScore.ai MCP Light

CertScore.ai MCP Light

**推荐的发现入口：面向 MCP 客户端的免认证 Streamable HTTP 网站隐私扫描。**向 Agent 提供一个公开 URL，即可获取有证据支持的观察结果，涵盖 Cookie 和存储、跟踪器和供应商、同意控制、隐私政策页面，以及 HTTPS/TLS 信号。

CertScore.ai MCP Light 已上线 GitHub MCP Registry，名称为 ai.certscore/mcp-light。它提供四种工具，无需注册、API 密钥、Bearer 令牌、浏览器登录或 OAuth。

端点	https://mcp.certscore.ai/mcp/light
传输方式	Streamable HTTP
身份验证	无
工具	certscore_scan_site、certscore_get_scan_status、certscore_get_scan_bundle、certscore_get_report_evidence_page
当前托管版本	0.2.31

从 MCP Light 开始 · 在 Cursor 中安装 · 阅读安装参考

约一分钟即可试用

将公共端点添加到 Codex：

codex mcp add certscore --url https://mcp.certscore.ai/mcp/light

然后提问：

检查 https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html 中的网站隐私风险。说明主要发现、支持证据、覆盖范围限制，以及下一步应检查的内容。

ErgoVeritas 是稳定且自有的金丝雀网站，包含有意设置的测试信号。若要进行常规审查，请替换为你获准评估的任意公开 HTTP 或 HTTPS URL。

Light MCP — 无需身份验证：从这里开始

Light 是面向首次使用及低频 Agent 工作流的匿名 Streamable HTTP 端点：

Light:
https://mcp.certscore.ai/mcp/light

Authentication: None
Tools: certscore_scan_site, certscore_get_scan_status, certscore_get_scan_bundle, certscore_get_report_evidence_page

Light 会对会话、请求方 IP 和共享创建量实施限制。请参阅 https://certscore.ai/developers/mcp#light-usage-limits 中的当前政策。符合条件的复用结果不会占用配额。

Light 是面向公共网站的免费网站隐私扫描器和 Cookie 检查器。它可以返回规范证据和发现，涵盖同意前的 Cookie 和存储、跟踪器和供应商、Cookie 横幅、CMP 和同意控制、司法管辖区中立的 GPC 对比、接受与拒绝路径的操作后观察结果或明确限制、隐私政策和透明度页面、GDPR/ePrivacy 和 CCPA/CPRA 审查信号，以及 HTTPS/TLS 传输观察结果。典型用途包括发布前隐私预检、公共供应商域名审查、落地页跟踪器检查、审计分流，以及人工隐私审查前的证据收集。

首次运行提示词：

检查 https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html 中的网站隐私风险。说明主要发现、支持证据、覆盖范围限制，以及下一步应检查的内容。

Light 规范工作流：

1. 使用公开 URL 调用 certscore_scan_site。
2. 如果可重试错误未包含 scanId，请等待 retryAfterSeconds 指定的时间，然后重试 certscore_scan_site。
3. 如果存在 preConsentPreview，它是检查点被动观测的部分预览。其计数是部分数据，而非完整扫描统计；切勿将其报告为最终总数。它不包含规范发现或评分，也不能替代已完成的结果包。
4. 如果结果处于排队、运行中或正在最终处理状态，请保留 scanId。
5. 仅使用 scanId 轮询 certscore_get_scan_status。在 scanId 存在之前，切勿轮询。
6. 在任何终止状态下停止轮询。在 completed 或 completed_limited 状态下，报告完整扫描结果前调用 certscore_get_scan_bundle，并使用其返回的最终统计、规范发现和限制；对于其他终止状态，请遵循返回的错误指引。
7. 使用 detail=findings 查看精简的发现摘要。
8. 使用 detail=evidence 查看发现摘要、有限数量的外部请求示例、策略表面候选项和引用，即使没有投影任何发现也如此。请求外部脚本本身并不能证明存在跟踪；若需查看更深入的保留报告证据，请使用 certscore_get_report_evidence_page。
9. 如果内容被截断，请遵循 recommendedNextAction，或增大 maxBytes。
10. 将发现与覆盖范围限制及报告 URL 一并总结。

建议的结果包预算为：summary 使用 maxBytes=5000，findings 使用 maxBytes=8000，evidence 使用 maxBytes=8000，full 使用 maxBytes=12000 至 25000。MCP Light 将响应限制在 25,000 字节以内，确保结果符合客户端的实际处理能力；请求的预算若更大，则会显示该值，但实际使用时会被限制。在 5,000 字节的最低预算下，精简的核心发现条目优先于可选清单和重复的信封字段。如果省略了重复出现的发现 URL，evidenceUrlTemplate 会指向 contentUrls.findings，并使用返回的发现 ID，以便仍可推导出相同的规范证据端点。请检查 canonicalFindingsComplete、requestedMaxBytes、effectiveMaxBytes、responseCeilingBytes、actualBytes、fullPayloadBytes、truncated、omittedSections、nextRecommendedMaxBytes，以及返回的报告或证据内容 URL。当 canonicalFindingsComplete 为 true 时，只有在需要省略的信封细节时才重试。

最终的最小核心回退机制也会遵守请求的结构化字节预算。空间不足时，它会移除空信封、冗余检索 URL 和重复说明，同时保留带类型的态势评分与覆盖范围、表单、无障碍信息、扫描标识和核心发现数据。contentUrls 可能为空，并带有明确的省略标记；请使用 reportUrl 或针对同一扫描调用证据工具。如果核心内容本身无法容纳，工具会返回有界且不可重试的 response_budget_exceeded 错误，而不会返回超大或被修改的报告。只有在足以符合传输上限时，其指引才会建议使用更大的预算；否则，请使用有界的报告证据分页。切勿为了从响应预算错误中恢复而创建替代扫描。

验证提示词：

列出可用的 CertScore 工具。如果支持资源，请读取 certscore://example-report；否则使用 scanId=9ba99a8c-b1ad-44c1-985f-92cef760ab40 调用 certscore_get_scan_bundle。报告所保留示例的原始日期和覆盖范围。如果无法获取，请如实说明；不要为了测试连接而创建新扫描。

当四个 Light 工具均在未出现授权页面的情况下列出，且可以获取带有原始日期和覆盖范围的保留示例时，连接验证即成功。无法获取历史示例并不代表可以创建替代扫描。首次检查网站时，扫描创建会单独返回稳定的扫描 ID，并说明该扫描是新建还是复用；符合条件的复用不会消耗新扫描额度。 CertScore 结果是通过扫描公开网页自动得出的观察结果。未通过、未观察到和覆盖有限的结果，并不能证明符合规定、不存在风险或具有某种法律状态。依赖某项发现前，请先审查留存的证据和适用背景。

扫描反映的是特定时间点可观察到的行为。公开网站在后续访问时或在其他执行环境中可能表现不同。CertScore 发现和 CertScore 评分用于支持人工和 Agent 式审查；它们不是法律建议、认证或合规判定。

应该使用哪种 MCP 接入方式？

接入方式	访问方式	最适用于
轻量版 MCP — 无需身份验证	无需账户、API 密钥、Bearer 令牌、浏览器登录或 OAuth；提供 4 个工具；当前会话、请求者 IP 和共享限额：https://certscore.ai/developers/mcp#light-usage-limits；符合条件的复用免费	首次使用、测试和探索
托管版 MCP — OAuth	托管式 Streamable HTTP，支持 OAuth 作用域、更高用量、历史记录和获批的高级工具	生产环境、团队和托管式远程客户端
本地 MCP — 作用域受限的 API 密钥	本地 stdio，使用作用域受限的密钥，并提供其作用域允许的工具	后端、本地和受控自动化工作流

完整／经过身份验证的 Streamable HTTP 端点是 https://mcp.certscore.ai/mcp。当工作流需要身份验证、更高用量、历史记录或高级工具时，请在轻量版之后改用此端点。切换到经过身份验证的访问方式后，核心标识符和规范响应字段仍保持兼容。

加权读取限额

MCP 扫描资源读取采用与 CertScore API 直接调用相同的加权滚动策略。托管版 MCP 会在内部扇出之前拒绝超出限额的复合调用；本地 MCP 则受到底层 API 的同等保护。仅轮询仍处于活动状态的状态资源，到达终止状态后即停止，不要重复获取终止状态的扫描资源，并在重试前遵循 Retry-After。当前限额和权重发布于 https://certscore.ai/developers/reference#read-rate-limits，以及公开 OpenAPI 文档中的 x-certscore-read-rate-policy 扩展。

经过身份验证和本地 MCP 工具参考

以下部分介绍更广泛的经过身份验证及本地软件包接口。轻量版合约提供 certscore_scan_site、certscore_get_scan_status、certscore_get_scan_bundle 和 certscore_get_report_evidence_page。

• certscore_scan_site - 用于用户请求的网站上线审查、供应商评估、Cookie／跟踪器清单、同意／GPC 调查或隐私政策审查。提供公开 URL 或域名即可。此工具会创建隐私扫描，或复用符合条件的近期已完成扫描；默认的 freshness=latest 可节省新扫描限额。仅当用户明确要求进行全新扫描或修复后复查时，才使用 refresh。保留 scanId，仅在扫描处于活动状态时按 retryAfterSeconds 轮询 certscore_get_scan_status，然后读取 certscore_get_scan_bundle。初步的 preConsentPreview 并非最终发现结果或汇总数据。覆盖范围包括同意前存储、跟踪器、同意及 CMP 信号、隐私政策披露、传输安全，以及 GDPR/ePrivacy 或 CCPA/CPRA 审查信号。结果是自动化观察结果，不是法律建议、认证或合规判定。https://certscore.ai/developers/mcp。 工作流说明：运行时通道完成或到达 6 秒检查点时，新扫描可能包含 preConsentPreview。该预览将捕获总数与有界返回的身份信息分开。trackingVendorCount 不包括基础设施、安全和同意管理供应商；这些供应商会显示在 operationalVendors 中。兼容性预览计数无法与已完成清单中范围更广的 trackerCount 相比较。请继续调用 certscore_get_scan_status，切勿并行轮询，也不要在扫描处于活动状态时重新提交 certscore_scan_site。随后在状态为 completed 或 completed_limited 时调用 certscore_get_scan_bundle。

• certscore_get_scan - 获取 API v2 的公开安全扫描资源，其中包括 completed-limited 不予继续的判定、针对具体原因的指导，以及可用时的时间信息。

• certscore_get_scan_status - 返回稳定 CertScore scanId 的生命周期状态。活动状态的响应包括阶段、心跳、预估进度、retryAfterSeconds，有时还包括有界的初步 preConsentPreview。终态响应包括完成状态、可用时的 CertScore 评分和风险元数据、覆盖范围、已持久化的执行区域和时间戳、报告 URL，以及后续操作字段。初步观察与已完成的发现是分开的。

• certscore_get_report - 重点后续查询：获取有界的 Pulse 报告，其中包含高信号 TextContent 和类型化 structuredContent，也包括面向客户的安全不予继续说明。对于宽泛的隐私问题，请先使用 certscore_get_scan_bundle，因为它会整合规范发现、限制和预先同意行，避免冗余调用。

• certscore_get_evidence - 重点后续查询：获取有界的公开安全证据包，其中包含简洁的 TextContent 摘要和类型化 structuredContent。对于宽泛的隐私问题，请先使用 certscore_get_scan_bundle。排除原始 Cookie 值、原始正文、敏感载荷、完整 DOM 和未编辑的查询值。

• certscore_get_scan_bundle - 对已完成或 completed-limited 扫描的主要答复：规范发现、后续步骤、支持证据、评分、日期/区域、覆盖范围和报告 URL。只需提供现有 scanId；不会创建新扫描。证据索引描述的是响应交付情况，而非证据缺失。可选的后续操作会指向更深入的报告表、跟踪工作底稿以及 JSON/CSV 导出。使用 detail=evidence 获取请求示例和策略候选项，包括没有发现项的扫描；detail=full 会添加有界的保留上下文。保留返回数/总数及省略元数据。Accept/Reject 执行 succeeded 表示点击已完成且进行了有界观察；succeeded_with_confirmation 还会验证同意决定。点击后保留的事实与已登记的决定仍是分开的。未捕获或捕获失败的情况会明确标记为有限。评分影响以规范发现为准。之后未发现某项并不能证明问题已修复。结果是对公开网络的自动化观察，不构成法律建议、认证或合规性判定。

  两种执行成功状态都应计数；已登记的成功路径可能省略 afterAction，历史执行信息缺失则表示不可用。 拒绝后观察可以有意在首次符合条件的非必要活动或保留的同意信号矛盾出现后停止。若已确认的观察包含 termination.kind=evidence_satisfied，则它是对所返回观察的正面证据，而非不确定的拒绝路径结果。coverageLimitations 仅描述未测量的其他行为或持久性。

• certscore_export_findings - 返回结构化发现，以及已完成但范围有限的禁行处置结果和指导，供下游审核或工单工作流使用。

• certscore_list_findings - 定向跟进：列出规范管道已投影的有界 API v2 公开安全发现，并提供匹配的高信号 TextContent 和类型化 structuredContent。对于宽泛的隐私问题，请先使用 certscore_get_scan_bundle。

• certscore_get_pre_consent_cookies_trackers - 定向跟进：检索有界、逐行且公开安全的同意前 Cookie／跟踪器证据，并提供匹配的 TextContent 和类型化 structuredContent。对于检查网站是否存在同意前跟踪等新的宽泛请求，请先使用 certscore_scan_site，然后使用 certscore_get_scan_bundle。

• certscore_explain_finding - 解释一项已投影的发现，提供公开证据、注意事项、审核者后续步骤，以及适用时针对具体原因的禁行背景。

• certscore_get_latest_domain_scan - 检索某个域名最新符合条件的 API v2 公开安全扫描。

状态来源字段彼此独立：provenance.retrievalMode 描述当前读取，provenance.creationDecision 报告保留的原始新建／复用决策，或 unknown，而 provenance.scanAgeSeconds 则在可用时报告数值形式的扫描年龄。仅凭扫描 ID 查询，绝不能证明发生了复用。

在紧凑的 bundle 预算下，只有在不挤占任何发现的前提下能够容纳的简短规范 nextStep 操作才会保留。较长的操作和证据详情可通过返回的规范 URL 或更大的完整层级获取。

• certscore_get_latest_domain_pre_consent_cookies_trackers - 定向跟进：从某个域名最新符合条件的扫描中检索有界、逐行且公开安全的同意前 Cookie／跟踪器证据，并提供匹配的 TextContent 和类型化 structuredContent。对于当前网站的宽泛审核，请先使用 certscore_scan_site，然后使用 certscore_get_scan_bundle。

初始 MCP 接口有意不包含账户扫描浏览或扫描比较工具。

扫描时间字段

由 API v2 扫描资源提供支持的 MCP 工具，仅在 CertScore 掌握足够的时间证据时才会返回扫描时间：

• startedAt
• completedAt
• scanTimeSeconds

这适用于返回 API v2 扫描资源或作业的 certscore_scan_site、certscore_get_scan，以及传入 scanId 调用的 certscore_get_scan_status。scanTimeSeconds: null 表示时间信息不可用或不完整，不应显示为 0。

已完成的 Light 结果是规范结果。certscore_scan_site、终态的 certscore_get_scan_status 和 certscore_get_scan_bundle 会返回相同的分数、风险级别、覆盖范围和时间字段。分数包含 scoreStatus、scoreVersion 和 scoreUpdatedAt；扫描会保持 finalizing 状态，直到持久化的规范报告投影准备就绪，因此已完成的响应始终携带 scoreStatus: "final"。

No-go 结果在 MCP 文本中会优先展示保留的访问阻碍、“未评分”、证据摘录、后续操作和重试指引。结构化响应会保留 resultDisposition、noGo、空值分数／风险级别以及空 findings。Bundle 预算紧张时，会优先保留该阻碍和解决方法，再提供可选的 lane 诊断信息；省略的诊断信息会列在 mcpMetadata.omittedSections 中。No-go 的 full 请求不会伪造完整报告。

该值标记为 CertScore score，绝不会标记为合规分数。它仅涵盖可观察到的公共 Web 扫描信号。客户端不得推断返回证据中未包含的技术，不得将该值与假设的合规基准进行比较，也不得推断法律合规状态。

每个 failed、expired 或 rate_limited 状态都包含一个范围受限的 error 对象，其中包含 code、message、retryable、retryAfterSeconds 和 recommendedNextAction。

Light Review 后续操作

已完成的 bundle 包含证据索引，以及针对任务相关报告证据和 tracking JSON/CSV 导出的可选后续操作。交付标签描述的是响应，而不是证据是否缺失。请说明结果是新生成的还是复用的。保留基线扫描 ID、日期和执行区域，以便之后在明确请求时进行新的复查；未发现问题并不能证明修复已完成。只有在有帮助时，才提供修复建议，或为用户选择的其他站点提供同样的 Review。Light 提供可选的 certscore_launch_review、certscore_compare_scans 和 certscore_remediation_checklist 提示词，以及 certscore://project-instructions 资源。certscore://example-report 用于测试检索，不会创建扫描。

Light Bundle 详情与字节预算

已完成的 Light 捆绑包响应还会在 _meta["ai.certscore/responseGuidance"] 和追加的 guidance TextContent 中包含精简的 reviewActions。 即使较小的结构化捆绑包省略了 reviewNavigation，这些内容仍然可用。 版本为 certscore.light-review-actions.v1。openReport 是一个 open_url 操作，使用本次扫描返回的 HTTPS CertScore.ai 报告 URL；若该 URL 缺失或无效，则省略此操作。不会合成报告 URL。 当返回的发现项身份具有受支持的报告目标时，evidenceLinks 和 primaryReportLink 会说明报告将打开的内容。它们会保留扫描和 访问参数，并选择匹配的审查重点。聚焦的报告证据页面也会基于其返回的发现项提供相同范围的导航。使用一个与问题相关的链接，并将 openReport 作为后备；用户请求查看加利福尼亚报告时，不得改用 GDPR 证据链接。 一个可选的 followUp 会根据返回的捆绑包，提供剩余证据、开发者检查清单提示、 保留的跟踪导出、有限覆盖范围审查，或未来变更后的复查。读取和检查清单操作会保留扫描 ID，并声明 createsScan: false。未来复查只是建议，声明 createsScan: true，但不包含可执行的扫描调用。所有后续操作都需要用户请求。先回答原始问题，跳过重复或已拒绝的建议，并且不得声称问题已修复或符合相关法律。活跃、失败、禁止执行和错误结果均不包含审查操作。其他工具配置文件保持不变。

此指导不会增加 API 请求、扫描、模型调用或存储。预计在每月完成 100,000 个捆绑包响应时，额外响应传输成本低于 $0.10；无需更改基础设施容量。

每个捆绑包都会声明所选的 detail 模式。summary 会返回概览、规范结果、最多五个精简的投影发现项、精简的逐行同意前 Cookie/跟踪器证据、覆盖范围、限制、计数和报告 URL。这样，对话式 MCP 客户端无需调用第二个工具，即可枚举投影中的同意控制、CMP 上下文、传输、GDPR/ePrivacy 透明度、社交媒体/媒体嵌入、无障碍、披露及其他返回的审查信号；只返回规范投影中实际存在的类别。发现项和清单各部分都会声明 total、returned 和 truncated。每个精简发现项都会保留其公共 API v2 证据锚点。每个清单行都包含 Cookie/跟踪器身份、存在时的 Cookie 名称、供应商、用途、类别、首次观察时间、域名、证据分类和置信度。findings 会将默认发现项数量上限提高到 20。evidence 会增加有界的证据摘要和引用。full 会在有效字节预算范围内添加所有可用且不重复的部分；发现项、重点发现项和传输安全只会在其规范的顶层捆绑包部分中返回一次。当 fullPayloadBytes 超过 Light 响应上限时，请使用规范内容 URL，而不要重试并突破上限。

TextContent 上限为 8,000 个字符，并使用简短的纯文本行，而非大型表格或嵌套 JSON。它会先呈现规范概览事实和投影发现项，再呈现逐行清单，避免某一类证据挤占其他内容。完整配置文件的结构化捆绑包默认上限为 50,000 字节，并接受调用方选择的 5,000-200,000 字节范围。Light 默认并应用 25,000 字节的响应上限。如果任一表示必须省略已返回的项目，会明确说明，并保留总数和截断元数据。 mcpMetadata 始终包含 requestedMaxBytes、effectiveMaxBytes、responseCeilingBytes、responseBudgetClamped、actualBytes、fullPayloadBytes、truncated、canonicalFindingsComplete、truncationReason、omittedSections、deduplicatedSections、nextRecommendedMaxBytes、omittedContentAvailableViaUrl 和 contentUrls。在字节数受限时，会先减少可选的详细信息和清单行，再减少精简的核心发现行。canonicalFindingsComplete 用于区分完整的投影发现与部分省略的封装。nextRecommendedMaxBytes 是获取完整请求层级所需的取整后大小，而不是增量重试步长；当完整层级超出 MCP 上限时，响应会引导 Agent 使用可用的报告／证据 URL。

输入验证错误仍为 MCP -32602 错误，并且还包含结构化的 invalid_arguments 详细信息，指出受影响的字段和安全的后续操作。错误结果使用简洁文本和机器可读的详细信息。成功结果会将类型化结果放入 structuredContent；扫描包还会在 TextContent 中呈现有界的逐行证据摘要，以兼容客户端。

Light 工作流如下：

1. 使用公开 URL 调用 certscore_scan_site。
2. 如果可重试的错误没有 scanId，请等待 retryAfterSeconds，然后重试 certscore_scan_site；不要轮询。
3. 如果结果为 queued、running 或 finalizing，请保留 scanId，并仅使用该 ID 轮询 certscore_get_scan_status。
4. 在任何终止状态下停止轮询。对于 completed 或 completed_limited，调用 certscore_get_scan_bundle。
5. 如果扫描包已截断，请遵循 recommendedNextAction、增大 maxBytes，或打开列出的内容 URL。
6. 总结 CertScore 评分、风险、同意前行、发现、覆盖范围、局限性和报告 URL；不要将 no-go、not-observed 或有限覆盖视为合规证明。

已完成的有限范围 No-Go 结果

No-go 扫描是可用的终止结果，而非传输失败。相关工具会保留 status: "completed_limited"、resultDisposition: "no_go"、稳定的原因代码、对客户安全的标题和说明、limitationKind 归因、重试指引，以及在保留时提供的有界 evidenceExcerpt。对于未知的未来原因，工具会使用通用的客户文案，同时将其结构化为 reasonCode: "unknown"。

托管 MCP — OAuth

支持 OAuth 的 MCP 客户端可以连接到：

https://mcp.certscore.ai/mcp

发现端点：

https://mcp.certscore.ai/.well-known/oauth-protected-resource/mcp
https://certscore.ai/.well-known/oauth-authorization-server

完整的托管服务使用带 PKCE 的 OAuth 授权码流程。活跃工作区的成员可通过已注册的 OAuth 客户端连接，适用于各个套餐，并具有 scan:read、scan:create 和 mcp 权限。现有限制仍然适用。规范的资格条件、授权和重新连接行为：https://certscore.ai/developers/mcp#hosted-oauth-start。本地范围限定的 API 密钥策略是独立的。

若要在不设置账户或 OAuth 的情况下进行低频 Agent 发现，请使用未经身份验证的端点：

https://mcp.certscore.ai/mcp/anonymous

若要使用最简单的免账户工作流，请参阅本文档顶部的 Light 快速入门。OAuth 元数据仅适用于 https://mcp.certscore.ai/mcp。

本地 MCP — 范围限定的 API 密钥配置

在 macOS 上使用 Homebrew 安装：

brew tap ergoveritas1-alt/certscore https://github.com/ergoveritas1-alt/certscore.ai
brew install --cask certscore-mcp

对于希望使用持久本地二进制文件的用户，cask 会安装预构建的 MCP 命令。

在 MCP 客户端中使用已安装的命令：

{
  "mcpServers": {
    "certscore": {
      "command": "certscore-mcp",
      "env": {
        "CERTSCORE_API_KEY": "YOUR_TOKEN",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

在此 monorepo 中运行以进行本地开发：

CERTSCORE_API_KEY=... pnpm mcp:certscore

应用数据库迁移后，生成范围限定的预览密钥：

pnpm db:migrate
pnpm mcp:certscore:generate-key -- --name "CertScore MCP preview"

本地构建后，直接运行已构建的软件包：

CERTSCORE_API_KEY=... certscore-mcp

可选：

CERTSCORE_BASE_URL=https://certscore.ai
CERTSCORE_REQUEST_TIMEOUT_MS=300000

CERTSCORE_API_KEY 应为工作区或预览用户的范围限定 CertScore API 令牌。MCP 服务会将其作为 bearer 令牌传递给 Pulse，且不会持久保存。

本地 MCP — 限定范围的 API 密钥访问

Stdio API 密钥需要 pulse:read 和 mcp；创建扫描还需要 pulse:scan。托管 OAuth 在已注册客户端的活动工作区策略下使用 scan:read scan:create mcp。有关当前资格要求和已验证客户端的可用情况，请参阅 https://certscore.ai/developers/mcp#hosted-oauth-start。

验证安装

certscore-mcp --version
certscore-mcp --help
CERTSCORE_API_KEY=... certscore-mcp doctor
CERTSCORE_API_KEY=... certscore-mcp doctor --check-auth

doctor 命令会检查二进制文件启动、版本输出、Node.js 运行时兼容性、已配置的 CertScore 基础 URL、API v2 健康状况以及 API 密钥是否存在。添加 --check-auth 可通过 /api/v2/auth/check 验证凭据，不会创建扫描。该命令不会打印密钥或检查原始扫描器产物。

无账户 Agent 扫描路径

无法创建账户或配置 OAuth 的 Agent 可以使用公开的 API v2 扫描路径，无需 Authorization 标头：

curl -X POST https://certscore.ai/api/v2/scans \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html","freshness":"latest","scanFrom":"eu_ie"}'

每个 UTC 日内，每个请求方 IP 最多可发起 20 次新的匿名扫描。重用符合条件的近期结果不会消耗配额。轮询返回的状态资源，然后获取发现或证据。如需更高额度（包括通过重用结果满足当前请求的情况），请联系 [email protected]。

MCP 客户端示例

Claude Desktop 风格的配置：

{
  "mcpServers": {
    "certscore": {
      "command": "certscore-mcp",
      "env": {
        "CERTSCORE_API_KEY": "YOUR_TOKEN",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

Cursor 配置：

{
  "mcpServers": {
    "certscore": {
      "command": "certscore-mcp",
      "env": {
        "CERTSCORE_API_KEY": "YOUR_TOKEN",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

Windsurf 或通用 Stdio MCP 客户端配置：

{
  "mcpServers": {
    "certscore": {
      "command": "certscore-mcp",
      "env": {
        "CERTSCORE_API_KEY": "YOUR_TOKEN",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

贡献者的本地仓库配置：

{
  "mcpServers": {
    "certscore": {
      "command": "pnpm",
      "args": ["mcp:certscore"],
      "cwd": "/path/to/WC01",
      "env": {
        "CERTSCORE_API_KEY": "YOUR_TOKEN",
        "CERTSCORE_BASE_URL": "https://certscore.ai"
      }
    }
  }
}

Agent 工作流

1. 使用公开 URL 调用 certscore_scan_site。符合条件的重用结果可能会立即完成；新扫描会返回稳定的 scanId，并且运行时通道完成或到达 6 秒检查点时，可能返回部分预览。
2. 如果存在 preConsentPreview，请区分捕获的总数与有界返回的身份信息。对于非运行类跟踪供应商，请使用 trackingVendorCount，并将其与 operationalVendors 分开；不要将兼容性预览中的 trackerCount 与已完成清单中范围更广的 trackerCount 进行比较。它不是发现、评分或最终结果。
3. 如果状态为 queued、running 或 finalizing，请保留返回的 scanId，并且仅使用该 ID 轮询 certscore_get_scan_status。当状态变为 completed、completed_limited、failed、expired 或 rate_limited 时，停止轮询。
4. 对于 completed 或 completed_limited，在报告完整扫描结果前，先使用默认的 detail: "summary" 调用 certscore_get_scan_bundle。使用其最终返回的统计、规范发现和限制。只有在需要逐步深入且有界的上下文时，才使用 findings、evidence 或 full。
5. 总结规范评分、风险、发现、覆盖范围、限制、报告 URL 和下一步行动。绝不要将预览、禁止项、未观察到的情况或有限覆盖视为合规证明。

规范的首次运行提示词：

扫描这些公开 URL。对每个 URL，调用 certscore_scan_site。如果存在 preConsentPreview，请将其视为部分预览，其计数仅为检查点数据且不完整，而非完整扫描统计；切勿将其报告为最终总数，并继续执行工作流。如果状态为 queued、running 或 finalizing，请保留 scanId，并仅使用 scanId 轮询 certscore_get_scan_status。状态变为 completed、completed_limited、failed、expired 或 rate_limited 时停止轮询。对于 completed 或 completed_limited 扫描，在报告完整扫描结果前，调用 certscore_get_scan_bundle，并设置 detail=findings。使用该 bundle 获取最终返回的统计、规范 findings 和限制。如果结果被截断，请遵循 recommendedNextAction，或增大 maxBytes。报告规范评分、风险等级、覆盖范围、findings、限制、报告 URL 和下一步操作。切勿将 preConsentPreview、no-go、not-observed 或有限覆盖视为合规证明。

4. 仅当任务需要专用视图时，才调用 certscore_get_report、certscore_get_evidence、certscore_list_findings 或 certscore_get_pre_consent_cookies_trackers。
5. 当审核人员需要了解特定 finding 的证据和注意事项时，调用 certscore_explain_finding。
6. 当用户请求某个域名最新的符合条件的公开数据时，调用 certscore_get_latest_domain_scan 或 certscore_get_latest_domain_pre_consent_cookies_trackers。

certscore_scan_site 会报告结果是否复用、作出新鲜度判断的原因、是否消耗了匿名配额、每日剩余额度、UTC 重置时间，以及建议使用的下一工具。

设置 freshness: "latest" 时，CertScore 会复用同一规范化目标和扫描区域中最近 24 小时内完成且符合条件的扫描。可复用结果必须具有已完成且可用的页面覆盖范围，且不能是过早丢失、无页面或其他不可复用的有限结果。复用不会消耗匿名配额。freshnessDecision 会说明是复用了近期结果，还是排队启动了新扫描；reusedScanAgeSeconds 会报告复用结果的时长。

来源信息会将当前检索与最初的创建决策区分开。retrievalMode=creation_response 表示结果来自 certscore_scan_site；retrievalMode=scan_id_lookup 表示后续工具通过 ID 获取了保留的扫描结果。仅当响应保留了相关事实时，creationDecision 才为 new_scan 或 reused_scan，否则为 unknown。不要将 scan_id_lookup 解释为复用扫描。若有保留的时长或完成时间戳，scanAgeSeconds 会报告非负时长。

{
  "tool": "certscore_get_pre_consent_cookies_trackers",
  "arguments": {
    "scanId": "00000000-0000-4000-8000-000000000123"
  }
}

{
  "tool": "certscore_get_latest_domain_pre_consent_cookies_trackers",
  "arguments": {
    "domain": "ergoveritas.com",
    "scanFrom": "eu_ie"
  }
}

汇总表格数据时，除非用户要求逐行 JSON，否则请按 vendor、purpose 和 host 对行分组。 将 MCP 输出视为面向人工和 Agent 审查的自动化公开网络观测结果。它们不是法律建议、认证或合规判定。MCP 工具不得根据原始标签、原始网络事件、缺失数据或仅用于显示的上下文推断 findings。

实时冒烟测试

CERTSCORE_API_KEY=... pnpm mcp:certscore:smoke

可选：

CERTSCORE_MCP_SMOKE_URL=https://ergoveritas.com/.well-known/certscore-canary/sentinels/broad-baseline.html

如果未设置 CERTSCORE_API_KEY，冒烟测试脚本会跳过并成功退出。

如需运行完整的生产环境操作员冒烟测试，请在 WC01 仓库中运行：

CERTSCORE_ALLOW_PAID_ECS_SMOKE=1 pnpm ops:smoke:mcp-cli-production

此操作会通过 Homebrew 安装的 certscore-mcp 命令，针对实时 https://certscore.ai 进行验证。它会先要求已安装的 CLI 版本与工作区版本一致，然后创建一个短期预览密钥，仅将其哈希通过获批的 ECS/Fargate 路径存储到生产环境中，检查必需工具，要求 findings 和预同意 cookies/trackers 行均非空，最后撤销临时密钥。由于这项独立的 CLI 检查会启动一次性 Fargate 任务，因此必须明确选择承担费用。对于托管式、保留扫描结果、只读的 canary，请使用 pnpm ops:smoke:mcp-production。

故障排查

• Codex 中意外出现 OAuth：移除该服务，然后使用准确的 Light URL https://mcp.certscore.ai/mcp/light 重新添加。不要配置 bearer token。
• Light 连接成功：Streamable HTTP 初始化完成，未打开授权页面，且 tools/list 恰好返回 certscore_scan_site、certscore_get_scan_status 和 certscore_get_scan_bundle。
• 缺少扫描 ID：仅当错误可重试时，才重试 certscore_scan_site。在 scanId 存在之前，切勿调用 certscore_get_scan_status。
• 触发速率限制：遵循 retryAfterSeconds 和 recommendedNextAction，等待返回的 UTC 重置时间，或复用符合条件的结果。
• 复用结果：说明复用了符合条件的先前扫描，且未消耗配额。
• 结果包被截断：先检查 canonicalFindingsComplete；若为 true，仅针对遗漏的信封详情重试。否则，遵循 nextRecommendedMaxBytes、提高 maxBytes，或打开返回的报告或证据内容 URL。
• URL 无效：更正结构化 invalid_arguments 响应中指出的字段，并使用公开的 HTTP 或 HTTPS URL 重试。
• 结果受限与失败的区别：completed_limited、no-go、not-observed 和覆盖范围有限都只是观测结果，绝不能作为合规证明。failed、expired 和连接错误属于失败，并附有重试指引。
• 找不到命令：重新运行 Homebrew 安装，并确认 Homebrew 的 bin 目录已加入 PATH。
• 缺少 API 密钥：在 MCP 客户端环境中设置 CERTSCORE_API_KEY，然后重新运行 certscore-mcp doctor。
• 令牌无效：轮换密钥，或向 [email protected] 申请具备限定作用域的 API/MCP 密钥。
• API 无法访问：检查 CERTSCORE_BASE_URL，并验证 https://certscore.ai/api/v2/health。
• Homebrew tap 过期：运行 brew update，然后重新安装 certscore-mcp。
• 缓存的版本过旧：更新 tap 后，运行 brew reinstall --cask certscore-mcp。

操作手册

Homebrew 发布步骤请参阅 docs/certscore-mcp-homebrew-release.md；密钥签发、冒烟测试、部署验证及从扫描到报告的防护措施请参阅 docs/certscore-mcp-preview-runbook.md。

托管请求诊断

托管 MCP 会保留有明确提交的工具参数和客户端元数据的有界、脱敏预览，用于运维诊断。管理界面中的 “What the caller sent” 弹窗会区分当前参数、每个请求的元数据和初始化元数据。该弹窗会记录因敏感字段、敏感内容、深度、文本、字段数量及字节预算限制而省略内容的原因。这些由调用方声明的值并非经验证的声明，也不是周边对话的副本。

整个请求详情记录仍受 4 KB 上限约束，并沿用现有的 90 天事件保留期限。预览最多包含 24 个字段，每个字符串最多 300 个字符。身份验证标头、cookie、已知凭据字段以及聊天记录/消息集合均会被排除；URL 预览仅保留源站。任务上下文的问题摘要仅在明确要求共享且注明来源时保留，不能通过通用预览路径恢复。通用预览可能显示作为单独参数明确提交的简短文本，例如 reason、notes 或 prompt；它不会获取用户的聊天内容。

只有在调用方、会话、扫描、提供方和入口点均匹配，且来源时间距当前调用不超过 24 小时时，才会单独显示先前请求中的问题上下文，并附带来源链接。缺少身份信息、已过滤的流量及无效上下文都会默认拒绝。继承的上下文不会写回当前事件，也不会改变扫描、发现项或评分行为。

按 2026 年 9 月观测到的请求量估算，额外成本低于 $0.10/月，使用现有存储和记录限制。不引入模型调用、基础设施容量变更或更长的保留期限。

完整报告证据 JSON（OAuth 和 Light）

使用 certscore_get_scan_bundle 获取简明摘要。若要获取单页或全站报告中显示的所有字段，请使用 certscore_get_report_evidence_page({scanId})。继续使用 {scanId, cursor: pagination.nextCursor}，直到 pagination.complete 为 true。这样会增加第 4 个 Light 工具；三工具的扫描 → 状态 → 数据包工作流仍是默认方式。

每个页面都包含 entries，其中包含 RFC 6901 JSON Pointer path 和 JSON value。按顺序应用这些条目，并在创建子项前创建父级容器。空路径会替换根节点。对于超长字符串，在赋值前按从零开始的 stringPart 顺序拼接 value，直到 stringParts。将路径视为数据；重建对象时使用自有属性，以防原型污染。所有页面的 snapshot 必须相同；HTTP 409 表示应在不带游标的情况下重新开始，并丢弃旧的部分导出结果。

导出内容会保留报告投影中已有的规范化发现、证据表、政策摘录、清单、同意/操作/GPC 证据及覆盖情况。完整导出不代表扫描观察完整：保留的样本、不可用的证据和报告限制仍具有权威性。不包含报告之外的原始扫描器工件和内嵌图像二进制数据。全站数据位于 fullSiteReport 下，其中包含所有页面/资源行、服务、表单和保留字段。可用的表单快照下载 URL 位于 fullSiteReport.collectionSurfaces.rows[].snapshot.url；对于工作区图像，请使用 OAuth bearer 凭据；对于符合条件的匿名公共扫描，则无需凭据。这些下载会保留现有的来源追踪和图像安全检查。被隐藏或不可用的快照不会被提升。OAuth 可读取其工作区报告和符合条件的公共扫描；Light 只能读取符合条件的匿名公共扫描。此工具不会创建扫描。现有的读取限流仍然适用；请遵守 Retry-After。

直接 JSON 端点：GET /api/v2/scans/{scanId}/report-evidence?cursor={nextCursor}。TypeScript SDK：client.getReportEvidencePage(scanId, {cursor})。

CMP/CMS 一致性：section=cmp 会返回全部 13 项标准的结果及保留的比较数据；section=cms 会返回已验证的平台/版本证据和现有公告。detailedEvidence 包含报告中共用的表述、显示标签、计数、修正步骤和交叉链接。其审计行不属于额外的规范化发现。请保留来源状态和证据限制。只有在请求时才会检索这些部分；紧凑型扫描数据包会在字节预算允许时链接到这些内容。完整导出和 section=policy 还包含保留的加州隐私选择证据和通知；面向加州的报告还包含 privacy 展示部分。已验证的控制措施与未经验证的链接候选项仍然彼此区分；不会测试选择功能。完整数据包会完整保留类型化的 Pulse 证据，并根据现有的字节上限明确省略过大的报告部分。

• certscore_get_connection_status - 读取当前经过身份验证的连接模式、已授予的范围、工作区访问权限、滚动扫描配额和恢复操作。无需扫描 ID，也不会创建扫描。使用此工具诊断只读访问或配额限制；仅当访问权限过期、被撤销或需要扩大时才重新连接。
• certscore_get_report_evidence_page - 对于具体问题，请使用 section=cmp、cms、consent、gpc、policy、tracking、transport、forms 或 accessibility。此工具会返回选定的保留报告章节，以及共享的扫描、评分、发现项和覆盖范围上下文。CMP 包含全部 13 项标准及其评估结果和保留的比较数据；CMS 包含平台/版本证据和现有公告。Policy 还包含保留的隐私选择控件、未经验证的链接候选项和通知内容；以 California 为重点的报告包含其共享的隐私章节。detailedEvidence 包含共享的显示文案、计数和交叉链接；这些审计行不属于额外的发现项。使用游标继续时，请保留 section；未选中或未返回的字段不代表相关内容不存在。请单独使用 workpaper=tracking 获取起始页的跟踪清单、隐私选择/通知和 GPC 证据，并提供 JSON 和 CSV 下载。绝不要同时使用 section 和 workpaper。workpaper 选择器也适用于每个继续请求。其他情况下，请将扫描报告的显示内容作为分页 JSON 获取，不要下载内部诊断 JSON。响应还提供单文件完整 JSON 下载；私有 JSON 下载链接在五分钟后过期，且无需 OAuth 标头；如果你的宿主阻止文件下载，请使用分页。重复的显示记录使用 reportContentRef JSON Pointers。内容包括证据表、全站页面和资源清单、所有保留的附加页面表单字段、表单快照下载引用，以及保留的限制项。快照图片需通过返回的 URL 单独下载；对于工作区扫描，需使用 OAuth bearer 身份验证。OAuth 和 Light 均可使用。请从 scanId 开始；沿着 pagination.nextCursor 继续，直到完成。各页共享同一快照；如果快照发生变化，请重新开始。每个条目都有一个 JSON Pointer 路径和值；超长字符串会拆分为带编号的部分。导出完成不代表观察覆盖范围完整。摘要请使用精简扫描包；如需详尽的报告证据，请使用此工具。此工具不会创建新的扫描。

报告证据导出页最多包含 64 KB 的 JSON 条目，在托管 MCP 和 API 上均消耗一个终端读取额度。现有的 120 次/10 分钟和每日限额仍然有效，包括重复使用游标的请求。完整证据报告、发现项导出和数据包仍消耗四个额度。如果较大的导出触及限额，请保留最后一个 nextCursor，等待 Retry-After 后继续，而不要重新开始。

完整报告 JSON 下载

certscore_get_scan_bundle 仍是获取精简摘要的默认方式。要导出完整 报告，请调用一次 certscore_get_report_evidence_page：download.url 会在一个 HTTP 响应中返回完整的报告显示 JSON，并附带其字节大小。工作区下载 URL 包含一个仅限报告使用的功能凭据，有效期为五分钟。直接获取返回的 URL，无需携带 OAuth 标头。请将私有链接视为机密信息，不要公开发布。链接过期后，请请求一个新页面以获取新链接。符合条件的公开报告仍可匿名下载。 如果宿主无法获取需要身份验证的文件，请改用 MCP 沿着 pagination.nextCursor 继续。这无需添加其他连接器。

导出不包含诊断 JSON 下载和内部运行时图。重复记录使用导出文档中的 reportContentRef RFC 6901 指针；加载文档后再解析这些指针。表单字段、清单行、覆盖范围限制和可用的快照链接仍会包含在内。图片字节需单独下载。下载使用现有的报告读取配额，不会创建新的扫描或已存储的导出产物。必须单独测试宿主是否支持实际下载；返回 URL 并不能证明 Cursor 或 Claude 可以获取它。

隐私与追踪工作底稿（0.2.24）

当有经过验证的保留证据时，certscore_get_scan_bundle 会包含 privacyAuditSummary：观察到的隐私选择控件、通知主题、来源哈希和保留数量。detail=full 还会包含 privacyAuditEvidence。因字节预算而省略的内容会列在 mcpMetadata.omittedSections 中；缺少某个部分并不能证明控件或通知不存在。

使用现有读取器获取起始页面清单和工作底稿：

{"scanId":"00000000-0000-4000-8000-000000000123","workpaper":"tracking"}

将这些参数传递给 certscore_get_report_evidence_page。它会返回分页 JSON 条目、JSON 工作底稿的 download.url 和清单 CSV 的 download.csvUrl。每次使用游标继续请求时，都要保留 workpaper。此功能适用于 OAuth 和 Light，并遵守现有的工作区／公共访问边界及读取配额；不会创建扫描。请对五分钟有效的私有下载链接保密。

在 GPC 摘要开头列出返回的观察事实，以及存在时的 gpcResponse.activityComparison 请求计数。保留与这些计数匹配的时长。将“禁止出售／共享”控件是否存在以及保留的通知段落作为观察结果报告；不要推断选择退出是否有效、通知是否充分、是否发生出售／共享，或是否遵循 GPC。历史记录保持不变，分数仍为现有的 CertScore 分数。

聚焦报告部分（0.2.26）

针对具体问题，使用现有的 scanId 和一个 section 调用 certscore_get_report_evidence_page：consent、gpc、policy、tracking、transport 或 forms。每次使用返回的游标时，都要保留此选择器。共享的扫描标识、分数、发现项和覆盖范围均保持不变。选择在去重前进行，因此引用始终位于所选文档内。selection.notReturnedFields 描述的是未交付的内容，不代表经验证不存在。JSON 下载链接会保留所选部分。起始页面工作底稿和 CSV 请单独使用 workpaper="tracking"；切勿同时使用 section 和 workpaper。不会执行额外扫描、模型调用或证据采集。