Chrome Debugging and Browser Manipulation via Remote Debugging Protocol

通过远程调试协议实现Chrome调试与浏览器操控

Overview

概述

Chrome DevTools Protocol (CDP) enables remote browser automation and debugging through mcporter.

Key capabilities:

Live browser debugging alongside Agent conversations
Automated form filling and interaction testing
Visual feedback via screenshots
Console log and network request inspection
JavaScript execution in page context

Chrome DevTools Protocol (CDP) 可通过mcporter实现远程浏览器自动化与调试。

核心功能：

与Agent对话同步进行实时浏览器调试
自动化表单填充与交互测试
通过截图提供视觉反馈
控制台日志与网络请求检查
在页面上下文中执行JavaScript

Prerequisites [CRITICAL]

前置条件 [至关重要]

Before using Chrome DevTools, ensure:

Chrome/Chromium is running with remote debugging enabled
The browser is listening on port 9222 (default)
Test connection with:

bash

mise x node@20 -- mcporter call chrome-devtools.list_pages

If this fails:

Start Chrome:

google-chrome --remote-debugging-port=9222

Check no other process is using port 9222
Get a human to help with browser setup

在使用Chrome DevTools前，请确保：

Chrome/Chromium已启动并启用远程调试
浏览器正在默认端口9222监听
使用以下命令测试连接：

bash

mise x node@20 -- mcporter call chrome-devtools.list_pages

如果连接失败：

启动Chrome：

google-chrome --remote-debugging-port=9222

检查端口9222未被其他进程占用
请他人协助完成浏览器设置

Available Tools

可用工具

Tool	Purpose
`list_pages`	List all open pages/tabs
`select_page`	Select a specific page/tab to work with
`new_page`	Create a new browser page/tab
`close_page`	Close a browser page/tab
`navigate_page`	Navigate to a URL, back, forward, or reload
`take_snapshot`	Take a DOM snapshot for inspection (returns UIDs)
`take_screenshot`	Capture a screenshot of the current page
`click`	Click an element on the page
`fill`	Fill input fields with text
`hover`	Hover over an element
`press_key`	Press keyboard keys (Enter, Tab, Escape, etc.)
`evaluate_script`	Execute JavaScript code in the page context
`wait_for`	Wait for elements, navigation, or conditions
`list_console_messages`	Get all console messages (logs, errors, warnings)
`list_network_requests`	Get all network requests made by the page
`emulate`	Emulate device settings (network, CPU throttling)
`resize_page`	Resize the browser viewport
`performance_start_trace`	Start performance tracing
`performance_stop_trace`	Stop performance tracing and get results

[!TIP] Get full tool list:

mcporter list chrome-devtools --json | jq -r '.tools[] | [.name, .description] | @tsv' | column -t -s $'\t'

工具	用途
`list_pages`	列出所有打开的页面/标签页
`select_page`	选择特定页面/标签页进行操作
`new_page`	创建新的浏览器页面/标签页
`close_page`	关闭浏览器页面/标签页
`navigate_page`	导航至URL、后退、前进或刷新页面
`take_snapshot`	生成DOM快照用于检查（返回UID）
`take_screenshot`	捕获当前页面的截图
`click`	点击页面上的元素
`fill`	为输入框填充文本
`hover`	悬停在元素上
`press_key`	按下键盘按键（如Enter、Tab、Escape等）
`evaluate_script`	在页面上下文中执行JavaScript代码
`wait_for`	等待元素出现、页面导航完成或指定条件满足
`list_console_messages`	获取所有控制台消息（日志、错误、警告）
`list_network_requests`	获取页面发起的所有网络请求
`emulate`	模拟设备设置（网络、CPU节流）
`resize_page`	调整浏览器视口大小
`performance_start_trace`	启动性能追踪
`performance_stop_trace`	停止性能追踪并获取结果

[!TIP] 获取完整工具列表：

mcporter list chrome-devtools --json | jq -r '.tools[] | [.name, .description] | @tsv' | column -t -s $'\t'

Core Concepts

核心概念

1. Page Selection Model

1. 页面选择模型

Chrome DevTools works with multiple pages/tabs
Use
```
list_pages
```
to see all open pages
Use
```
select_page
```
to choose which page to work with
All subsequent commands operate on the selected page

Chrome DevTools支持多页面/标签页操作
使用
```
list_pages
```
查看所有打开的页面
使用
```
select_page
```
选择要操作的页面
后续所有命令均针对选中的页面执行

