chrome-devtools-mcp 0.2.0 → 0.2.2

package/build/src/McpContext.js

@@ -3,6 +3,23 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { listPages } from './tools/pages.js';
+import { WaitForHelper } from './WaitForHelper.js';
+const DEFAULT_TIMEOUT = 5_000;
+const NAVIGATION_TIMEOUT = 10_000;
+function getNetworkMultiplierFromString(condition) {
+    const puppeteerCondition = condition;
+    switch (puppeteerCondition) {
+        case 'Fast 4G':
+            return 1;
+        case 'Slow 4G':
+            return 2.5;
+        case 'Fast 3G':
+            return 5;
+        case 'Slow 3G':
+            return 10;
+    }
+    return 1;
+}
 export class McpContext {
     browser;
     logger;
@@ -14,8 +31,8 @@ export class McpContext {
     #networkCollector;
     #consoleCollector;
     #isRunningTrace = false;
-    #networkConditions = null;
-    #cpuThrottlingRate = 1;
+    #networkConditionsMap = new WeakMap();
+    #cpuThrottlingRateMap = new WeakMap();
     #dialog;
     #nextSnapshotId = 1;
     #traceResults = [];
@@ -28,10 +45,10 @@ export class McpContext {
             });
         });
         this.#consoleCollector = new PageCollector(this.browser, (page, collect) => {
