playwright-trace-decoder-mcp

🎭 playwright-trace-decoder-mcp

Playwright の trace.zip アーカイブを展開して構造化し、AI エージェントが CI の失敗原因を分析できるようにする MCP サーバーです。生の JSON に埋もれたり、コンテキストウィンドウを超過したりすることなく分析できます。

🤔 課題

Playwright のテストが CI で失敗すると、trace.zip が生成されます。これはバイナリデータであり、LLM はそのまま読み取れず、生の内容を出力するとコンテキストウィンドウを超過します。その結果、エンジニアはまるで 2022 年のように、ログの断片を手作業で ChatGPT にコピーすることになります。

この MCP サーバーは、この問題を解決します。エージェントが失敗を診断するために必要な情報だけを公開する、用途を絞った 16 個のツールを備えています。ページネーションと ARIA 圧縮により、トークンのコストも抑えます。

🐸 E2E 失敗調査の例

v0.3.0 の新しいツールを AI エージェントがどのように使い、失敗をすばやく特定して調査するのかを簡単に紹介します。

1. map_locator_to_source で、バグの正確なソースコード上の位置を特定します。

   // Request arguments
   { "trace_path": "/path/to/trace.zip" }
   
   // Response payload
   {
     "action_type": "Click locator('#super-toad-not-found')",
     "locator": "#super-toad-not-found",
     "error": "TimeoutError: locator.click: Timeout 5000ms exceeded.",
     "step_title": "Click locator('#super-toad-not-found')",
     "stack": [
       {
         "file": "/Users/albertdev/Projects/ideas/sample-playwright-project/tests/google-pom.spec.ts",
         "line": 18,
         "column": 17
       }
     ],
     "source_location": {
       "file": "/Users/albertdev/Projects/ideas/sample-playwright-project/tests/google-pom.spec.ts",
       "line": 18,
       "column": 17
     }
   }
   

   推測する必要はもうありません。タイムアウトの原因となったファイル、行、列が正確にわかります。

2. extract_critical_frames で、失敗前後の重要なビジュアルフレームを抽出します。

   // Request arguments
   { "trace_path": "/path/to/trace.zip", "limit": 1 }
   
   // Response payload
   [
     {
       "timestamp": 1779137404287,
       "mime_type": "image/jpeg",
       "step_title": "Clicking #super-toad-not-found element",
       "data": "/9j/4AAQSkZJRgABAQAAAQABAAD/..." // Base64 JPEG
     }
   ]
   

   大量の画像リストを取得せずに、失敗の直前と直後のページ状態をエージェントがすぐに視覚的に確認できます。

3. trim_trace_archive で、CI のストレージや転送のコストを削減するためにトレースを縮小します。

   // Request arguments
   { "trace_path": "/path/to/trace.zip" }
   
   // Response payload
   {
     "original_size_bytes": 2449682,
     "trimmed_size_bytes": 511698,
     "compression_ratio_percent": 79,
     "trimmed_trace_path": "/path/to/trace.trimmed.zip"
   }
   

   失敗の重要な時間範囲外にあるスクリーンショットを削除し、大きなトレースを縮小します。ディスク容量を 79％節約しました。

🛠️ ツール

ツールは、失敗の診断時にエージェントが使用する順序に応じてグループ化されています。

調査 — トレースデータの読み取り

ツール	引数	返される内容
get_test_metadata	trace_path	ブラウザー、プラットフォーム、ビューポート、テストタイトル、実時間の開始時刻
get_trace_summary	trace_path	失敗したアクション、トップレベルのエラー、アクションの総数
get_action_timeline	trace_path, limit, offset	API 名、ロケーター、タイミングを含む全アクションのページネーション付き一覧
get_filtered_network_logs	trace_path, limit, offset	4xx／5xx のレスポンスのみ。静的アセット（CSS、JS、フォント、画像）は除外
get_console_errors	trace_path, limit, offset	ブラウザーコンソールの JS 例外と警告
get_element_state_at_failure	trace_path	失敗したロケーター、エラーメッセージ、生の失敗前／失敗後メタデータ
extract_trace_metadata_strict	trace_path	フォーマットのバージョン、再試行セッションの内訳、HAR ペイロードモード（埋め込み／添付／省略）

一覧を返すすべてのツールは、limit（1～500、デフォルトは 50）と、has_more フラグ付きの offset ページネーションに対応しています。

trace_path には、絶対ローカルパスまたは HTTPS URL を指定できます。サーバーがファイルを自動的にダウンロードし、セッション中キャッシュします。

DOM／UI 分析

