# PWA Debug Layer [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/aryanduntley/pwa-debug-layer  
**GitHub Stars:** 0  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pwa-debug-layer

## Description
Debug PWAs in your real browser via MCP: service-worker, cache, installability & framework state.

## Tools
Capabilities this server exposes over MCP:

- **click** — Clicks on the provided element
- **close_page** — Closes the page by its index. The last open page cannot be closed.
- **drag** — Drag an element onto another element
- **emulate** — Emulates various features on the target page. Each call replaces all emulation settings (except extraHttpHeaders), so pass all desired settings in a single call.
- **evaluate_script** — Evaluate JavaScript inside the target page. The source can be provided inline or loaded from a local file. Returns the response as JSON, so returned values have to be JSON-serializable.
- **fill** — Type text into an input, text area or select an option from a <select> element.
- **fill_form** — Fill out multiple form elements (inputs, selects, checkboxes, radios) at once. ALWAYS prefer this tool over multiple individual 'fill' or 'click' calls when interacting with forms. It is significantly faster, more reliable, and reduces turn count. Example: Fill username, password, and check "Remember Me" in one call.
- **get_console_message** — Gets a console message by its ID. You can get all messages by calling list_console_messages.
- **get_css_styles** — Retrieve matched CSS rules, inline styles (element.style), inherited styles, custom properties, and cascade wrappers (@layer, @media, @container, @scope) for an element identified by its UID.
Rules are ordered from highest to lowest cascade precedence and include source line numbers (e.g. index:196). Active (winning) declarations have no prefix tag, while (losing) overridden declarations are prefixed with [overloaded].
Treat the output as authoritative and complete.
Results are paginated (10 rules per page by default); use pageIdx to page through the remaining rules. Requires a UID from take_snapshot.
- **get_network_request** — Gets a network request by an optional reqid, if omitted returns the currently selected request in the DevTools Network panel. Useful for inspecting request headers (including 'Cookie') and response headers (including 'Set-Cookie' and directives).
- **handle_dialog** — If a browser dialog was opened, use this command to handle it
- **hover** — Hover over the provided element
- **lighthouse_audit** — Get Lighthouse scores, failing audits, and the DOM nodes they flag for accessibility, SEO, best practices, and agentic browsing. Full reports are saved to disk. This excludes performance. For performance audits, run performance_start_trace
- **list_console_messages** — List all console messages for the target page since the last navigation.
- **list_network_requests** — Lists the most recent requests for the target page since the last navigation.
- **list_pages** — Get a list of pages open in the browser.
- **navigate_page** — Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.
- **new_page** — Open a new tab and load a URL. Use project URL if not specified otherwise.
- **performance_analyze_insight** — Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.
- **performance_start_trace** — Start a performance trace on the target webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.
- **performance_stop_trace** — Stop the active performance trace recording on the target webpage.
- **press_key** — Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).
- **resize_page** — Resizes the page's window so that the page has specified dimension
- **screencast_start** — Starts recording a screencast (video) of the target page.
- **screencast_stop** — Stops the active screencast recording on the target page.
- **select_page** — Select a page as a context for future tool calls.
- **take_heapsnapshot** — Capture a heap snapshot of the target page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.
- **take_screenshot** — Take a screenshot of the page or element.
- **take_snapshot** — Take a text snapshot of the target page based on the a11y tree. The snapshot lists page elements along with a unique
identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot. The snapshot indicates the element selected
in the DevTools Elements panel (if any).
- **type_text** — Type text using keyboard into a previously focused input
- **upload_file** — Upload a file through a provided element.
- **wait_for** — Wait for the specified text to appear on the selected page. By default, hidden text is also matched. Set visible to true to wait until the matched text is visible.

## Claude Desktop Quick Installation
No generated config for this server: it installs through its own setup steps.

The project's own setup steps (from https://github.com/aryanduntley/pwa-debug-layer), copied verbatim. Run them in order; they are not an mcpServers config.

1. Add to Claude Code:

```sh
claude mcp add pwa-debug --scope user -- node /absolute/path/to/pwa-debug-layer/packages/host/dist/main.js
```

2. Start the server:

```sh
npx -y @aryanduntley/pwa-debug@latest
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/pwa-debug-layer/readme_