## **Usage statistics**
Google collects usage statistics (such as tool invocation success rates,
latency, and environment information) to improve the reliability and
performance of Chrome DevTools MCP.
Data collection is **enabled by default**. You can opt-out by passing
the `--no-usage-statistics` flag when starting the server:
```json
"args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"]
```
Google handles this data in accordance with the [Google Privacy
Policy](https://policies.google.com/privacy).
Google's collection of usage statistics for Chrome DevTools MCP is
independent from the Chrome browser's usage statistics. Opting out of
Chrome metrics does not automatically opt you out of this tool, and
vice-versa.
The code determining statistics that are collected is in here
https://github.com/ChromeDevTools/chrome-devtools-mcp/tree/main/src/telemetry.
This PR completes the telemetry system by implementing the transport
layer for `ClearcutSender`. It enables actual HTTP communication with
the Clearcut backend, handling event batching, rate limiting, and
reliable delivery, including robust shutdown handling.
**Key Changes:**
* **HTTP Transport**: Implemented `fetch`-based transport sending `POST`
requests to the Clearcut HTTP server.
* **Event Batching**: Events are now buffered and flushed periodically
(default: 15 minutes) or on shutdown.
* **Reliability & Rate Limiting**:
* **Server-Side Backoff**: Respects `next_request_wait_millis` from
server responses to handle rate limiting dynamically.
* **Transient Error Retries**: Failed requests (5xx, 429) result in
events being requeued for the next flush.
* **Request Timeouts**: Enforced 30s timeout on requests to prevent
hanging processes.
* **Session Rotation**: Automatically rotates session IDs every 24
hours.
* **Safety & Stability**:
* **Buffer Overflow Protection**: Caps the buffer at 1000 events to
prevent memory leaks, dropping oldest events if necessary.
* **Optimistic Removal**: Prevents race conditions and duplicate events
during shutdown by optimistically removing events from the buffer before
sending.
* **Testing Improvements**:
* **E2E Robustness**: Updated E2E tests to use a mock web server instead
of relying on the logger to log specific lines.
**Implementation Roadmap:**
These changes finalize the planned telemetry architecture:
1. **CLI & Opt-out Mechanism
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/757))**
2. **Logger Scaffolding & Integration
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/758))**
3. **Persistence Layer
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/766))**
4. **Watchdog Process Architecture
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/769))**
5. **Transport, Batching & Retries (This PR):**
* Finalized `ClearcutSender` with HTTP transport, batching, and
server-directed backoff strategies.
---------
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
## Summary
- Add `background` boolean parameter to the `new_page` tool
- When set to `true`, the new page opens in the background without
bringing it to the front
- Uses Puppeteer's existing `background` option for `browser.newPage()`
Fixes#826
---------
Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
previously, Chrome DevTools MCP was strictly requiring the client to use
the latest snapshot. This change updates the behavior to be more
lenient. Previously issued uids will be recognized if the underlying
backend Id (loaderId + backendNodeId) still exists.
Related https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/726
This is the stack trace of the console message itself. If the argument
is an Error object or an "Error.stack" like string we don't do anything
special (yet).
The stack trace is source mapped if source maps are available.
The function matches the target ID of the console message to the
`SDK.Target` of DevTools. The only oddity is that DevTools works in a
lazy manor: It creates stack traces upfront and as source maps come in,
stack traces get updated. This does not work for the MCP server.
Instead, we wait for script parsed events and source maps to attach
before creating the stack trace. Since this could take potentially a
while, we guard it with a time out.
This PR implements the watchdog process architecture for the telemetry
system. It moves the `ClearcutSender` execution to a dedicated child
process, ensuring that events—especially shutdown events—are reliably
transmitted even if the main server process terminates abruptly.
Added an e2e test that runs the server, checks the log file and confirms
the telemetry logs exist and that the watchdog process is correctly
killed after sending the shutdown event once the main process is killed.
**Implementation Roadmap:**
This is the fourth in a series of PRs designed to implement the
telemetry system:
1. **CLI & Opt-out Mechanism
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/757)):**
* Added `--usage-statistics` flag and transparency logging.
2. **Logger Scaffolding & Integration
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/758)):**
* **`ClearcutLogger`**: Implemented the main logging entry point.
* **One-way Data Flow**: Integrated `logToolInvocation` and
`logServerStart` hooks into `main.ts` to capture events.
* **`ClearcutSender`**: Introduced a transport abstraction.
* **Type Definitions**: Added TypeScript definitions for the telemetry
Protocol Buffer messages.
3. **Persistence Layer
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/766)):**
* **`FilePersistence`**: Implemented a local file-based state manager to
persist the `lastActive` timestamp.
* **Daily Active Logic**: Integrated persistence into `ClearcutLogger`
to automatically detect and log `daily_active` events (with
`days_since_last_active` calculation) via `logDailyActiveIfNeeded`.
4. **Watchdog Process Architecture (This PR):**
* **`WatchdogClient`**: Added a client-side wrapper to spawn and
communicate with the watchdog process via `stdin`.
* **`watchdog/main.ts`**: Created the entry point for the watchdog
process. It listens for IPC messages and uses `ClearcutSender` to
transmit events.
* **Reliable Shutdown**: The watchdog monitors the parent process and
guarantees a `shutdown` event is sent when the parent exits or crashes
(detecting `stdin` closure).
* **Refactoring**: Moved `ClearcutSender` to the `watchdog` directory
and updated `ClearcutLogger` to delegate event sending to the
`WatchdogClient`.
5. **Transport, Batching & Retries (Next):**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching and exponential backoff retries.
build/src/third_party/devtools.js is only used during bundling, but we
publish it unnecessarily. We should remove it to not cause confusion and
slightly decrease package size.
Co-authored-by: Piotr Paulski <piotrpaulski@chromium.org>
The `devtools-formatter-worker` is a separate entrypoint from the MCP
entrypoint. It is identical to the upstream
`front_end/entrypoints/formatter_worker/formatter_worker-entrypoint.js`
and a required part to make source mapping, formatting and other
AST-based DevTools features work.
The implementation consists of 3 parts:
1) A trivial `devtools-formatter-worker.ts` file that imports the
DevTools entrypoint.
2) A new bundle output, bundling everything that needs to run in the
worker.
3) A call that initializes the `FormatterWorkerPool` with the custom
entrypoint. Otherwise we'd use the unbundled entrypoint from
`chrome-devtools-frontend` not available to us at runtime.
Note that we could improve code splitting in the future as some things
like `core/common` are now bundled twice.
---------
Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
We should make sure there is always an empty line after license notice,
otherwise it gets dropped during build if it happens to be before import
statement.
---------
Co-authored-by: Piotr Paulski <piotrpaulski@chromium.org>
This PR implements the persistence layer for the telemetry system. It
introduces `FilePersistence` for local state management and integrates
it with `ClearcutLogger` to support "Daily Active" metric. I have
decided not to send `first_time_installation` events since we can deduce
them from `daily active` events where the `days_since_last_active` will
be `-1` for that case.
**Implementation Roadmap:**
This is the third in a series of PRs designed to implement the telemetry
system:
1. **CLI & Opt-out Mechanism
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/757)):**
* Added `--usage-statistics` flag and transparency logging.
2. **Logger Scaffolding & Integration
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/758)):**
* **`ClearcutLogger`**: Implemented the main logging entry point.
* **One-way Data Flow**: Integrated `logToolInvocation` and
`logServerStart` hooks into `main.ts` to capture events.
* **`ClearcutSender`**: Introduced a transport abstraction.
* **Type Definitions**: Added TypeScript definitions for the telemetry
Protocol Buffer messages.
3. **Persistence Layer (This PR):**
* **`FilePersistence`**: Implemented a local file-based state manager to
persist the `lastActive` timestamp.
* **Daily Active Logic**: Integrated persistence into `ClearcutLogger`
to automatically detect and log `daily_active` events (with
`days_since_last_active` calculation) via `logDailyActiveIfNeeded`.
4. **Watchdog Process Architecture (Next):**
* Move `ClearcutSender` execution to a dedicated watchdog process to
ensure reliable event transmission even during abrupt server shutdowns.
5. **Transport, Batching & Retries (Next):**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching and exponential backoff retries.
Related Issue -
[465](https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/465)
### Description
This change make sure that the browser window is restored to a `normal`
state before resizing the page. When the window is in `fullscreen` mode
we have to set the state twice to match how Chrome CDP behaves.
Tests cover window resizing for every available window states `type
WindowState = 'normal' | 'minimized' | 'maximized' | 'fullscreen';`
---------
Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
This PR implements the core logging infrastructure for the telemetry
system. It introduces the `ClearcutLogger` class, integrates it into the
server lifecycle events, and establishes the `ClearcutSender`
abstraction.
**Implementation Roadmap:**
This is the second in a series of PRs designed to implement a robust,
privacy-conscious telemetry system:
1. **CLI & Opt-out Mechanism
([Merged](https://github.com/ChromeDevTools/chrome-devtools-mcp/pull/757)):**
* Added `--usage-statistics` flag and transparency logging.
2. **Logger Scaffolding & Integration (This PR):**
* **`ClearcutLogger`**: Implemented the main logging entry point.
* **One-way Data Flow**: Integrated `logToolInvocation` and
`logServerStart` hooks into `main.ts` to capture events.
* **`ClearcutSender`**: Introduced a transport abstraction (currently a
dummy implementation) that will later handle HTTP requests, batching,
and retries.
* **Type Definitions**: Added TypeScript definitions for the telemetry
Protocol Buffer messages.
3. **Persistence Layer (Next):**
* Implement local state management to reliably track "First Time
Installation" and "Daily Active" metrics.
4. **Watchdog Process Architecture (Next):**
* Move `ClearcutSender` execution to a dedicated watchdog process to
ensure reliable event transmission even during abrupt server shutdowns.
5. **Transport, Batching & Retries (Next):**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching and exponential backoff retries.
This PR initiates the implementation of clearcut telemetry. It
introduces the CLI configuration required to opt-out of usage
statistics, along with the necessary transparency disclaimers for the
user. It's hidden by default during development & while we get the
launch approvals.
**Implementation Roadmap:**
This is the first in a series of PRs designed to implement the telemetry
system:
1. **CLI & Opt-out Mechanism (This PR):**
* Adds the `--usage-statistics` flag (hidden, default `false` for now).
* Adds transparency logging to specify data collection when enabled.
2. **Logger Scaffolding & Integration:**
* Implement `ClearcutLogger` and integrate it into `main.ts`.
* Add hooks for `logServerStart` and `logToolInvocation`.
* Introduce `ClearcutSender` as an abstraction layer for transport
logic.
3. **Persistence Layer:**
* Implement local state management to reliably track "First Time
Installation" and "Daily Active" metrics.
* Implement sending the daily active and first time installation event
based on this local state.
4. **Watchdog Process Architecture:**
* Move `ClearcutSender` execution to a dedicated watchdog process to
ensure reliable event transmission even during abrupt server shutdowns.
5. **Transport, Batching & Retries:**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching, respecting `next_request_wait_millis` and retries.
The idea is to turn formatters into instances and support both text and
JSON formatting. The structured content is output if the experimental
structured content flag is passed. For now, only the snapshots are
returned in a structured way.
Refs https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/689
Related Issue -
https://github.com/ChromeDevTools/chrome-devtools-mcp/issues/430
### Description
When Chrome is launched via Puppeteer, it automatically adds a set of
default flags like `--enable-automation --disable-extensions
--disable-component-extensions-with-background-pages.`
Currently, there is no way to opt out of these defaults, which makes
certain use cases difficult or impossible to support. this PR adds a way
to selectively ignore specific default Chrome launch flags applied by
Puppeteer using its
[ignoreDefaultArgs](https://pptr.dev/api/puppeteer.launchoptions#ignoredefaultargs)
property.
```json
{
"name": "chrome-devtools-mcp",
"version": "latest",
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": [
"chrome-devtools-mcp@latest",
"--ignore-default-chrome-arg='--enable-automation'",
"--ignore-default-chrome-arg='--disable-extensions'"
]
}
}
}
```
**Feedback appreciated** @OrKoN
Alex Rudenko