chrome-devtools-mcp 0.12.1 → 0.14.0

package/build/src/tools/performance.js

@@ -3,25 +3,30 @@
  * Copyright 2025 Google LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { logger } from '../logger.js';
+import zlib from 'node:zlib';
 import { zod } from '../third_party/index.js';
-import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
+import { parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
 import { ToolCategory } from './categories.js';
 import { defineTool } from './ToolDefinition.js';
+const filePathSchema = zod
+    .string()
+    .optional()
+    .describe('The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).');
 export const startTrace = defineTool({
     name: 'performance_start_trace',
-    description: 'Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.',
+    description: `Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.`,
     annotations: {
         category: ToolCategory.PERFORMANCE,
-        readOnlyHint: true,
+        readOnlyHint: false,
     },
     schema: {
         reload: zod
             .boolean()
-            .describe('Determines if, once tracing has started, the page should be automatically reloaded.'),
+            .describe('Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the navigate_page tool BEFORE starting the trace if reload or autoStop is set to true.'),
         autoStop: zod
             .boolean()
             .describe('Determines if the trace recording should be automatically stopped.'),
+        filePath: filePathSchema,
     },
     handler: async (request, response, context) => {
         if (context.isRunningPerformanceTrace()) {
@@ -68,7 +73,7 @@ export const startTrace = defineTool({
         }
         if (request.params.autoStop) {
             await new Promise(resolve => setTimeout(resolve, 5_000));
-            await stopTracingAndAppendOutput(page, response, context);
+            await stopTracingAndAppendOutput(page, response, context, request.params.filePath);
         }
         else {
             response.appendResponseLine(`The performance trace is being recorded. Use performance_stop_trace to stop it.`);
@@ -80,15 +85,17 @@ export const stopTrace = defineTool({
     description: 'Stops the active performance trace recording on the selected page.',
     annotations: {
         category: ToolCategory.PERFORMANCE,
-        readOnlyHint: true,
+        readOnlyHint: false,
     },
-    schema: {},
-    handler: async (_request, response, context) => {
+    schema: {
+        filePath: filePathSchema,
+    },
+    handler: async (request, response, context) => {
         if (!context.isRunningPerformanceTrace()) {
             return;
         }
         const page = context.getSelectedPage();
-        await stopTracingAndAppendOutput(page, response, context);
+        await stopTracingAndAppendOutput(page, response, context, request.params.filePath);
     },
 });
 export const analyzeInsight = defineTool({
@@ -112,35 +119,39 @@ export const analyzeInsight = defineTool({
             response.appendResponseLine('No recorded traces found. Record a performance trace so you have Insights to analyze.');
             return;
         }
-        const insightOutput = getInsightOutput(lastRecording, request.params.insightSetId, request.params.insightName);
-        if ('error' in insightOutput) {
-            response.appendResponseLine(insightOutput.error);
-            return;
-        }
-        response.appendResponseLine(insightOutput.output);
+        response.attachTraceInsight(lastRecording, request.params.insightSetId, request.params.insightName);
     },
 });
-async function stopTracingAndAppendOutput(page, response, context) {
+async function stopTracingAndAppendOutput(page, response, context, filePath) {
     try {
         const traceEventsBuffer = await page.tracing.stop();
+        if (filePath && traceEventsBuffer) {
+            let dataToWrite = traceEventsBuffer;
+            if (filePath.endsWith('.gz')) {
+                dataToWrite = await new Promise((resolve, reject) => {
+                    zlib.gzip(traceEventsBuffer, (error, result) => {
+                        if (error) {
+                            reject(error);
+                        }
+                        else {
+                            resolve(result);
+                        }
+                    });
+                });
+            }
+            const file = await context.saveFile(dataToWrite, filePath);
+            response.appendResponseLine(`The raw trace data was saved to ${file.filename}.`);
+        }
         const result = await parseRawTraceBuffer(traceEventsBuffer);
         response.appendResponseLine('The performance trace has been stopped.');
         if (traceResultIsSuccess(result)) {
             context.storeTraceRecording(result);
-            const traceSummaryText = getTraceSummary(result);
-            response.appendResponseLine(traceSummaryText);
+            response.attachTraceSummary(result);
         }
         else {
-            response.appendResponseLine('There was an unexpected error parsing the trace:');
-            response.appendResponseLine(result.error);
+            throw new Error(`There was an unexpected error parsing the trace: ${result.error}`);
         }
     }
-    catch (e) {
-        const errorText = e instanceof Error ? e.message : JSON.stringify(e);
-        logger(`Error stopping performance trace: ${errorText}`);
-        response.appendResponseLine('An error occurred generating the response for this trace:');
-        response.appendResponseLine(errorText);
-    }
     finally {
         context.setIsRunningPerformanceTrace(false);
     }

package/build/src/tools/tools.js

@@ -5,6 +5,7 @@
  */
 import * as consoleTools from './console.js';
 import * as emulationTools from './emulation.js';
+import * as extensionTools from './extensions.js';
 import * as inputTools from './input.js';
 import * as networkTools from './network.js';
 import * as pagesTools from './pages.js';
@@ -15,6 +16,7 @@ import * as snapshotTools from './snapshot.js';
 const tools = [
     ...Object.values(consoleTools),
     ...Object.values(emulationTools),
+    ...Object.values(extensionTools),
     ...Object.values(inputTools),
     ...Object.values(networkTools),
     ...Object.values(pagesTools),

package/build/src/utils/ExtensionRegistry.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export class ExtensionRegistry {
+    #extensions = new Map();
+    async registerExtension(id, extensionPath) {
+        const manifestPath = path.join(extensionPath, 'manifest.json');
+        const manifestContent = await fs.readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+        const name = manifest.name ?? 'Unknown';
+        const version = manifest.version ?? 'Unknown';
+        const extension = {
+            id,
+            name,
+            version,
+            isEnabled: true,
+            path: extensionPath,
+        };
+        this.#extensions.set(extension.id, extension);
+        return extension;
+    }
+    remove(id) {
+        this.#extensions.delete(id);
+    }
+    list() {
+        return Array.from(this.#extensions.values());
+    }
+    getById(id) {
+        return this.#extensions.get(id);
+    }
+}

package/build/src/utils/string.js

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Converts a given string to snake_case.
+ * This function handles camelCase, PascalCase, and acronyms, including transitions between letters and numbers.
+ * It uses Unicode-aware regular expressions (`\p{L}`, `\p{N}`, `\p{Lu}`, `\p{Ll}` with the `u` flag)
+ * to correctly process letters and numbers from various languages.
+ *
+ * @param text The input string to convert to snake_case.
+ * @returns The snake_case version of the input string.
+ */
+export function toSnakeCase(text) {
+    if (!text) {
+        return '';
+    }
+    // First, handle case-based transformations to insert underscores correctly.
+    // 1. Add underscore between a letter and a number.
+    //    e.g., "version2" -> "version_2"
+    // 2. Add underscore between an uppercase letter sequence and a following uppercase+lowercase sequence.
+    //    e.g., "APIFlags" -> "API_Flags"
+    // 3. Add underscore between a lowercase/number and an uppercase letter.
+    //    e.g., "lastName" -> "last_Name", "version_2Update" -> "version_2_Update"
+    // 4. Replace sequences of non-alphanumeric with a single underscore
+    // 5. Remove any leading or trailing underscores.
+    const result = text
+        .replace(/(\p{L})(\p{N})/gu, '$1_$2') // 1
+        .replace(/(\p{Lu}+)(\p{Lu}\p{Ll})/gu, '$1_$2') // 2
+        .replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, '$1_$2') // 3
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, '_') // 4
+        .replace(/^_|_$/g, ''); // 5
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "MCP server for Chrome DevTools",
   "type": "module",
   "bin": "./build/src/index.js",
@@ -16,14 +16,14 @@
     "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:node20": "node --import ./build/tests/setup.js --test-reporter spec --test-force-exit --test build/tests",
-    "test:no-build": "node --import ./build/tests/setup.js --no-warnings=ExperimentalWarning --experimental-print-required-tla --test-reporter spec --test-force-exit --test \"build/tests/**/*.test.js\"",
-    "test": "npm run build && npm run test:no-build",
-    "test:only": "npm run build && npm run test:only:no-build",
-    "test:only:no-build": "node --import ./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 --import ./build/tests/setup.js --no-warnings=ExperimentalWarning --test-force-exit --test --test-update-snapshots \"build/tests/**/*.test.js\"",
+    "test": "npm run build && node scripts/test.mjs",
+    "test:no-build": "node scripts/test.mjs",
+    "test:only": "npm run build && node scripts/test.mjs --test-only",
+    "test:update-snapshots": "npm run build && node scripts/test.mjs --test-update-snapshots",
     "prepare": "node --experimental-strip-types scripts/prepare.ts",
-    "verify-server-json-version": "node --experimental-strip-types scripts/verify-server-json-version.ts"
+    "verify-server-json-version": "node --experimental-strip-types scripts/verify-server-json-version.ts",
+    "eval": "npm run build && node --experimental-strip-types scripts/eval_gemini.ts",
+    "count-tokens": "node --experimental-strip-types scripts/count_tokens.ts"
   },
   "files": [
     "build/src",
@@ -41,7 +41,8 @@
   "mcpName": "io.github.ChromeDevTools/chrome-devtools-mcp",
   "devDependencies": {
     "@eslint/js": "^9.35.0",
-    "@modelcontextprotocol/sdk": "1.24.3",
+    "@google/genai": "^1.37.0",
+    "@modelcontextprotocol/sdk": "1.25.3",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
@@ -53,16 +54,16 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1555430",
-    "core-js": "3.47.0",
+    "chrome-devtools-frontend": "1.0.1573331",
+    "core-js": "3.48.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",
     "eslint-import-resolver-typescript": "^4.4.4",
     "eslint-plugin-import": "^2.32.0",
-    "globals": "^16.4.0",
+    "globals": "^17.0.0",
     "prettier": "^3.6.2",
-    "puppeteer": "24.33.0",
-    "rollup": "4.53.3",
+    "puppeteer": "24.36.0",
+    "rollup": "4.56.0",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-license": "^3.6.0",
     "sinon": "^21.0.0",

package/build/src/formatters/consoleFormatter.js

@@ -1,121 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-// The short format for a console message, based on a previous format.
-export function formatConsoleEventShort(msg) {
-    if (msg.type === 'issue') {
-        return `msgid=${msg.consoleMessageStableId} [${msg.type}] ${msg.message} (count: ${msg.count})`;
-    }
-    return `msgid=${msg.consoleMessageStableId} [${msg.type}] ${msg.message} (${msg.args?.length ?? 0} args)`;
-}
-function getArgs(msg) {
-    const args = [...(msg.args ?? [])];
-    // If there is no text, the first argument serves as text (see formatMessage).
-    if (!msg.message) {
-        args.shift();
-    }
-    return args;
-}
-// The verbose format for a console message, including all details.
-export function formatConsoleEventVerbose(msg, context) {
-    const aggregatedIssue = msg.item;
-    const result = [
-        `ID: ${msg.consoleMessageStableId}`,
-        `Message: ${msg.type}> ${aggregatedIssue ? formatIssue(aggregatedIssue, msg.description, context) : msg.message}`,
-        aggregatedIssue ? undefined : formatArgs(msg),
-    ].filter(line => !!line);
-    return result.join('\n');
-}
-function formatArg(arg) {
-    return typeof arg === 'object' ? JSON.stringify(arg) : String(arg);
-}
-function formatArgs(consoleData) {
-    const args = getArgs(consoleData);
-    if (!args.length) {
-        return '';
-    }
-    const result = ['### Arguments'];
-    for (const [key, arg] of args.entries()) {
-        result.push(`Arg #${key}: ${formatArg(arg)}`);
-    }
-    return result.join('\n');
-}
-export function formatIssue(issue, description, context) {
-    const result = [];
-    let processedMarkdown = description?.trim();
-    // Remove heading in order not to conflict with the whole console message response markdown
-    if (processedMarkdown?.startsWith('# ')) {
-        processedMarkdown = processedMarkdown.substring(2).trimStart();
-    }
-    if (processedMarkdown)
-        result.push(processedMarkdown);
-    const links = issue.getDescription()?.links;
-    if (links && links.length > 0) {
-        result.push('Learn more:');
-        for (const link of links) {
-            result.push(`[${link.linkTitle}](${link.link})`);
-        }
-    }
-    const issues = issue.getAllIssues();
-    const affectedResources = [];
-    for (const singleIssue of issues) {
-        const details = singleIssue.details();
-        if (!details)
-            continue;
-        // We send the remaining details as untyped JSON because the DevTools
-        // frontend code is currently not re-usable.
-        // eslint-disable-next-line
-        const data = structuredClone(details);
-        let uid;
-        let request;
-        if ('violatingNodeId' in details && details.violatingNodeId && context) {
-            uid = context.resolveCdpElementId(details.violatingNodeId);
-            delete data.violatingNodeId;
-        }
-        if ('nodeId' in details && details.nodeId && context) {
-            uid = context.resolveCdpElementId(details.nodeId);
-            delete data.nodeId;
-        }
-        if ('documentNodeId' in details && details.documentNodeId && context) {
-            uid = context.resolveCdpElementId(details.documentNodeId);
-            delete data.documentNodeId;
-        }
-        if ('request' in details && details.request) {
-            request = details.request.url;
-            if (details.request.requestId && context) {
-                const resolvedId = context.resolveCdpRequestId(details.request.requestId);
-                if (resolvedId) {
-                    request = resolvedId;
-                    delete data.request.requestId;
-                }
-            }
-        }
-        // These fields has no use for the MCP client (redundant or irrelevant).
-        delete data.errorType;
-        delete data.frameId;
-        affectedResources.push({
-            uid,
-            data: data,
-            request,
-        });
-    }
-    if (affectedResources.length) {
-        result.push('### Affected resources');
-    }
-    result.push(...affectedResources.map(item => {
-        const details = [];
-        if (item.uid)
-            details.push(`uid=${item.uid}`);
-        if (item.request) {
-            details.push((typeof item.request === 'number' ? `reqid=` : 'url=') + item.request);
-        }
-        if (item.data)
-            details.push(`data=${JSON.stringify(item.data)}`);
-        return details.join(' ');
-    }));
-    if (result.length === 0)
-        return 'No affected resources found';
-    return result.join('\n');
-}

package/build/src/formatters/networkFormatter.js

@@ -1,77 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-import { isUtf8 } from 'node:buffer';
-const BODY_CONTEXT_SIZE_LIMIT = 10000;
-export function getShortDescriptionForRequest(request, id, selectedInDevToolsUI = false) {
-    // TODO truncate the URL
-    return `reqid=${id} ${request.method()} ${request.url()} ${getStatusFromRequest(request)}${selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
-}
-export function getStatusFromRequest(request) {
-    const httpResponse = request.response();
-    const failure = request.failure();
-    let status;
-    if (httpResponse) {
-        const responseStatus = httpResponse.status();
-        status =
-            responseStatus >= 200 && responseStatus <= 299
-                ? `[success - ${responseStatus}]`
-                : `[failed - ${responseStatus}]`;
-    }
-    else if (failure) {
-        status = `[failed - ${failure.errorText}]`;
-    }
-    else {
-        status = '[pending]';
-    }
-    return status;
-}
-export function getFormattedHeaderValue(headers) {
-    const response = [];
-    for (const [name, value] of Object.entries(headers)) {
-        response.push(`- ${name}:${value}`);
-    }
-    return response;
-}
-export async function getFormattedResponseBody(httpResponse, sizeLimit = BODY_CONTEXT_SIZE_LIMIT) {
-    try {
-        const responseBuffer = await httpResponse.buffer();
-        if (isUtf8(responseBuffer)) {
-            const responseAsTest = responseBuffer.toString('utf-8');
-            if (responseAsTest.length === 0) {
-                return `<empty response>`;
-            }
-            return `${getSizeLimitedString(responseAsTest, sizeLimit)}`;
-        }
-        return `<binary data>`;
-    }
-    catch {
-        return `<not available anymore>`;
-    }
-}
-export async function getFormattedRequestBody(httpRequest, sizeLimit = BODY_CONTEXT_SIZE_LIMIT) {
-    if (httpRequest.hasPostData()) {
-        const data = httpRequest.postData();
-        if (data) {
-            return `${getSizeLimitedString(data, sizeLimit)}`;
-        }
-        try {
-            const fetchData = await httpRequest.fetchPostData();
-            if (fetchData) {
-                return `${getSizeLimitedString(fetchData, sizeLimit)}`;
-            }
-        }
-        catch {
-            return `<not available anymore>`;
-        }
-    }
-    return;
-}
-function getSizeLimitedString(text, sizeLimit) {
-    if (text.length > sizeLimit) {
-        return `${text.substring(0, sizeLimit) + '... <truncated>'}`;
-    }
-    return `${text}`;
-}

package/build/src/formatters/snapshotFormatter.js

@@ -1,73 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-export function formatSnapshotNode(root, snapshot, depth = 0) {
-    const chunks = [];
-    if (depth === 0) {
-        // Top-level content of the snapshot.
-        if (snapshot?.verbose &&
-            snapshot?.hasSelectedElement &&
-            !snapshot.selectedElementUid) {
-            chunks.push(`Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
-Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
-        }
-    }
-    const attributes = getAttributes(root);
-    const line = ' '.repeat(depth * 2) +
-        attributes.join(' ') +
-        (root.id === snapshot?.selectedElementUid
-            ? ' [selected in the DevTools Elements panel]'
-            : '') +
-        '\n';
-    chunks.push(line);
-    for (const child of root.children) {
-        chunks.push(formatSnapshotNode(child, snapshot, depth + 1));
-    }
-    return chunks.join('');
-}
-function getAttributes(serializedAXNodeRoot) {
-    const attributes = [`uid=${serializedAXNodeRoot.id}`];
-    if (serializedAXNodeRoot.role) {
-        // To match representation in DevTools.
-        attributes.push(serializedAXNodeRoot.role === 'none'
-            ? 'ignored'
-            : serializedAXNodeRoot.role);
-    }
-    if (serializedAXNodeRoot.name) {
-        attributes.push(`"${serializedAXNodeRoot.name}"`);
-    }
-    const excluded = new Set([
-        'id',
-        'role',
-        'name',
-        'elementHandle',
-        'children',
-        'backendNodeId',
-    ]);
-    const booleanPropertyMap = {
-        disabled: 'disableable',
-        expanded: 'expandable',
-        focused: 'focusable',
-        selected: 'selectable',
-    };
-    for (const attr of Object.keys(serializedAXNodeRoot).sort()) {
-        if (excluded.has(attr)) {
-            continue;
-        }
-        const value = serializedAXNodeRoot[attr];
-        if (typeof value === 'boolean') {
-            if (booleanPropertyMap[attr]) {
-                attributes.push(booleanPropertyMap[attr]);
-            }
-            if (value) {
-                attributes.push(attr);
-            }
-        }
-        else if (typeof value === 'string' || typeof value === 'number') {
-            attributes.push(`${attr}="${value}"`);
-        }
-    }
-    return attributes;
-}

package/build/src/third_party/devtools.js

@@ -1,6 +0,0 @@
-/**
- * @license
- * Copyright 2025 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-export { AgentFocus, TraceEngine, PerformanceTraceFormatter, PerformanceInsightFormatter, AggregatedIssue, Issue, Target as SDKTarget, DebuggerModel, Foundation, TargetManager, MarkdownIssueDescription, Marked, ProtocolClient, Common, I18n, createIssuesFromProtocolIssue, IssueAggregator, } from '../../node_modules/chrome-devtools-frontend/mcp/mcp.js';

package/build/src/third_party/issue-descriptions/SameSiteInvalidSameParty.md

@@ -1,8 +0,0 @@
-# Mark SameParty cookies as Secure and do not use SameSite=Strict for SameParty cookies
-
-Cookies marked with `SameParty` must also be marked with `Secure`. In addition, cookies marked
-with `SameParty` cannot use `SameSite=Strict`.
-
-Resolve this issue by updating the attributes of the cookie:
-  * Remove `SameParty` if the cookie should only be used by the same site but not the same first-party set
-  * Remove `SameSite=Strict` and specify `Secure` if the cookie should be available to all sites of the same first-party set

package/build/src/third_party/issue-descriptions/SameSiteSamePartyCrossPartyContextSet.md

@@ -1,10 +0,0 @@
-# Make sure a cookie is using the SameParty attribute correctly
-
-Setting cross-site cookies with the `SameParty` attribute is only possible if
-both domains are a part of the same First-Party Set.
-
-To allow setting cross-site cookies, try one of the following:
-* If the domains satisfy the First-Party Set criteria, add them to the same First-Party Set.
-* If the domains don't satisfy the First-Party Set criteria, remove the `SameParty` attribute and specify `SameSite=None`.
-
-If you don't have the option to do any of the above, cookies are not intended to be set in cross-site contexts.