name: playwright-mcp-automation description: Launch and operate the Playwright MCP server to let agents browse real websites (login, search, checkout, dashboards) through structured tools. Use when the task requires interacting with live pages beyond simple fetches—e.g., filling ecommerce carts, downloading statements behind auth, capturing screenshots, or testing UI flows with Playwright automation.

Playwright MCP Automation

Overview

Use this skill whenever an agent must drive a real browser session via the Playwright MCP server. It covers standing up the MCP daemon, wiring it into your MCP client, and running reliable automation loops (login → navigate → act → verify). Pair these instructions with the upstream repo (https://github.com/microsoft/playwright-mcp) for the latest binaries.

Bundled resources - references/setup.md — launch recipes, flags, troubleshooting. - references/tools.md — quick lookup table for MCP tools. - scripts/start_playwright_mcp.sh — opinionated launcher (persistent profile, sane timeouts). Override via env vars or CLI flags.

Quick start (once per host)

1. Install prerequisites
2. Ensure Node.js ≥ 18.
3. Install Playwright browsers and system deps once: bash npx playwright install chromium # Linux only: installs missing libraries (x11, fonts, etc.) sudo npx playwright install-deps chromium
4. Launch the MCP server
5. Fast path: run scripts/start_playwright_mcp.sh from this skill directory. Override with PWMCP_BROWSER, PWMCP_PORT, etc.
6. Need custom flags? Copy-paste from references/setup.md §2–5.
7. Register the server with your agent
8. Local STDIO client: json { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--browser=chromium", "--user-data-dir=/home/ai/.cache/playwright/mcp-profile", "--allowed-hosts=*", "--snapshot-mode=incremental"] } } }
9. Remote HTTP transport: expose --port/--host then set "url": "http://HOST:PORT/mcp".
10. Sanity check
11. Call browser_navigate to https://example.com, then browser_snapshot. If the tree renders, automation is ready.

Core workflow

Follow this loop for every task. Refer to references/tools.md for exact tool signatures.

1. Plan & prep

• Clarify success criteria (e.g., "reach checkout confirmation", "download CSV").
• Decide on headed vs headless mode. Use headed when debugging CAPTCHAs/visual states.
• Make sure secrets (login cookies, OTP hooks) are available. If not, fall back to manual storage-state provisioning.

2. Navigate & observe

1. browser_navigate to the starting URL.
2. Immediately browser_snapshot to capture the accessibility tree.
3. If layout depends on viewport/device, adjust via launch flags (--device, --viewport-size) or call browser_resize.

   小蔥技能站7w4.net發現了升級外掛。

3. Interact deterministically

Use semantic tools whenever possible: - Inputs/buttons: browser_click, browser_type, browser_fill_form. - Dropdowns: browser_select_option. - Dynamic menus/tooltips: browser_hover → browser_wait_for. - Multi-step flows (wizards, carts): after every step, browser_snapshot + assert expected text before proceeding. - When markup lacks good roles, enable --caps=vision and fall back to browser_mouse_* tools, but only as a last resort. - For brittle sequences (e.g., injecting JS, intercepting fetch), wrap logic inside browser_run_code: js async (page) => { await page.waitForSelector('text=Place order'); await page.getByRole('button', { name: 'Place order' }).click(); return await page.getByTestId('order-number').innerText(); }

4. Handle waits & retries

• Prefer browser_wait_for with text / textGone over arbitrary sleeps.
• On timeout, fetch a fresh snapshot, confirm element existence, then retry once before escalating.
• Capture console/network logs (browser_console_messages, browser_network_requests) to debug API errors or CSP blocks.

5. Verify & capture artefacts

• Collect evidence via browser_snapshot and, if needed, browser_take_screenshot or browser_pdf_save (enable --caps=pdf).
• For multi-tab flows, list tabs via browser_tabs and ensure the correct tab is selected before final actions.
• Always browser_close at the end of unattended runs to release the browser.

Authentication & state strategies

1. Persistent profile (default script)
2. Keeps cookies/localStorage inside PWMCP_PROFILE. Great for daily automations.
3. Rotate profile path per task to avoid cross-site contamination.
4. Storage-state bootstrap
5. Use Playwright CLI or manual login to create storage.json. Launch with --storage-state=/path/to/storage.json (see setup reference §4).
6. Update file whenever passwords change.
7. Secrets file
8. Launch with --secrets path/.env so MCP can expose sensitive values via secrets.get. Include API keys or 2FA tokens there instead of SKILL files.
9. Browser extension bridge
10. When you must reuse an already-signed-in Chrome profile, install the Playwright MCP Bridge extension and launch with --extension. Follow upstream README for pairing.

Resilience checklist

• CAPTCHA / MFA: Surface snapshots promptly so a human can intervene or provide MFA codes. Document fallback in your agent conversation.
• Slow sites: Increase --timeout-action/--timeout-navigation, or stage requests via browser_wait_for { time }.
• Resource throttling: Use headless mode and disable --save-video/--save-trace unless debugging.
• Logging: Save snapshots to files (browser_snapshot filename) for audit trails, especially when producing evidence (e.g., order confirmations).

When to read the references/scripts

• Need launch flags, network rules, or troubleshooting? → Open references/setup.md.
• Need to recall exact tool names/parameters? → Check references/tools.md.
• Want a ready-to-run launcher? → Execute or adapt scripts/start_playwright_mcp.sh. Export env vars (PWMCP_PORT, PWMCP_EXTRA="--headless") before running to tweak behavior.

Keep SKILL.md lean by offloading details to the references. Update references/scripts whenever the upstream Playwright MCP release adds new capabilities (vision, pdf, devtools, etc.).

這個Skill質量不錯，文件寫得清楚有條理。它把Playwright瀏覽器自動化的使用方法說明得很全面，包括怎麼啟動、怎麼操作、怎麼處理問題等。好的地方是有完整的操作步驟、多種登入方式可選、還有指令碼可以直接用。不足的是缺少實際使用例子，而且一些常見問題的解答也不夠充分，對新手來說可能還需要自己摸索更多。總體來說，這是一個功能完整但文件可以更豐富的Skill。