Applitools

Applitools MCP Server

Applitools MCP サーバーを使うと、Applitools Eyes を使用して、サポート対象のあらゆる SDK でビジュアルテストを作成、更新、レビュー、解決できます。

Model Context Protocol（MCP）を通じて AI アシスタントに接続し、Cursor、GitHub Copilot、Cline、Claude Code などのツールを使って、テストのセットアップ、ビジュアルチェックポイントの追加、クロスブラウザーテストの設定、ビジュアルテストの失敗の調査（変更の承認、却下、調整）を IDE を離れずに行えます。

詳細については、こちらの MCP ドキュメントをご覧ください。

目的

このサーバーは、AI 支援ワークフローを利用する開発者、テスター、QA 担当者向けに構築されています。

AI アシスタントで次のことができます。

• プロジェクト設定を理解する
• Eyes のセットアップを案内する
• ビジュアルチェックポイントを追加し、ベストプラクティスを提案する
• ビジュアルテストの失敗について、バッチ、シナリオ、セッション、ステップ単位で調査し、何が変わったのか、バグかどうか、そしてその理由を伝える
• チェックポイントのマッチ領域を承認、却下、または調整する。ベースラインに変更を確定する前に、必ず明示的な承認を求める

手作業によるエラーが発生しやすい操作や、IDE を離れる必要はありません。

対象ユーザー

• Applitools Eyes を初めて利用するエンジニアで、Eyes SDK をインストールまたは実装したことがない方
• Ultrafast Grid のカバレッジ（クロスブラウザーおよびデバイスのテスト）を追加したい、Applitools のビジュアル AI を使って既存のテストをビジュアルテストに変換したい、またはビジュアルテストの結果を取得して分析したい既存の Eyes SDK ユーザー
• 大規模にビジュアルテストの失敗をトリアージするチーム
  • テストごとに Eyes ダッシュボードをクリックして確認する代わりに、AI アシスタントに失敗したテストのバッチを調査させ、根拠を集め、何が変わったのか、対応が必要かどうかを正確に伝えてほしい方

要件と制限事項

• Node.js 18 以降
• VS Code、Cursor、Claude Code、Cline、またはその他の MCP クライアントアシスタント
• セットアップツールとチェックポイントツール（eyes_setup_project、eyes_setup_ufg、eyes_add_checkpoints_to_test）がサポートするのは、当社の Playwright Fixtures SDK のみです。その他の SDK フレームワークのサポートは近日中に提供予定です。
  • Playwright、Node.js、当社の Playwright JavaScript Fixtures SDK は、最新バージョンを使用してください
  • セットアップツールとチェックポイントツールを使用するには、プロジェクトのソースコードへのアクセスが必要です
• 検査、解決、レビューのツール（eyes_inspect_*, eyes_resolve_*, eyes_review_*）は、どの SDK や言語で生成されたかにかかわらず、あらゆる Eyes テスト結果に対応します。すでに取得済みのバッチ、セッション、DOM データを操作するためです
  • これらのツールには、別途、読み取り用と書き込み用の API キーが必要です

インストール

推奨：VS Code 拡張機能または Cursor MCP インストール

Eyes MCP を使い始める最も簡単な方法は、Applitools VS Code 拡張機能を使うか、MCP サーバーを Cursor に直接インストールすることです。

• MCP サーバーを自動的に実行します
• Copilot または Cursor の AI アシスタントに接続します
• コンテキストを考慮したコード編集を提供します
• IDE または任意の MCP クライアント CLI 内にビジュアルテストの結果を表示します

以下のいずれかをクリックして、MCP サーバーをインストールしてください。

または、以下のManual Setupセクションの手順に従って、サーバーを手動でインストールできます。

手動セットアップ

拡張機能を使わない場合は、以下の例に従って MCP サーバーを手動でインストールできます。

標準の MCP 設定：

{
  "mcpServers": {
    "applitools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@applitools/mcp@latest"]
    }
  }
}

{
 "mcpServers": {
   "applitools-mcp": {
     "type": "local",
     "command": "npx",
     "tools": [
       "*"
     ],
     "args": [
       "@applitools/mcp@latest"
     ]
   }
 }
}

{
  "mcpServers": {
    "applitools-mcp": {
      "command": "npx",
      "args": ["--yes", "@applitools/mcp@latest"],
      "disabled": false,
      "type": "stdio",
	   "timeout": 60
    }
  }
}

認証

サーバーの操作権限を制御する 3 つのキーがあります。グローバル環境変数として設定するか、プロジェクト内の .env ファイルに設定するか、mcp.json ファイル内の applitools-mcp 設定を更新してください。

