mcp-trust

MCP Trust Registry

连接前先检查。为 AI Agent 所依赖的 MCP 服务提供中立、公开的危险等级。

在线版： mcp-trust.vercel.app

尚未发布到 PyPI。 请使用下方的快速入门从源代码安装。

用作 MCP 服务

mcp-trust 以只读 MCP 服务的形式运行，让 Agent 能在连接前检查服务的危险等级——它提供真实扫描等级的内置快照，并明确标注每条记录的来源，因此无需数据库或网络。

mcp-trust mcp-serve          # from a source/dev install (works today)
uvx mcp-trust mcp-serve      # once published to PyPI

工具	描述
list_servers	所有已评定等级的 MCP 服务，以及其 A-F 等级、透明度和危险分数。
check_server	通过 slug 查询单个服务的完整等级、风险维度和发现项。
get_methodology	A-F 等级和透明度维度的计算方式，以及诚信模型。

MCP 运行时只有在通过确定性的 schema-v2 验证后，才会接纳打包的目录。验证包括拒绝重复键、检查必需字段和类型、验证 slug 和来源坐标唯一性、检查受支持的枚举值、确认沙箱与扫描模式一致，以及确认扫描时间戳包含时区信息。接纳流程还会验证等级与危险分数之间的关系、透明度与注释覆盖率之间的关系，以及关键发现项与等级上限之间的关系。原始 JSON 大小上限为 1 MiB，并设有确定性的服务、发现项、工具和公开字符串数量上限。Schema v2 会保留新增的未知字段；缺少或无效的必需字段以及未知的 schema 版本均会导致验证失败。

如果目录未能通过接纳验证，list_servers 和 check_server 将不提供任何记录，并返回 mcp-trust-mcp-error.v1，其中包含状态 UNKNOWN、错误代码 CATALOG_SNAPSHOT_INVALID、排序后的原因代码，以及 server_count_served: 0。get_methodology 仍可使用。此边界会检查内部一致性，但不能证明快照的真实性、作者身份、不可变性或时效性。

离线使用者可以通过 mcp-trust verify-snapshot 补充这些缺失的发布检查：一份独立的 Ed25519 声明会绑定确切的快照字节、发布者 ID、有界的签发/过期时间窗口、单调递增的发布 ID，以及先前的使用者检查点。使用者必须独立固定信任根 SHA-256，并保存返回的检查点，以防回滚。对于无效、过期、签名者未知、存在分叉或已回滚的输入，只会返回 UNKNOWN 原因代码，不会返回任何等级。请参阅 docs/OFFLINE-SNAPSHOT-TRUST-V1.md。 声明时效性证明的是近期发布授权，而非近期扫描；每条记录的扫描时间戳和 90 天过期策略仍是独立检查。

目前尚未随附生产环境信任根、签名密钥、声明或检查点，因此除非使用者另行提供并固定这些输入，否则内置 MCP 快照仍仅经过结构验证。测试夹具密钥并非发布密钥。

连接 MCP 服务意味着赋予它影响 Agent 行为的能力。工具投毒、提示词注入、权限过宽和工具突变式抽逃都是有记录的攻击类型——而目前还没有快捷的方法能在接入服务前对其进行审查。MCP Trust Registry 会扫描公开的 MCP 服务，为每个服务提供一个直观的危险等级（A-F）、单独的透明度信号，以及相应的发现项。

可以把它看作 OSV.dev / Socket.dev / haveibeenpwned，专门面向 MCP 服务。

前提条件

• Python 3.12 或更高版本；.python-version 为本地设置固定了 3.15.0
• uv（用于依赖管理和运行项目）

项目要求使用 uv==0.13.0。请在仓库根目录运行以下命令；uv sync 会使用已提交的锁文件创建项目虚拟环境。

MCP 配置可移植性工作室

将一个带版本号且仅含密钥占位符的 MCP 连接意图，渲染为暂存的 Codex、Claude Code、Claude Desktop 或 VS Code 配置，并接收明确的语义损失／扩展报告：

