browsing-with-playwright

ブラウザ自動化

Playwright MCP サーバーを介してブラウザ操作を自動化します。

サーバーのライフサイクル

サーバーの起動

# Using helper script (recommended)
bash scripts/start-server.sh

# Or manually
npx @playwright/mcp@latest --port 8808 --shared-browser-context &

サーバーの停止

# Using helper script (closes browser first)
bash scripts/stop-server.sh

# Or manually
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_close -p '{}'
pkill -f "@playwright/mcp"

停止のタイミング

• タスクの終了時: ブラウザでの作業が完了したら停止します
• 長時間のセッション: 複数のブラウザタスクを実行する場合は起動したままにします
• エラー時: ブラウザが応答しなくなったら停止して再起動します

重要: 複数の mcp-client.py 呼び出しにわたってブラウザの状態を維持するには、--shared-browser-context フラグが必要です。これがない場合、各呼び出しで新しいブラウザコンテキストが取得されます。

クイックリファレンス

ナビゲーション

# Go to URL
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate \
  -p '{"url": "https://example.com"}'

# Go back
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate_back -p '{}'

ページの状態を取得

# Accessibility snapshot (returns element refs for clicking/typing)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_snapshot -p '{}'

# Screenshot
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_take_screenshot \
  -p '{"type": "png", "fullPage": true}'

要素の操作

スナップショット出力の ref を使用して要素を指定します:

# Click element
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_click \
  -p '{"element": "Submit button", "ref": "e42"}'

# Type text
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_type \
  -p '{"element": "Search input", "ref": "e15", "text": "hello world", "submit": true}'

# Fill form (multiple fields)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_fill_form \
  -p '{"fields": [{"ref": "e10", "value": "[email protected]"}, {"ref": "e12", "value": "password123"}]}'

# Select dropdown
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_select_option \
  -p '{"element": "Country dropdown", "ref": "e20", "values": ["US"]}'

条件の待機

# Wait for text to appear
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
  -p '{"text": "Success"}'

# Wait for time (ms)
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
  -p '{"time": 2000}'

JavaScript の実行

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_evaluate \
  -p '{"function": "return document.title"}'

複数ステップの Playwright コード

複雑なワークフローでは、browser_run_code を使用して複数のアクションを 1 回の呼び出しで実行します:

python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_run_code \
  -p '{"code": "async (page) => { await page.goto(\"https://example.com\"); await page.click(\"text=Learn more\"); return await page.title(); }"}'

ヒント: アトミック（オール・オア・ナッシング）であるべき複雑な複数ステップの操作には、browser_run_code を使用してください。

ワークフロー: フォームの送信

1. ページに移動します
2. スナップショットを取得して要素の ref を見つけます
3. ref を使用してフォームフィールドに入力します
4. 送信をクリックします
5. 確認を待機します
6. 結果をスクリーンショットします

ワークフロー: データ抽出

1. ページに移動します
2. スナップショットを取得します（テキストコンテンツが含まれます）
3. 複雑な抽出には browser_evaluate を使用します
4. 結果を処理します

検証

実行: python3 scripts/verify.py

期待される結果: ✓ Playwright MCP server running

検証が失敗した場合

1. 診断を実行: pgrep -f "@playwright/mcp"
2. 確認: サーバープロセスがポート 8808 で実行されていること
3. 試す: bash scripts/start-server.sh
4. それでも失敗する場合は 停止して報告してください - 後続のステップに進まないでください

ツールリファレンス

完全なツールドキュメントについては、references/playwright-tools.md を参照してください。

トラブルシューティング

問題	解決策
要素が見つからない	最初に browser_snapshot を実行して現在の ref を取得します
クリックが失敗する	最初に browser_hover を試してから、クリックします
フォームが送信されない	browser_type で "submit": true を使用します
ページが読み込まれない	待機時間を増やすか、browser_wait_for を使用します
サーバーが応答しない	停止して再起動します: bash scripts/stop-server.sh && bash scripts/start-server.sh