Better Playwright MCP

🚀 better-playwright-mcp

このプロジェクトは、クライアント・サーバーアーキテクチャを用いた、より優れたPlaywright MCP（Model Context Protocol）サーバーです。ブラウザ自動化に最適化されています。

🚀 クイックスタート

このセクションでは、better-playwright-mcp の概要、インストール方法、基本的な使用法について説明します。

✨ 主な機能

• 🎯 セマンティックHTMLスナップショットにより、トークン使用量を最大90%削減
• 🎭 MCPを介した完全なPlaywrightブラウザ自動化
• 🏗️ 関心事の分離を実現するクライアント・サーバーアーキテクチャ
• 🛡️ 検出を回避するステルスモード
• 📍 正確なターゲティングのためのハッシュベースの要素識別子
• 💾 永続的なブラウザプロファイル
• 🚀 長時間実行の自動化タスクに最適化
• 📊 自動トランケーションによるトークン対応出力

📦 インストール

npm install -g better-playwright-mcp

💻 使用例

基本的な使用法

MCPモード

MCPサーバーはHTTPサーバーが実行されている必要があります。両方を起動する必要があります。

ステップ1: HTTPサーバーの起動

npx better-playwright-mcp server

ステップ2: 別のターミナルでMCPサーバーを起動

npx better-playwright-mcp

MCPサーバーは以下の処理を行います。

1. MCPプロトコルメッセージを標準入力で待機します。
2. ポート3102でHTTPサーバーに接続します。
3. HTTPサーバーを介してブラウザ自動化コマンドをルーティングします。

オプション:

• --snapshot-dir <path> - スナップショットを保存するディレクトリ

スタンドアロンHTTPサーバーモード

HTTPサーバーを独立して実行することもできます（デバッグやカスタム統合に便利です）。

npx better-playwright-mcp server

オプション:

• -p, --port <number> - サーバーのポート（デフォルト: 3102）
• --host <string> - サーバーのホスト（デフォルト: localhost）
• --headless - ヘッドレスモードでブラウザを実行
• --chromium - Chromeの代わりにChromiumを使用
• --no-user-profile - 永続的なユーザープロファイルを使用しない
• --user-data-dir <path> - ユーザーデータディレクトリ
• --snapshot-dir <path> - スナップショットを保存するディレクトリ

高度な使用法

MCPツールの使用

AIアシスタントと一緒に使用する場合、以下のツールが利用可能です。

ページ管理

• createPage - 名前と説明を指定して新しいブラウザページを作成
• activatePage - IDで特定のページをアクティブ化
• closePage - 特定のページを閉じる
• listPages - タイトルとURLを含むすべての管理対象ページをリスト表示
• closeAllPages - すべての管理対象ページを閉じる
• listPagesWithoutId - 管理されていないブラウザページをリスト表示
• closePagesWithoutId - すべての管理されていないページを閉じる
• closePageByIndex - インデックスでページを閉じる

ブラウザアクション

• browserClick - xp識別子を使用して要素をクリック
• browserType - 要素にテキストを入力
• browserHover - 要素上にホバー
• browserSelectOption - ドロップダウンでオプションを選択
• browserPressKey - キーボードのキーを押す
• browserFileUpload - ファイル入力にファイルをアップロード
• browserHandleDialog - ブラウザダイアログ（アラート、確認、プロンプト）を処理
• browserNavigate - URLに移動
• browserNavigateBack - 前のページに戻る
• browserNavigateForward - 次のページに進む
• scrollToBottom - ページ/要素の一番下までスクロール
• scrollToTop - ページ/要素の一番上までスクロール
• waitForTimeout - 指定されたミリ秒間待機
• waitForSelector - 要素が表示されるまで待機

スナップショットとユーティリティ

• getPageSnapshot - xp識別子付きのセマンティックHTMLスナップショットを取得
• getScreenshot - スクリーンショットを撮る（PNG/JPEG）
• getPDFSnapshot - ページのPDFを生成
• getElementHTML - 特定の要素のHTMLを取得
• downloadImage - URLから画像をダウンロード
• captureSnapshot - 自動スクロールで全ページをキャプチャ

📚 ドキュメント

なぜこれが良いのか？

従来のブラウザ自動化ツールは、ページ全体のHTMLをAIアシスタントに送信するため、すぐにトークン制限に達し、複雑なWebインタラクションが実用的ではなくなります。better-playwright-mcp は、革新的なセマンティックスナップショットアルゴリズムを使用して、すべての意味のある要素を保持しながら、ページコンテンツを最大90%削減することでこの問題を解決します。