uv run --frozen --extra dev mcp-trust portability validate \
  tests/fixtures/portability/local-stdio.json
uv run --frozen --extra dev mcp-trust portability round-trip \
  tests/fixtures/portability/local-stdio.json --host codex

该工作室仅在本地运行。它不会发现或编辑真实的主机配置、 启动 MCP 服务、联系 URL，也不会输出建模的密钥值。生成的 配置仅证明与有文档记录的主机格式兼容，不代表运行时连接或已采用。请参阅 docs/MCP-CONFIG-PORTABILITY-STUDIO.md。

工作原理

register a server  ->  scan via engine  ->  derive grade  ->  persist  ->  serve at a stable URL

该注册表不会重新实现漏洞检测。它负责协调可插拔的扫描引擎——随附的后端封装了公开的 mcp-audits (>=2.7.0,<3) 软件包——并负责管理 目录、公开信任等级的规范化、持久化和查询 API。

快速入门

git clone https://github.com/saagpatel/mcp-trust.git
cd mcp-trust
uv sync --frozen --extra dev

demo_dir="$(mktemp -d)"
uv run --no-sync mcp-trust seed --db "$demo_dir/registry.db"
env -u MCP_TRUST_RECEIPTS_DIR uv run --no-sync mcp-trust scan \
  mcp-reference-time --engine stub --db "$demo_dir/registry.db"
uv run --no-sync mcp-trust check mcp-reference-time --db "$demo_dir/registry.db"

安装依赖项后，此演示只会使用一个新建的临时 SQLite 数据库和显式指定的 StubEngine；它不会启动目录服务，且其 等级为演示数据。--db 可避免使用默认数据库及任何操作员设置的 MCP_TRUST_DB 覆盖值；清除 MCP_TRUST_RECEIPTS_DIR 可避免写入操作员的 收据目录。

若要通过本地 API 查看此演示，可以选择启动一个仅绑定环回接口的只读服务， 并在完成后按 Ctrl-C 将其停止：

MCP_TRUST_ENGINE=stub MCP_TRUST_PUBLIC_READONLY=1 \
  MCP_TRUST_MASKED_GRADES="$PWD/masked-grades.json" \
  uv run --no-sync mcp-trust serve --db "$demo_dir/registry.db" \
    --host 127.0.0.1 --port 8000

真实引擎扫描需要单独准备的 [engine] 环境、 经审核的目标、沙箱决策，以及操作员运行手册中当前的资质认定／预检证据。此类扫描可能启动 服务进程或联系远程端点，不属于此本地演示 和常规验证的范围。有关固定样例检查，请参阅本地开发和验证。

API

方法	路径	用途
GET	/	网页 -- 公共目录页面（每个服务的等级 + 透明度）
GET	/ui/servers/{slug}	网页 -- 服务详情页面 + README 徽章嵌入代码片段
GET	/healthz	存活状态
GET	/servers	目录 + 每个服务的最新等级、来源信息和过期状态（JSON）
GET	/servers/{slug}	完整的最新扫描记录 + 来源信息、过期状态和元数据（JSON）
POST	/servers/{slug}/scan	由运营人员触发扫描；公共部署会禁用此路由
GET	/servers/{slug}/badge.json	与 shields.io 兼容的 README 徽章

每个服务都有两个相互独立的信号：危险等级（A-F）和 透明度级别（高/中/低，依据注释覆盖率）。自动生成的等级并非对服务的背书、 认证，也不代表声称服务具有恶意行为。低透明度服务的低等级意味着“无法验证其安全性”， 而非“已知危险”。

默认情况下，HTTP 扫描触发采用失败关闭策略。公共部署应设置 MCP_TRUST_PUBLIC_READONLY=1，使 POST /servers/{slug}/scan 在任何引擎运行前返回 403。运营人员通常应通过 CLI 对持久化注册表数据库执行扫描，而非通过公共流量触发扫描。

