chrome-devtools-mcp-for-extension 0.5.0

package/build/src/tools/performance.js

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { logger } from '../logger.js';
+import { getInsightOutput, getTraceSummary, parseRawTraceBuffer, traceResultIsSuccess, } from '../trace-processing/parse.js';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+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.',
+    annotations: {
+        category: ToolCategories.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {
+        reload: z
+            .boolean()
+            .describe('Determines if, once tracing has started, the page should be automatically reloaded.'),
+        autoStop: z
+            .boolean()
+            .describe('Determines if the trace recording should be automatically stopped.'),
+    },
+    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 = context.getSelectedPage();
+        const pageUrlForTracing = page.url();
+        if (request.params.reload) {
+            // Before starting the recording, navigate to about:blank to clear out any state.
+            await page.goto('about:blank', {
+                waitUntil: ['networkidle0'],
+            });
+        }
+        // Keep in sync with the categories arrays in:
+        // https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/timeline/TimelineController.ts
+        // https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/gather/gatherers/trace.js
+        const categories = [
+            '-*',
+            'blink.console',
+            'blink.user_timing',
+            'devtools.timeline',
+            'disabled-by-default-devtools.screenshot',
+            'disabled-by-default-devtools.timeline',
+            'disabled-by-default-devtools.timeline.invalidationTracking',
+            'disabled-by-default-devtools.timeline.frame',
+            'disabled-by-default-devtools.timeline.stack',
+            'disabled-by-default-v8.cpu_profiler',
+            'disabled-by-default-v8.cpu_profiler.hires',
+            'latencyInfo',
+            'loading',
+            'disabled-by-default-lighthouse',
+            'v8.execute',
+            'v8',
+        ];
+        await page.tracing.start({
+            categories,
+        });
+        if (request.params.reload) {
+            await page.goto(pageUrlForTracing, {
+                waitUntil: ['load'],
+            });
+        }
+        if (request.params.autoStop) {
+            await new Promise(resolve => setTimeout(resolve, 5_000));
+            await stopTracingAndAppendOutput(page, response, context);
+        }
+        else {
+            response.appendResponseLine(`The performance trace is being recorded. Use performance_stop_trace to stop it.`);
+        }
+    },
+});
+export const stopTrace = defineTool({
+    name: 'performance_stop_trace',
+    description: 'Stops the active performance trace recording on the selected page.',
+    annotations: {
+        category: ToolCategories.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response, context) => {
+        if (!context.isRunningPerformanceTrace) {
+            return;
+        }
+        const page = context.getSelectedPage();
+        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 (traceResultIsSuccess(result)) {
+            context.storeTraceRecording(result);
+            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) {
+        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/screenshot.js

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const screenshot = defineTool({
+    name: 'take_screenshot',
+    description: `Take a screenshot of the page or element.`,
+    annotations: {
+        category: ToolCategories.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {
+        format: z
+            .enum(['png', 'jpeg'])
+            .default('png')
+            .describe('Type of format to save the screenshot as. Default is "png"'),
+        uid: z
+            .string()
+            .optional()
+            .describe('The uid of an element on the page from the page content snapshot. If omitted takes a pages screenshot.'),
+        fullPage: z
+            .boolean()
+            .optional()
+            .describe('If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.'),
+    },
+    handler: async (request, response, context) => {
+        if (request.params.uid && request.params.fullPage) {
+            throw new Error('Providing both "uid" and "fullPage" is not allowed.');
+        }
+        let pageOrHandle;
+        if (request.params.uid) {
+            pageOrHandle = await context.getElementByUid(request.params.uid);
+        }
+        else {
+            pageOrHandle = context.getSelectedPage();
+        }
+        const screenshot = await pageOrHandle.screenshot({
+            type: request.params.format,
+            fullPage: request.params.fullPage,
+        });
+        if (request.params.uid) {
+            response.appendResponseLine(`Took a screenshot of node with uid "${request.params.uid}".`);
+        }
+        else if (request.params.fullPage) {
+            response.appendResponseLine('Took a screenshot of the full current page.');
+        }
+        else {
+            response.appendResponseLine("Took a screenshot of the current page's viewport.");
+        }
+        if (screenshot.length >= 2_000_000) {
+            const { filename } = await context.saveTemporaryFile(screenshot, `image/${request.params.format}`);
+            response.appendResponseLine(`Saved screenshot to ${filename}.`);
+        }
+        else {
+            response.attachImage({
+                mimeType: `image/${request.params.format}`,
+                data: Buffer.from(screenshot).toString('base64'),
+            });
+        }
+    },
+});

package/build/src/tools/script.js

@@ -0,0 +1,57 @@
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const evaluateScript = defineTool({
+    name: 'evaluate_script',
+    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 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 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(() => {
+                // Ignore errors
+            });
+        }
+    },
+});

package/build/src/tools/snapshot.js

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Locator } from 'puppeteer-core';
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+export const takeSnapshot = defineTool({
+    name: 'take_snapshot',
+    description: `Take a text snapshot of the currently selected page. The snapshot lists page elements along with a unique
+identifier (uid). Always use the latest snapshot. Prefer taking a snapshot over taking a screenshot.`,
+    annotations: {
+        category: ToolCategories.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response) => {
+        response.setIncludeSnapshot(true);
+    },
+});
+export const waitFor = defineTool({
+    name: 'wait_for',
+    description: `Wait for the specified text to appear on the selected page.`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: true,
+    },
+    schema: {
+        text: z.string().describe('Text to appear on the page'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        await Locator.race([
+            page.locator(`aria/${request.params.text}`),
+            page.locator(`text/${request.params.text}`),
+        ]).wait();
+        response.appendResponseLine(`Element with text "${request.params.text}" found.`);
+        response.setIncludeSnapshot(true);
+    },
+});

package/build/src/tools/webstore-auto-screenshot.js

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+// Tool for generating extension screenshots automatically
+export const generateExtensionScreenshots = defineTool({
+    name: 'generate_extension_screenshots',
+    description: `Automatically generate screenshots for Chrome Web Store submission`,
+    annotations: {
+        category: ToolCategories.EXTENSION_DEVELOPMENT,
+        readOnlyHint: false,
+    },
+    schema: {
+        extensionPath: z.string().describe('Path to the extension directory'),
+        extensionId: z.string().optional().describe('Extension ID if already installed'),
+    },
+    handler: async (request, response, context) => {
+        const { extensionPath, extensionId } = request.params;
+        const screenshotsDir = path.join(path.dirname(extensionPath), 'screenshots');
+        // Create screenshots directory
+        if (!fs.existsSync(screenshotsDir)) {
+            fs.mkdirSync(screenshotsDir, { recursive: true });
+        }
+        const page = context.getSelectedPage();
+        response.appendResponseLine('📸 **Generating Extension Screenshots**');
+        response.appendResponseLine('='.repeat(40));
+        response.appendResponseLine('');
+        try {
+            // Set viewport to Chrome Web Store recommended size
+            await page.setViewport({ width: 1280, height: 800 });
+            // Screenshot 1: Extension in action on a popular website
+            response.appendResponseLine('1️⃣ Taking screenshot of extension in action...');
+            // Navigate to a demo page
+            await page.goto('https://www.example.com', { waitUntil: 'networkidle0' });
+            // If extension has a popup, try to capture it
+            if (extensionId) {
+                // Open extension popup if possible
+                const extensionUrl = `chrome-extension://${extensionId}/popup.html`;
+                // Try to open popup in new tab for screenshot
+                const popupPage = await page.browser().newPage();
+                await popupPage.setViewport({ width: 1280, height: 800 });
+                try {
+                    await popupPage.goto(extensionUrl, { waitUntil: 'networkidle0' });
+                    // Take screenshot of popup
+                    const popupScreenshot = await popupPage.screenshot({
+                        type: 'png',
+                        fullPage: false,
+                    });
+                    const popupPath = path.join(screenshotsDir, 'screenshot-1-popup.png');
+                    fs.writeFileSync(popupPath, popupScreenshot);
+                    response.appendResponseLine(`✅ Popup screenshot saved: ${popupPath}`);
+                    await popupPage.close();
+                }
+                catch (error) {
+                    response.appendResponseLine(`⚠️ Could not capture popup: ${error}`);
+                }
+            }
+            // Screenshot 2: Extension toolbar icon
+            response.appendResponseLine('2️⃣ Taking screenshot with extension icon visible...');
+            // Navigate to chrome://extensions to show the extension
+            await page.goto('chrome://extensions/', { waitUntil: 'networkidle0' });
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            const extensionsScreenshot = await page.screenshot({
+                type: 'png',
+                fullPage: false,
+            });
+            const extensionsPath = path.join(screenshotsDir, 'screenshot-2-extensions.png');
+            fs.writeFileSync(extensionsPath, extensionsScreenshot);
+            response.appendResponseLine(`✅ Extensions page screenshot saved: ${extensionsPath}`);
+            // Screenshot 3: Options page (if exists)
+            response.appendResponseLine('3️⃣ Taking screenshot of options page...');
+            if (extensionId) {
+                const optionsUrl = `chrome-extension://${extensionId}/options.html`;
+                try {
+                    await page.goto(optionsUrl, { waitUntil: 'networkidle0' });
+                    const optionsScreenshot = await page.screenshot({
+                        type: 'png',
+                        fullPage: false,
+                    });
+                    const optionsPath = path.join(screenshotsDir, 'screenshot-3-options.png');
+                    fs.writeFileSync(optionsPath, optionsScreenshot);
+                    response.appendResponseLine(`✅ Options page screenshot saved: ${optionsPath}`);
+                }
+                catch (error) {
+                    response.appendResponseLine(`⚠️ No options page found`);
+                }
+            }
+            // Screenshot 4: Extension working on a real website
+            response.appendResponseLine('4️⃣ Taking screenshot on a real website...');
+            // Navigate to a website where the extension might be useful
+            await page.goto('https://www.google.com', { waitUntil: 'networkidle0' });
+            await new Promise(resolve => setTimeout(resolve, 2000));
+            const websiteScreenshot = await page.screenshot({
+                type: 'png',
+                fullPage: false,
+            });
+            const websitePath = path.join(screenshotsDir, 'screenshot-4-website.png');
+            fs.writeFileSync(websitePath, websiteScreenshot);
+            response.appendResponseLine(`✅ Website screenshot saved: ${websitePath}`);
+            // Generate promotional images (smaller versions)
+            response.appendResponseLine('');
+            response.appendResponseLine('5️⃣ Generating promotional images...');
+            // Small promo tile: 440x280
+            await page.setViewport({ width: 440, height: 280 });
+            await page.goto('chrome://extensions/', { waitUntil: 'networkidle0' });
+            const smallPromo = await page.screenshot({
+                type: 'png',
+                fullPage: false,
+            });
+            const smallPromoPath = path.join(screenshotsDir, 'promo-small-440x280.png');
+            fs.writeFileSync(smallPromoPath, smallPromo);
+            response.appendResponseLine(`✅ Small promo tile saved: ${smallPromoPath}`);
+            // Large promo tile: 920x680
+            await page.setViewport({ width: 920, height: 680 });
+            const largePromo = await page.screenshot({
+                type: 'png',
+                fullPage: false,
+            });
+            const largePromoPath = path.join(screenshotsDir, 'promo-large-920x680.png');
+            fs.writeFileSync(largePromoPath, largePromo);
+            response.appendResponseLine(`✅ Large promo tile saved: ${largePromoPath}`);
+            // Marquee promo: 1400x560
+            await page.setViewport({ width: 1400, height: 560 });
+            const marqueePromo = await page.screenshot({
+                type: 'png',
+                fullPage: false,
+            });
+            const marqueePromoPath = path.join(screenshotsDir, 'promo-marquee-1400x560.png');
+            fs.writeFileSync(marqueePromoPath, marqueePromo);
+            response.appendResponseLine(`✅ Marquee promo saved: ${marqueePromoPath}`);
+            response.appendResponseLine('');
+            response.appendResponseLine('='.repeat(40));
+            response.appendResponseLine('✅ **Screenshots Generated Successfully!**');
+            response.appendResponseLine('');
+            response.appendResponseLine(`📁 Screenshots saved in: ${screenshotsDir}`);
+            response.appendResponseLine('');
+            response.appendResponseLine('**Chrome Web Store Requirements:**');
+            response.appendResponseLine('• Screenshots: 1280x800 or 640x400 (PNG or JPG)');
+            response.appendResponseLine('• Small promo tile: 440x280');
+            response.appendResponseLine('• Large promo tile: 920x680');
+            response.appendResponseLine('• Marquee promo: 1400x560');
+            response.appendResponseLine('');
+            response.appendResponseLine('💡 **Tip:** Edit these screenshots to highlight your extension features!');
+        }
+        catch (error) {
+            response.appendResponseLine(`❌ Error generating screenshots: ${error}`);
+        }
+        finally {
+            // Reset viewport
+            await page.setViewport({ width: 1280, height: 800 });
+        }
+    },
+});