2. UID-Based Element Model [CRITICAL]

2. 基于UID的元素模型 [至关重要]

You CANNOT interact with elements using CSS selectors directly
Must first call
```
take_snapshot
```
to get accessibility tree with UIDs
UIDs are temporary identifiers for elements (e.g., "5", "12", "42")
UIDs are invalidated on navigation - take new snapshot after nav

不能直接使用CSS选择器与元素交互
必须先调用
```
take_snapshot
```
获取包含UID的可访问性树
UID是元素的临时标识符（例如："5"、"12"、"42"）
页面导航后UID会失效 - 导航后需重新获取快照

3. JSON Arguments Required

3. 需传入JSON参数

All mcporter commands require
```
--args
```
with JSON object
Property names are camelCase (e.g.,
```
filePath
```
,
```
fullPage
```
,
```
pageIdx
```
)
Never use individual flags like
```
--file-path
```
or
```
--full-page
```

所有mcporter命令均需通过
```
--args
```
传入JSON对象
属性名称采用camelCase格式（例如：
```
filePath
```
、
```
fullPage
```
、
```
pageIdx
```
）
请勿使用
```
--file-path
```
或
```
--full-page
```
这类独立标志

4. Function-Based Script Evaluation

4. 基于函数的脚本执行

```
evaluate_script
```
requires a function declaration, not plain code
Return values must be JSON-serializable
Can pass element arguments via
```
args
```
array with UIDs

```
evaluate_script
```
要求传入函数声明，而非普通代码
返回值必须可序列化为JSON
可通过包含UID的
```
args
```
数组传入元素参数

Quick Reference

快速参考

Essential commands in bash-friendly format:

bash

undefined

适合Bash环境的常用命令：

bash

undefined

List and select page

列出并选择页面

mise x node@20 -- mcporter call chrome-devtools.list_pages mise x node@20 -- mcporter call chrome-devtools.select_page --args '{"pageIdx":0}'

Take snapshot to get UIDs

获取快照以获取UID

mise x node@20 -- mcporter call chrome-devtools.take_snapshot

Take screenshot

捕获截图

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

Take full-page screenshot

捕获全页面截图

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./full.png","fullPage":true}'

Navigate to URL

导航至指定URL

mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"url","url":"http://localhost:3000"}'

Navigate back/forward/reload

后退/前进/刷新页面

mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"back"}' mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"reload"}'

Click element (requires UID from snapshot)

点击元素（需从快照获取UID）

mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"12"}'

Fill input field

填充输入框

mise x node@20 -- mcporter call chrome-devtools.fill --args '{"uid":"5","value":"test@example.com"}'

Hover element

悬停元素

mise x node@20 -- mcporter call chrome-devtools.hover --args '{"uid":"8"}'

Press key

按下按键

mise x node@20 -- mcporter call chrome-devtools.press_key --args '{"key":"Enter"}'

Run JavaScript

执行JavaScript代码

mise x node@20 -- mcporter call chrome-devtools.evaluate_script --args '{"function":"() => { return document.title }"}'

Run JS with element argument

传入元素参数执行JS

mise x node@20 -- mcporter call chrome-devtools.evaluate_script --args '{"function":"(el) => { return el.innerText }","args":[{"uid":"12"}]}'

List console messages

列出控制台消息

mise x node@20 -- mcporter call chrome-devtools.list_console_messages

List only errors

仅列出错误消息

mise x node@20 -- mcporter call chrome-devtools.list_console_messages --args '{"types":["error"]}'

List network requests

列出网络请求

mise x node@20 -- mcporter call chrome-devtools.list_network_requests

Filter network by type

按类型过滤网络请求

mise x node@20 -- mcporter call chrome-devtools.list_network_requests --args '{"types":["fetch","xhr"]}'

Wait for text to appear

等待文本出现

mise x node@20 -- mcporter call chrome-devtools.wait_for --args '{"text":"Success"}'

Emulate network conditions

模拟网络条件

mise x node@20 -- mcporter call chrome-devtools.emulate --args '{"networkConditions":"Slow 3G"}'

undefined

mise x node@20 -- mcporter call chrome-devtools.emulate --args '{"networkConditions":"Slow 3G"}'

undefined

Common Workflows

常见工作流

Basic Element Interaction

基础元素交互

bash

undefined

bash

undefined