使用确定性的 StubEngine 进行本地 API 演示时，请设置 MCP_TRUST_ALLOW_UNAUTHENTICATED_STUB_SCANS=1。在公共环境中不要设置此项。 私有运营人员界面仍可通过令牌门控触发 API 扫描：设置 MCP_TRUST_SCAN_TOKEN，并将其作为 Authorization: Bearer <token> 或 X-MCP-Trust-Scan-Token 传入。

如果最新存储的扫描记录行不可读，API、网页、静态页面、徽章和 快照投影都会失败关闭并返回 UNKNOWN；它们绝不会恢复使用较早的 等级。存储的来源/风险/发现项/证据 JSON 每个字段的准入上限为 1 MiB，且发现项/工具集合有数量限制，并提供不含内容的诊断信息。 较早的记录行不可读时，可读的最新等级仍会保留，但扫描 历史记录和等级变化声明会明确标为 UNKNOWN。修复或处置不可读的历史记录之前， 快照构建会停止。

所有公共界面使用统一的失败关闭新鲜度投影。扫描后恰好 90 天仍为 FRESH； 之后的任何时刻均为 STALE。缺失、格式错误或时间在未来的扫描时间会标为 UNKNOWN， 并隐藏判定字段。未扫描的条目为 NOT_APPLICABLE。即使不存在扫描记录，运营人员屏蔽设置仍会生效，且绝不会根据扫描状态推断该设置。静态页面和徽章是不可变的历史证据，并附有扫描日期或有效期边界；它们不承诺在请求时仍然是最新的。危险性、透明度和证据质量仍是相互独立的信号，等级绝不是背书。

在真实扫描运行期间设置 MCP_TRUST_RECEIPTS_DIR=/data/mcp-trust/receipts，以便 为每次扫描存档一份 JSON 回执，并将其可移植的制品文件名存入 report_ref。

远程授权元数据预检

Remote Registry 候选项可以在不联系 MCP 端点或处理凭据的情况下，检查是否存在可发现的 MCP 授权元数据。首先，根据之前保存的官方 Registry 响应生成候选清单，然后选择一个确切的 stable_id：

uv run python scripts/plan_registry_corpus.py \
  --input path/to/saved-registry-response.json > /tmp/registry-candidates.json

uv run mcp-trust auth-posture com.example/[email protected] \
  --manifest /tmp/registry-candidates.json \
  --pretty

如果已通过单独的操作员工作流获取公开的 WWW-Authenticate: Bearer 挑战，请使用 --www-authenticate 传入其值。否则，该命令会先尝试 MCP 要求的受保护资源 well-known 路径，然后按规范顺序尝试 RFC 8414 和 OpenID Connect 授权服务器发现。

该命令会输出 McpAuthorizationPostureV1 JSON。退出码为 0 且 state=metadata-ready 仅表示至少有一个授权服务器公开了策略审查所需的端点和 PKCE S256 元数据。这并不能证明已获得授权、凭据可用、运行时安全、符合扫描条件或具有信任等级。未知或无效的证据会以退出码 1 结束，并保持阻止状态；本地清单绑定无效则以退出码 2 结束。

网络边界刻意保持狭窄：仅允许 HTTPS 元数据 GET 请求，不使用环境代理、重定向或凭据，不建立端点会话，也不执行写入。每个请求只解析一次 DNS；所有解析结果都必须可在全球范围内路由，并且连接会固定到经接受的地址，同时 TLS 验证和 SNI 仍绑定到原始主机名。响应正文有大小限制，会经过验证，输出中仅以字节数和 SHA-256 表示。成功的元数据响应还必须包含有效的 HTTP Date；声明的缓存有效期最多遵循 24 小时的策略上限，而缺失、日期在未来或已过期的源证据仍视为未知。实现依据包括 MCP 授权规范、RFC 9728、RFC 8414 和 OpenID Connect 发现。

可复用的 Web 发布回读

本仓库负责维护与语言无关的 WebReleaseReadbackV1 契约及其标准库参考验证器。使用者需提供明确的 HTTPS 源站和带版本的路由哨兵清单：

python scripts/web_release_readback.py \
  --manifest path/to/release-routes.json \
  --target-url https://preview.example.com \
  --pretty