• APPLITOOLS_API_KEY：テスト実行に使用します（変更はありません。Eyes のビジュアルテストの実行にすでに使用しているキーです）。実行キーの取得方法については、ドキュメントを参照してください。
  • 注：MCP サーバーは、このキーを追加の場所からも検索します。詳細については、eyes_verify_api_key ツールを参照してください。
• APPLITOOLS_READ_KEY：読み取り専用キーです。すべての Inspection ツール、すべての Resolution ツール、およびいずれかのモードで実行される Review ツールに必要です。
• APPLITOOLS_WRITE_KEY：書き込み専用キーです。すべての Resolution ツール、および resolve モード（デフォルト）で実行される Review ツールに必要です。

読み取り専用 API キーと書き込み専用 API キーの取得方法：

API キーの管理については、ドキュメントを参照してください。

1. Applitools Admin API Keys ページに移動します。
2. ユーザーとチームに関連付けられた読み取り専用 API キーを作成またはコピーします。
3. ユーザーとチームに関連付けられた書き込み専用 API キーを作成またはコピーします。
4. プロジェクト内の .env ファイル、グローバル環境変数、または mcp.json ファイル内の applitools-mcp 設定を使って設定します。

注：テスト実行用の APPLITOOLS_API_KEY は、APPLITOOLS_READ_KEY および APPLITOOLS_WRITE_KEY とは異なります。Inspection、Resolution、および Review ツール（eyes_inspect_*, eyes_resolve_*, eyes_review_*）では、セッションデータの取得、テストのレビュー／検査、および解決を行うために、これらの個別の読み取り専用および書き込み専用の権限キーが必要です。

3 つのキーすべてを設定した applitools-mcp の mcp.json 設定例：

{
  "mcpServers": {
    "applitools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@applitools/mcp@latest"],
      "env": {
        "APPLITOOLS_API_KEY": "<your execution API key>",
        "APPLITOOLS_READ_KEY": "<your read-only key>",
        "APPLITOOLS_WRITE_KEY": "<your write-only key>"
      }
    }
  }
}

3 つのキーすべてを設定した、プロジェクト内の .env ファイルの例：

APPLITOOLS_API_KEY=<your execution API key>
APPLITOOLS_READ_KEY=<your read-only key>
APPLITOOLS_WRITE_KEY=<your write-only key>

利用可能なツール

セットアップと設定

eyes_verify_api_key

Applitools API キーを検証し、指定された Eyes サーバー URL（例：パブリッククラウド以外）が提供されている場合は、そのサーバーへの接続も検証します。

次の一般的な場所を検索します。

• 該当する場合、APPLITOOLS_API_KEY 環境変数および／または APPLITOOLS_SERVER_URL
• プロジェクト内の .env ファイル
• applitools.config.*
• playwright.config.*
• applitools-mcp の mcp.json 設定ファイル

対応する Eyes SDK：すべて

eyes_setup_project

Playwright プロジェクトで Applitools Eyes をセットアップする手順を案内します（Fixtures 版）。

含まれる内容：

• Eyes レポーターの設定
  • Playwright の HTML レポートを拡張し、Eyes のビジュアルテスト結果を含めます。ユーザーは Eyes ダッシュボードにアクセスしなくても、レポート内で結果を承認または却下できます。
• プロジェクトファイルへの Eyes の設定と依存関係のインポートの追加
• 推奨されるデフォルト設定

対応する Eyes SDK： Playwright TypeScript/JavaScript Fixtures

eyes_add_checkpoints_to_test

ベストプラクティスに沿って、既存の Playwright テストに Eyes のビジュアルチェックポイントを追加します。

対応する Eyes SDK： Playwright TypeScript/JavaScript Fixtures

eyes_setup_ufg

クロスブラウザーおよびクロスデバイスのテスト用に Ultrafast Grid（UFG）を設定します。複数のブラウザー、ビューポート、デバイスを同時に使用してビジュアルテストを実行できるよう、UFG のセットアップを案内します。

対応する Eyes SDK： Playwright TypeScript/JavaScript Fixtures

インスペクション（読み取り専用）

APPLITOOLS_READ_KEY が必要です。これらのツールは、バッチ、セッション、ステップ、DOM のデータを変更せずに照会します。アシスタントは通常、Review の一部としてユーザーに代わってこれらを呼び出します（後述）。手動またはアドホックな調査のために、個別に直接依頼することもできます。

対応する Eyes SDK：すべて

