Merge branch 'main' into browser-url

Author: sebastianbenz

README.md

@@ -343,9 +343,12 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** string
 
 - **`--isolated`**
-  If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed.
+  If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.
   - **Type:** boolean
-  - **Default:** `false`
+
+- **`--userDataDir`**
+  Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE
+  - **Type:** string
 
 - **`--channel`**
   Specify a different Chrome channel that should be used. The default is the stable channel version.

docs/tool-reference.md

@@ -196,6 +196,7 @@
 **Parameters:**
 
 - **cpuThrottlingRate** (number) _(optional)_: Represents the CPU slowdown factor. Set the rate to 1 to disable throttling. If omitted, throttling remains unchanged.
+- **geolocation** (unknown) _(optional)_: Geolocation to [`emulate`](#emulate). Set to null to clear the geolocation override.
 - **networkConditions** (enum: "No emulation", "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G") _(optional)_: Throttle network. Set to "No emulation" to disable. If omitted, conditions remain unchanged.
 
 ---

package-lock.json

@@ -52,7 +52,7 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1549484",
+    "chrome-devtools-frontend": "1.0.1550444",
     "core-js": "3.47.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",

package.json

@@ -88,6 +88,13 @@ export const LOCAL_FETCH_PATTERN = './locales/@[email protected]';`;
   const runtimeContent = `
 export function getChromeVersion() { return ''; };
 export const hostConfig = {};
+export const Runtime = {
+  isDescriptorEnabled: () => true,
+  queryParam: () => null,
+}
+export const experiments = {
+  isEnabled: () => false,
+}
   `;
   writeFile(runtimeFile, runtimeContent);
 

scripts/post-build.ts

@@ -8,14 +8,26 @@ import {
   type Issue,
   type AggregatedIssue,
   type IssuesManagerEventTypes,
+  type Target,
+  DebuggerModel,
+  Foundation,
+  TargetManager,
   MarkdownIssueDescription,
   Marked,
+  ProtocolClient,
   Common,
   I18n,
 } from '../node_modules/chrome-devtools-frontend/mcp/mcp.js';
 
+import {PuppeteerDevToolsConnection} from './DevToolsConnectionAdapter.js';
 import {ISSUE_UTILS} from './issue-descriptions.js';
 import {logger} from './logger.js';
+import {Mutex} from './Mutex.js';
+import type {
+  Browser,
+  Page,
+  Target as PuppeteerTarget,
+} from './third_party/index.js';
 
 export function extractUrlLikeFromDevToolsTitle(
   title: string,
@@ -125,6 +137,9 @@ export function mapIssueToMessageObject(issue: AggregatedIssue) {
   };
 }
 
+// DevTools CDP errors can get noisy.
+ProtocolClient.InspectorBackend.test.suppressRequestErrors = true;
+
 I18n.DevToolsLocale.DevToolsLocale.instance({
   create: true,
   data: {
@@ -134,3 +149,129 @@ I18n.DevToolsLocale.DevToolsLocale.instance({
   },
 });
 I18n.i18n.registerLocaleDataForTest('en-US', {});
+
+export interface TargetUniverse {
+  /** The DevTools target corresponding to the puppeteer Page */
+  target: Target;
+  universe: Foundation.Universe.Universe;
+}
+export type TargetUniverseFactoryFn = (page: Page) => Promise<TargetUniverse>;
+
+export class UniverseManager {
+  readonly #browser: Browser;
+  readonly #createUniverseFor: TargetUniverseFactoryFn;
+  readonly #universes = new WeakMap<Page, TargetUniverse>();
+
+  /** Guard access to #universes so we don't create unnecessary universes */
+  readonly #mutex = new Mutex();
+
+  constructor(
+    browser: Browser,
+    factory: TargetUniverseFactoryFn = DEFAULT_FACTORY,
+  ) {
+    this.#browser = browser;
+    this.#createUniverseFor = factory;
+  }
+
+  async init(pages: Page[]) {
+    try {
+      await this.#mutex.acquire();
+      const promises = [];
+      for (const page of pages) {
+        promises.push(
+          this.#createUniverseFor(page).then(targetUniverse =>
+            this.#universes.set(page, targetUniverse),
+          ),
+        );
+      }
+
+      this.#browser.on('targetcreated', this.#onTargetCreated);
+      this.#browser.on('targetdestroyed', this.#onTargetDestroyed);
+
+      await Promise.all(promises);
+    } finally {
+      this.#mutex.release();
+    }
+  }
+
+  get(page: Page): TargetUniverse | null {
+    return this.#universes.get(page) ?? null;
+  }
+
+  dispose() {
+    this.#browser.off('targetcreated', this.#onTargetCreated);
+    this.#browser.off('targetdestroyed', this.#onTargetDestroyed);
+  }
+
+  #onTargetCreated = async (target: PuppeteerTarget) => {
+    const page = await target.page();
+    try {
+      await this.#mutex.acquire();
+      if (!page || this.#universes.has(page)) {
+        return;
+      }
+
+      this.#universes.set(page, await this.#createUniverseFor(page));
+    } finally {
+      this.#mutex.release();
+    }
+  };
+
+  #onTargetDestroyed = async (target: PuppeteerTarget) => {
+    const page = await target.page();
+    try {
+      await this.#mutex.acquire();
+      if (!page || !this.#universes.has(page)) {
+        return;
+      }
+      this.#universes.delete(page);
+    } finally {
+      this.#mutex.release();
+    }
+  };
+}
+
+const DEFAULT_FACTORY: TargetUniverseFactoryFn = async (page: Page) => {
+  const settingStorage = new Common.Settings.SettingsStorage({});
+  const universe = new Foundation.Universe.Universe({
+    settingsCreationOptions: {
+      syncedStorage: settingStorage,
+      globalStorage: settingStorage,
+      localStorage: settingStorage,
+      settingRegistrations: Common.SettingRegistration.getRegisteredSettings(),
+    },
+    overrideAutoStartModels: new Set([DebuggerModel]),
+  });
+
+  const session = await page.createCDPSession();
+  const connection = new PuppeteerDevToolsConnection(session);
+
+  const targetManager = universe.context.get(TargetManager);
+  targetManager.observeModels(DebuggerModel, SKIP_ALL_PAUSES);
+
+  const target = targetManager.createTarget(
+    'main',
+    '',
+    'frame' as any, // eslint-disable-line @typescript-eslint/no-explicit-any
+    /* parentTarget */ null,
+    session.id(),
+    undefined,
+    connection,
+  );
+  return {target, universe};
+};
+
+// We don't want to pause any DevTools universe session ever on the MCP side.
+//
+// Note that calling `setSkipAllPauses` only affects the session on which it was
+// sent. This means DevTools can still pause, step and do whatever. We just won't
+// see the `Debugger.paused`/`Debugger.resumed` events on the MCP side.
+const SKIP_ALL_PAUSES = {
+  modelAdded(model: DebuggerModel): void {
+    void model.agent.invoke_setSkipAllPauses({skip: true});
+  },
+
+  modelRemoved(): void {
+    // Do nothing.
+  },
+};

src/DevtoolsUtils.ts

@@ -38,6 +38,11 @@ export interface TextSnapshotNode extends SerializedAXNode {
   children: TextSnapshotNode[];
 }
 
+export interface GeolocationOptions {
+  latitude: number;
+  longitude: number;
+}
+
 export interface TextSnapshot {
   root: TextSnapshotNode;
   idToNode: Map<string, TextSnapshotNode>;
@@ -104,6 +109,7 @@ export class McpContext implements Context {
   #isRunningTrace = false;
   #networkConditionsMap = new WeakMap<Page, string>();
   #cpuThrottlingRateMap = new WeakMap<Page, number>();
+  #geolocationMap = new WeakMap<Page, GeolocationOptions>();
   #dialog?: Dialog;
 
   #nextSnapshotId = 1;
@@ -123,41 +129,33 @@ export class McpContext implements Context {
     this.#locatorClass = locatorClass;
     this.#options = options;
 
-    this.#networkCollector = new NetworkCollector(
-      this.browser,
-      undefined,
-      this.#options.experimentalIncludeAllPages,
-    );
+    this.#networkCollector = new NetworkCollector(this.browser);
 
-    this.#consoleCollector = new ConsoleCollector(
-      this.browser,
-      collect => {
-        return {
-          console: event => {
-            collect(event);
-          },
-          pageerror: event => {
-            if (event instanceof Error) {
-              collect(event);
-            } else {
-              const error = new Error(`${event}`);
-              error.stack = undefined;
-              collect(error);
-            }
-          },
-          issue: event => {
+    this.#consoleCollector = new ConsoleCollector(this.browser, collect => {
+      return {
+        console: event => {
+          collect(event);
+        },
+        pageerror: event => {
+          if (event instanceof Error) {
             collect(event);
-          },
-        } as ListenerMap;
-      },
-      this.#options.experimentalIncludeAllPages,
-    );
+          } else {
+            const error = new Error(`${event}`);
+            error.stack = undefined;
+            collect(error);
+          }
+        },
+        issue: event => {
+          collect(event);
+        },
+      } as ListenerMap;
+    });
   }
 
   async #init() {
-    await this.createPagesSnapshot();
-    await this.#networkCollector.init();
-    await this.#consoleCollector.init();
+    const pages = await this.createPagesSnapshot();
+    await this.#networkCollector.init(pages);
+    await this.#consoleCollector.init(pages);
   }
 
   dispose() {
@@ -285,6 +283,20 @@ export class McpContext implements Context {
     return this.#cpuThrottlingRateMap.get(page) ?? 1;
   }
 
+  setGeolocation(geolocation: GeolocationOptions | null): void {
+    const page = this.getSelectedPage();
+    if (geolocation === null) {
+      this.#geolocationMap.delete(page);
+    } else {
+      this.#geolocationMap.set(page, geolocation);
+    }
+  }
+
+  getGeolocation(): GeolocationOptions | null {
+    const page = this.getSelectedPage();
+    return this.#geolocationMap.get(page) ?? null;
+  }
+
   setIsRunningPerformanceTrace(x: boolean): void {
     this.#isRunningTrace = x;
   }
@@ -625,25 +637,19 @@ export class McpContext implements Context {
     return this.#networkCollector.getIdForResource(request);
   }
 
-  waitForTextOnPage({
-    text,
-    timeout,
-  }: {
-    text: string;
-    timeout?: number | undefined;
-  }): Promise<Element> {
+  waitForTextOnPage(text: string, timeout?: number): Promise<Element> {
     const page = this.getSelectedPage();
     const frames = page.frames();
 
-    const locator = this.#locatorClass.race(
+    let locator = this.#locatorClass.race(
       frames.flatMap(frame => [
         frame.locator(`aria/${text}`),
         frame.locator(`text/${text}`),
       ]),
     );
 
     if (timeout) {
-      locator.setTimeout(timeout);
+      locator = locator.setTimeout(timeout);
     }
 
     return locator.wait();
@@ -663,6 +669,6 @@ export class McpContext implements Context {
         },
       } as ListenerMap;
     });
-    await this.#networkCollector.init();
+    await this.#networkCollector.init(await this.browser.pages());
   }
 }