PWA Debug Layer

What PWA Debug Layer does

PWA Debug Layer gives MCP clients access to a live browser session rather than a newly created, isolated tab. That makes it suitable for debugging applications whose behavior depends on logged-in state, browser extensions, existing cookies, service workers, caches, or other profile data.

Its focus extends beyond ordinary page automation. The project is designed to inspect PWA runtime problems such as service workers that remain on an older version, stale cached assets, failed installation checks, browser capability gaps, and inconsistent application state. It also supports introspection for React, Vue, Svelte, and Solid applications, along with Redux, Zustand, Pinia, and Jotai stores.

How it works

An MCP client communicates over stdio with a native messaging host. The host coordinates persistent buffers and replay or snapshot storage, then communicates with a browser extension through native messaging. The extension uses the Chrome DevTools Protocol and routes requests to the selected tab, while content scripts handle DOM observation and actions. A page-world script provides access to framework hooks and page-level activity that isolated content scripts cannot reach.

The default operating model attaches to an existing browser profile. This preserves the page's authentication, extensions, cookies, service-worker state, and other runtime conditions. The project also describes Android support through adb for driving Android Chrome tabs and installed PWAs.

Setup and configuration

The full MCP-to-browser path is verified on Linux. macOS and Windows paths have unit coverage but have not been verified on physical machines, so browser discovery, profile paths, native-messaging registration, and system-default handling may require troubleshooting there.

Firefox is not supported because the implementation depends on Chrome DevTools Protocol support. The architecture is intended to coexist with chrome-devtools-mcp: the two can be used together, with this project providing real-profile, framework, store, service-worker, cache, and page-world access.

Tools and capabilities

The exposed browser tools cover:

• Opening, closing, selecting, listing, navigating, resizing, and capturing pages.
• Taking accessibility-tree snapshots and screenshots.
• Clicking, dragging, hovering, filling controls and forms, typing text, pressing keys, and handling dialogs.
• Evaluating JSON-serializable JavaScript in the target page.
• Reading console messages, network requests, CSS rules, and matched styles.
• Running Lighthouse audits, starting and analyzing performance traces, and capturing heap snapshots.
• Recording and stopping page screencasts.

The wider debugging surface includes persistent console, network, error, DOM-mutation, and lifecycle capture; framework and store inspection; touch gestures; library-popup capture and replay; rrweb session replay; source-map resolution; responsive layout sweeps; and PWA runtime diagnostics. These diagnostics include service-worker versions and lifecycle, CacheStorage contents and age, installability gaps, capability checks, IndexedDB and web-storage inspection, and version-skew analysis.

Limitations and notes

The implementation is currently centered on Chromium-based browsers and has been tested most extensively on Linux. Performance auditing is handled through trace tools rather than the Lighthouse audit tool, whose documented audit areas are accessibility, SEO, best practices, and agentic browsing. JavaScript evaluation returns JSON, so values returned from scripts must be JSON-serializable. CSS inspection requires a UID from the latest page snapshot and returns paginated rules.