playwright-mcp

playwright-mcp

目的

このスキルは、ブラウザー自動化のための Playwright ベースの MCP サーバーを提供し、MCP プロトコルを介してウェブページをプログラムから操作できるようにします。サイトの移動、要素の操作、フォームへの入力といったタスクに重点を置き、AI 主導のワークフローを実現するために OpenClaw と統合されています。

使用する場面

ウェブスクレイピング、UI テスト、動的なフォーム送信などのシナリオで、ブラウザー操作を自動化する際にこのスキルを使用します。CI/CD パイプライン、JavaScript を多用するサイトからのデータ抽出、複数ページにわたるユーザー操作のシミュレーションなど、リモートでブラウザーを制御する必要がある場合に最適です。

主な機能

• ブラウザー（Chromium、Firefox など）を起動し、MCP プロトコルを介してセッションを管理します。
• page.click('button') などのメソッドを使って、ページ内の要素を選択、クリック、入力できます。
• page.fill('input[name="username"]', 'user123') を使って、フォームへの入力と送信に対応します。フィールドへの自動入力と送信が可能です。
• page.waitForSelector('selector') を使った要素の待機など、非同期処理に対応します。
• 組み込みタイムアウトを使って、失敗した読み込みを再試行する、エラーに強いナビゲーションを実現します。
• {"browser": "chromium", "headless": true} などの JSON ファイルで設定できます。

使用パターン

このスキルを使用するには、MCP サーバーを起動し、OpenClaw からコマンドを送信します。必ず $PLAYWRIGHT_MCP_API_KEY による認証を初期化してください。パターン 1：ブラウザーセッションを起動し、操作を順番に実行します。パターン 2：フォームテストなどの反復タスクでループを使用します。統合時は、呼び出しを try-catch ブロックで囲みます。使用例：CLI でサーバーをセットアップし、API エンドポイントを使ってスクリプトを実行します。

主なコマンド／API

• CLI：playwright-mcp start --port 8080 --headless を実行してサーバーを起動します。詳細なログを出力するには --debug を追加します。
• API：{"action": "navigate", "url": "https://example.com"} などの JSON ペイロードを /mcp/execute に POST します。
• 基本的なナビゲーションのコードスニペット：

  const response = fetch('http://localhost:8080/mcp/execute', {
    method: 'POST',
    headers: {'Authorization': `Bearer ${process.env.PLAYWRIGHT_MCP_API_KEY}`},
    body: JSON.stringify({action: 'goto', url: 'https://example.com'})
  });
  

• 要素の操作：/mcp/interact エンドポイントを使用します。たとえば、{"selector": '#id', "action": "click"} を指定して POST します。
• 設定形式：--config path/to/config.json で渡すファイルに、{"timeout": 30000, "retries": 3} などの YAML または JSON を記述します。
• 認証：ヘッダーに必ず $PLAYWRIGHT_MCP_API_KEY を含めてください。指定されていない場合は、401 エラーを確認します。

統合に関する注意事項

サーバーをサブプロセスとして実行するか、OpenClaw の HTTP クライアントを介して統合します。認証用に $PLAYWRIGHT_MCP_API_KEY を環境変数として設定してください。たとえば、OpenClaw のスクリプトでは、モジュールとしてインポートし、mcpClient.execute({action: 'fill', selector: 'input', value: 'data'}). のような関数を呼び出します。リアルタイム更新には /mcp/ws の WebSocket を使用します。Node.js 14+ との互換性を確保してください。CORS に対応するには、CLI に --allow-origins * を追加します。モックサーバーを使って統合をテストし、障害をシミュレートしてください。

エラー処理

よくあるエラーには、タイムアウト例外（ネットワーク遅延など）やセレクターの失敗があります。操作の前に page.waitForTimeout(5000) を使用してください。API エラーの場合は、レスポンスコードを確認します。無効なエンドポイントは 404、サーバーの問題は 500 です。コードでは、次のように try-catch で処理します。

try {
  await page.click('nonexistent');
} catch (error) {
  console.error('Element not found:', error.message);
  // Retry or fallback
}

--debug フラグを使って、すべてのエラーをログに記録するようにしてください。認証に失敗した場合は、$PLAYWRIGHT_MCP_API_KEY を確認して再試行します。429（レート制限）などの一時的なエラーには、指数バックオフを使用してください。

具体的な使用例

1. フォーム入力の自動化：playwright-mcp start --port 8080 でサーバーを起動し、ログインフォームへの入力と送信を行う API 呼び出しを送信します。{"action": "fill", "selector": '#username', "value": "testuser", "then": "click('#submit')"} を指定して /mcp/execute に POST します。これにより、データを抽出したり、ログインの成功を確認したりできます。
2. ウェブスクレイピングタスク：OpenClaw でページに移動し、コンテンツを抽出します。CLI コマンド playwright-mcp execute --url 'https://site.com' --script 'page.evaluate(() => document.querySelector("#data").textContent)' を実行し、出力を分析用に処理します。

グラフ上の関係

• 関連：browser-automation（中核機能のために依存）、web-scraping（データ抽出機能を拡張）、mcp-protocol（ベースとして実装）。
• クラスター：community（その一部）、automation-tools（より広範なエコシステムとのつながり）。
• 依存関係：playwright-core（ブラウザー制御に必要）、mcp-server（プロトコル処理の基盤）。