浏览器操控
用于针对现有 Chrome 会话执行浏览器任务。
配置修复详情见 mcporter-config.md。
路由
- 如果
Chrome或Chrome [Internal]插件在当前会话中可调用,则使用其内置的 Chrome 控制技能。 - 否则,使用下面描述的 mcporter
chrome-devtools路由。
插件已捆绑或安装在磁盘上并不代表其可用;该插件必须在活动会话中可调用。两条路由都必须使用用户现有的 Chrome 配置文件。
对于 mcporter 回退,请使用以下目标:
mcporter call chrome-devtools.<tool>
大多数需要登录的网站在隔离配置文件中都会失败,因为全新的会话会触发验证码、设备检查或丢失 SSO/扩展状态。对于任何需要登录的网站,强烈优先使用现有的 Chrome 配置文件。
除非用户明确要求使用隔离/全新的浏览器,否则切勿使用 chrome-isolated、Playwright、Puppeteer、Codex 内嵌浏览器、AppleScript、osascript、GUI 脚本或 macOS open 来控制浏览器。
截图/实时 UI 错误需要此现有 Chrome 路径。curl、源码检查、Worker 烟雾测试或本地 Playwright 仅作为辅助证明;当用户展示了渲染后的浏览器问题,或者页面可能依赖于登录/配置文件状态时,不要将其视为同等解决方案。
检查 MCP
mcporter list chrome-devtools --schema
mcporter call chrome-devtools.list_pages --args '{}' --output text
list_pages 必须显示用户实际打开的标签页。如果显示的是空白/默认的隔离 Chrome,则停止并提示重新连接失败。
如果调用似乎在 Chrome 显示认证/附加/更新提示时挂起,请在回退之前处理附加提示。优先使用 Peekaboo 点击可见的 Chrome 允许 按钮;否则等待人工操作。不要仅仅因为第一次输出慢就重启守护进程或杀死 MCP 进程。
已测试的附加提示恢复方法:
PB="${PEEKABOO_BIN:-$HOME/bin/peekaboo}"
[ -x "$PB" ] || PB="$(command -v peekaboo)"
"$PB" permissions status --json
"$PB" see --app frontmost --path /tmp/chrome-attach.png --json --annotate
# 如果 UI 显示 Chrome 提示“允许远程调试?”,仅点击可见的“允许”按钮。
"$PB" click --coords <allow_x>,<allow_y> --json
mcporter call chrome-devtools.list_pages --args '{}' --output text
使用当前 Peekaboo 快照中的坐标,而不是过时的记录。成功的标志是 list_pages 返回用户真实的 Chrome 标签页。
附加提示规则:当当前快照清晰地显示 Chrome 请求允许 DevTools/MCP/浏览器自动化连接时,点击可见的 允许 按钮一次,然后重新运行 list_pages。如果按钮不可见或提示不明确,则停止并询问;不要静默切换到 Playwright/Puppeteer。
如果 list_pages 失败并出现 DevToolsActivePort 错误,请用户重启 Chrome 或 DevTools 桥接,然后重试一次:
mcporter daemon restart
mcporter call chrome-devtools.list_pages --args '{}' --output text
如果仍然失败,则停止并提示 Chrome DevTools MCP 不可用。不要使用 AppleScript。
避免产生噪音的恢复循环。重复的 MCP/浏览器重启可能会触发重新连接/登录提示和警告。尝试一次,然后暂停并选择更安静的路径。
典型流程
# 从 list_pages 中选择页面 ID
mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
# 检查页面
mcporter call chrome-devtools.take_snapshot --args '{}' --output text
# 导航到所选页面
mcporter call chrome-devtools.navigate_page --args '{"url":"https://example.com"}' --output text
# 点击最新快照中的元素 UID
mcporter call chrome-devtools.click --args '{"uid":"1_38","includeSnapshot":true}' --output text
# 输入/填充
mcporter call chrome-devtools.fill --args '{"uid":"1_13","value":"text","includeSnapshot":true}' --output text
# 运行 JavaScript,将秘密信息排除在输出之外
mcporter call chrome-devtools.evaluate_script --args '{"function":"() => document.title"}' --output json
在操作前使用 take_snapshot,并且只使用当前的 uid 值。除非视觉布局很重要,否则避免使用 take_screenshot。
实时 UI 验证
对于截图回归、已部署的仪表板检查或任何渲染后的浏览器本身就是错误的情况:
mcporter call chrome-devtools.list_pages --args '{}' --output text
mcporter call chrome-devtools.select_page --args '{"pageId":9}' --output text
mcporter call chrome-devtools.navigate_page --args '{"url":"https://example.com"}' --output text
mcporter call chrome-devtools.take_snapshot --args '{}' --output text
mcporter call chrome-devtools.evaluate_script --args '{"function":"() => document.body.innerText"}' --output json
使用现有的已登录/带配置文件的标签页集合。如果浏览器自动化不可用,则报告为验证缺口,而不是替换为隔离的浏览器工具。
秘密信息处理
切勿从页面 DOM、网络日志或输入中打印令牌/密码。对于令牌检查,仅返回形状信息:存在/不存在、长度、状态码、账户/组织名。