playwright-mcp-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright MCP Skill

Playwright MCP 技能

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.

使用该技能通过固定的stdio端点，借助

uxc

运行Playwright MCP操作。

复用

uxc

技能实现通用协议发现、认证/错误处理以及信封解析规则。

Prerequisites

前置条件

```
uxc
```
is installed and available in
```
PATH
```
.
```
npx
```
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).

已安装
```
uxc
```
且可在
```
PATH
```
中访问。
可在
```
PATH
```
中访问
```
npx
```
（已安装Node.js）。
首次拉取
```
@playwright/mcp
```
包时需要网络访问权限。
浏览器运行时可在本地启动（本技能默认使用无头模式）。

Core Workflow (Playwright-Specific)

核心工作流（Playwright专属）

Endpoint candidate inputs before finalizing:

Raw package form from docs:
```
npx @playwright/mcp@latest
```
Reliable non-interactive form:
```
npx -y @playwright/mcp@latest
```

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):

npx -y @playwright/mcp@latest --user-data-dir ~/.uxc/playwright-profile

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).
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.

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.

Inspect operation schema before execution:

```
playwright-mcp-cli browser_navigate -h
```
```
playwright-mcp-cli browser_snapshot -h
```
```
playwright-mcp-cli browser_click -h
```

Prefer read-first interaction:
- Start with navigation/snapshot before mutating page state.
Execute actions with explicit confirmation when impact is high:
- Confirm before form submission, checkout, delete/destructive actions, or irreversible multi-step flows.

最终确定前的候选端点输入：

文档中的原始包形式：
```
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

从官方来源验证协议/路径并探测：
- 官方来源：
```
https://github.com/microsoft/playwright-mcp
```
- 使用以下命令探测候选端点：
  - ```
  uxc "npx -y @playwright/mcp@latest --headless --isolated" -h
```
- 确认协议为MCP stdio（信封中
```
protocol == "mcp"
```
  ）。
显式检测认证要求：
- 运行宿主帮助命令或最小化读取调用并检查信封。
- 本地stdio使用场景下，
```
@playwright/mcp
```
  默认流程无需OAuth/API密钥。

默认使用固定链接命令：

```
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
```
如检测到命令冲突且无法安全复用，停止操作并告知技能维护者选择其他固定命令名。

执行前检查操作schema：

```
playwright-mcp-cli browser_navigate -h
```
```
playwright-mcp-cli browser_snapshot -h
```
```
playwright-mcp-cli browser_click -h
```

优先采用先读取的交互模式：
- 在变更页面状态前先执行导航/快照操作。
高影响操作执行时需要显式确认：
- 表单提交、结账、删除/破坏性操作或不可逆多步流程执行前需要确认。

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.

playwright-mcp-cli <operation> ...

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.

自动化过程保持使用JSON输出信封，不要依赖
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
使用
```
playwright-mcp-cli
```
作为默认命令路径。

playwright-mcp-cli <operation> ...

等价于

uxc "npx -y @playwright/mcp@latest --headless --isolated" <operation> ...

。

仅当链接设置不可用时，临时使用直接
```
uxc "<endpoint>" ...
```
的方式作为降级方案。
如出现浏览器配置文件冲突，在端点中保留
```
--isolated
```
参数，通过同一个固定链接命令重试。
使用共享
```
--user-data-dir
```
时，串行运行无头/有头链接（不可并发）。
要实现使用同一配置目录在有头UI登录和无头CLI自动化之间无缝切换，需设置守护进程专属密钥：
- 优先使用链接级别设置（上文推荐方案），或为临时运行设置
```
UXC_DAEMON_EXCLUSIVE=~/.uxc/playwright-profile
```
  。
- 如配置文件仍被占用（另一个会话正在运行），降级方案：
```
uxc daemon stop
```
模型操作循环中优先使用
```
browser_snapshot
```
而非截图。

References

参考资料

Invocation patterns:
- ```
references/usage-patterns.md
```

调用模式：
- ```
references/usage-patterns.md
```