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.