该命令会向 stdout 输出一份结构化回执；如果任何状态、必需或禁止的哨兵、精确正文、摘要、正文大小限制、超时或重定向断言失败，则以非零状态码退出。它仅实现 GET 和 HEAD，不使用环境代理，不接受凭据，也不具备部署、别名、DNS、晋级或回滚能力。架构、确定性制品清单、版本策略和回滚边界位于 contracts/web-release-readback-v1/ 下。

所有者仓库还通过 deploy/web-release-readback.json 使用此契约。deploy/smoke-readonly.sh 会先输出共享路由回执，然后运行针对 Registry 的健康状况、API、徽章、便携式回执引用及拒绝扫描 POST 断言。这种自采用仅用于发布回读检查；它既不会部署，也不会更改别名。

此通用回执是增补项。在有证据证明回执等效性足以支持移除重复的 HTTP 断言代码之前，产品专属的 API、徽章、隐私、发布沿袭和拒绝变更检查仍由各使用者负责。

证据沿袭决策

EvidenceLineageLedgerV1 是一份仅包含元数据、默认拒绝的合约，用于 MCP 语料库的准入、刷新、发布和撤回决策。它绑定精确身份、摘要、可移植的凭证引用、新鲜度、权利证据、公开投影、替代关系和保留期限，而不存储原始日志或机密信息。只读评估器要求明确的观测时间，并生成稳定的原因代码；只有明确的 ALLOWED 状态才能授权准入或发布。

有关架构、决策语义、包含三条记录的打包目录试点、声明上限和回滚边界，请参阅 docs/EVIDENCE-LINEAGE-LEDGER-V1.md。此源能力本身不会迁移目录、发布或撤回记录、运行扫描，也不会更改部署状态。

手动刷新候选项

首先生成不执行操作的清单、精确的源代码／工具／镜像预检，以及确定性的重复样本凭证：

运行时刷新命令要求单独准备冻结的 [engine] 环境。它们使用该环境中的精确解释器，并且不会在预检或创建候选项的过程中安装依赖项：

PYTHON=./.venv/bin/python
test -x "$PYTHON"

"$PYTHON" scripts/grade_refresh.py engine-materialization \
  --repo-root "$PWD" \
  --out ./dist/grade-refresh/engine-materialization.json
"$PYTHON" scripts/grade_refresh.py inventory \
  --out ./dist/grade-refresh/inventory.json
"$PYTHON" scripts/grade_refresh.py host-capacity \
  --anchor "$PWD" \
  --out ./dist/grade-refresh/host-capacity.json

# Stop unless the two-reading receipt is READY. Start the separately approved
# Colima instance only after this point, then create the bound preflight.
"$PYTHON" scripts/grade_refresh.py preflight \
  --repo-root "$PWD" \
  --engine-materialization ./dist/grade-refresh/engine-materialization.json \
  --host-capacity ./dist/grade-refresh/host-capacity.json \
  --out ./dist/grade-refresh/preflight.json
uv run --frozen --extra dev python scripts/grade_refresh.py fixture-repeat \
  --out ./dist/grade-refresh/fixture-repeatability.json

容量凭证要求至少有 5 GiB 可用空间，且两次读数间隔至少 30 秒、容量均低于 100％。在执行 Docker、MCP 或注册表数据库操作前会重新验证；凭证在 120 秒后过期，并绑定主机文件系统设备，而不会记录主机路径。源合约本身无法证明操作员在凭证通过前一直保持 Colima 停止状态，也无法针对同一用户的替换操作验证观测结果；如果没有单独密封的操作员绑定，来源信息仍为 UNKNOWN。 离线镜像资格认定要求每次调用都使用一份新观测、限定到对应批次的凭证。凭证集合只增不减；五个批次都使用同一个新的、经审核的集合名称，但绝不可在不同批次间重复使用容量凭证：