eyes_inspect_sessions

バッチのセッションとバッチ全体の統計情報を一覧表示します。未解決または未保存のセッションだけに絞り込んだり、詳細全体、統計情報のみ、または重複を除いたシナリオ名の一覧に応答形式を変更したりできます。バッチを閲覧する際の開始点です。「このバッチには何が含まれていますか？」「まだ確認が必要なものは何ですか？」と尋ねる場合は、まずこれを使用してください。

eyes_inspect_steps

セッションのステップを一覧表示します。各ステップが一致しているかどうかに加えて、ベースライン／チェックポイント画像と DOM の ID、サイズ、解決状況を確認できます。特定のセッションを詳しく調べる場合に使用します。

eyes_inspect_changed_areas

ステップの差分領域を返します。生のピクセル単位の差分から領域をまとめ、すでに追加した領域も考慮します。1 ステップあたりの変更領域が 20 を超える場合、密集したクラスターは単一の外接領域にまとめられます。そのため、アシスタントはピクセルノイズではなく、意味のある差分に集中できます。

eyes_inspect_image

ステップのベースラインまたはチェックポイントのスクリーンショットをエクスポートします。必要に応じて特定の領域に切り抜くこともできます。

eyes_inspect_image_diff

変更領域をハイライトしたチェックポイントのスクリーンショットをエクスポートし、移動または変更された箇所を一目で確認できるようにします。

eyes_inspect_dom

ステップの DOM キャプチャをファイルにエクスポートし、すべての要素に安定した ID を割り当てます。これにより、アシスタントは XPath や生の座標の代わりに「要素 14」のように参照できます。テスト実行時に DOM キャプチャが有効になっている必要があります。無効だった場合は、エラーではなくデータなしが返されます。

eyes_inspect_dom_diff

ステップのチェックポイント DOM とベースライン DOM の構造上の差分を返します（実際に変更された箇所のみ）。純粋な位置のずれや大規模な変更（例：「下のすべてが下に移動した」）は、要素ごとに列挙せず、自動的にまとめられます。

eyes_inspect_dom_search

独自の MCP リソースとして文書化されている述語クエリ言語を使って、DOM キャプチャを検索します。プロパティの比較、位置やサイズのチェック、祖先／子孫の関係、image や button などのショートカットキーワードを and／or／not と組み合わせられるため、アシスタントがキャプチャ全体を読み込む必要はありません。

eyes_inspect_evidence

1 回の呼び出しで、ステップの変更領域を確認するために必要なすべての情報を返します。指定した各領域について、画像差分とベースラインおよびチェックポイントのスクリーンショットに加え、ステップ全体の DOM 差分と現在適用されている一致領域が含まれます。eyes_inspect_image_diff、eyes_inspect_image、eyes_inspect_dom_diff、eyes_inspect_regions を個別に呼び出すよりもこちらを推奨します。Review がエビデンスを収集する際に使用するツールです。

eyes_inspect_regions

ステップで現在有効なマッチ領域を返します。テストコードで定義された領域と、テスト実行後に追加または変更された領域を組み合わせます。新しい領域を追加する前に確認するため、アシスタントが重複する領域や重なり合う領域を作成することを防ぎます。

eyes_inspect_history

過去の実行における DOM ノードの差分履歴を返します。変更が一度限りの実際の変更ではなく、繰り返し発生する変更や動的コンテンツであることを示す根拠として使用します。

Review（オーケストレーション）

常に APPLITOOLS_READ_KEY が必要です。また、resolve モード（デフォルト）で実行する場合は APPLITOOLS_WRITE_KEY も必要です。日常的にこれらのツールを使う主な方法です。バッチ、シナリオ、セッション、またはステップのレビューをアシスタントに依頼すると、調査全体を進めます。

対応する Eyes SDK：すべて

eyes_review_progress

依頼されたスコープ（バッチ、シナリオ、セッション、または単一ステップ）に応じて、ガイド付きの調査を進めます。変更された各領域について、所見を報告する前に必要な証拠（画像、DOM 差分、履歴）を収集します。「バッチをレビューして」や「このセッションをレビューして」と依頼したときにアシスタントが使用するツールです。適切な順序で内部的に Inspection ツールを呼び出すため、手動で呼び出す必要はありません。

eyes_review_diff_report

変更された領域について、分類、ページ周辺との整合性、バグの有無、期待どおりかどうかを含む構造化された所見を記録します。また、繰り返し発生する変更や動的コンテンツの場合は、裏付けとなる証拠と推奨するマスクも記録します。先にアシスタントが関連する証拠を収集する必要があります。証拠なしで登録された所見は拒否され、不足している検査呼び出しに差し戻されます。

