name: dev-browser description: 通过MCP工具实现浏览器自动化。始终使用这些工具来完成任何网络任务——浏览网站、点击、输入、填写表单、截图或提取数据。这是控制浏览器的唯一方式。

Dev Browser

使用MCP工具实现浏览器自动化。直接使用这些工具来完成所有网络自动化任务。

重要提示：不要使用Shell命令打开浏览器

绝不要使用bash/shell命令来打开浏览器或URL。 这包括：

open (macOS)
xdg-open (Linux)
start (Windows)
Python subprocess, webbrowser 或类似工具
任何启动浏览器进程的脚本

Shell命令会打开用户的默认浏览器（Safari、Arc、Firefox等），而不是自动化控制的Chrome实例。这会破坏工作流程，因为你无法与通过shell命令打开的页面进行交互。

所有浏览器自动化必须使用下面的browser_ MCP工具。*

重要提示：使用browser_script提高速度

对于多步骤工作流，始终使用browser_script。 它比单独调用快5-10倍。

browser_script在运行时使用CSS选择器找到元素——你不需要事先准备好refs。这可以在一个调用中完成整个工作流。

何时使用browser_script

登录流程：导航 → 填写电子邮件 → 填写密码 → 提交 → 验证
表单提交：填写多个字段 → 点击提交 → 等待结果
多页面工作流：导航 → 点击 → 等待 → 交互 → 快照
任何有2个以上步骤的工作流

示例：完整的登录流程（一次调用）

browser_script(actions=[
  {"action": "goto", "url": "example.com/login"},
  {"action": "waitForLoad"},
  {"action": "findAndFill", "selector": "input[type='email']", "text": "user@example.com"},
  {"action": "findAndFill", "selector": "input[type='password']", "text": "secret123"},
  {"action": "findAndClick", "selector": "button[type='submit']"},
  {"action": "waitForNavigation"}
])

这将在一次往返中执行整个登录流程。自动返回快照，所以你总是能看到最终页面状态。

browser_script动作

动作	参数	描述
`goto`	url	导航到URL
`waitForLoad`	timeout?	等待页面加载
`waitForSelector`	selector, timeout?	等待元素出现
`waitForNavigation`	timeout?	等待导航完成
`findAndFill`	selector, text, pressEnter?, skipIfNotFound?	查找元素，填充它
`findAndClick`	selector, skipIfNotFound?	查找元素，点击它
`fillByRef`	ref, text, pressEnter?	使用快照中的ref填充
`clickByRef`	ref	使用快照中的ref点击
`snapshot`	-	获取ARIA快照（最后返回）
`screenshot`	fullPage?	截图（最后返回）
`keyboard`	key OR text	按键或输入文本
`evaluate`	code	在页面中运行JavaScript

核心特性

运行时元素发现：findAndFill 和 findAndClick 在动作运行时定位元素
自动快照：最终页面状态总是返回——无需添加快照动作
skipIfNotFound：设置为true以在元素缺失时继续（适用于可选字段）
自动等待：像goto和点击这样的动作等待页面稳定
错误调试：如果脚本失败，自动捕获失败时的页面状态

示例：带有可选字段的表单

browser_script(actions=[
  {"action": "goto", "url": "example.com/signup"},
  {"action": "waitForLoad"},
  {"action": "findAndFill", "selector": "#name", "text": "John Doe"},
  {"action": "findAndFill", "selector": "#email", "text": "john@example.com"},
  {"action": "findAndFill", "selector": "#phone", "text": "555-1234", "skipIfNotFound": true},
  {"action": "findAndClick", "selector": "button[type='submit']"},
  {"action": "waitForNavigation"}
])

注意：不需要在最后添加snapshot——它是自动的！

工具

browser_navigate(url, page_name?) - 导航到URL

url: 要访问的URL（例如，“google.com”或“https://example.com”）
page_name: 页面的可选名称（默认：“main”）

browser_snapshot(page_name?, interactive_only?) - 获取页面的可访问性树

返回包含元素refs的YAML，如[ref=e5]
使用这些refs与browser_click和browser_type
interactive_only=true: 仅显示可点击/可输入的元素（推荐！）

browser_click(x?, y?, ref?, selector?, page_name?) - 在页面上点击

x, y: 像素坐标（默认方法）
ref: 来自browser_snapshot的元素ref（替代方法）
selector: CSS选择器（替代方法）

browser_type(ref?, selector?, text, press_enter?, page_name?) - 在输入框中输入

ref: 来自browser_snapshot的元素ref（首选）
selector: CSS选择器作为备选
text: 要输入的文本
press_enter: 设置为true在输入后按Enter

browser_screenshot(page_name?, full_page?) - 截取屏幕

返回图像以供视觉检查
full_page: 设置为true以获取完整可滚动页面

browser_evaluate(script, page_name?) - 运行自定义JavaScript

script: 纯JavaScript代码（无TypeScript）

