zenobi-us 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:
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_pagesto see all open pages - Use
select_pageto 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_snapshotto 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
--argswith JSON object - Property names are camelCase (e.g.,
filePath,fullPage,pageIdx) - Never use individual flags like
--file-pathor--full-page
4. Function-Based Script Evaluation
evaluate_scriptrequires a function declaration, not plain code- Return values must be JSON-serializable
- Can pass element arguments via
argsarray with UIDs
Quick Reference
Essential commands in bash-friendly format:
# 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
# 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
# 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
# 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
# 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
# ❌ 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
# 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
# ❌ 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.