chrome-devtools-mcp 0.1.0 → 0.2.1

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`,
@@ -16,7 +15,7 @@ export const click = defineTool({
     },
     schema: {
         uid: z
-            .number()
+            .string()
             .describe('The uid of an element on the page from the page content snapshot'),
         dblClick: z
             .boolean()
@@ -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,
                 });
@@ -51,14 +50,14 @@ export const hover = defineTool({
     },
     schema: {
         uid: z
-            .number()
+            .string()
             .describe('The uid of an element on the page from the page content snapshot'),
     },
     handler: async (request, response, context) => {
         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`);
@@ -78,14 +77,14 @@ export const fill = defineTool({
     },
     schema: {
         uid: z
-            .number()
+            .string()
             .describe('The uid of an element on the page from the page content snapshot'),
         value: z.string().describe('The value to fill in'),
     },
     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`);
@@ -104,14 +103,14 @@ export const drag = defineTool({
         readOnlyHint: false,
     },
     schema: {
-        from_uid: z.number().describe('The uid of the element to drag'),
-        to_uid: z.number().describe('The uid of the element to drop into'),
+        from_uid: z.string().describe('The uid of the element to drag'),
+        to_uid: z.string().describe('The uid of the element to drop into'),
     },
     handler: async (request, response, context) => {
         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);
@@ -135,7 +134,7 @@ export const fillForm = defineTool({
     schema: {
         elements: z
             .array(z.object({
-            uid: z.number().describe('The uid of the element to fill out'),
+            uid: z.string().describe('The uid of the element to fill out'),
             value: z.string().describe('Value for the element'),
         }))
             .describe('Elements from snapshot to fill out.'),
@@ -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);
                 });
             }
@@ -165,7 +164,7 @@ export const uploadFile = defineTool({
     },
     schema: {
         uid: z
-            .number()
+            .string()
             .describe('The uid of the file input element or an element that will open file chooser on the page from the page content snapshot'),
         filePath: z.string().describe('The local path of the file to upload'),
     },

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 { insightOutput, parseRawTraceBuffer } from '../trace-processing/parse.js';
+import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, } 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,
@@ -91,13 +91,40 @@ export const stopTrace = defineTool({
         await stopTracingAndAppendOutput(page, response, context);
     },
 });
+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.',
+    annotations: {
+        category: ToolCategories.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {
+        insightName: z
+            .string()
+            .describe('The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"'),
+    },
+    handler: async (request, response, context) => {
+        const lastRecording = context.recordedTraces().at(-1);
+        if (!lastRecording) {
+            response.appendResponseLine('No recorded traces found. Record a performance trace so you have Insights to analyze.');
+            return;
+        }
+        const insightOutput = getInsightOutput(lastRecording, request.params.insightName);
+        if ('error' in insightOutput) {
+            response.appendResponseLine(insightOutput.error);
+            return;
+        }
+        response.appendResponseLine(insightOutput.output);
+    },
+});
 async function stopTracingAndAppendOutput(page, response, context) {
     try {
         const traceEventsBuffer = await page.tracing.stop();
         const result = await parseRawTraceBuffer(traceEventsBuffer);
         response.appendResponseLine('The performance trace has been stopped.');
         if (result) {
-            const insightText = insightOutput(result);
+            context.storeTraceRecording(result);
+            const insightText = getTraceSummary(result);
             if (insightText) {
                 response.appendResponseLine('Insights with performance opportunities:');
                 response.appendResponseLine(insightText);

package/build/src/tools/screenshot.js

@@ -19,7 +19,7 @@ export const screenshot = defineTool({
             .default('png')
             .describe('Type of format to save the screenshot as. Default is "png"'),
         uid: z
-            .number()
+            .string()
             .optional()
             .describe('The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.'),
         fullPage: z

package/build/src/tools/script.js

@@ -6,30 +6,55 @@
 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.`,
+    description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON
+so returned values have to JSON-serializable.`,
     annotations: {
         category: ToolCategories.DEBUGGING,
         readOnlyHint: false,
     },
     schema: {
-        function: z
-            .string()
-            .describe('A JavaScript function to run in the currently selected page. Example: `() => {return document.title}` or `async () => {return await fetch("example.com")}`'),
+        function: z.string().describe(`A JavaScript function to run in the currently selected page.
+Example without arguments: \`() => {
+  return document.title
+}\` or \`async () => {
+  return await fetch("example.com")
+}\`.
+Example with arguments: \`(el) => {
+  return el.innerText;
+}\`
+`),
+        args: z
+            .array(z.object({
+            uid: z
+                .string()
+                .describe('The uid of an element on the page from the page content snapshot'),
+        }))
+            .optional()
+            .describe(`An optional list of arguments to pass to the function.`),
     },
     handler: async (request, response, context) => {
         const page = context.getSelectedPage();
-        const script = `(async () => {
-      return JSON.stringify(await (${request.params.function})());
-    })()`;
-        await waitForEventsAfterAction(page, async () => {
-            const result = await page.evaluate(script);
-            response.appendResponseLine('Script ran on page and returned:');
-            response.appendResponseLine('```json');
-            response.appendResponseLine(`${result}`);
-            response.appendResponseLine('```');
-        });
+        const fn = await page.evaluateHandle(`(${request.params.function})`);
+        const args = [fn];
+        try {
+            for (const el of request.params.args ?? []) {
+                args.push(await context.getElementByUid(el.uid));
+            }
+            await context.waitForEventsAfterAction(async () => {
+                const result = await page.evaluate(async (fn, ...args) => {
+                    // @ts-expect-error no types.
+                    return JSON.stringify(await fn(...args));
+                }, ...args);
+                response.appendResponseLine('Script ran on page and returned:');
+                response.appendResponseLine('```json');
+                response.appendResponseLine(`${result}`);
+                response.appendResponseLine('```');
+            });
+        }
+        finally {
+            Promise.allSettled(args.map(arg => arg.dispose())).catch(() => { });
+        }
     },
 });

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