ツール	引数	返される内容
get_aria_accessibility_tree	trace_path, action_index?	コンパクトな YAML 形式の ARIA アクセシビリティツリー（生の HTML よりトークン数を約 90％削減）。失敗したアクション時点のスナップショットがデフォルトです。
get_dom_mutation_delta	trace_path, action_index	特定のアクション前後の ARIA 行の差分。追加／削除された要素のみを返し、2 つの完全な DOM ダンプは返しません。
get_screenshot_at_failure	trace_path, screenshot_index?	失敗した時点に最も近い Base64 JPEG スクリーンショット。ARIA ツリーが空の場合（CAPTCHA、空白ページ）に使用します。screenshot_index を指定すると、ビジュアルの全タイムラインをたどれます。
analyze_race_conditions	trace_path	インタラクションまたはアサーションが実行された時点で進行中だったネットワークリクエスト
correlate_dom_and_network	trace_path	fetch の完了と DOM の変更が ±100ms 以内に発生した各アクションについて、トリガーとなった URL、レスポンスステータス、本文の抜粋、追加／削除されたノードを正確に返します
extract_critical_frames	trace_path, lookback_ms?, lookforward_ms?, limit?	失敗前後の時間範囲から重要なスクリーンキャストのスクリーンショット（Base64）を抽出し、ステップのタイトルと対応付けます

根本原因分析

ツール	引数	返される内容
get_causal_chain_for_failure	trace_path, lookback_ms?	失敗につながった直前のアクション、ネットワークエラー、コンソールエラーの時系列順の連鎖（デフォルトの時間範囲：5 秒）
generate_error_signature	trace_path	正規化されたエラーの安定した 12 文字の SHA-1 ハッシュ。並列 CI 実行で発生した重複する失敗をまとめるために使用します。
compare_traces	passing_trace_path, failing_trace_path	成功時と失敗時の実行間で、LCS に基づいて整列したアクションシーケンス。構造上の差異、タイミングの異常（>500 ms）、対応しないアクション、ネットワーク差分を示します
map_locator_to_source	trace_path, action_index?	ランナーの実行スタックを通じて、失敗したブラウザー操作（または特定のアクションインデックス）をテストコード内の正確な行に対応付けます

パフォーマンス分析

ツール	引数	戻り値
detect_performance_anomalies	trace_path, slow_action_threshold_ms?, frame_drop_threshold_ms?	遅いアクションとフレームドロップを、suspected_cause（メインスレッドのブロック／ネットワークの飽和／ナビゲーションのタイムアウト）とともに、優先度順に一覧表示します。また、アクション時間の p50／p95 とメモリリークのフラグも報告します。
trim_trace_archive	trace_path, divergence_only?	重大な障害が発生した時間帯（t_fail - 5s から t_fail + 1s）以外のスクリーンショットを削除して、トレースの zip ファイルを縮小します。トリミング後のパスとサイズの差分を返します。

💬 エージェントにおすすめのワークフロー

get_trace_summary              ← what failed?
get_causal_chain_for_failure   ← what led up to it?
get_aria_accessibility_tree    ← what did the page look like?
get_screenshot_at_failure      ← ARIA empty? get the actual screenshot
get_dom_mutation_delta         ← what changed right before the failure?
analyze_race_conditions        ← was a network request still pending?
correlate_dom_and_network      ← which fetch caused which DOM change?
compare_traces                 ← flaky? compare to a passing run
detect_performance_anomalies   ← timeout but no JS error? check for Long Tasks

🚀 セットアップ

ソースからビルドする

git clone https://github.com/vola-trebla/playwright-trace-decoder-mcp.git
cd playwright-trace-decoder-mcp
npm install
npm run build

MCP クライアントに追加する

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）

{
  "mcpServers": {
    "playwright-trace-decoder": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-trace-decoder-mcp/dist/index.js"]
    }
  }
}

Cursor（.cursor/mcp.json）または VS Code（.vscode/mcp.json）

{
  "mcpServers": {
    "playwright-trace-decoder": {
      "command": "node",
      "args": ["/absolute/path/to/playwright-trace-decoder-mcp/dist/index.js"]
    }
  }
}

Claude Code

claude mcp add playwright-trace-decoder \
  node /absolute/path/to/playwright-trace-decoder-mcp/dist/index.js

Docker

docker build -t playwright-trace-decoder-mcp .

{
  "mcpServers": {
    "playwright-trace-decoder": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/traces:/traces", "playwright-trace-decoder-mcp"]
    }
  }
}

💬 使用例

基本的な障害分析

エージェントに尋ねます：

「CI の実行に失敗しました。トレースはこちらです：/tmp/trace.zip。何が起きたのか、なぜ失敗したのか教えてください」

エージェントは get_trace_summary → get_causal_chain_for_failure → get_aria_accessibility_tree の順に呼び出し、必要に応じてさらに詳しく調べます。コピー＆ペーストは不要です。

ページが真っ白だった、またはリダイレクトされた場合

「ARIA ツリーが空です。失敗時に画面に実際に表示されていたものを見せてもらえますか？」

エージェントは get_screenshot_at_failure を呼び出し、失敗した瞬間に最も近いタイミングで撮影された JPEG を取得します。CAPTCHA、エラーページ、予期しないリダイレクトの検出に役立ちます。