: "${MCP_TRUST_QUALIFICATION_RECEIPT_SET:?set a new reviewed task-owned receipt-set name}"
for cohort in reference live-batch batch3 batch4 basic-memory; do
  uv run --frozen python scripts/grade_refresh.py qualification-capacity \
    --operation qualification \
    --receipt-set "${MCP_TRUST_QUALIFICATION_RECEIPT_SET}" \
    --cohort "$cohort" \
    --out "./dist/grade-refresh/qualification-capacity-$cohort.json"
  uv run --frozen python scripts/qualify_refresh_images.py \
    --cohort "$cohort" \
    --host-capacity "./dist/grade-refresh/qualification-capacity-$cohort.json" \
    --receipt-set "${MCP_TRUST_QUALIFICATION_RECEIPT_SET}"
done

src/mcp_trust/catalog/refresh_policy.json 中精确指定的五个 qualification_receipt 路径具有权威性；文档中的版本标签永远不具权威性。 限定器会创建不可变的源/输入绑定集合清单，并在首次 Docker 变更前写入悲观的仅追加尝试意图。每次启动 Docker 或 Buildx 子进程前，它都会重新验证绑定回执，且绝不续期。如果容量到期或倒退，则不会生成资格验证回执，意图也会保持未解决状态，因此 Docker 状态和资格验证状态均为 UNKNOWN。重试该批次前，请使用 --operation cleanup 签发新回执，并使用 --cleanup-cohort "$cohort" 运行限定器；清理操作仅针对精确记录的标签和输出，并且必须追加一份成功的回读回执。缺少不可变清单的现有集合、未知构件、被覆盖的回执，以及源或输入漂移都会被拒绝。成功构建会追加资格验证完成绑定；只有中断的尝试才需要清理完成记录。资格验证清单会将其起始修订版保留为溯源信息，但会依据资格验证专用摘要映射重新打开。该映射包含限定器及其运行时模块、Dockerfile、依赖输入、锁文件、构件描述符和嵌套的源构建证据。生成的 docker/refresh/qualification/ 证据和 refresh_policy.json 回执指针属于采纳元数据，因此跟踪它们不会导致已完成集合自我失效；每次构建前都会依据描述符摘要独立重新验证依赖包字节，而回执和图完整性仍必须独立满足。 任何可执行文件或构建输入的漂移仍会导致安全失败。每个集合的进程锁和唯一于每次尝试的临时标签，可防止并发资格验证共享变更状态。中断清理仅移除意图中记录的 OCI、验证回执和摘要绑定的工具快照残留。它绝不会重写最终标签：回读必须显示记录的基线或任务独占的精确镜像 ID；任何其他值都视为有歧义，并会被阻止。 只有预检返回 READY，才能执行目录服务器。该回执绑定 31 项分类，包括精确推导出的 22 项可扫描和 9 项阻止执行边界、源和策略摘要、工具版本、本地 Docker 权限、不可变镜像 ID，以及明确的网络、文件系统、资源和机密控制。请参阅 docs/GRADE-REFRESH-PROGRAM.md 和 操作员运行手册。

创建评审候选项，但不更改规范注册表、烘焙快照、静态站点、计划或部署：

"$PYTHON" scripts/refresh_candidate.py create \
  --db ./registry.db \
  --out-dir ./dist/refresh-candidates \
  --qualification-receipt ./dist/grade-refresh/preflight.json

只有在绑定的预检回执仍有效且状态为 READY，并且 Docker 和每个由目录固定的镜像都已在本地以记录的不可变 ID 提供时，该命令才会执行本地进程扫描。这些源会在现有的禁用网络、只读、移除能力并限制资源的沙箱中运行。每个本地容器都会预先创建，且连接器被绑定为仅启动该不可变 ID；只有绑定的守护进程证明容器已不存在后，才会接受扫描证据。若超时后没有此类回读，状态仍为 UNKNOWN。远程端点会通过其实际网络传输进行探测，不使用本地进程沙箱，并会据此标记。新的不可变包使用 RefreshCandidateV2，包含自带摘要的执行绑定回执、目录身份、扫描时间和扫描年龄、受阻/屏蔽/失败/超时/未知证据状态、归因的扫描漂移、如实的静态快照、源/工具绑定、新鲜度计数和最早过期时间、语义投影摘要，以及内容绑定清单。旧版 V1 包在结构上仍可检查，但不具备发布资格。 候选项创建不具备发布或部署权限。结构验证会分别报告架构有效性和发布资格；有效的 V1 工件不能通过自我声明获得 V2 权限。当前、完整且绑定经审核输入的 V2 候选项，只能作为后续本地准入的输入。资格绝不会授予批准、发布、部署、回滚、调度或联络权限。