1. Select page and take snapshot

1. 选择页面并获取快照

mise x node@20 -- mcporter call chrome-devtools.list_pages mise x node@20 -- mcporter call chrome-devtools.select_page --args '{"pageIdx":0}' SNAPSHOT=$(mise x node@20 -- mcporter call chrome-devtools.take_snapshot) echo "$SNAPSHOT"

2. Find element UID in snapshot output

2. 在快照输出中查找元素UID

Example: uid=12 input type="email"

示例：uid=12 类型为email的输入框

3. Interact with element using its UID

3. 使用UID与元素交互

mise x node@20 -- mcporter call chrome-devtools.fill --args '{"uid":"12","value":"user@example.com"}' mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"15"}'

undefined

mise x node@20 -- mcporter call chrome-devtools.fill --args '{"uid":"12","value":"user@example.com"}' mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"15"}'

undefined

Screenshot Workflow

截图工作流

bash

undefined

bash

undefined

Take viewport screenshot

捕获视口截图

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

Take full-page screenshot

捕获全页面截图

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./full.png","fullPage":true}'

Screenshot specific element

捕获特定元素截图

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"uid":"20","filePath":"./button.png"}'

undefined

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"uid":"20","filePath":"./button.png"}'

undefined

Debug JavaScript Errors

JavaScript错误调试

bash

undefined

bash

undefined

Check console for errors

检查控制台中的错误与警告

mise x node@20 -- mcporter call chrome-devtools.list_console_messages --args '{"types":["error","warn"]}'

Check network requests

检查网络请求

mise x node@20 -- mcporter call chrome-devtools.list_network_requests --args '{"types":["fetch","xhr"]}'

undefined

mise x node@20 -- mcporter call chrome-devtools.list_network_requests --args '{"types":["fetch","xhr"]}'

undefined

Run Performance Tests

性能测试

bash

undefined

bash

undefined

Execute JavaScript to get performance metrics

执行JavaScript获取性能指标

mise x node@20 -- mcporter call chrome-devtools.evaluate_script
--args '{"function":"() => { const perf = performance.getEntriesByType("navigation")[0]; return { loadTime: perf.loadEventEnd - perf.fetchStart, domInteractive: perf.domInteractive - perf.fetchStart }; }"}'

undefined

mise x node@20 -- mcporter call chrome-devtools.evaluate_script
--args '{"function":"() => { const perf = performance.getEntriesByType("navigation")[0]; return { loadTime: perf.loadEventEnd - perf.fetchStart, domInteractive: perf.domInteractive - perf.fetchStart }; }"}'

undefined

Important Reminders

重要提示

UID Workflow is Mandatory

UID工作流是必须的

bash

undefined

bash

undefined

❌ WRONG - CSS selectors don't work

❌ 错误用法 - CSS选择器无效

mise x node@20 -- mcporter call chrome-devtools.click --selector "#login-button"

✅ CORRECT - Use UIDs from snapshot

✅ 正确用法 - 使用快照中的UID

mise x node@20 -- mcporter call chrome-devtools.take_snapshot # Get UIDs first mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"12"}'

undefined

mise x node@20 -- mcporter call chrome-devtools.take_snapshot # 先获取UID mise x node@20 -- mcporter call chrome-devtools.click --args '{"uid":"12"}'

undefined

UIDs Expire on Navigation

导航后UID会失效

bash

undefined

bash

undefined

After navigation, UIDs are invalid

导航后，UID将不再有效

mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"url","url":"..."}'

Take fresh snapshot to get new UIDs

获取新快照以获取新UID

mise x node@20 -- mcporter call chrome-devtools.take_snapshot

undefined

mise x node@20 -- mcporter call chrome-devtools.take_snapshot

undefined

Always Use --args with JSON

始终使用--args传入JSON

bash

undefined

bash

undefined

❌ WRONG - Individual flags don't work

❌ 错误用法 - 独立标志无效

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --file-path "./screen.png"

✅ CORRECT - Use --args with JSON

✅ 正确用法 - 使用--args传入JSON

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

undefined

mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

undefined

Quick Troubleshooting

快速故障排查

Error	Solution
"Element not found" / "Invalid UID"	Take fresh snapshot: `take_snapshot`
"No page selected"	Select page: `select_page --args '{"pageIdx":0}'`
"Connection refused"	Start Chrome: `google-chrome --remote-debugging-port=9222`
Screenshot not created	Ensure directory exists and use `--args` format
UIDs not working	UIDs expired after navigation - take new snapshot

