playwright-mcp

playwright-mcp

用途

此技能提供基于 Playwright 的 MCP 服务，可通过 MCP 协议以编程方式控制网页，实现浏览器自动化。它侧重于浏览网站、与元素交互和填写表单等任务，并与 OpenClaw 集成以支持 AI 驱动的工作流。

适用场景

在网页抓取、UI 测试或动态表单提交等场景中自动执行浏览器交互时，可使用此技能。当你需要远程控制浏览器时，它尤其适用，例如在 CI/CD 流水线中、从 JavaScript 密集型网站提取数据，或模拟跨多个页面的用户操作。

主要功能

• 启动浏览器（如 Chromium、Firefox），并通过 MCP 协议管理会话。
• 与页面元素交互：使用 page.click('button') 等方法选择、点击或输入。
• 处理表单填写和提交：自动填充字段并使用 page.fill('input[name="username"]', 'user123') 提交。
• 支持异步操作：使用 page.waitForSelector('selector') 等待元素。
• 支持容错导航：使用内置超时机制重试加载失败的页面。
• 通过 JSON 文件进行配置，例如 {"browser": "chromium", "headless": true}。

使用模式

要使用此技能，请启动 MCP 服务，并从 OpenClaw 发送命令。始终使用 $PLAYWRIGHT_MCP_API_KEY 进行身份验证并初始化。模式 1：启动浏览器会话并按顺序执行操作。模式 2：在循环中用于重复性任务，例如表单测试。集成时，请使用 try-catch 块包装调用。示例模式：使用命令行配置服务，然后通过 API 端点执行脚本。

常用命令/API

• CLI：运行 playwright-mcp start --port 8080 --headless 启动服务；添加 --debug 以启用详细日志记录。
• API：向 /mcp/execute 发送包含 JSON 负载的 POST 请求，例如 {"action": "navigate", "url": "https://example.com"}。
• 基本导航代码片段：

  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 请求。
• 配置格式：YAML 或 JSON，例如在通过 --config path/to/config.json 指定的文件中设置 {"timeout": 30000, "retries": 3}。
• 身份验证：始终在标头中包含 $PLAYWRIGHT_MCP_API_KEY；如果缺少该密钥，请检查是否出现 401 错误。

集成说明

通过将服务作为子进程运行，或在 OpenClaw 中使用 HTTP 客户端进行集成。将 $PLAYWRIGHT_MCP_API_KEY 设置为环境变量以进行身份验证。例如，在 OpenClaw 脚本中，可将其作为模块导入，并调用 mcpClient.execute({action: 'fill', selector: 'input', value: 'data'}). 等函数。使用 /mcp/ws 上的 WebSockets 获取实时更新。确保兼容 Node.js 14+；在 CLI 中添加 --allow-origins * 以处理 CORS。使用模拟服务测试集成，以模拟故障。

错误处理

常见错误包括超时异常（例如网络延迟）或选择器失败；请在操作前使用 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 调用以填写并提交登录表单：向 /mcp/execute 发送包含 {"action": "fill", "selector": '#username', "value": "testuser", "then": "click('#submit')"} 的 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（基于此项目处理协议）。