-            page.on('console', (event) => {
+            page.on('console', event => {
                 collect(event);
             });
-            page.on('pageerror', (event) => {
+            page.on('pageerror', event => {
                 collect(event);
             });
         });
@@ -76,16 +93,27 @@ export class McpContext {
         throw new Error('Request not found for selected page');
     }
     setNetworkConditions(conditions) {
-        this.#networkConditions = conditions;
+        const page = this.getSelectedPage();
+        if (conditions === null) {
+            this.#networkConditionsMap.delete(page);
+        }
+        else {
+            this.#networkConditionsMap.set(page, conditions);
+        }
+        this.#updateSelectedPageTimeouts();
     }
     getNetworkConditions() {
-        return this.#networkConditions;
+        const page = this.getSelectedPage();
+        return this.#networkConditionsMap.get(page) ?? null;
     }
     setCpuThrottlingRate(rate) {
-        this.#cpuThrottlingRate = rate;
+        const page = this.getSelectedPage();
+        this.#cpuThrottlingRateMap.set(page, rate);
+        this.#updateSelectedPageTimeouts();
     }
     getCpuThrottlingRate() {
-        return this.#cpuThrottlingRate;
+        const page = this.getSelectedPage();
+        return this.#cpuThrottlingRateMap.get(page) ?? 1;
     }
     setIsRunningPerformanceTrace(x) {
         this.#isRunningTrace = x;
@@ -129,11 +157,23 @@ export class McpContext {
         this.#selectedPageIdx = idx;
         const newPage = this.getSelectedPage();
         newPage.on('dialog', this.#dialogHandler);
+        this.#updateSelectedPageTimeouts();
+    }
+    #updateSelectedPageTimeouts() {
+        const page = this.getSelectedPage();
         // For waiters 5sec timeout should be sufficient.
-        newPage.setDefaultTimeout(5_000);
+        // Increased in case we throttle the CPU
+        const cpuMultiplier = this.getCpuThrottlingRate();
+        page.setDefaultTimeout(DEFAULT_TIMEOUT * cpuMultiplier);
         // 10sec should be enough for the load event to be emitted during
         // navigations.
-        newPage.setDefaultNavigationTimeout(10_000);
+        // Increased in case we throttle the network requests
+        const networkMultiplier = getNetworkMultiplierFromString(this.getNetworkConditions());
+        page.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT * networkMultiplier);
+    }
+    getNavigationTimeout() {
+        const page = this.getSelectedPage();
+        return page.getDefaultNavigationTimeout();
     }
     async getElementByUid(uid) {
         if (!this.#textSnapshot?.idToNode.size) {
@@ -216,4 +256,14 @@ export class McpContext {
     recordedTraces() {
         return this.#traceResults;
     }
+    getWaitForHelper(page, cpuMultiplier, networkMultiplier) {
+        return new WaitForHelper(page, cpuMultiplier, networkMultiplier);
+    }
+    waitForEventsAfterAction(action) {
+        const page = this.getSelectedPage();
+        const cpuMultiplier = this.getCpuThrottlingRate();
+        const networkMultiplier = getNetworkMultiplierFromString(this.getNetworkConditions());
+        const waitForHelper = this.getWaitForHelper(page, cpuMultiplier, networkMultiplier);
+        return waitForHelper.waitForEventsAfterAction(action);
+    }
 }

package/build/src/McpResponse.js

@@ -8,7 +8,7 @@ export class McpResponse {
     #attachedNetworkRequestUrl;
     #includeConsoleData = false;
     #textResponseLines = [];
-    #formatedConsoleData;
+    #formattedConsoleData;
     #images = [];
     setIncludePages(value) {
         this.#includePages = value;
@@ -64,7 +64,7 @@ export class McpResponse {
             const consoleMessages = context.getConsoleData();
             if (consoleMessages) {
                 formattedConsoleMessages = await Promise.all(consoleMessages.map(message => formatConsoleEvent(message)));
-                this.#formatedConsoleData = formattedConsoleMessages;
+                this.#formattedConsoleData = formattedConsoleMessages;
             }
         }
         return this.format(toolName, context);
@@ -78,6 +78,7 @@ export class McpResponse {
         if (networkConditions) {
             response.push(`## Network emulation`);
             response.push(`Emulating: ${networkConditions}`);
+            response.push(`Navigation timeout set to ${context.getNavigationTimeout()} ms`);
         }
         const cpuThrottlingRate = context.getCpuThrottlingRate();
         if (cpuThrottlingRate > 1) {
@@ -120,9 +121,9 @@ Call browser_handle_dialog to handle it before continuing.`);
                 response.push('No requests found.');
             }
         }
-        if (this.#includeConsoleData && this.#formatedConsoleData) {
+        if (this.#includeConsoleData && this.#formattedConsoleData) {
             response.push('## Console messages');
-            response.push(...this.#formatedConsoleData);
+            response.push(...this.#formattedConsoleData);
         }
         const text = {
             type: 'text',

package/build/src/WaitForHelper.js

@@ -0,0 +1,127 @@
+import { logger } from './logger.js';
+export class WaitForHelper {
+    #abortController = new AbortController();
+    #page;
+    #stableDomTimeout;
+    #stableDomFor;
+    #expectNavigationIn;
+    #navigationTimeout;
+    constructor(page, cpuTimeoutMultiplier, networkTimeoutMultiplier) {
+        this.#stableDomTimeout = 3000 * cpuTimeoutMultiplier;
+        this.#stableDomFor = 100 * cpuTimeoutMultiplier;
+        this.#expectNavigationIn = 100 * cpuTimeoutMultiplier;
+        this.#navigationTimeout = 3000 * networkTimeoutMultiplier;
+        this.#page = page;
+    }
+    /**
+     * A wrapper that executes a action and waits for
+     * a potential navigation, after which it waits
+     * for the DOM to be stable before returning.
+     */
+    async waitForStableDom() {
+        const stableDomObserver = await this.#page.evaluateHandle(timeout => {
+            let timeoutId;
+            function callback() {
+                clearTimeout(timeoutId);
+                timeoutId = setTimeout(() => {
+                    domObserver.resolver.resolve();
+                    domObserver.observer.disconnect();
+                }, timeout);
+            }
+            const domObserver = {
+                resolver: Promise.withResolvers(),
+                observer: new MutationObserver(callback),
+            };
+            // It's possible that the DOM is not gonna change so we
+            // need to start the timeout initially.
+            callback();
+            domObserver.observer.observe(document.body, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+            });
+            return domObserver;
+        }, this.#stableDomFor);
+        this.#abortController.signal.addEventListener('abort', async () => {
+            try {
+                await stableDomObserver.evaluate(observer => {
+                    observer.observer.disconnect();
+                    observer.resolver.resolve();
+                });
+                await stableDomObserver.dispose();
+            }
+            catch {
+                // Ignored cleanup errors
+            }
+        });
+        return Promise.race([
+            stableDomObserver.evaluate(async (observer) => {
+                return await observer.resolver.promise;
+            }),
+            this.timeout(this.#stableDomTimeout).then(() => {
+                throw new Error('Timeout');
+            }),
+        ]);
+    }
+    async waitForNavigationStarted() {
+        // Currently Puppeteer does not have API
+        // For when a navigation is about to start
+        const navigationStartedPromise = new Promise(resolve => {
+            const listener = (event) => {
+                if ([
+                    'historySameDocument',
+                    'historyDifferentDocument',
+                    'sameDocument',
+                ].includes(event.navigationType)) {
+                    resolve(false);
+                    return;
+                }
+                resolve(true);
+            };
+            this.#page._client().on('Page.frameStartedNavigating', listener);
+            this.#abortController.signal.addEventListener('abort', () => {
+                resolve(false);
+                this.#page._client().off('Page.frameStartedNavigating', listener);
+            });
+        });
+        return await Promise.race([
+            navigationStartedPromise,
+            this.timeout(this.#expectNavigationIn).then(() => false),
+        ]);
+    }
+    timeout(time) {
+        return new Promise(res => {
+            const id = setTimeout(res, time);
+            this.#abortController.signal.addEventListener('abort', () => {
+                res();
+                clearTimeout(id);
+            });
+        });
+    }
+    async waitForEventsAfterAction(action) {
+        const navigationFinished = this.waitForNavigationStarted()
+            .then(navigationStated => {
+            if (navigationStated) {
+                return this.#page.waitForNavigation({
+                    timeout: this.#navigationTimeout,
+                    signal: this.#abortController.signal,
+                });
+            }
+            return;
+        })
+            .catch(error => logger(error));
+        await action();
+        try {
+            await navigationFinished;
+            // Wait for stable dom after navigation so we execute in
+            // the correct context
+            await this.waitForStableDom();
+        }
+        catch (error) {
+            logger(error);
+        }
+        finally {
+            this.#abortController.abort();
+        }
+    }
+}

package/build/src/browser.js

@@ -53,11 +53,7 @@ export async function launch(options) {
             recursive: true,
         });
     }
-    const args = [
-        '--remote-debugging-pipe',
-        '--no-first-run',
-        '--hide-crash-restore-bubble',
-    ];
+    const args = ['--hide-crash-restore-bubble'];
     if (customDevTools) {
         args.push(`--custom-devtools-frontend=file://${customDevTools}`);
     }
@@ -69,7 +65,7 @@ export async function launch(options) {
                 : 'chrome';
     }
     try {
-        return await puppeteer.launch({
+        const browser = await puppeteer.launch({
             ...connectOptions,
             channel: puppeterChannel,
             executablePath,
@@ -79,12 +75,19 @@ export async function launch(options) {
             headless,
             args,
         });
+        if (options.logFile) {
+            // FIXME: we are probably subscribing too late to catch startup logs. We
+            // should expose the process earlier or expose the getRecentLogs() getter.
+            browser.process()?.stderr?.pipe(options.logFile);
+            browser.process()?.stdout?.pipe(options.logFile);
+        }
+        return browser;
     }
     catch (error) {
-        // TODO: check browser logs for `Failed to create a ProcessSingleton for
-        // your profile directory` instead.
         if (userDataDir &&
-            error.message.includes('The browser is already running')) {
+            (error.message.includes('The browser is already running') ||
+                error.message.includes('Target closed') ||
+                error.message.includes('Connection closed'))) {
             throw new Error(`The browser is already running for ${userDataDir}. Use --isolated to run multiple browser instances.`, {
                 cause: error,
             });

package/build/src/index.js

@@ -61,10 +61,9 @@ export const cliOptions = {
     },
     channel: {
         type: 'string',
-        description: 'Specify a different Chrome channel that should be used.',
+        description: 'Specify a different Chrome channel that should be used. The default is the stable channel version.',
         choices: ['stable', 'canary', 'beta', 'dev'],
         conflicts: ['browserUrl', 'executablePath'],
-        default: 'stable',
     },
     logFile: {
         type: 'string',
@@ -72,6 +71,22 @@ export const cliOptions = {
         hidden: true,
     },
 };
+function readPackageJson() {
+    const currentDir = import.meta.dirname;
+    const packageJsonPath = path.join(currentDir, '..', '..', 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return {};
+    }
+    try {
+        const json = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        assert.strict(json['name'], 'chrome-devtools-mcp');
+        return json;
+    }
+    catch {
+        return {};
+    }
+}
+const version = readPackageJson().version ?? 'unknown';
 const yargsInstance = yargs(hideBin(process.argv))
     .scriptName('npx chrome-devtools-mcp@latest')
     .options(cliOptions)
@@ -98,26 +113,9 @@ const yargsInstance = yargs(hideBin(process.argv))
 export const args = yargsInstance
     .wrap(Math.min(120, yargsInstance.terminalWidth()))
     .help()
+    .version(version)
     .parseSync();
-if (args.logFile) {
-    saveLogsToFile(args.logFile);
-}
-function readPackageJson() {
-    const currentDir = import.meta.dirname;
-    const packageJsonPath = path.join(currentDir, '..', '..', 'package.json');
-    if (!fs.existsSync(packageJsonPath)) {
-        return {};
-    }
-    try {
-        const json = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-        assert.strict(json['name'], 'chrome-devtools-mcp');
-        return json;
-    }
-    catch {
-        return {};
-    }
-}
-const version = readPackageJson().version ?? 'unknown';
+const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
 logger(`Starting Chrome DevTools MCP Server v${version}`);
 const server = new McpServer({
     name: 'chrome_devtools',
@@ -136,6 +134,7 @@ async function getContext() {
         customDevTools: args.customDevtools,
         channel: args.channel,
         isolated: args.isolated,
+        logFile,
     });
     if (context?.browser !== browser) {
         context = await McpContext.from(browser, logger);

package/build/src/logger.js

@@ -22,5 +22,6 @@ export function saveLogsToFile(fileName) {
         logFile.end();
         process.exit(1);
     });
+    return logFile;
 }
 export const logger = debug(mcpDebugNamespace);

package/build/src/tools/input.js

@@ -6,7 +6,6 @@
 import z from 'zod';
 import { defineTool } from './ToolDefinition.js';
 import { ToolCategories } from './categories.js';
-import { waitForEventsAfterAction } from '../waitForHelpers.js';
 export const click = defineTool({
     name: 'click',
     description: `Clicks on the provided element`,
@@ -27,7 +26,7 @@ export const click = defineTool({
         const uid = request.params.uid;
         const handle = await context.getElementByUid(uid);
         try {
-            await waitForEventsAfterAction(handle.frame.page(), async () => {
+            await context.waitForEventsAfterAction(async () => {
                 await handle.asLocator().click({
                     count: request.params.dblClick ? 2 : 1,
                 });
@@ -58,7 +57,7 @@ export const hover = defineTool({
         const uid = request.params.uid;
         const handle = await context.getElementByUid(uid);
         try {
-            await waitForEventsAfterAction(handle.frame.page(), async () => {
+            await context.waitForEventsAfterAction(async () => {
                 await handle.asLocator().hover();
             });
             response.appendResponseLine(`Successfully hovered over the element`);
@@ -85,7 +84,7 @@ export const fill = defineTool({
     handler: async (request, response, context) => {
         const handle = await context.getElementByUid(request.params.uid);
         try {
-            await waitForEventsAfterAction(handle.frame.page(), async () => {
+            await context.waitForEventsAfterAction(async () => {
                 await handle.asLocator().fill(request.params.value);
             });
             response.appendResponseLine(`Successfully filled out the element`);
@@ -111,7 +110,7 @@ export const drag = defineTool({
         const fromHandle = await context.getElementByUid(request.params.from_uid);
         const toHandle = await context.getElementByUid(request.params.to_uid);
         try {
-            await waitForEventsAfterAction(fromHandle.frame.page(), async () => {
+            await context.waitForEventsAfterAction(async () => {
                 await fromHandle.drag(toHandle);
                 await new Promise(resolve => setTimeout(resolve, 50));
                 await toHandle.drop(fromHandle);
@@ -144,7 +143,7 @@ export const fillForm = defineTool({
         for (const element of request.params.elements) {
             const handle = await context.getElementByUid(element.uid);
             try {
-                await waitForEventsAfterAction(handle.frame.page(), async () => {
+                await context.waitForEventsAfterAction(async () => {
                     await handle.asLocator().fill(element.value);
                 });
             }

package/build/src/tools/pages.js

@@ -6,7 +6,6 @@
 import z from 'zod';
 import { defineTool } from './ToolDefinition.js';
 import { ToolCategories } from './categories.js';
-import { waitForEventsAfterAction } from '../waitForHelpers.js';
 export const listPages = defineTool({
     name: 'list_pages',
     description: `Get a list of pages open in the browser.`,
@@ -69,7 +68,7 @@ export const newPage = defineTool({
     },
     handler: async (request, response, context) => {
         const page = await context.newPage();
-        await waitForEventsAfterAction(page, async () => {
+        await context.waitForEventsAfterAction(async () => {
             await page.goto(request.params.url);
         });
         response.setIncludePages(true);
@@ -87,7 +86,7 @@ export const navigatePage = defineTool({
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
-        await waitForEventsAfterAction(page, async () => {
+        await context.waitForEventsAfterAction(async () => {
             await page.goto(request.params.url);
         });
         response.setIncludePages(true);

package/build/src/tools/performance.js

@@ -5,12 +5,12 @@
  */
 import z from 'zod';
 import { defineTool } from './ToolDefinition.js';
-import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, } from '../trace-processing/parse.js';
+import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
 import { logger } from '../logger.js';
 import { ToolCategories } from './categories.js';
 export const startTrace = defineTool({
     name: 'performance_start_trace',
-    description: 'Starts a performance trace recording',
+    description: 'Starts a performance trace recording on the selected page.',
     annotations: {
         category: ToolCategories.PERFORMANCE,
         readOnlyHint: true,
@@ -77,7 +77,7 @@ export const startTrace = defineTool({
 });
 export const stopTrace = defineTool({
     name: 'performance_stop_trace',
-    description: 'Stops the active performance trace recording',
+    description: 'Stops the active performance trace recording on the selected page.',
     annotations: {
         category: ToolCategories.PERFORMANCE,
         readOnlyHint: true,
@@ -93,7 +93,7 @@ export const stopTrace = defineTool({
 });
 export const analyzeInsight = defineTool({
     name: 'performance_analyze_insight',
-    description: 'Provides more detailed information on a specific Performance Insight that was highlighed in the results of a trace recording',
+    description: 'Provides more detailed information on a specific Performance Insight that was highlighed in the results of a trace recording.',
     annotations: {
         category: ToolCategories.PERFORMANCE,
         readOnlyHint: true,
@@ -122,20 +122,22 @@ async function stopTracingAndAppendOutput(page, response, context) {
         const traceEventsBuffer = await page.tracing.stop();
         const result = await parseRawTraceBuffer(traceEventsBuffer);
         response.appendResponseLine('The performance trace has been stopped.');
-        if (result) {
+        if (traceResultIsSuccess(result)) {
             context.storeTraceRecording(result);
-            const insightText = getTraceSummary(result);
-            if (insightText) {
-                response.appendResponseLine('Insights with performance opportunities:');
-                response.appendResponseLine(insightText);
-            }
-            else {
-                response.appendResponseLine('No insights have been found. The performance looks good!');
-            }
+            response.appendResponseLine('Here is a high level summary of the trace and the Insights that were found:');
+            const traceSummaryText = getTraceSummary(result);
+            response.appendResponseLine(traceSummaryText);
+        }
+        else {
+            response.appendResponseLine('There was an unexpected error parsing the trace:');
+            response.appendResponseLine(result.error);
         }
     }
     catch (e) {
-        logger(`Error stopping performance trace: ${e instanceof Error ? e.message : JSON.stringify(e)}`);
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Error stopping performance trace: ${errorText}`);
+        response.appendResponseLine('An error occured generating the response for this trace:');
+        response.appendResponseLine(errorText);
     }
     finally {
         context.setIsRunningPerformanceTrace(false);

package/build/src/tools/script.js

@@ -6,7 +6,6 @@
 import z from 'zod';
 import { defineTool } from './ToolDefinition.js';
 import { ToolCategories } from './categories.js';
-import { waitForEventsAfterAction } from '../waitForHelpers.js';
 export const evaluateScript = defineTool({
     name: 'evaluate_script',
     description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON
@@ -43,7 +42,7 @@ Example with arguments: \`(el) => {
             for (const el of request.params.args ?? []) {
                 args.push(await context.getElementByUid(el.uid));
             }
-            await waitForEventsAfterAction(page, async () => {
+            await context.waitForEventsAfterAction(async () => {
                 const result = await page.evaluate(async (fn, ...args) => {
                     // @ts-expect-error no types.
                     return JSON.stringify(await fn(...args));

package/build/src/trace-processing/parse.js

@@ -9,14 +9,21 @@ import * as TraceEngine from '../../node_modules/chrome-devtools-frontend/front_
 import { logger } from '../logger.js';
 import { AgentFocus } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AIContext.js';
 const engine = TraceEngine.TraceModel.Model.createWithAllHandlers();
+export function traceResultIsSuccess(x) {
+    return 'parsedTrace' in x;
+}
 export async function parseRawTraceBuffer(buffer) {
     engine.resetProcessor();
     if (!buffer) {
-        return null;
+        return {
+            error: 'No buffer was provided.',
+        };
     }
     const asString = new TextDecoder().decode(buffer);
     if (!asString) {
-        return null;
+        return {
+            error: 'Decoding the trace buffer returned an empty string.',
+        };
     }
     try {
         const data = JSON.parse(asString);
@@ -24,25 +31,22 @@ export async function parseRawTraceBuffer(buffer) {
         await engine.parse(events);
         const parsedTrace = engine.parsedTrace();
         if (!parsedTrace) {
-            return null;
-        }
-        const insights = parsedTrace?.insights;
-        if (!insights) {
-            return null;
+            return {
+                error: 'No parsed trace was returned from the trace engine.',
+            };
         }
+        const insights = parsedTrace?.insights ?? null;
         return {
             parsedTrace,
             insights,
         };
     }
     catch (e) {
-        if (e instanceof Error) {
-            logger(`Error parsing trace: ${e.message}`);
-        }
-        else {
-            logger(`Error parsing trace: ${JSON.stringify(e)}`);
-        }
-        return null;
+        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
+        logger(`Unexpeced error parsing trace: ${errorText}`);
+        return {
+            error: errorText,
+        };
     }
 }
 export function getTraceSummary(result) {
@@ -53,6 +57,11 @@ export function getTraceSummary(result) {
     return output;
 }
 export function getInsightOutput(result, insightName) {
+    if (!result.insights) {
+        return {
+            error: 'No Performance insights are available for this trace.',
+        };
+    }
     // Currently, we do not support inspecting traces with multiple navigations. We either:
     // 1. Find Insights from the first navigation (common case: user records a trace with a page reload to test load performance)
     // 2. Fall back to finding Insights not associated with a navigation (common case: user tests an interaction without a page load).