Chrome Debugging and Browser Manipulation via Remote Debugging Protocol

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

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

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'

Core Concepts

1. Page Selection Model

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

2. UID-Based Element Model [CRITICAL]

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

3. JSON Arguments Required

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
```

4. Function-Based Script Evaluation

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

Quick Reference

Essential commands in bash-friendly format:

bash

# 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
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
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)
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
mise x node@20 -- mcporter call chrome-devtools.evaluate_script --args '{"function":"() => { return document.title }"}'

# Run JS with element argument
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"}'

Common Workflows

Basic Element Interaction

bash

# 1. Select page and take snapshot
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
# Example: uid=12 input type="email"

# 3. Interact with element using its 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"}'

Screenshot Workflow

bash

# 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"}'

Debug JavaScript Errors

bash

# 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"]}'

Run Performance Tests

bash

# Execute JavaScript to get performance metrics
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 }; }"}'

Important Reminders

UID Workflow is Mandatory

bash

# ❌ WRONG - CSS selectors don't work
mise x node@20 -- mcporter call chrome-devtools.click --selector "#login-button"

# ✅ CORRECT - Use UIDs from snapshot
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"}'

UIDs Expire on Navigation

bash

# After navigation, UIDs are invalid
mise x node@20 -- mcporter call chrome-devtools.navigate_page --args '{"type":"url","url":"..."}'

# Take fresh snapshot to get new UIDs
mise x node@20 -- mcporter call chrome-devtools.take_snapshot

Always Use --args with JSON

bash

# ❌ 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
mise x node@20 -- mcporter call chrome-devtools.take_screenshot --args '{"filePath":"./screen.png"}'

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

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.

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-debug

NPX Install

Tags

SKILL.md Content

Chrome Debugging and Browser Manipulation via Remote Debugging Protocol

Overview

Prerequisites [CRITICAL]

Available Tools

Core Concepts

1. Page Selection Model

2. UID-Based Element Model [CRITICAL]

3. JSON Arguments Required

4. Function-Based Script Evaluation

Quick Reference

Common Workflows

Basic Element Interaction

Screenshot Workflow

Debug JavaScript Errors

Run Performance Tests

Important Reminders

UID Workflow is Mandatory

UIDs Expire on Navigation

Always Use --args with JSON

Quick Troubleshooting

Additional Resources

Real-World Impact