Unified `capture_debug_bundle` Tool (HAR + Console + Performance + Screenshot)

[hamdigaied]

Is your feature request related to a problem? Please describe.

When an agent using chrome-devtools-mcp encounters a bug, regression, or “suspicious behavior” in the page, it’s often necessary to collect multiple types of DevTools data to debug it properly:

• Network behavior (HAR / waterfall).
• Console errors & warnings.
• Performance characteristics (long tasks, main thread activity, layout thrashing).
• Visual context (screenshot, viewport snapshot).
• Possibly some DOM / storage context.

Right now, an agent (or the host) would need to:

• Call several low-level tools (if exposed) or
• Rely on custom scripting and CDP calls outside of the MCP server, or
• Skip collecting this data entirely, which makes handoff to humans or later analysis much harder.

In contrast, when humans debug in Chrome DevTools, it’s common to “export a HAR”, “take a screenshot”, or “record a performance trace” around the point where the issue occurs and attach it to a bug report.

For agents, there’s no single, high-level way to say:

“I’ve hit a problem here — please capture the relevant DevTools artifacts so a human (or another system) can analyze this later.”

Describe the solution you'd like

Introduce a single, high-level tool (e.g. capture_debug_bundle) that collects a configurable set of debugging artifacts from the current page/session and returns them in a structured form.

1. capture_debug_bundle tool

• Inputs (example shape, exact schema flexible):

  • include_network_har: bool (default: true)
  • include_console_logs: bool (default: true)
  • include_performance_trace: bool (default: false or time‑bounded)
  • include_screenshot: bool (default: true)
  • trace_duration_ms: number (optional; if a mini trace should be captured around the call)
  • note: string (optional, agent’s short description of why this bundle is captured)

• Outputs (example):

  • bundle_id: string
  • artifacts: { ... } with fields such as:
    • network_har (HAR JSON, or reference/URL to stored HAR)
    • console_logs (structured array: type, message, timestamp, stack)
    • performance_trace (trace JSON or URL to trace file)
    • screenshot (data URL or binary reference / URL)
  • metadata (URL, timestamp, user agent, environment/profile name if available, etc.)

The server could optionally store these bundles somewhere (file system / configured storage) and return references that the host or a human can later retrieve.

2. Optional helper tools

Not strictly required, but could complement the main tool:

• list_debug_bundles → enumerate captured bundles in the current session / time window.
• get_debug_bundle(bundle_id) → re‑fetch a previously captured bundle.

From the agent’s perspective, the core flow would be:

1. Detect a failure / anomaly (HTTP 5xx, incorrect UI state, unexpected error).
2. Call capture_debug_bundle with a short note.
3. Surface the resulting bundle_id / artifacts to the user, or attach them to a bug tracking system.

Describe alternatives you've considered

Calling multiple low-level tools for each artifact.
This is possible in theory, but:

• It’s easy to forget one (e.g. you capture HAR but not console errors).

• It increases complexity for every agent or framework that wants good diagnostics.

• There’s no standard “debug package” shape, making host tooling and integrations harder.

• Relying on external CDP scripts or manual DevTools usage.
  Humans can still open DevTools and export HARs or traces manually, but:

  • This breaks the autonomous / semi‑autonomous agent workflow.
  • It makes it hard to automate regression workflows (e.g. nightly tests that automatically attach debug bundles to failures).

• Logging only text descriptions of failures.
  Better than nothing, but:

  • Lacks the rich, structured data (network timing, trace events, console stacks) that engineers rely on.
  • Makes it difficult to reproduce complex issues in distributed or flaky environments.

Additional context

This feature would be especially useful for:

• Agents running automated regression tests against web apps, where failures need to be triaged by humans later.
• Performance and reliability testing scenarios, where capturing consistent bundles around anomalies is critical.
• Any workflow where the agent needs to hand off a detailed “case file” to a developer or another system.

It also aligns conceptually with how DevTools is used today: as a hub for collecting rich diagnostic artifacts. Exposing a unified capture_debug_bundle at the MCP layer would make it much easier for agents to tap into that power without needing deep knowledge of CDP or managing multiple separate tools.

[natorion]

In scenarios like this I found it helpful to guide the AI agent what information it should collect e.g. in your automated regression tests tell it to:

If you encounter an error, make sure that you collect network, console and performance data. Also take a screenshot. Attach all of these information to the bug report you are creating on Jira.

An AI agent typically is able to figure out the lower level tools to call based on such guidance.

[natorion]

Thinking about this more, there is one technical argument where a unified tool outperforms agent orchestration: state drift.

If an Agent calls list_console_messages, then thinks for a few seconds, then calls take_screenshot, the state of the page might have changed significantly in between. An uberfunction would be able to prevent such a lag.

Is this 'time-synchronization' the main driver for your request?