問題点

• 全ページのHTMLはしばしば100K以上のトークンを超えます。
• ほとんどのHTMLはノイズです：インラインスタイル、トラッキングスクリプト、不可視要素
• AIアシスタントのコンテキストウィンドウは限られています（200Kの制限がある場合でも）
• 数回のページロード後には、複雑なWeb自動化が不可能になります。

解決策：セマンティックスナップショット

このプロジェクトの核心的な革新は、多段階のプルーニングアルゴリズムです。

1. 意味のある要素を識別 - インタラクティブ要素（ボタン、入力）、セマンティックHTML5タグ、およびテキストを含む要素
2. 一意の識別子を生成 - 各要素には、XPathから派生したハッシュベースの xp 属性が付与され、正確なターゲティングが可能になります。
3. 不可視コンテンツを削除 - display:none、サイズがゼロ、または非表示の親を持つ要素はマークされて削除されます。
4. 無駄なラッパーを解除 - 他の要素をラップするだけのdivやspanを削除します。
5. 不要な属性を削除 - href、value、placeholder などの必須属性のみを保持します。

結果として、通常は元のトークンのわずか10% を使用するクリーンなセマンティック表現が得られ、完全な機能が維持されます。

アーキテクチャ

このプロジェクトは、独自の2層アーキテクチャを実装しています。

1. MCPサーバー - モデルコンテキストプロトコルを介してAIアシスタントと通信
2. HTTPサーバー - 実際のブラウザインスタンスを制御するためにバックグラウンドで実行

AI Assistant <--[MCP Protocol]--> MCP Server <--[HTTP]--> HTTP Server <---> Browser

この設計により、MCPサーバーを軽量に保ちながら、ブラウザ制御を専用のHTTPサービスに委任することができます。

仕組み

セマンティックスナップショットの実際の動作

変換前（元のHTML）:

<div class="wrapper" style="padding: 20px; margin: 10px;">
  <div class="container">
    <div class="inner">
      <button class="btn btn-primary" onclick="handleClick()" 
              style="background: blue; color: white;">
        Click me
      </button>
    </div>
  </div>
</div>

変換後（セマンティックスナップショット）:

button xp=3fa2b8c1 Click me

アルゴリズムは以下の処理を行います。

• 不要なラッパーdivを削除
• インラインスタイルとイベントハンドラーを削除
• 一意の識別子（xp 属性）を追加 - 要素のXPathのハッシュ
• 意味のあるコンテンツのみを保持

差分ベースの最適化

データ転送とトークン使用量を削減するために、以下の最適化が行われます。

• 最初のスナップショットは常に完全なものです。
• それ以降のスナップショットは変更点（差分）のみを含みます。
• パフォーマンスのために自動キャッシュが行われます。

ステルス機能

ブラウザインスタンスは以下のように構成されています。

• カスタムユーザーエージェント文字列
• 自動化インジケーターの無効化
• WebGLベンダーのスプーフィング
• キャンバスフィンガープリント保護

🔧 技術詳細

開発環境

前提条件

• Node.js >= 18.0.0
• TypeScript
• ChromeまたはChromiumブラウザ

ソースからビルド

# リポジトリをクローン
git clone https://github.com/yourusername/better-playwright-mcp.git
cd better-playwright-mcp

# 依存関係をインストール
npm install

# プロジェクトをビルド
npm run build

# 開発モードで実行
npm run dev

プロジェクト構造

better-playwright-mcp/
├── src/
│   ├── index.ts                 # MCPモードのエントリポイント
│   ├── server.ts                # HTTPサーバーモードのエントリポイント
│   ├── playwright-mcp.ts        # MCPサーバーの実装
│   ├── client/
│   │   └── playwright-client.ts # MCP→HTTP通信のためのHTTPクライアント
│   ├── server/
│   │   └── playwright-server.ts # ブラウザを制御するHTTPサーバー
│   ├── extractor/
│   │   ├── parse2.ts           # xp識別子を生成するHTMLパース
│   │   ├── simplify-html.ts    # HTMLの簡略化
│   │   └── utils.ts            # 抽出ユーティリティ
│   └── utils/
│       └── token-limiter.ts    # トークンのカウントと制限
├── bin/
│   └── cli.js                  # CLIのエントリポイント
├── package.json
├── tsconfig.json
├── CLAUDE.md                   # AIアシスタントのための指示書
└── README.md

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。