litmus

litmus

MCP サーバー向けのオープンな動作リトマス試験ハーネス — 再現可能な A〜F の評価。

1 つのコマンドでサーバーを評価

# -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 が必要です。評価ではコミット SHA を固定します）、https:// の MCP エンドポイント、またはローカルのエントリーファイルを指定できます。ハーネスはエージェントと同じ方法で接続し、ツールの正確な構成をフィンガープリントして、4 つのプローブカテゴリを実行し、その根拠となる所見とともに評価を出力します。さらに、ディスク上に決定論的な証拠バンドルを作成します。対象のコードを実行するため（外部への通信は Docker サンドボックスで制限されます。Docker がない場合は C-02 がスキップされ、評価は B が上限です）、所要時間は約 20〜60 秒です。D/F の場合は 0 以外の終了コードを返すため、どこでもスクリプトに組み込めます。公開済みの評価に異議を唱える場合は、同じサーバーに対してこのコマンドを再実行してください。オープンかつ決定論的であるため、再実行すれば同じ評価が再現されるか、評価に反証できます。

すでに公開されている評価の確認は 1 秒もかからず、何も実行しません。polygraph.so のインデックス、または以下の MCP ツールにある check_server をご利用ください。

エージェントから利用 — 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 — サーバーの公開済みグレードを 1 秒以内に確認します（コードは実行しません）。サーバーを推奨またはインストールする前の事前チェックに使用します。
• list_servers — 公開済みグレードのあるサーバーを A から順に一覧表示します。ページ分割に対応しています（1 回あたりのデフォルトは 25 件で、grade／limit／offset フィルターと全件の概要を利用できます）。
• request_grade — polygraph.so にグレードのリクエストを記録します（1 回限りの料金は $1 で、支払いから 48 時間以内にグレーディングされます。レスポンスに支払いリンクが含まれます）。
• run_litmus — サーバーをその場でグレーディングします。完全なハーネスを実行し、グレードと証拠をエージェントに返します。
• run_skill_litmus — Claude Code／Agent Skill をグレーディングします（静的スキャン、A/B/D/F）。
• verify_attestation — 公開済みグレードの根拠となるオンチェーン証明を確認します（Base 上の EAS）。

Claude Code では、プラグインがサーバーと 2 つのコマンドをまとめて設定します。

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

その後、/polygraph:grade <server> と /polygraph:check <server> を実行します。Cursor と手動での JSON 設定については polygraph.so をご覧ください。すべてのツールのドキュメントは packages/litmus/README.md にあります。

MCP のグレードを CI のゲートにする — GitHub Action

オープンな動作リトマスで、MCP サーバーまたは同梱する Agent Skill が D/F と評価された場合、ビルドを失敗させます。サーバーではハイブリッド方式で、公開済みグレードをすばやく照会し、グレード未取得の場合はハーネスを実行します。Skill ではすばやく静的スキャンを行います。グレーディングできない対象は、strict が指定されていない限り警告になります。

polygraphso/litmus@v1 として GitHub Marketplace で公開されています。セキュリティゲートとして使用する場合、変更可能な @v1 タグではなく、コミット SHA を指定してください。

# .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 ヘッダーとして送信されるため、明示的に信頼している固定済みのリモートにのみ渡してください。自動検出との併用や信頼できないプルリクエストでの使用は避け、スコープを限定し、有効期間を短くしてください。

GitHub を利用していない場合も、ゲートは単純なコマンドとして使えます。npx @polygraphso/[email protected] ci（バージョンを固定してください）で実行できるため、あらゆる CI やコミット前フックで利用できます。グレードは測定結果であり、保証ではありません。結果を再現するには、オープンなハーネスを再実行してください。

litmus とは

これは、polygraph.so が提供する MCP サーバー向けオープンな振る舞い検査ハーネス、@polygraphso/litmus のソースです。

このハーネスは、エージェントと同じ方法で MCP サーバーに接続し、正確なツール構成をフィンガープリントしたうえで、4 つのプローブカテゴリを実行します。C-01 ツール出力へのインジェクション（静的、動的、および二次的――あるツールの出力を別のツールの入力として悪用）、C-02 権限／外部送信（強化されたデフォルト拒否の Docker サンドボックス内で、ホストとポートの両方を照合）、C-03 機密データの取り扱い（埋め込んだカナリアを使用）、C-04 敵対的入力への対応（不正形式／過大な入力およびジェイルブレイク入力）を検査し、サーバーを A～F で評価します。合格評価は測定結果であり、保証ではありません。手法とその開示済みの制限については polygraph.so をご覧ください（ここにあるオープンソースが実際の基準です）。

評価に加えて、npm の対象については依存関係ツリーを osv.dev の脆弱性データベースと照合し、脆弱な依存関係があれば依存関係アドバイザリとして報告します。これは独立したある時点でのシグナルであり、参考情報にすぎません。A～F の評価には一切影響せず、再現可能な証拠にも含まれません（脆弱性データは時間とともに変化するため、評価に組み込むと再実行時の再現性が損なわれます）。対象が npm の場合にのみ適用され、その他の対象種別ではスキップとして報告されます。依存関係の解決では npm install --package-lock-only --ignore-scripts を実行し、tarball のダウンロードやパッケージコードの実行を行わずにツリーを解決します。--no-deps-audit（または LITMUS_DEPS_AUDIT=0）で無効にできます。

同じパッケージは、別個の静的 litmus（litmus-skill-v3）を使って Claude Code / Agent Skills（SKILL.md とバンドル）も評価します。決定論的なバイトスキャンである S-01 プロンプトインジェクション、S-03 データ流出の指示、S-04 SKILL.md の本文またはバンドルされたスクリプト内の危険なコマンド（base64 で難読化された curl | bash を含む）を検査し、ディレクトリ全体のコンテンツハッシュで基準化したうえで A/B/D/F で評価し、品質に関する別個のアドバイザリシグナルも提供します。これは静的な検査であり（実行はしません）、A は静的に問題がないことを示すもので、振る舞いの証明ではありません。packages/litmus/README.md をご覧ください。

ホスト型の運用者実行による評価サービスはこのリポジトリには含まれていません。別のプライベートリポジトリにあり、他のクライアントと同様に npm からこのパッケージを利用します。

構成

これは pnpm モノレポです。公開されるのは @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 provenance を付与して公開します。全手順と、下流の利用者向けローカル開発ワークフローについては CONTRIBUTING.md をご覧ください。

ライセンス

Apache-2.0 — © polygraph.so.