eyes_review_end

指定されたスコープで調査を要約し、完了します。すべての子所見を重複排除して、漏れも二重計上もない簡潔な要約にまとめます。ステップ単位では、ステップの承認／却下／未解決の結果（resolve モード）もここで決定します。

Review には 2 つのモードがあります。

• inspect：読み取り専用です。変更内容の要約を生成しますが、変更は行いません。最初の確認や、対応を決める前に所見を確認したい場合に適しています。
• resolve（デフォルト）：動的な差分と確認されたものにマスクを適用し、所見が届くたびに各ステップの承認／却下／未解決の結果も自動で決定します。この処理のために、アシスタントが Resolution ツールを個別に呼び出す必要はありません。

どちらのモードでも、バッチ全体を対象にすることも、単一のシナリオ、セッション、またはステップに絞ることもできます。inspect モードのレビューは、調査をやり直さずに後から resolve モードへ昇格できます。キャッシュされた所見が resolve モードの判定ロジックで再処理されます。ベースラインへの変更の保存やリセットは Review 自体では行いません。別途 eyes_resolve_save（または eyes_resolve_reset）を依頼してください。どちらも引き続き明示的な承認が必要です。

Resolution（変更を伴う操作）

APPLITOOLS_READ_KEY と APPLITOOLS_WRITE_KEY の両方が必要です。通常の使用では、これらを直接呼び出すことはほとんどありません。Review は、バッチの処理中に同等の判定を自動的に適用します。Review を行わずに、内容を把握済みの単一ステップを承認するなど、単発の手動解決を行う場合に限り、これらのツールを直接使用してください。

対応する Eyes SDK：すべて

eyes_resolve_checkpoint

ステップのチェックポイントを承認または却下として記録します。承認されたチェックポイントは保存後にベースラインを置き換えます。却下されたチェックポイントでは既存のベースラインが維持されます。デフォルトでは、同一の差分を共有するすべてのステップ（セッション内、および同じシナリオ名を持つ兄弟セッション間）に同じ判定を適用します。

eyes_resolve_regions

ベースラインまたはチェックポイントの画像／DOM を基準として、ステップのマッチ領域を追加、削除、または更新します。変更は eyes_resolve_checkpoint と同様に適用されます。

注：このツールの実行には、常に明示的な承認が必要です。

eyes_resolve_save

受け入れまたは却下したすべてのステップと、バッチ全体でのすべての領域変更をベースラインにコミットします。指定したセッションだけでなく、バッチ内のすべてのテストが対象です。このツールを実行するまでは、解決の判断は保留中のままで、ベースラインは変更されません。

注：このツールの実行には、毎回、明示的な承認が必要です。

eyes_resolve_reset

セッションまたはバッチのベースラインを、テストが最初に実行されたリビジョンに復元し、保留中の解決の判断をすべてクリアします。

注：このツールの実行には、毎回、明示的な承認が必要です。

はじめに＆使用例

Applitools について AI アシスタントに質問してみましょう。

• 「Applitools MCP サーバーを使って、次のタスクを実行してください」
  • このプロンプトの接頭辞は省略可能です。アシスタントがより適切な結果を得るために MCP サーバーを使うよう促すことができます。
• 「Applitools API キーを確認してください」
• 「Playwright プロジェクト用に Applitools Eyes をセットアップしてください」
  • Playwright の TypeScript／JavaScript 向け
• 「login.spec テストに Eyes のビジュアルチェックポイントを追加してください」
  • Playwright の TypeScript／JavaScript 向け
• 「Applitools UFG を使ったクロスブラウザーテストを設定してください」
  • Playwright の TypeScript／JavaScript 向け
• 「直近のテスト結果のバッチ URL を表示してください」
• 「バッチの結果を分析して要約してください」
• 「直近のバッチを確認して、何が変わったか教えてください」
• 「このバッチで変わった点だけを表示してください。まだ解決はしないでください」
• 「すべて問題なさそうです。解決を進めてください」
• 「このシナリオのすべてのセッションで、チェックアウトボタンの差分を受け入れてください」
• 「タイムスタンプ要素のこの差分は動的なものですか、それとも実際の変更ですか？」
• 「このバッチのベースラインを、最初に実行されたときの状態にリセットしてください」

参考リンク

• Applitools MCP ドキュメント
• サポートへのお問い合わせ

Applitools が ❤️ を込めて制作