不安定さの診断

「このテストはローカルでは成功しますが、CI では失敗します。この 2 つのトレースを比較して、何が違ったのか教えてください」

エージェントは compare_traces を呼び出します。このツールは両方のアクションシーケンスを LCS で整列し、最初の構造上の差異、タイミングの異常、失敗した実行でのみ発生したネットワークリクエストを示します。

並列 CI 実行で重複する障害をグループ化する

「このパイプラインで 12 件のトレースが失敗しました。すべて同じ障害でしょうか？」

各トレースに対して generate_error_signature を呼び出します。シグネチャが一致すれば、根本原因も同じです。すべてのトレースを読む必要はありません。

DOM の変更を引き起こした API 呼び出しを特定する

「モーダルが表示されましたが、どの fetch がきっかけだったのかわかりません」

correlate_dom_and_network は HAR ログと DOM スナップショットを自動的に突き合わせます。出力例：

{
  "total_correlations": 1,
  "correlations": [
    {
      "action_id": "4:Locator.click",
      "triggering_request_url": "https://api.example.com/cart/items",
      "response_status_code": 200,
      "response_body_snippet": "{\"items\":[{\"id\":\"abc\",\"qty\":1}]}",
      "time_to_dom_mutation_ms": 38,
      "resulting_dom_mutations": [
        { "type": "added", "selector": "heading \"Cart (1 item)\"" },
        { "type": "removed", "selector": "button \"Add to cart\" [disabled]" }
      ]
    }
  ]
}

パフォーマンスによるタイムアウト — 要素が見つからないだけではありません

「goto でテストがタイムアウトしますが、JavaScript エラーはありません。ページの読み込みを妨げているものは何ですか？」

detect_performance_anomalies はスクリーンキャストのフレーム間隔を調べ、Long Task にフラグを付けます。出力例：

{
  "anomalies": [
    {
      "kind": "slow_action",
      "blocked_action_id": "2:Frame.goto",
      "task_duration_ms": 4200,
      "threshold_ms": 500,
      "concurrent_network_load": 9,
      "frame_drop_count": 0,
      "worst_frame_gap_ms": 0,
      "suspected_cause": "network_saturation"
    }
  ],
  "suspected_memory_leak_flag": false,
  "p50_action_duration_ms": 95,
  "p95_action_duration_ms": 780,
  "total_frame_drop_count": 0
}

suspected_cause は、メインスレッドのブロック（main_thread_blocked — フレーム間隔あり）、同時に実行される fetch の連続（network_saturation — 同時実行中のリクエストが 5 件以上）、ナビゲーションまたはハードタイムアウト（timeout_or_navigation — 他に兆候がなく、所要時間が 3 秒超）を区別します。

トレースで使用されている Playwright のバージョンと HAR モードを確認する

「見慣れない CI 設定から取得したトレースです。レスポンス本文のデータは利用できますか？」

extract_trace_metadata_strict は、ほかのツールを実行する前にアーカイブを調べます。

{
  "format_version": 6,
  "har_mode": "embed",
  "retry_sessions": [
    { "session_id": "s1", "failed": false },
    { "session_id": "s2", "failed": true }
  ],
  "failed_session_id": "s2"
}

har_mode: "embed" は、本文のスニペットがインラインで含まれていることを意味します。"attach" は、別のリソースファイルに保存されていることを意味します。"omit" は、ヘッダーのみであることを意味します。この場合、correlate_dom_and_network は空の response_body_snippet を返します。

🏗️ アーキテクチャ

trace.zip
  ├── *.trace          → JSONL: before/after action pairs, console events, frame snapshots
  ├── *.network        → JSONL: HAR resource-snapshot entries
  └── resources/
      ├── page@*.jpeg  → screenshots taken during the run
      └── ...          → fonts, stylesheets, other captured resources

パーサーは各ファイルを1行ずつストリーミングして処理し（全体をバッファーに読み込んで分割することはありません）、LRU（最大50エントリー）で結果をプロセス内にキャッシュします。キャッシュのキーにはパスと mtime を使用します。変更されていない同じトレースを再読み込みする場合、I/O は発生しません。

フレームのスナップショットでは、DOM をネストされた配列（["TAG", {attrs}, ...children]）として保存します。ARIA トランスレーターはこのツリーをたどり、コンパクトな YAML を出力することで、生の HTML と比べてトークンコストを約90％削減します。

🏗️ 技術スタック

• @modelcontextprotocol/sdk — MCP サーバーのランタイム
• adm-zip — zip の展開
• zod v4 — 入力スキーマの検証
• TypeScript、ESLint、Prettier、Husky、GitHub Actions CI

📋 スクリプト

npm run build        # compile TypeScript → dist/
npm run lint         # ESLint
npm run format       # Prettier --write
npm run format:check # Prettier check (used in CI)

📄 ライセンス

MIT