@@ -3,9 +3,11 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
+import { PerformanceTraceFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.js';
 import { PerformanceInsightFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.js';
 import * as TraceEngine from '../../node_modules/chrome-devtools-frontend/front_end/models/trace/trace.js';
 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 async function parseRawTraceBuffer(buffer) {
     engine.resetProcessor();
@@ -43,31 +45,33 @@ export async function parseRawTraceBuffer(buffer) {
         return null;
     }
 }
-// TODO(jactkfranklin): move the formatters from DevTools to use here.
-// This is a very temporary helper to output some text from the tool call to aid development.
-export function insightOutput(result) {
+export function getTraceSummary(result) {
+    const focus = AgentFocus.full(result.parsedTrace);
+    const serializer = new TraceEngine.EventsSerializer.EventsSerializer();
+    const formatter = new PerformanceTraceFormatter(focus, serializer);
+    const output = formatter.formatTraceSummary();
+    return output;
+}
+export function getInsightOutput(result, insightName) {
+    // 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).
     const mainNavigationId = result.parsedTrace.data.Meta.mainFrameNavigations.at(0)?.args.data
         ?.navigationId;
-    if (!mainNavigationId) {
-        return '';
-    }
-    let text = '';
-    const insightsForNav = result.insights.get(mainNavigationId);
+    const insightsForNav = result.insights.get(mainNavigationId ?? TraceEngine.Types.Events.NO_NAVIGATION);
     if (!insightsForNav) {
-        text += 'No Performance insights were found for this trace.';
-        return text;
+        return {
+            error: 'No Performance Insights for this trace.',
+        };
     }
-    const failingInsightKeys = Object.keys(insightsForNav.model).filter(insightKey => {
-        const key = insightKey;
-        const data = insightsForNav.model[key] ?? null;
-        return data?.state === 'fail';
-    });
-    logger(`Found failing Insight keys: ${failingInsightKeys.join(', ')}`);
-    for (const failingKey of failingInsightKeys) {
-        const modelData = insightsForNav.model[failingKey];
-        const formatter = new PerformanceInsightFormatter(result.parsedTrace, modelData);
-        const output = formatter.formatInsight();
-        text += `${output}\n`;
+    const matchingInsight = insightName in insightsForNav.model
+        ? insightsForNav.model[insightName]
+        : null;
+    if (!matchingInsight) {
+        return {
+            error: `No Insight with the name ${insightName} found. Double check the name you provided is accurate and try again.`,
+        };
     }
-    return text;
+    const formatter = new PerformanceInsightFormatter(result.parsedTrace, matchingInsight);
+    return { output: formatter.formatInsight() };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "MCP server for Chrome DevTools",
   "type": "module",
   "bin": {
@@ -8,15 +8,18 @@
   },
   "main": "index.js",
   "scripts": {
-    "build": "tsc && node --experimental-strip-types scripts/post-build.ts",
-    "format": "eslint --cache --fix . ;prettier --write --cache .",
-    "check-format": "eslint --cache .; prettier --check --cache .;",
-    "generate-docs": "npm run build && node --experimental-strip-types scripts/generate-docs.ts",
+    "build": "tsc && node --experimental-strip-types --no-warnings=ExperimentalWarning scripts/post-build.ts",
+    "typecheck": "tsc --noEmit",
+    "format": "eslint --cache --fix . && prettier --write --cache .",
+    "check-format": "eslint --cache . && prettier --check --cache .;",
+    "docs": "npm run build && npm run docs:generate && npm run format",
+    "docs:generate": "node --experimental-strip-types scripts/generate-docs.ts",
     "start": "npm run build && node build/src/index.js",
     "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js",
-    "test": "npm run build && node --test-reporter spec --test-force-exit --test 'build/tests/**/*.test.js'",
-    "test:only": "npm run build && node --test-reporter spec --test-force-exit --test --test-only 'build/tests/**/*.test.js'",
-    "test:only:no-build": "node --test-reporter spec --test-force-exit --test --test-only 'build/tests/**/*.test.js'",
+    "test": "npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test \"build/tests/**/*.test.js\"",
+    "test:only": "npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test --test-only \"build/tests/**/*.test.js\"",
+    "test:only:no-build": "node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-reporter spec --test-force-exit --test --test-only \"build/tests/**/*.test.js\"",
+    "test:update-snapshots": "npm run build && node --require ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-force-exit --test --test-update-snapshots \"build/tests/**/*.test.js\"",
     "prepare": "node --experimental-strip-types scripts/prepare.ts"
   },
   "files": [
@@ -33,9 +36,9 @@
   },
   "homepage": "https://github.com/ChromeDevTools/chrome-devtools-mcp#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.18.0",
+    "@modelcontextprotocol/sdk": "1.18.1",
     "debug": "4.4.3",
-    "puppeteer-core": "24.21.0",
+    "puppeteer-core": "24.22.0",
     "yargs": "18.0.0"
   },
   "devDependencies": {
@@ -47,11 +50,11 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1514545",
+    "chrome-devtools-frontend": "1.0.1516909",
     "eslint": "^9.35.0",
     "globals": "^16.4.0",
     "prettier": "^3.6.2",
-    "puppeteer": "24.21.0",
+    "puppeteer": "24.22.0",
     "sinon": "^21.0.0",
     "typescript": "^5.9.2",
     "typescript-eslint": "^8.43.0"

package/build/src/waitForHelpers.js

@@ -1,109 +0,0 @@
-import { logger } from './logger.js';
-async function waitForStableDom(page, signal) {
-    const stableDomObserver = await page.evaluateHandle(() => {
-        let timeoutId;
-        function callback() {
-            clearTimeout(timeoutId);
-            timeoutId = setTimeout(() => {
-                domObserver.resolver.resolve();
-                domObserver.observer.disconnect();
-            }, 100);
-        }
-        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;
-    });
-    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;
-        }),
-        timeout(3000, signal).then(() => {
-            throw new Error('Timeout');
-        }),
-    ]);
-}
-async function waitForNavigationStarted(page, signal) {
-    // 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);
-        };
-        page._client().on('Page.frameStartedNavigating', listener);
-        signal.addEventListener('abort', () => {
-            resolve(false);
-            page._client().off('Page.frameStartedNavigating', listener);
-        });
-    });
-    return await Promise.race([
-        navigationStartedPromise,
-        timeout(100).then(() => false),
-    ]);
-}
-function timeout(time, signal) {
-    return new Promise(res => {
-        const id = setTimeout(res, time);
-        signal?.addEventListener('abort', () => {
-            res();
-            clearTimeout(id);
-        });
-    });
-}
-/**
- * A wrapper that executes a action and waits for
- * a potential navigation, after which it waits
- * for the DOM to be stable before returning.
- */
-export async function waitForEventsAfterAction(page, callback) {
-    const controller = new AbortController();
-    const navigationStartedPromise = waitForNavigationStarted(page, controller.signal);
-    await callback();
-    try {
-        const navigationStated = await navigationStartedPromise;
-        if (navigationStated) {
-            await page.waitForNavigation({
-                timeout: 3000,
-                signal: controller.signal,
-            });
-        }
-        // Wait for stable dom after navigation so we execute in
-        // the correct context
-        await waitForStableDom(page, controller.signal);
-    }
-    catch (error) {
-        logger(error);
-    }
-    finally {
-        controller.abort();
-    }
-}