错误	解决方案
"Element not found" / "Invalid UID"	获取新快照： `take_snapshot`
"No page selected"	选择页面： `select_page --args '{"pageIdx":0}'`
"Connection refused"	启动Chrome： `google-chrome --remote-debugging-port=9222`
截图未生成	确保目录存在并使用 `--args` 格式
UID无法使用	导航后UID已失效 - 获取新快照

Additional Resources

额外资源

Lazy-load these references based on your needs:

Reference	When to Use
Element Interaction	When working with UIDs, clicking, hovering, or measuring elements
Form Filling	When filling forms, submitting data, or handling keyboard input
Screenshots	When capturing screenshots, visual testing, or documenting state
Performance	When measuring page performance, network timing, or emulating conditions
Debugging	When investigating console errors, network failures, or script evaluation
Navigation	When navigating pages, managing tabs, or handling viewports
Troubleshooting	When encountering errors or unexpected behavior

[!IMPORTANT] Load references only when needed - Don't read all files upfront. Read the specific reference that matches your current task.

根据需求按需加载以下参考文档：

参考文档	使用场景
Element Interaction	处理UID、点击、悬停或元素测量操作时
Form Filling	填充表单、提交数据或处理键盘输入时
Screenshots	捕获截图、视觉测试或记录页面状态时
Performance	测量页面性能、网络时序或模拟环境条件时
Debugging	排查控制台错误、网络故障或脚本执行问题时
Navigation	页面导航、标签页管理或视口调整时
Troubleshooting	遇到错误或意外行为时

[!IMPORTANT] 仅在需要时加载参考文档 - 不要预先阅读所有文件。阅读与当前任务匹配的特定参考文档即可。

Real-World Impact

实际应用价值

Integrating Chrome DevTools Protocol enables:

Live browser debugging alongside Agent conversations
Automated form filling and interaction testing
Visual feedback on application behavior
Immediate error diagnostics from console logs
Screenshot-based validation workflows

Without this integration, debugging web applications requires constant context-switching between browser and Agent.

集成Chrome DevTools Protocol可实现：

与Agent对话同步进行实时浏览器调试
自动化表单填充与交互测试
可视化反馈应用行为
从控制台日志中即时诊断错误
基于截图的验证工作流

如果没有此集成，调试Web应用需要在浏览器与Agent之间频繁切换上下文。

chrome-debug

Original

Translation

Chrome Debugging and Browser Manipulation via Remote Debugging Protocol

通过远程调试协议实现Chrome调试与浏览器操控

Overview

概述

Prerequisites [CRITICAL]

前置条件 [至关重要]

Available Tools

可用工具

Core Concepts

核心概念

1. Page Selection Model

1. 页面选择模型

2. UID-Based Element Model [CRITICAL]

2. 基于UID的元素模型 [至关重要]

3. JSON Arguments Required

3. 需传入JSON参数

4. Function-Based Script Evaluation

4. 基于函数的脚本执行

Quick Reference

快速参考

List and select page

列出并选择页面

Take snapshot to get UIDs

获取快照以获取UID

Take screenshot

捕获截图

Take full-page screenshot

捕获全页面截图

Navigate to URL

导航至指定URL

Navigate back/forward/reload

后退/前进/刷新页面

Click element (requires UID from snapshot)

点击元素（需从快照获取UID）

Fill input field

填充输入框

Hover element

悬停元素

Press key

按下按键

Run JavaScript

执行JavaScript代码

Run JS with element argument

传入元素参数执行JS

List console messages

列出控制台消息

List only errors

仅列出错误消息

List network requests

列出网络请求

Filter network by type

按类型过滤网络请求

Wait for text to appear

等待文本出现

Emulate network conditions

模拟网络条件

Common Workflows

常见工作流

Basic Element Interaction

基础元素交互

1. Select page and take snapshot

1. 选择页面并获取快照

2. Find element UID in snapshot output

2. 在快照输出中查找元素UID

Example: uid=12 input type="email"

示例：uid=12 类型为email的输入框

3. Interact with element using its UID

3. 使用UID与元素交互

Screenshot Workflow

截图工作流

Take viewport screenshot

捕获视口截图

Take full-page screenshot

捕获全页面截图

Screenshot specific element

捕获特定元素截图

Debug JavaScript Errors