browser_pages(action, page_name?) - 管理页面

action: "list"查看所有页面，"close"关闭页面

browser_keyboard(text?, key?, page_name?) - 在焦点元素上输入

text: 要输入的文本（使用真实的键盘事件）
key: 特殊键如"Enter", “Tab”, “Escape”，或组合如"Control+a"
对于复杂的编辑器如Google Docs, Monaco等没有简单输入refs的情况使用这个
工作流程：先点击以聚焦编辑区域，然后使用browser_keyboard输入

browser_script(actions, page_name?) - 在一次调用中执行完整的工作流（见上文）

使用这个提高速度——在运行时找到元素，不需要事先准备好refs
动作：goto, waitForLoad, waitForSelector, waitForNavigation, findAndFill, findAndClick, fillByRef, clickByRef, snapshot, screenshot, keyboard, evaluate

browser_batch_actions(urls, extractScript, waitForSelector?, page_name?) - 在一次调用中从多个URL提取数据

使用这个进行多页面数据收集——访问每个URL，运行你的JS，返回紧凑的JSON
提供多达20个URL和一个JS提取脚本
返回JSON仅（无快照/屏幕截图）以最小化令牌使用
每个URL的错误会被跳过——一个失败的页面不会停止批次
每页30秒超时

browser_sequence(actions, page_name?) - 更简单的批处理（需要事先准备好refs）

当你已经从快照中获得refs时使用
支持的动作：click, type, snapshot, screenshot, wait

browser_get_text(ref?, selector?, page_name?) - 获取元素的文本内容

返回元素的文本内容
用于验证文本是否已输入或内容是否出现

browser_is_visible(ref?, selector?, page_name?) - 检查元素是否可见

返回true/false
用于验证元素在操作后是否出现

browser_is_enabled(ref?, selector?, page_name?) - 检查元素是否启用

返回true/false
用于验证按钮/输入是否可点击

browser_is_checked(ref?, selector?, page_name?) - 检查复选框/单选按钮是否被选中

返回true/false
用于验证表单状态

工作流

首选：使用browser_script完成完整的工作流

browser_script(actions=[
  {"action": "goto", "url": "example.com"},
  {"action": "waitForLoad"},
  {"action": "findAndFill", "selector": "input[name='search']", "text": "query", "pressEnter": true},
  {"action": "waitForNavigation"}
])

→ 自动返回步骤结果+最终页面快照

替代方案：当你需要先检查时逐步执行

browser_navigate("example.com") - 转到页面
browser_snapshot() - 查找refs如[ref=e5]
browser_script或browser_sequence - 执行剩余动作

重要提示：以验证为驱动的工作流

在每个动作之后验证它是否成功，然后再继续：

导航 → 拍摄快照以确认页面已加载
点击 → 拍摄快照或使用browser_is_visible确认预期变化
输入 → 使用browser_get_text确认文本已输入
表单操作 → 使用browser_is_checked确认复选框状态

示例验证流程：

# 点击提交按钮
browser_click(ref="e5")

# 验证：检查成功消息是否出现
browser_is_visible(selector=".success-message")
# 输出：true

# 如果为false，则操作可能已失败——在继续之前进行调查
browser_snapshot()  # 查看实际发生了什么

为什么这很重要：

页面动态变化——refs变得陈旧
动作可能会默默失败（覆盖层、加载状态）
验证告诉你何时继续vs重试
没有验证，代理假设成功并在事情出错时放弃

当验证失败时：

拍摄新的快照以查看当前页面状态
查找错误消息、加载指示器或覆盖层
解决阻塞问题（关闭模态、等待加载等）
重试原始动作
再次验证

错误恢复

当动作失败时，错误消息会告诉你该怎么做：

错误	这意味着什么	该怎么做
“元素被覆盖层阻挡”	模态/弹出窗口覆盖元素	找到关闭按钮，按Escape，或点击外部
“元素未找到”	页面变化，ref已陈旧	运行browser_snapshot()以获取更新的refs
“多个元素匹配”	选择器太宽泛	使用快照中更具体的ref
“元素不可见”	元素存在但隐藏	滚动到视图中或等待它出现
“页面已关闭”	标签页被关闭	使用browser_tabs(action=“list”)查找正确的标签页

永远不要在第一次失败时放弃。 拍摄快照，了解发生了什么，然后适应。

重要提示：点击后的标签页意识

在点击链接或按钮后始终检查是否有新标签页打开。

许多网站在新标签页中打开内容。如果你点击了某物而页面似乎没有变化，很可能打开了新标签页。

点击后的流程：

browser_click(ref="e5") - 点击元素
browser_tabs(action="list") - 检查是否打开了新标签页
如果存在新标签页：browser_tabs(action="switch", index=N) - 切换到它
browser_snapshot() - 从正确的标签页获取内容

示例：

# 点击可能会打开新标签页的链接
browser_click(ref="e3")