可以验证单独提供的 McpTrustPublicationApprovalV1，并用它构建确定性的本地只读副本包：

uv run --frozen python scripts/build_publication_package.py \
  --verify-approval ./dist/publication-approval.json \
  --candidate ./dist/site-candidates/<name>
uv run --frozen python scripts/build_publication_package.py --build \
  --candidate ./dist/site-candidates/<name> \
  --approval ./dist/publication-approval.json \
  --out ./dist/publication-packages/<name>
uv run --frozen python scripts/build_publication_package.py \
  --verify-package ./dist/publication-packages/<name> \
  --approval ./dist/publication-approval.json

此准入过程无需供应方参与，且仅在本地进行。它绑定 V2 候选项、可重复性和分诊溯源、确切的 V38 审核、当前供应方证据、回滚目标、操作员声明摘要以及最短有效期。所有变更权限仍为 false。软件包不代表部署权限、发布证明、回滚权限、调度器权限、背书或生产时效性证据。

手动静态部署通道需要单独的短期 McpTrustProductionDeployAuthorizationV4 绑定，该绑定需关联确切的软件包、内容批准、供应方和操作员回执、保留的回滚字节、源代码修订版本、输出和工具摘要。它会在实时 TTY 确认前后重新验证。任何供应方调用后，时效性仍为 UNKNOWN，直至供应方和源代码绑定的 McpTrustProductionPublicationReceiptV1 验证确切的全路由回读回执。缺失的供应方工件摘要绝不能提升为 FRESH。

快照签名是在候选项批准／暂存之后的独立权限。刷新流程永远不会获得签名密钥或恢复密钥，其 SHA-256 清单也不是发布者身份。在操作员根据离线信任契约选择根密钥、保管机制、阈值、发布计数器和检查点所有者之前，生产签名仍处于禁用状态。

状态

技术栈

该项目使用 Python、FastAPI、SQLite、Typer、Pydantic、作为可选扫描引擎的 mcp-audits、Ruff、Pyright 和 pytest。依赖项版本已锁定在 uv.lock 中；该项目需要 Python 3.12 或更高版本。

已知风险

目前已在 mcp-trust.vercel.app 上线，作为静态生成的目录，并根据本地注册表重新生成。捆绑的目录快照包含 23 条可见的真实 mcp-audits 评级；其中没有八条种子条目，包括目前由 masked-grades.json 隐藏的四条。捆绑快照将可见的本地进程评级的网络和沙箱来源标记为未知；只有经过回执验证的刷新候选项才能声称执行时未联网。每条评级都标注了来源，因此演示／存根数据绝不会被误认为真实扫描结果，未扫描的服务也不会显示字母评级。当前生产部署是包含 31 个服务的静态目录；自 2026-07-11 起，评级均为静态数据。当周重新扫描通道已停用，且部署权限已移除（参见 docs/CAPABILITY-RULING-2026-07-10.md）。

静态入口是低运维的启动路径（参见 DEPLOY-VERCEL.md）；deploy/launchd/ 下的每周 launchd 任务已持续停用，当前主机回读结果显示其已卸载。一个休眠的已安装 plist 仍然存在，且与仓库模板不一致；应将其视为配置漂移，不要加载或启用它。兼容入口只能在执行前预检之后创建本地审核候选项；它不能发布或部署。作为替代方案，文档 DEPLOY-VM.md 仍介绍了在线 FastAPI 服务和 VM 路径。完整契约参见 SPEC.md，启动历史参见 LAUNCH-GATE.md。已部署的目录以扫描时间戳作为新鲜度依据；静态 HTML 不声称能够证明机器本地的调度器状态。

