@yezack/chrome-devtools-mcp-108 0.0.0-stage → 1.10.2

package/build/src/tools/performance.js

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import zlib from 'node:zlib';
+import { zod, DevTools } from '../third_party/index.js';
+import { parseRawTraceBuffer, traceResultIsSuccess, } from '../processors/PerformanceTrace.js';
+import { logger } from '../utils/logger.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } 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 = definePageTool(() => ({
+    name: 'performance_start_trace',
+    description: `Start a performance trace on the target webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.`,
+    annotations: {
+        category: ToolCategory.PERFORMANCE,
+        readOnlyHint: false,
+    },
+    schema: {
+        reload: zod
+            .boolean()
+            .default(true)
+            .describe('Determines if, once tracing has started, the target 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()
+            .default(true)
+            .describe('Determines if the trace recording should be automatically stopped.'),
+        filePath: filePathSchema,
+    },
+    blockedByDialog: true,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    handler: async (request, response, context) => {
+        if (context.isRunningPerformanceTrace()) {
+            response.appendResponseLine('Error: a performance trace is already running. Use performance_stop_trace to stop it. Only one trace can be running at any given time.');
+            return;
+        }
+        context.setIsRunningPerformanceTrace(true);
+        const page = request.page;
+        const pageUrlForTracing = page.pptrPage.url();
+        try {
+            if (request.params.reload) {
+                // Before starting the recording, navigate to about:blank to clear out any state.
+                // We use `load` because `networkidle0` is known to be flaky for about:blank in Puppeteer.
+                await page.pptrPage.goto('about:blank', {
+                    waitUntil: 'load',
+                });
+            }
+            const categories = [
+                '-*',
+                ...DevTools.TracingDefaultCategories,
+                // These categories are optional in DevTools, but enabled by default in the DevTools UI, so we enable them here too.
+                ...DevTools.TracingOptionalCategories.JsSampling,
+                ...DevTools.TracingOptionalCategories.Screenshot,
+            ];
+            await page.pptrPage.tracing.start({
+                categories,
+                bufferSize: 1200 * 1000,
+            });
+            if (request.params.reload) {
+                await page.pptrPage.goto(pageUrlForTracing, {
+                    waitUntil: ['load'],
+                });
+            }
+            if (request.params.autoStop) {
+                await new Promise(resolve => setTimeout(resolve, 5_000));
+                await stopTracingAndAppendOutput(page, response, context, request.params.filePath);
+            }
+            else {
+                response.appendResponseLine(`The performance trace is being recorded. Use performance_stop_trace to stop it.`);
+            }
+        }
+        catch (error) {
+            // If a setup step (navigation, tracing.start) throws before
+            // stopTracingAndAppendOutput runs, the running flag would otherwise stay
+            // stuck `true` for the rest of the session, blocking all future traces.
+            // Unwind here: stop tracing if it was started and clear the flag. When
+            // autoStop already ran stopTracingAndAppendOutput the flag is already
+            // false and this is a no-op.
+            if (context.isRunningPerformanceTrace()) {
+                try {
+                    await page.pptrPage.tracing.stop();
+                }
+                catch {
+                    // Tracing may not have started yet; ignore.
+                }
+                context.setIsRunningPerformanceTrace(false);
+            }
+            throw error;
+        }
+    },
+}));
+export const stopTrace = definePageTool(() => ({
+    name: 'performance_stop_trace',
+    description: 'Stop the active performance trace recording on the target webpage.',
+    annotations: {
+        category: ToolCategory.PERFORMANCE,
+        readOnlyHint: false,
+    },
+    schema: {
+        filePath: filePathSchema,
+    },
+    blockedByDialog: true,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    handler: async (request, response, context) => {
+        if (!context.isRunningPerformanceTrace()) {
+            return;
+        }
+        const page = request.page;
+        await stopTracingAndAppendOutput(page, response, context, request.params.filePath);
+    },
+}));
+export const analyzeInsight = definePageTool(() => ({
+    name: 'performance_analyze_insight',
+    description: 'Provides more detailed information on a specific Performance Insight of an insight set that was highlighted in the results of a trace recording.',
+    annotations: {
+        category: ToolCategory.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {
+        insightSetId: zod
+            .string()
+            .describe('The id for the specific insight set. Only use the ids given in the "Available insight sets" list.'),
+        insightName: zod
+            .string()
+            .describe('The name of the Insight you want more information on. For example: "DocumentLatency" or "LCPBreakdown"'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    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;
+        }
+        response.attachTraceInsight(lastRecording, request.params.insightSetId, request.params.insightName);
+    },
+}));
+async function stopTracingAndAppendOutput(page, response, context, filePath) {
+    try {
+        const traceEventsBuffer = await page.pptrPage.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, filePath.endsWith('.gz') ? '.gz' : '.json');
+            response.appendResponseLine(`The raw trace data was saved to ${file.filename}.`);
+        }
+        const result = await parseRawTraceBuffer(traceEventsBuffer, {
+            cpuThrottling: page.cpuThrottlingRate,
+            networkThrottling: page.networkConditions ?? undefined,
+        });
+        response.appendResponseLine('The performance trace has been stopped.');
+        if (traceResultIsSuccess(result)) {
+            if (context.isCruxEnabled()) {
+                await populateCruxData(result);
+            }
+            context.storeTraceRecording(result);
+            response.attachTraceSummary(result);
+        }
+        else {
+            throw new Error(`There was an unexpected error parsing the trace: ${result.error}`);
+        }
+    }
+    finally {
+        context.setIsRunningPerformanceTrace(false);
+    }
+}
+/** We tell CrUXManager to fetch data so it's available when DevTools.PerformanceTraceFormatter is invoked */
+async function populateCruxData(result) {
+    logger?.('populateCruxData called');
+    const cruxManager = DevTools.CrUXManager.CrUXManager.instance();
+    // go/jtfbx. Yes, we're aware this API key is public. ;)
+    cruxManager.setEndpointForTesting('https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=AIzaSyBn5gimNjhiEyA_euicSKko6IlD3HdgUfk');
+    const cruxSetting = DevTools.Common.Settings.Settings.instance().createSetting('field-data', {
+        enabled: true,
+    });
+    cruxSetting.set({ enabled: true });
+    // Gather URLs to fetch CrUX data for
+    const urls = [...(result.parsedTrace.insights?.values() ?? [])].map(c => c.url.toString());
+    urls.push(result.parsedTrace.data.Meta.mainFrameURL);
+    const urlSet = new Set(urls);
+    if (urlSet.size === 0) {
+        logger?.('No URLs found for CrUX data');
+        return;
+    }
+    logger?.(`Fetching CrUX data for ${urlSet.size} URLs: ${Array.from(urlSet).join(', ')}`);
+    const cruxData = await Promise.all(Array.from(urlSet).map(async (url) => {
+        const data = await cruxManager.getFieldDataForPage(url);
+        logger?.(`CrUX data for ${url}: ${data ? 'found' : 'not found'}`);
+        return data;
+    }));
+    result.parsedTrace.metadata.cruxFieldData = cruxData;
+}
+//# sourceMappingURL=performance.js.map

