Playwright MCP Skill
Use this skill to run Playwright MCP operations through uxc using fixed stdio endpoints.
Reuse the uxc skill for generic protocol discovery, auth/error handling, and envelope parsing rules.
Prerequisites
- -
uxc is installed and available in PATH. - INLINECODE4 is available in
PATH (Node.js installed). - Network access for first-time
@playwright/mcp package fetch. - Browser runtime can start locally (headless mode is default in this skill).
Core Workflow (Playwright-Specific)
Endpoint candidate inputs before finalizing:
- - Raw package form from docs: INLINECODE7
- Reliable non-interactive form: INLINECODE8
- Isolated/headless stable form (default for this skill):
-
npx -y @playwright/mcp@latest --headless --isolated
- Shared-profile headless form (for persistent login state):
-
npx -y @playwright/mcp@latest --headless --user-data-dir ~/.uxc/playwright-profile
- Shared-profile headed form (for interactive debug with same login state):
- INLINECODE11
- 1. Verify protocol/path from official source and probe:
- Official source:
https://github.com/microsoft/playwright-mcp
- probe candidate endpoints with:
-
uxc "npx -y @playwright/mcp@latest --headless --isolated" -h
- Confirm protocol is MCP stdio (
protocol == "mcp" in envelope).
- 2. Detect auth requirement explicitly:
- Run host help or a minimal read call and inspect envelope.
-
@playwright/mcp default flow is no OAuth/API key for local stdio use.
- 3. Use fixed link command by default:
-
command -v playwright-mcp-cli
- If missing, create it:
-
uxc link playwright-mcp-cli "npx -y @playwright/mcp@latest --headless --isolated"
- Optional shared-profile dual command setup for persistent sessions:
-
command -v playwright-mcp-headless
-
command -v playwright-mcp-ui
-
uxc link --daemon-exclusive ~/.uxc/playwright-profile playwright-mcp-headless "npx -y @playwright/mcp@latest --headless --user-data-dir ~/.uxc/playwright-profile"
-
uxc link --daemon-exclusive ~/.uxc/playwright-profile playwright-mcp-ui "npx -y @playwright/mcp@latest --user-data-dir ~/.uxc/playwright-profile"
-
playwright-mcp-cli -h
- If command conflict is detected and cannot be safely reused, stop and ask skill maintainers to pick another fixed command name.
- 4. Inspect operation schema before execution:
-
playwright-mcp-cli browser_navigate -h
-
playwright-mcp-cli browser_snapshot -h
-
playwright-mcp-cli browser_click -h
- 5. Prefer read-first interaction:
- Start with navigation/snapshot before mutating page state.
- 6. Execute actions with explicit confirmation when impact is high:
- Confirm before form submission, checkout, delete/destructive actions, or irreversible multi-step flows.
Guardrails
- - Keep automation on JSON output envelope; do not rely on
--text. - Parse stable fields first:
ok, kind, protocol, data, error. - Use
playwright-mcp-cli as default command path. - INLINECODE33 is equivalent to
uxc "npx -y @playwright/mcp@latest --headless --isolated" <operation> .... - Use direct
uxc "<endpoint>" ... only as temporary fallback when link setup is unavailable. - If browser profile conflict appears, keep
--isolated in endpoint and retry via the same fixed link command. - When using shared
--user-data-dir, run headless/headed links serially (not concurrently). - To enable seamless switching between headed UI login and headless CLI automation using the same profile directory, set a daemon exclusive key:
- Prefer link-level setup (recommended above), or set
UXC_DAEMON_EXCLUSIVE=~/.uxc/playwright-profile for ad-hoc runs.
- If the profile is still busy (another session is actively running), fallback:
uxc daemon stop
- - Prefer
browser_snapshot over screenshots for model-action loops.
References
- INLINECODE41
Playwright MCP 技能
使用此技能通过 uxc 利用固定 stdio 端点运行 Playwright MCP 操作。
复用 uxc 技能进行通用协议发现、认证/错误处理以及信封解析规则。
前提条件
- - uxc 已安装并可在 PATH 中找到。
- npx 可在 PATH 中找到（已安装 Node.js）。
- 首次获取 @playwright/mcp 包需要网络访问。
- 浏览器运行时可在本地启动（本技能默认使用无头模式）。
核心工作流程（Playwright 专用）
最终确定前的端点候选输入：
- - 来自文档的原始包形式：npx @playwright/mcp@latest
- 可靠的非交互形式：npx -y @playwright/mcp@latest
- 隔离/无头稳定形式（本技能默认）：
- npx -y @playwright/mcp@latest --headless --isolated
- 共享配置文件无头形式（用于持久登录状态）：
- npx -y @playwright/mcp@latest --headless --user-data-dir ~/.uxc/playwright-profile
- 共享配置文件有头形式（用于相同登录状态的交互式调试）：
- npx -y @playwright/mcp@latest --user-data-dir ~/.uxc/playwright-profile
- 1. 从官方来源验证协议/路径并进行探测：
- 官方来源：https://github.com/microsoft/playwright-mcp
- 使用以下命令探测候选端点：
- uxc npx -y @playwright/mcp@latest --headless --isolated -h
- 确认协议为 MCP stdio（信封中的 protocol == mcp）。
- 2. 明确检测认证需求：
- 运行主机帮助或最小读取调用并检查信封。
- @playwright/mcp 默认流程对于本地 stdio 使用无需 OAuth/API 密钥。
- 3. 默认使用固定链接命令：
- command -v playwright-mcp-cli
- 如果缺失，则创建：
- uxc link playwright-mcp-cli npx -y @playwright/mcp@latest --headless --isolated
- 可选：用于持久会话的共享配置文件双命令设置：
- command -v playwright-mcp-headless
- command -v playwright-mcp-ui
- uxc link --daemon-exclusive ~/.uxc/playwright-profile playwright-mcp-headless npx -y @playwright/mcp@latest --headless --user-data-dir ~/.uxc/playwright-profile
- uxc link --daemon-exclusive ~/.uxc/playwright-profile playwright-mcp-ui npx -y @playwright/mcp@latest --user-data-dir ~/.uxc/playwright-profile
- playwright-mcp-cli -h
- 如果检测到命令冲突且无法安全复用，则停止并请技能维护者选择另一个固定命令名称。
- 4. 在执行前检查操作模式：
- playwright-mcp-cli browser_navigate -h
- playwright-mcp-cli browser_snapshot -h
- playwright-mcp-cli browser_click -h
- 5. 优先采用先读后交互的方式：
- 在修改页面状态前，先进行导航/快照操作。
- 6. 当影响较大时，执行操作前需明确确认：
- 在表单提交、结账、删除/破坏性操作或不可逆的多步骤流程前进行确认。
防护措施
- - 保持自动化使用 JSON 输出信封；不要依赖 --text。
- 首先解析稳定字段：ok、kind、protocol、data、error。
- 默认使用 playwright-mcp-cli 作为命令路径。
- playwright-mcp-cli ... 等同于 uxc npx -y @playwright/mcp@latest --headless --isolated ...。
- 仅在链接设置不可用时，作为临时回退方案直接使用 uxc ...。
- 如果出现浏览器配置文件冲突，在端点中保留 --isolated 并通过相同的固定链接命令重试。
- 使用共享的 --user-data-dir 时，串行运行无头/有头链接（不要并发运行）。
- 为了在使用相同配置文件目录时，能够在有头 UI 登录和无头 CLI 自动化之间无缝切换，请设置守护进程独占键：
- 优先使用链接级别设置（推荐上述方式），或为临时运行设置 UXC
DAEMONEXCLUSIVE=~/.uxc/playwright-profile。
- 如果配置文件仍被占用（另一个会话正在运行），回退方案：uxc daemon stop
- - 在模型-动作循环中，优先使用 browser_snapshot 而非截图。
参考资料
- references/usage-patterns.md