因此，已部署的目录可能过时。在线 URL 的响应可能来自缓存；本仓库说明无法验证当前目录内容的新近程度。静态 HTML 的新鲜度不能证明当前调度器状态，本地测试也无法确认在线提供方或部署行为。本仓库说明同样无法验证当前 GitHub Actions 状态。

在这台 macOS 主机上，Python 3.15.0 需要从源码构建已锁定的 pydantic-core 2.46.4；构建已完成，但其扩展加载失败。完整的 Python 3.15 CI 结果尚未验证。支持的 CI 矩阵仍为 3.12 至 3.15，等待该托管检查完成。

后续步骤

贡献

为确保在不同环境中可复现安装，仓库有意提交了 uv.lock。添加或更新依赖项时，请将更新后的 uv.lock 与 pyproject.toml 的更改一并提交。

运行 make setup 安装冻结的开发依赖项，并运行 make check 执行本地综合检查。

本地开发与验证

在仓库根目录运行 make setup。这与 CI 使用相同的核心/开发环境；它不会安装可选的真实扫描引擎。准备一个使用临时数据库且未设置操作员扫描/收据覆盖项的开发 Shell：

verification_dir="$(mktemp -d)"
export MCP_TRUST_DB="$verification_dir/registry.db"
export MCP_TRUST_ENGINE=stub
export MCP_TRUST_PUBLIC_READONLY=0
unset MCP_TRUST_MASKED_GRADES MCP_TRUST_RECEIPTS_DIR \
  MCP_TRUST_RUN_INTEGRATION MCP_TRUST_RUN_DOCKER_RUNTIME_READBACK

# Focused CLI/API fixtures; choose the test file or node for your changed module.
uv run --no-sync pytest -q tests/test_cli.py tests/test_api.py
# Aggregate deterministic local gate, as used by CI.
make check

测试夹具使用临时数据，并模拟运行时/提供方边界。两个集成测试选项都应保持未设置：MCP_TRUST_RUN_INTEGRATION=1 会启动真实的 MCP 服务，而 MCP_TRUST_RUN_DOCKER_RUNTIME_READBACK=1 会使用 Docker。这些检查需要单独的操作员授权和前置条件；它们不属于常规检查门槛。完整测试套件包含 POSIX 伪终端测试；如果本地平台无法提供伪终端，请使用 Ubuntu CI 运行器。对于负载较高的机器，MCP_TRUST_TEST_TTY_TIMEOUT 可调整这些测试的子进程时限，而不会降低断言要求。

make check 会运行 Ruff lint 和格式检查、Pyright、pytest 以及软件包构建。对于 Web/静态资源/徽章相关改动，请重点运行 tests/test_web.py、tests/test_site_generator.py、tests/test_build_site_script.py 和 tests/test_api.py，然后在交付前运行更全面的检查门槛。

当 HTML、布局、导航或展示的信任声明发生变化时，还应在本地浏览器中检查桌面宽度和窄屏宽度下的预览。使用明确的临时路径和脚本的纯存根演示模式构建：

uv run --no-sync python scripts/build_site.py \
  --db "$verification_dir/preview.db" --out "$verification_dir/site" \
  --demo-fill --base-url http://127.0.0.1:8765
uv run --no-sync python -m http.server 8765 --bind 127.0.0.1 \
  --directory "$verification_dir/site"

打开 http://127.0.0.1:8765，并检查目录、一个详情页、导航、演示/来源标签、脱敏等级和徽章内容。按 Ctrl-C 停止预览。此开发构建只会写入临时演示数据和页面；它不是可发布的候选版本。仅当用户可见行为发生变化时才需要进行浏览器检查，纯文档改动则不需要。API 和 Web/静态资源指南定义了必须在各界面保持一致的信任声明。本地测试夹具/构建/浏览器检查结果无法证明真实引擎、提供方、部署或生产环境的实际情况。

许可证

MIT