litmus

litmus

面向 MCP 服务的开放式行为测试工具，可给出 A–F 等级，并支持复现。

一条命令为服务评级

# -p is required: the package ships three bins, so npx must be told which to run
npx -y -p @polygraphso/litmus polygraphso-litmus litmus npm/@modelcontextprotocol/server-filesystem

可指定 npm 引用、pypi 引用、github/owner/repo 引用（会克隆、构建并在沙盒中运行，需要 Docker；评级会固定到 commit SHA）、https:// MCP 端点或本地入口文件。测试工具会像 Agent 一样连接服务，记录其完整工具接口特征，运行四类探测，并输出评级及其依据，还会在磁盘上生成确定性证据包。 它会运行目标代码（出站流量由 Docker 沙盒隔离；未安装 Docker 时会跳过 C-02，评级最高为 B），耗时约 20–60s；若结果为 D/F，则会以非零状态码退出，因此可在任何地方用于脚本。若要质疑已发布的评级，可针对同一服务重新运行此命令——开放且确定意味着重新运行会复现该评级，或证明其不成立。

查询他人已发布的评级只需不到一秒，且不会运行任何内容：可查看 polygraph.so 索引，或使用下方 MCP 工具中的 check_server。

在你的 Agent 中使用 — MCP 服务 + 插件

查询评级时，将任意 MCP 客户端指向 polygraph 托管的端点，无需安装：

claude mcp add --transport http polygraph https://polygraph.so/api/mcp

或使用原始配置：

{ "mcpServers": { "polygraph": { "url": "https://polygraph.so/api/mcp" } } }

此端点仅提供查询工具（check_server、list_servers、request_grade）；自行对服务进行评级（run_litmus、run_skill_litmus）会执行其代码，因此需要使用下方的本地 stdio 安装方式。

此软件包还附带一个 stdio MCP 服务（polygraphso-litmus-mcp），提供完整工具集，可供任何支持 MCP 的客户端使用：

• check_server — 在不到一秒内读取服务已发布的评级（不执行代码）；在推荐或安装服务前进行预检。
• list_servers — 列出已发布评级的服务，按 A 级优先；支持分页（每次调用默认 25 个，并提供 grade/limit/offset 筛选器和完整语料库摘要）。
• request_grade — 在 polygraph.so 提交评级请求（一次性收费 1 美元；付款后 48 小时内完成评级——响应中会附带付款链接）。
• run_litmus — 立即为服务评级：运行完整测试框架，并将评级和证据返回给 Agent。
• run_skill_litmus — 为 Claude Code / Agent Skill 评级（静态扫描，A/B/D/F）。
• verify_attestation — 读取已发布评级背后的链上证明（Base 上的 EAS）。

在 Claude Code 中，插件可一步配置服务和两个命令：

/plugin marketplace add polygraphso/litmus
/plugin install polygraph@polygraphso

然后使用 /polygraph:grade <server> 和 /polygraph:check <server>。Cursor 和手动 JSON 配置请见 polygraph.so；完整工具文档请见 packages/litmus/README.md。

在 CI 中使用 MCP 评级作为门禁 — GitHub Action

当 MCP 服务或其提供的 Agent Skill 在开放行为基准测试中获得 D/F 评级时，让构建失败。对于服务，该操作采用混合方式：先快速查询已发布的评级，若尚未评级则运行测试框架；对于 Skill，则进行快速静态扫描。无法评级的目标会发出警告，除非启用了 strict。

它已上架 GitHub Marketplace，名称为 polygraphso/litmus@v1。作为安全门禁时，请固定到某个提交 SHA，而不是可变的 @v1 标签：

# .github/workflows/mcp-gate.yml
name: mcp-gate
on: [pull_request]            # NOT pull_request_target — that exposes secrets to fork PRs
permissions:
  contents: read
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: polygraphso/litmus@<commit-sha>   # pin to a SHA; resolve from the v1 release
        with:
          # Name the targets explicitly (recommended). Grading runs a server's code,
          # so on a public repo prefer an allowlist over discovering PR-controlled config:
          servers: |
            npm/@modelcontextprotocol/server-filesystem
          skills: |
            ./my-skill
          # discover: "true"  # opt in to auto-discovery (.mcp.json/.vscode/.cursor) — trusted repos only
          # min-grade: B      # stricter than the default D/F gate
          # strict: "true"    # also fail on targets that cannot be graded

输入项： servers · skills · discover（默认 false）· min-grade · strict · working-directory · version · bearer。输出项： result · failed · report。

