TestivAI

@testivai/mcp

AI コーディングエージェントにビジュアルリグレッションの結果を確認させる MCP（Model Context Protocol）サーバーです。エージェントが UI コードを変更してテストスイートを実行した後、これらのツールを使って、画面上で実際に何が変わったのか、またそれが本当の変更なのか、描画ノイズの可能性が高いのか、DOM やスタイルのシグナルだけでは判断できないケースなのかを確認できます。

ツール

ツール	機能
get_visual_results	visual-report/results.json を読み込みます。2つ以上のスナップショットで環境変更が共通している場合、レンダリングのドリフトがいくつあるかを示す1行を最初に表示し、その後、スナップショットごとに1行の判定を返します。判定には、キャプチャの異常（現在のキャプチャまたはベースラインでウェブフォントやスタイルシートの読み込みに失敗した場合。判定でどちらかを明示します。キャプチャの不具合、またはアセットの破損であり、ノイズでもベースラインとして承認すべきものでもありません。他の情報より先に示します）／合格（自動合格した差分の場合、合格の根拠となった設定済みの基準を示します）／サイズ変更（現在のキャプチャの寸法がベースラインと異なる場合。ページが高くなった、または短くなった場合は、DOM の概要とページのずれを合わせて読み取ります。DOM が同一なら、コンテンツが追加されたのではなく、同じコンテンツのレイアウトが変わっています。幅の変更はビューポートまたはデバイススケールの変更であり、ページの変更ではありません。余白部分のピクセルもすべて変更としてカウントされるため、合格にもノイズにもなりません）／レンダリングのドリフト（DOM と計算済みスタイルが両方とも一致し、スナップショットのキャプチャ後にキャプチャ環境がベースラインから変わった場合。ブラウザーのビルド、OS またはディストリビューション、デバイススケール、キャプチャ方法のいずれが変わったかを判定で示します。変わったのはマシンであり、ページではないため、ノイズとは呼びません）／レンダリングノイズの可能性が高い（DOM と計算済みスタイルが両方とも一致し、差分が小さく散在している場合。ただし、証明されたわけではありません）／1か所に集中、または大規模（DOM と計算済みスタイルは一致するものの、すべての差分領域がページの3分の1以下を覆うボックス内に収まる場合、またはピクセルの1％超に差分がある場合。キャプチャの不具合か、サイズ、オーバーフロー、トランスフォーム、画像など、スタイルチェックでは検出できない変更です。承認する前に画像を比較してください）／スタイルのみの変更（DOM は同一で、計算済みスタイルが異なる場合。実際の変更です）／構造上の変更（DOM の概要を含みます）／スタイル未比較（DOM は同一ですが、スタイルチェックを利用できない場合。レンダリングノイズ、またはスタイルシートのみの変更の可能性があるため、承認する前に画像を比較してください）。同一のシグナルを共有するスナップショット（同じ要素のスタイルのみの変更、同じページのずれ、スタイル未比較の同一 DOM、大きく広がった差分、レンダリングノイズの可能性が高いもの）は、最初にまとめられます。1か所に集中した差分やキャプチャの異常は、決してまとめられません。ベースラインが存在しない場合（コミット済みだが、今回の実行でキャプチャされなかった場合）は、それぞれ1行で表示されます（複数ある場合は判定の行を共有するため、部分的な実行でも短く収まります）。承認対象はなく、意図した削除の場合はベースラインディレクトリを削除します。最後に、HTML レポートと各差分画像を開くためのパスを表示します
explain_snapshot	1つのスナップショットに関する段階的な根拠を示します。ピクセル領域と差分の形状（layers.pixel.shape：散在、集中、大規模）、要素の帰属情報（移動したセレクターと変更されたセレクター、ページ全体のずれ）、DOM／スタイルのシグナル、キャプチャ環境（layers.environment：ベースラインからの変更内容、レンダリングの変更の説明、差分がレンダリングのドリフトかどうか）、キャプチャの健全性（layers.health：各キャプチャで読み込みに失敗したものと、異常がある側）、解釈のガイダンスを示します。ベースラインがない場合は、ステータス missing、コミット済みのベースラインファイル、代わりに確認すべき内容を示します
get_report	構造化データを解析するエージェント向けに、未加工の results.json ペイロードを返します
get_diff（別名 get_snapshot_diff）	エージェントが変更を確認できるよう、1つのスナップショットのベースライン、現在のキャプチャ、差分の画像を返します。モデルのコンテキストに収まるよう縮小したページ全体の画像（変更箇所を確認できます）に続き、縮小が必要だった場合は、ネイティブスケールで切り出した各変更領域の画像を返します。各画像には周囲32 pxを含み、ページ幅まで広げられます（最大1280 px）。これにより、縦長のページ全体キャプチャでもテキスト、折り返し、クリッピングを読み取れます（1回の呼び出しにつき最大3枚、各画像は最大1280×1024 px、合計2,000,000 px。近接する領域は1枚にまとめられ、変更はずれより先に表示されます。横に広い領域は1/2以下のスケールで表示され、縦に長い領域は先頭の行が表示されます。サイズ変更後は、各キャプチャをそれぞれの範囲で切り出します）。region（レスポンスに表示されるインデックス）、または y と height（全幅の帯状領域）を指定すると、その切り出し画像のみを返します。ベースラインがない場合は、コミット済みのベースライン画像のみを返します
list_baselines	.testivai/baselines/ 以下にあるコミット済みのベースラインを一覧表示します
approve_snapshot / approve_all	レビュー済みのキャプチャをコミット済みのベースラインに昇格します（testivai approve と同じ）。人間が確認した後にのみ実行してください
このサーバーには、2 つのプロンプトも付属しています。review-visual-changes は、概要、変更ごとの explain_snapshot、証拠が曖昧な場合の差分画像、各スナップショットの推奨事項を含む、一連のレビューをエージェントに案内します。
triage-visual-diff（snapshot と intent は任意の引数）は、各差分とベースラインがないものを、グリッチ、意図した変更、バグ、またはバグの可能性に分類し、証拠と次のステップを示します。DOM の変更や算出済みスタイルの変更がグリッチと判定されることはなく、ベースラインがない場合も同様です。同じルールは CI でも testivai/testivai-oss/review@v1 アクションによって実行されます。

