Shared-Browser Playwright And DevTools MCP Plan

Status: proposed Date: 2026-04-06

Goal

Expand the existing Playwright skill without renaming it. Rework the runtime so the container owns one long-lived, headless, debuggable Chrome or Chromium instance, then attach both Playwright automation and DevTools-backed diagnostics to that same browser.

The worthwhile version of this idea is not “swap Playwright for Chrome DevTools MCP”. It is “keep Playwright for automation, add DevTools capabilities against the same browser state”.

This document is a plan only. It does not imply that implementation has started.

Why This Is Worth Considering

  • The current Playwright skill is good at scripted automation, screenshots, CSS inspection, and repeatable interaction flows.
  • Chrome DevTools MCP adds capabilities that are awkward or less ergonomic in the current skill flow: network inspection, console inspection, performance tracing, memory snapshots, and audits.
  • The architecture is only worth doing if both paths use the same browser instance in the same container. If they spin up separate browsers, most of the value disappears.

Scope Boundary

  • Keep the existing Playwright skill name and entry point.
  • Use one long-lived browser process inside the existing persistent container model.
  • Default to Playwright for navigation, interaction, layout, and screenshot work.
  • Add DevTools-backed diagnostic flows for network, console, performance, memory, and audits.
  • Treat this as a skill-level integration. A SKILL.md file can surface these capabilities through routing guidance and bundled helper scripts, but it does not by itself register new first-class MCP tools in the client.

Isolation Model

The correct isolation primitive is a browser context, not a tab.

  • The container owns one long-lived headless browser process.
  • Each Playwright run creates a fresh browser context by default.
  • Pages or tabs for that run live inside that context.
  • Default behavior closes the context at the end of the run.
  • An opt-in retain mode keeps the context and page open for follow-up DevTools inspection.

This improves test isolation for cookies, storage, permissions, and session state while still allowing later inspection of the exact page state if retention is enabled.

This is test isolation, not hard security isolation. If stronger security isolation is required, separate browser processes or separate containers are still the safer boundary.

Proposed Architecture

Shared Browser Runtime

Refactor the container startup path so it owns the browser lifecycle rather than each user script.

  • Start Chrome or Chromium once per container.
  • Run it headless with --no-sandbox and a dedicated user data directory.
  • Expose a fixed remote debugging port for CDP attachment.
  • Add a health check so later calls can verify that the browser is alive.

Browser Manager

Add a helper that:

  • starts the browser if needed
  • waits for the CDP endpoint to become available
  • emits the browser URL or WebSocket endpoint for reuse
  • tracks retained contexts and pages for later inspection

Playwright Path

Refactor the current runner so it no longer expects user scripts to launch their own browser.

  • Connect to the shared browser over CDP
  • Create a fresh browser context per run by default
  • Create pages inside that context as needed
  • Close only the created context or page, not the shared browser
  • Support an explicit retain mode for follow-up inspection

DevTools Path

Add a DevTools wrapper inside the same skill that attaches to the shared browser and exposes high-value diagnostic flows.

  • list and select retained pages
  • inspect console messages
  • inspect network requests
  • capture performance traces
  • capture memory snapshots
  • optionally run audits

The recommended first version is transient per diagnostic action rather than a permanently resident MCP server process. That keeps lifecycle complexity lower while preserving the shared-browser requirement.

Phased Plan

  1. Define the shared-browser runtime in the current container wrapper so the browser process outlives individual script executions.
  2. Add a browser manager helper to bootstrap the browser and expose the CDP endpoint.
  3. Refactor the current runner from a single-mode script executor into a dispatcher that can support both Playwright automation and DevTools diagnostics while preserving the current result artifact shape where practical.
  4. Change the Playwright path to attach over CDP instead of launching a new browser process.
  5. Make per-run browser contexts the default isolation model.
  6. Add an explicit retain mode so a context and page can stay open for later DevTools inspection.
  7. Add a DevTools wrapper that can target retained pages deterministically.
  8. Limit the first DevTools surface to the capabilities that materially exceed the current Playwright workflow: network, console, performance, memory, and audits.
  9. Update the Playwright skill instructions and examples so they describe both automation and diagnostic paths, the per-run private-context model, and the retain mode.
  10. Validate the end-to-end architecture with a workflow where Playwright changes page state and DevTools inspects that exact retained page afterward.

Relevant Files

These are the expected primary touch points if implementation proceeds later.

  • playwright/scripts/run.sh
  • playwright/scripts/runner.js
  • playwright/SKILL.md
  • likely new: playwright/scripts/browser-manager.js
  • likely new: playwright/scripts/devtools-run.sh
  • likely new: playwright/scripts/devtools-helpers.js

Verification Criteria

If this plan is implemented later, the minimum acceptance checks should be:

  1. A normal Playwright screenshot or CSS inspection still works through the existing skill entry point.
  2. Playwright automation can mutate page state, then a DevTools step can inspect that exact retained page without starting a second browser.
  3. A performance trace can be captured without breaking later Playwright attachments.
  4. Per-run browser context isolation works by default.
  5. Retain mode keeps a page open long enough for later inspection, then cleanup removes it predictably.
  6. Idle cleanup removes both browser state and container state when the session expires.

Decisions

  • Keep the existing Playwright skill instead of creating a second user-facing skill first.
  • Only pursue this if Playwright automation and DevTools diagnostics target the same browser instance in the same container.
  • Preserve Playwright as the primary tool for basic interaction and screenshot flows.
  • Treat Playwright and DevTools control as serialized phases over a shared browser, not as two independent controllers running concurrently.

Open Risks

  • CDP attachment through connectOverCDP is lower fidelity than Playwright’s native browser server protocol, so some advanced features may be less reliable.
  • Page and context retention requires explicit lifecycle bookkeeping to avoid stale pages accumulating inside the shared browser.
  • Two controllers acting on the same browser at the same time will introduce race conditions, so the skill must steer usage toward serialized phases.
  • The shared-browser pattern improves observability and test-state continuity, but it is not a substitute for stronger sandbox boundaries when hostile content is in scope.

Recommendation

Do not start by replacing the Playwright skill runtime wholesale. Start by capturing this architecture as a plan, then implement only if the team wants the non-overlapping diagnostic capabilities badly enough to justify the added lifecycle complexity.