安全。 为服务评级会运行其代码（出口流量受 Docker 沙箱限制，但仍会执行代码）。 请使用 pull_request 触发，绝不要使用 pull_request_target。在公开仓库中请关闭 discover，并明确指定目标——自动发现的配置可由拉取请求控制。bearer 会作为 Authorization 标头发送给目标，因此只能用于明确可信且固定的远程服务——绝不要与自动发现功能或不受信任的 PR 一起使用，并确保其作用范围受限且有效期较短。

不使用 GitHub？此门禁只是一个普通命令——npx @polygraphso/[email protected] ci（请固定版本）——可在任何 CI 中运行，也可用作提交前钩子。评级是一次测量，并非保证：请重新运行开放测试框架以复现任何结果。

litmus 是什么

这是 @polygraphso/litmus 的源码，它是来自 polygraph.so 的 MCP 服务开源行为测试工具。

该测试工具会像 Agent 一样连接 MCP 服务，精确识别其工具范围，并运行四类探测——C-01 工具输出注入（静态、动态和二阶注入——将一个工具的输出武器化，作为另一个工具的输入）、C-02 权限／外联（在默认拒绝的强化 Docker 沙箱中，匹配主机和端口）、C-03 敏感数据处理（植入金丝雀）、C-04 对抗性输入处理（格式错误／超大输入和越狱输入）——然后对服务进行 A–F 评级。通过评级是一项测量结果，并非保证；方法论及其公开说明的局限请见 polygraph.so（这里的开源代码才是事实依据）。

除了评级外，还会根据 osv.dev 漏洞数据库检查 npm 目标的依赖树，并报告任何存在漏洞的依赖，作为依赖项安全公告。这是单独的、某一时点的信号，仅供参考：它不会影响 A–F 评级，也不属于可复现证据（漏洞数据会随时间变化，因此将其纳入评级会破坏重跑的可复现性）。此检查仅适用于 npm 目标；其他目标类型会将其报告为已跳过。解析依赖时会运行 npm install --package-lock-only --ignore-scripts，只解析依赖树，不会下载 tarball 或运行任何软件包代码。可通过 --no-deps-audit（或 LITMUS_DEPS_AUDIT=0）选择退出。

同一软件包还会对 Claude Code / Agent Skills（一个 SKILL.md 文件及其捆绑内容）进行评级，采用独立的静态 litmus（litmus-skill-v3）：确定性的字节扫描——检查 S-01 提示词注入、S-03 数据外泄指令、S-04 SKILL.md 正文或捆绑脚本中的危险命令（包括经 base64 混淆的 curl | bash）——评级为 A/B/D/F，并以整个目录的内容哈希作为锚点，另提供单独的质量参考信号。它是静态检查（不执行）：A 代表静态检查干净，并非行为证明。请参阅 packages/litmus/README.md。

托管式、由运营方运行的评级服务不在此代码库中——它位于单独的私有代码库，并像其他客户端一样从 npm 使用此软件包。

目录结构

这是一个 pnpm monorepo。只有 @polygraphso/litmus 会发布；@polygraph/* 软件包是私有构建模块，由 tsup 打包进该软件包。

packages/
  litmus/          # @polygraphso/litmus — the only published package (lib + 3 bins: CLI, skill CLI, MCP)
  core/            # contract types, canonical JSON, identity helpers
  probes/          # the harness: connect, fingerprint, grade, probe runners, sandbox
  onchain/         # EAS attestation read + encode/decode (Base) — read-only, no minting
  agent/           # agent-gate decision logic + live-fingerprint recheck
  mcp/             # MCP server wrapper
  cli/             # CLI commands + target/auth resolution
  demo-*-mcp/      # demo MCP servers used as test fixtures

npm 使用文档请参阅 packages/litmus/README.md，方法论和证明格式请参阅 polygraph.so。

开发

pnpm install
pnpm -r typecheck
pnpm -r test
pnpm --filter @polygraphso/litmus build   # → packages/litmus/dist

发布

@polygraphso/litmus 的版本在 packages/litmus/package.json 中管理。创建标签即可发布：

git tag litmus-v<x.y.z> && git push origin litmus-v<x.y.z>

Publish @polygraphso/litmus 工作流会进行构建、类型检查、测试，并使用 npm 来源证明发布。完整流程以及下游使用方的本地开发工作流，请参阅 CONTRIBUTING.md。

许可证

Apache-2.0 — © polygraph.so。