package/build/src/tools/pwa.js

@@ -0,0 +1,128 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+const manifestIdSchema = zod
+    .string()
+    .describe('The manifest ID of the web app: the resolved `id` member of its manifest. ' +
+    'If `id` is omitted, it defaults to the resolved `start_url` ' +
+    '(e.g. "https://example.com/"). See https://w3c.github.io/manifest/#id-member.');
+const displayModeSchema = zod
+    .enum(['standalone', 'browser'])
+    .optional()
+    .describe('Optional user display mode preference applied after install. ' +
+    '"standalone" opens the app in its own window; "browser" opens it as a ' +
+    'tab. Installs via the PWA CDP domain default to "browser" because they ' +
+    'do not simulate the install dialog, so pass "standalone" to get an ' +
+    'app-window experience.');
+export const installPwa = defineTool(() => ({
+    name: 'install_pwa',
+    description: 'Installs a Progressive Web App (PWA) identified by its manifest ID. ' +
+        'This installs through the PWA CDP domain without a user gesture or install ' +
+        'dialog. DevTools installs default to browser display mode.',
+    annotations: {
+        category: ToolCategory.PWA,
+        readOnlyHint: false,
+    },
+    schema: {
+        manifestId: manifestIdSchema,
+        installUrlOrBundleUrl: zod
+            .string()
+            .describe('The location of the app or bundle. For a normal site this is the page ' +
+            'URL; for an Isolated Web App it can be a file:// or http(s):// ' +
+            'signed web bundle.'),
+        displayMode: displayModeSchema,
+    },
+    blockedByDialog: false,
+    // We do not validate file paths for remote browser instances
+    // because they are on the remote host and not accessed by the MCP server.
+    verifyFilesSchema: {
+        installUrlOrBundleUrl: {
+            local: true,
+            remote: false,
+        },
+    },
+    handler: async (request, response, context) => {
+        const { manifestId, installUrlOrBundleUrl, displayMode } = request.params;
+        await context.installPWA({
+            manifestId,
+            installUrlOrBundleUrl,
+            displayMode,
+        });
+        response.appendResponseLine(`Installed PWA with manifest ID: ${manifestId}`);
+        if (displayMode) {
+            response.appendResponseLine(`Display mode set to: ${displayMode}`);
+        }
+    },
+}));
+export const uninstallPwa = defineTool(() => ({
+    name: 'uninstall_pwa',
+    description: 'Uninstalls a Progressive Web App identified by its manifest ID and ' +
+        'closes any open app windows.',
+    annotations: {
+        category: ToolCategory.PWA,
+        readOnlyHint: false,
+    },
+    schema: {
+        manifestId: manifestIdSchema,
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { manifestId } = request.params;
+        await context.uninstallPWA({ manifestId });
+        response.appendResponseLine(`Uninstalled PWA with manifest ID: ${manifestId}`);
+        response.setIncludePages(true);
+    },
+}));
+export const launchPwa = defineTool(() => ({
+    name: 'launch_pwa',
+    description: 'Launches an installed Progressive Web App using its saved display mode. ' +
+        'Optionally opens a specific URL within the same app instead of the default ' +
+        'start URL.',
+    annotations: {
+        category: ToolCategory.PWA,
+        readOnlyHint: false,
+    },
+    schema: {
+        manifestId: manifestIdSchema,
+        url: zod
+            .string()
+            .optional()
+            .describe('Optional URL within the app to open instead of the default start URL.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { manifestId, url } = request.params;
+        const page = await context.launchPWA({ manifestId, url });
+        response.appendResponseLine(`Launched PWA with manifest ID: ${manifestId} (${page.url()})`);
+        response.setIncludePages(true);
+    },
+}));
+export const getOsAppState = defineTool(() => ({
+    name: 'get_os_app_state',
+    description: 'Returns the OS integration state (badge count and registered file ' +
+        'handlers) for an installed web app, identified by its manifest ID.',
+    annotations: {
+        category: ToolCategory.PWA,
+        readOnlyHint: true,
+    },
+    schema: {
+        manifestId: manifestIdSchema,
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { manifestId } = request.params;
+        const state = await context.getPWAState({ manifestId });
+        response.appendResponseLine(`OS app state for manifest ID: ${manifestId}`);
+        response.appendResponseLine(`Badge count: ${state.badgeCount}`);
+        response.appendResponseLine(`File handlers: ${JSON.stringify(state.fileHandlers)}`);
+    },
+}));
+//# sourceMappingURL=pwa.js.map

package/build/src/tools/screencast.js

@@ -0,0 +1,119 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } from './ToolDefinition.js';
+async function generateTempFilePath() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'chrome-devtools-mcp-'));
+    return path.join(dir, `screencast.mp4`);
+}
+const supportedExtensions = ['.webm', '.mp4'];
+export const startScreencast = definePageTool((args) => ({
+    name: 'screencast_start',
+    description: `Starts recording a screencast (video) of the target page in specified format.`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+        conditions: ['experimentalScreencast'],
+    },
+    schema: {
+        filePath: zod
+            .string()
+            .optional()
+            .describe(`Output file path (${supportedExtensions.join(',')} are supported). Uses mkdtemp to generate a unique path if not provided.`),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    handler: async (request, response, context) => {
+        if (context.getScreenRecorder() !== null) {
+            response.appendResponseLine('Error: a screencast recording is already in progress. Use screencast_stop to stop it before starting a new one.');
+            return;
+        }
+        const requestedFilePath = request.params.filePath;
+        const filePath = requestedFilePath ?? (await generateTempFilePath());
+        // Match the extension case-insensitively so e.g. `.WEBM` is recognized as
+        // WebM. An explicitly requested but unsupported extension is rejected
+        // rather than being silently rewritten to `.mp4` (which would change both
+        // the format and the output path from what was requested). A missing
+        // extension falls back to `.mp4`. The matched extension is normalized to
+        // lower case.
+        const requestedExtension = path.extname(filePath);
+        const matchedExtension = supportedExtensions.find(supportedExtension => supportedExtension === requestedExtension.toLowerCase());
+        if (!matchedExtension && requestedExtension !== '') {
+            throw new Error(`Unsupported screencast file extension "${requestedExtension}". ` +
+                `Supported formats: ${supportedExtensions.join(', ')} (case-insensitive).`);
+        }
+        const enforcedExtension = matchedExtension ?? '.mp4';
+        const format = (matchedExtension?.substring(1) ??
+            'mp4');
+        const resolvedPath = await context.ensureExtension(filePath, enforcedExtension);
+        const page = request.page;
+        let recorder;
+        try {
+            recorder = await page.pptrPage.screencast({
+                path: resolvedPath,
+                format: format,
+                ffmpegPath: args?.experimentalFfmpegPath,
+                fps: args?.experimentalScreencastFps,
+            });
+        }
+        catch (err) {
+            // If we generated a temporary directory for this recording, remove it so
+            // a failed start (e.g. ffmpeg missing) does not leak an empty directory.
+            if (requestedFilePath === undefined) {
+                try {
+                    await fs.rm(path.dirname(resolvedPath), {
+                        recursive: true,
+                        force: true,
+                    });
+                }
+                catch {
+                    // no-op
+                }
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes('ENOENT') && message.includes('ffmpeg')) {
+                throw new Error('ffmpeg is required for screencast recording but was not found. ' +
+                    'Install ffmpeg (https://ffmpeg.org/) and ensure it is available in your PATH.');
+            }
+            throw err;
+        }
+        context.setScreenRecorder({ recorder, filePath: resolvedPath });
+        response.appendResponseLine(`Screencast recording started. The recording will be saved to ${resolvedPath}. Use ${stopScreencast(args).name} to stop recording.`);
+    },
+}));
+export const stopScreencast = definePageTool(() => ({
+    name: 'screencast_stop',
+    description: 'Stops the active screencast recording on the target page.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+        conditions: ['experimentalScreencast'],
+    },
+    schema: {},
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (_request, response, context) => {
+        const data = context.getScreenRecorder();
+        if (!data) {
+            response.appendResponseLine('Error: no active screencast recording to stop.');
+            return;
+        }
+        try {
+            await data.recorder.stop();
+            response.appendResponseLine(`The screencast recording has been stopped and saved to ${data.filePath}.`);
+        }
+        finally {
+            context.setScreenRecorder(null);
+        }
+    },
+}));
+//# sourceMappingURL=screencast.js.map