chrome-debug（镀铬调试）

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:

1. Chrome/Chromium is running with remote debugging enabled
2. The browser is listening on port 9222 (default)
3. 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

[!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:

# 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

Additional Resources

Lazy-load these references based on your needs:

[!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.