承認は人間が判断します

approve_snapshot と approve_all は、差分を確認した人間が会話の中で「承認して」と伝え、エージェントに実行させるためのものです。エージェントが自ら判断して使うためのものではありません。承認すると「正しい」の定義が書き換えられるため、エージェントが自分の変更を承認すると、リグレッションがベースラインに紛れ込むおそれがあります。どちらのツールの説明にも、review-visual-changes プロンプトにも、すべての get_visual_results の応答にも、このことが記載されています。承認した後は、.testivai/baselines/ をコミットしてください。

Claude Code では、クライアントによってこの動作が強制されます。両方の承認ツールに anthropic/requiresUserInteraction が設定されているため、自動承認の権限モードでも、承認を実行するたびに Claude Code が確認を求めます。これを無効にするには、サーバーを --no-approval-prompt を指定して起動するか、.testivai/config.json に "mcpApprovalPrompt": false を設定します（フラグが優先されます）。その場合、承認ツールはクライアント独自の権限設定に従います。手順については、Claude Code でのレビューと承認をご覧ください。

その他の承認方法も引き続き利用できます。ローカルで npx testivai approve <name> を実行するか、プルリクエストに /testivai approve <name> とコメントします。

セットアップ

Claude Code

claude mcp add testivai -- npx -y @testivai/mcp

Cursor ／その他の MCP クライアント

// .cursor/mcp.json (or your client's equivalent)
{
  "mcpServers": {
    "testivai": { "command": "npx", "args": ["-y", "@testivai/mcp"] }
  }
}

サーバーは作業ディレクトリからプロジェクトを読み込み（--root <path> を渡すと上書きできます）、.testivai/config.json の reportDir を使用します。

エージェントの一般的な流れ

1. エージェントが UI コードを編集します。
2. エージェントが npx playwright test を実行します（TestivAI レポーターがキャプチャと差分の確認を行います）。
3. エージェントが get_visual_results を呼び出し、たとえば homepage: changed (4.20% pixels differ) and the DOM changed (2 added, 1 removed, 0 attribute changes) — a real structural change; confirm it is intended before approving のような結果を確認します。
4. エージェントが証拠を確認するために explain_snapshot homepage を呼び出し、画像を確認するために get_diff homepage を呼び出します（最初にページ全体を確認し、次に変更箇所をネイティブスケールで確認します）。その後、変更がタスクの内容に沿っていることを確認するか、自らのリグレッションを修正します。
5. エージェントが人間に、何が変わったか、意図した変更に見えるか、どのスナップショットの承認が必要かを報告します。人間が承認するよう伝えた場合、エージェントは approve_snapshot を呼び出します。そうでなければ、人間が npx testivai approve を実行するか、PR で /testivai approve を実行します。

ローカルモードのみです。アカウントも API キーも不要で、マシンの外にデータが送信されることもありません。

統合ガイド全文（指示ファイルレベル、MCP レベル、テストスイートがないアプリ、実際のトランスクリプト）：docs/guides/ai-agents.md