# 检查标签页——点击后总是这样做！
browser_tabs(action="list")
# 输出：打开的标签页（2）：
# 0: https://original.com
# 1: https://newpage.com
#
# 检测到多个标签页！使用browser_tabs(action="switch", index=N)切换到另一个标签页。

# 新标签页已打开！切换到它
browser_tabs(action="switch", index=1)
# 输出：已切换到标签页1：https://newpage.com
#
# 现在使用browser_snapshot()查看此标签页的内容。

# 现在拍摄新标签页的快照
browser_snapshot()

你可能在错误的标签页上的迹象：

点击链接后页面内容没有变化
在快照中找不到预期的元素
导航后URL仍然是旧的URL

何时检查标签页：

点击任何链接后
点击"Open", “View”, "Details"按钮后
点击外部链接后
当页面内容与预期不符时

示例

Google搜索（一次调用browser_script）

browser_script(actions=[
  {"action": "goto", "url": "google.com"},
  {"action": "waitForLoad"},
  {"action": "findAndFill", "selector": "textarea[name='q']", "text": "cute animals", "pressEnter": true},
  {"action": "waitForNavigation"}
])

返回：步骤结果+最终页面快照（自动）

完整的登录流程（一次调用）

browser_script(actions=[
  {"action": "goto", "url": "example.com/login"},
  {"action": "waitForLoad"},
  {"action": "findAndFill", "selector": "input[type='email']", "text": "user@example.com"},
  {"action": "findAndFill", "selector": "input[type='password']", "text": "mypassword"},
  {"action": "findAndClick", "selector": "button[type='submit']"},
  {"action": "waitForNavigation"}
])

返回：步骤结果+最终页面快照（自动）

多步骤结账（一次调用）

browser_script(actions=[
  {"action": "goto", "url": "example.com/checkout"},
  {"action": "waitForLoad"},
  {"action": "findAndFill", "selector": "#name", "text": "John Doe"},
  {"action": "findAndFill", "selector": "#address", "text": "123 Main St"},
  {"action": "findAndFill", "selector": "#city", "text": "New York"},
  {"action": "findAndFill", "selector": "#zip", "text": "10001"},
  {"action": "findAndClick", "selector": "button.submit"},
  {"action": "waitForNavigation"}
])

返回：步骤结果+最终页面快照（自动）

批量数据提取（一次调用browser_batch_actions）

当你需要从多个页面（例如搜索结果、列表、产品比较）中提取数据时，首先收集URL，然后批量提取数据：

步骤1： 使用browser_evaluate或browser_script从搜索结果页面收集URL：

browser_evaluate(script="return [...document.querySelectorAll('a.listing-link')].map(a => a.href)")

步骤2： 一次调用中从所有URL提取数据：

browser_batch_actions({
  urls: ["https://example.com/listing/1", "https://example.com/listing/2", "..."],
  extractScript: "return { title: document.querySelector('h1')?.textContent, price: document.querySelector('.price')?.textContent, details: document.querySelector('.details')?.textContent?.slice(0, 300) }",
  waitForSelector: "h1"
})

返回：紧凑的JSON结果，每个URL——无快照，无屏幕截图，最小化令牌使用。

何时使用browser_batch_actions与browser_script：

browser_batch_actions: 访问多个URL以提取数据，每页无需交互。
browser_script: 在单个页面上执行工作流（填写表单、点击按钮、导航）。

Google Docs

重要提示：对于Google Docs/Sheets/Slides，直接导航并使用browser_keyboard：

browser_navigate(url="docs.google.com/document/create")
browser_click(x=640, y=300)  # 聚焦编辑器
browser_keyboard(text="Hello, this is my document")
browser_keyboard(key="Enter")
browser_keyboard(text="Second paragraph")
browser_screenshot()  # 验证

直接URLs：

新文档：docs.google.com/document/create
新表格：docs.google.com/spreadsheets/create
新幻灯片：docs.google.com/presentation/create

登录页面

当你遇到登录页面（例如，Google登录、OAuth屏幕、身份验证提示）：

不要说你不能登录或建议替代方法
相反，让用户在浏览器窗口中手动登录
拍摄屏幕截图以向用户显示登录页面
说些什么，比如：“我已经到达登录页面。请在浏览器窗口中登录到你的账户，然后告诉我你完成了。”
等待用户确认他们已经登录后再继续
用户确认登录后，再拍摄屏幕截图以验证你已经通过了登录屏幕
然后继续执行原始任务

这种交互式登录流程至关重要，因为：

用户期望自己进行身份验证以确保安全
许多服务需要人类验证（CAPTCHAs, 2FA）
代理不应该放弃需要身份验证的任务

文件系统

对于保存/下载内容：

使用浏览器的原生下载（点击下载按钮，另存为）
Chrome使用自己的权限处理下载
对于文本/数据，复制到剪贴板，以便用户可以粘贴到他们想要的地方