@vibebrowser/chrome-devtools-mcp 0.26.0

package/build/src/tools/input.js

@@ -0,0 +1,461 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { logger } from '../logger.js';
+import { zod } from '../third_party/index.js';
+import { parseKey } from '../utils/keyboard.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } from './ToolDefinition.js';
+const dblClickSchema = zod
+    .boolean()
+    .optional()
+    .describe('Set to true for double clicks. Default is false.');
+const includeSnapshotSchema = zod
+    .boolean()
+    .optional()
+    .describe('Whether to include a snapshot in the response. Default is false.');
+const submitKeySchema = zod
+    .string()
+    .optional()
+    .describe('Optional key to press after typing. E.g., "Enter", "Tab", "Escape"');
+function handleActionError(error, uid) {
+    logger('failed to act using a locator', error);
+    throw new Error(`Failed to interact with the element with uid ${uid}. The element did not become interactive within the configured timeout.`, {
+        cause: error,
+    });
+}
+async function selectNativeSelectOption(handle) {
+    const selectHandle = await handle.evaluateHandle(node => {
+        if (!(node instanceof HTMLOptionElement)) {
+            return null;
+        }
+        const select = node.closest('select');
+        if (!select || select.multiple || select.disabled || node.disabled) {
+            return null;
+        }
+        const parentElement = node.parentElement;
+        if (parentElement instanceof HTMLOptGroupElement &&
+            parentElement.disabled) {
+            return null;
+        }
+        return select;
+    });
+    try {
+        const select = selectHandle.asElement();
+        if (!select) {
+            return false;
+        }
+        const valueHandle = await handle.getProperty('value');
+        try {
+            const value = await valueHandle.jsonValue();
+            if (typeof value !== 'string') {
+                return false;
+            }
+            await select.asLocator().fill(value);
+        }
+        finally {
+            void valueHandle.dispose();
+        }
+        return true;
+    }
+    finally {
+        void selectHandle.dispose();
+    }
+}
+export const click = definePageTool({
+    name: 'click',
+    description: `Clicks on the provided element`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: zod
+            .string()
+            .describe('The uid of an element on the page from the page content snapshot'),
+        dblClick: dblClickSchema,
+        includeSnapshot: includeSnapshotSchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response) => {
+        const uid = request.params.uid;
+        const handle = await request.page.getElementByUid(uid);
+        const aXNode = request.page.getAXNodeByUid(uid);
+        const shouldSelectNativeOption = !request.params.dblClick && aXNode?.role === 'option';
+        try {
+            const result = await request.page.waitForEventsAfterAction(async () => {
+                if (shouldSelectNativeOption &&
+                    (await selectNativeSelectOption(handle))) {
+                    return;
+                }
+                await handle.asLocator().click({
+                    count: request.params.dblClick ? 2 : 1,
+                });
+            });
+            response.appendResponseLine(request.params.dblClick
+                ? `Successfully double clicked on the element`
+                : `Successfully clicked on the element`);
+            response.attachWaitForResult(result);
+            if (request.params.includeSnapshot) {
+                response.includeSnapshot();
+            }
+        }
+        catch (error) {
+            handleActionError(error, uid);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const clickAt = definePageTool({
+    name: 'click_at',
+    description: `Clicks at the provided coordinates`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+        conditions: ['experimentalVision'],
+    },
+    schema: {
+        x: zod.number().describe('The x coordinate'),
+        y: zod.number().describe('The y coordinate'),
+        dblClick: dblClickSchema,
+        includeSnapshot: includeSnapshotSchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response) => {
+        const page = request.page;
+        const result = await page.waitForEventsAfterAction(async () => {
+            await page.pptrPage.mouse.click(request.params.x, request.params.y, {
+                clickCount: request.params.dblClick ? 2 : 1,
+            });
+        });
+        response.appendResponseLine(request.params.dblClick
+            ? `Successfully double clicked at the coordinates`
+            : `Successfully clicked at the coordinates`);
+        response.attachWaitForResult(result);
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
+    },
+});
+export const hover = definePageTool({
+    name: 'hover',
+    description: `Hover over the provided element`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: zod
+            .string()
+            .describe('The uid of an element on the page from the page content snapshot'),
+        includeSnapshot: includeSnapshotSchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response) => {
+        const uid = request.params.uid;
+        const handle = await request.page.getElementByUid(uid);
+        try {
+            const result = await request.page.waitForEventsAfterAction(async () => {
+                await handle.asLocator().hover();
+            });
+            response.appendResponseLine(`Successfully hovered over the element`);
+            response.attachWaitForResult(result);
+            if (request.params.includeSnapshot) {
+                response.includeSnapshot();
+            }
+        }
+        catch (error) {
+            handleActionError(error, uid);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+// The AXNode for an option doesn't contain its `value`. We set text content of the option as value.
+// If the form is a combobox, we need to find the correct option by its text value.
+// To do that, loop through the children while checking which child's text matches the requested value (requested value is actually the text content).
+// When the correct option is found, use the element handle to get the real value.
+async function selectOption(handle, aXNode, value) {
+    let optionFound = false;
+    for (const child of aXNode.children) {
+        if (child.role === 'option' && child.name === value && child.value) {
+            optionFound = true;
+            const childHandle = await child.elementHandle();
+            if (childHandle) {
+                try {
+                    const childValueHandle = await childHandle.getProperty('value');
+                    try {
+                        const childValue = await childValueHandle.jsonValue();
+                        if (childValue) {
+                            await handle.asLocator().fill(childValue.toString());
+                        }
+                    }
+                    finally {
+                        void childValueHandle.dispose();
+                    }
+                    break;
+                }
+                finally {
+                    void childHandle.dispose();
+                }
+            }
+        }
+    }
+    if (!optionFound) {
+        throw new Error(`Could not find option with text "${value}"`);
+    }
+}
+function hasOptionChildren(aXNode) {
+    return aXNode.children.some(child => child.role === 'option');
+}
+async function fillFormElement(uid, value, context, page) {
+    const handle = await page.getElementByUid(uid);
+    try {
+        const aXNode = context.getAXNodeByUid(uid);
+        // We assume that combobox needs to be handled as select if it has
+        // role='combobox' and option children.
+        if (aXNode && aXNode.role === 'combobox' && hasOptionChildren(aXNode)) {
+            await selectOption(handle, aXNode, value);
+        }
+        else {
+            const isToggle = await handle.evaluate(el => {
+                if (el instanceof HTMLInputElement) {
+                    return el.type === 'checkbox' || el.type === 'radio';
+                }
+                const role = el.getAttribute('role');
+                return role === 'checkbox' || role === 'radio' || role === 'switch';
+            });
+            if (isToggle) {
+                if (['true', 'false'].includes(value)) {
+                    await handle.asLocator().fill(value === 'true');
+                }
+                else {
+                    throw new Error(`Checkboxes, radio boxes and toggles require "true" or "false" value, but ${value} was used`);
+                }
+            }
+            else {
+                // Increase timeout for longer input values.
+                const timeoutPerChar = 10; // ms
+                const fillTimeout = page.pptrPage.getDefaultTimeout() + value.length * timeoutPerChar;
+                await handle.asLocator().setTimeout(fillTimeout).fill(value);
+            }
+        }
+    }
+    catch (error) {
+        handleActionError(error, uid);
+    }
+    finally {
+        void handle.dispose();
+    }
+}
+export const fill = definePageTool({
+    name: 'fill',
+    description: `Type text into an input, text area or select an option from a <select> element.`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: zod
+            .string()
+            .describe('The uid of an element on the page from the page content snapshot'),
+        value: zod
+            .string()
+            .describe('The value to fill in. "true" or "false" for checkboxes and toggles, "true" for radio buttons.'),
+        includeSnapshot: includeSnapshotSchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response, context) => {
+        const page = request.page;
+        const result = await page.waitForEventsAfterAction(async () => {
+            await fillFormElement(request.params.uid, request.params.value, context, page);
+        });
+        response.appendResponseLine(`Successfully filled out the element`);
+        response.attachWaitForResult(result);
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
+    },
+});
+export const typeText = definePageTool({
+    name: 'type_text',
+    description: `Type text using keyboard into a previously focused input`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        text: zod.string().describe('The text to type'),
+        submitKey: submitKeySchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response) => {
+        const page = request.page;
+        const result = await page.waitForEventsAfterAction(async () => {
+            await page.pptrPage.keyboard.type(request.params.text);
+            if (request.params.submitKey) {
+                await page.pptrPage.keyboard.press(request.params.submitKey);
+            }
+        });
+        response.appendResponseLine(`Typed text "${request.params.text}${request.params.submitKey ? ` + ${request.params.submitKey}` : ''}"`);
+        response.attachWaitForResult(result);
+    },
+});
+export const drag = definePageTool({
+    name: 'drag',
+    description: `Drag an element onto another element`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        from_uid: zod.string().describe('The uid of the element to drag'),
+        to_uid: zod.string().describe('The uid of the element to drop into'),
+        includeSnapshot: includeSnapshotSchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response) => {
+        const fromHandle = await request.page.getElementByUid(request.params.from_uid);
+        const toHandle = await request.page.getElementByUid(request.params.to_uid);
+        try {
+            const result = await request.page.waitForEventsAfterAction(async () => {
+                await fromHandle.drag(toHandle);
+                await new Promise(resolve => setTimeout(resolve, 50));
+                await toHandle.drop(fromHandle);
+            });
+            response.appendResponseLine(`Successfully dragged an element`);
+            response.attachWaitForResult(result);
+            if (request.params.includeSnapshot) {
+                response.includeSnapshot();
+            }
+        }
+        finally {
+            void fromHandle.dispose();
+            void toHandle.dispose();
+        }
+    },
+});
+export const fillForm = definePageTool({
+    name: 'fill_form',
+    description: `Fill out multiple form elements (inputs, selects, checkboxes, radios) at once. ALWAYS prefer this tool over multiple individual 'fill' or 'click' calls when interacting with forms. It is significantly faster, more reliable, and reduces turn count. Example: Fill username, password, and check "Remember Me" in one call.`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        elements: zod
+            .array(
+        // eslint-disable-next-line @local/enforce-zod-schema
+        zod.object({
+            uid: zod.string().describe('The uid of the element to fill out'),
+            value: zod
+                .string()
+                .describe('Value for the element. "true" or "false" for checkboxes and toggles, "true" for radio buttons.'),
+        }))
+            .describe('Elements from snapshot to fill out.'),
+        includeSnapshot: includeSnapshotSchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response, context) => {
+        const page = request.page;
+        let lastResult = {};
+        for (const element of request.params.elements) {
+            lastResult = await page.waitForEventsAfterAction(async () => {
+                await fillFormElement(element.uid, element.value, context, page);
+            });
+        }
+        response.appendResponseLine(`Successfully filled out the form`);
+        response.attachWaitForResult(lastResult);
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
+    },
+});
+export const uploadFile = definePageTool({
+    name: 'upload_file',
+    description: 'Upload a file through a provided element.',
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: zod
+            .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: zod.string().describe('The local path of the file to upload'),
+        includeSnapshot: includeSnapshotSchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response, context) => {
+        const { uid, filePath } = request.params;
+        context.validatePath(filePath);
+        const handle = (await request.page.getElementByUid(uid));
+        try {
+            try {
+                await handle.uploadFile(filePath);
+            }
+            catch {
+                // Some sites use a proxy element to trigger file upload instead of
+                // a type=file element. In this case, we want to default to
+                // Page.waitForFileChooser() and upload the file this way.
+                try {
+                    const [fileChooser] = await Promise.all([
+                        request.page.pptrPage.waitForFileChooser({ timeout: 3000 }),
+                        handle.asLocator().click(),
+                    ]);
+                    await fileChooser.accept([filePath]);
+                }
+                catch {
+                    throw new Error(`Failed to upload file. The element could not accept the file directly, and clicking it did not trigger a file chooser.`);
+                }
+            }
+            if (request.params.includeSnapshot) {
+                response.includeSnapshot();
+            }
+            response.appendResponseLine(`File uploaded from ${filePath}.`);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const pressKey = definePageTool({
+    name: 'press_key',
+    description: `Press a key or key combination. Use this when other input methods like fill() cannot be used (e.g., keyboard shortcuts, navigation keys, or special key combinations).`,
+    annotations: {
+        category: ToolCategory.INPUT,
+        readOnlyHint: false,
+    },
+    schema: {
+        key: zod
+            .string()
+            .describe('A key or a combination (e.g., "Enter", "Control+A", "Control++", "Control+Shift+R"). Modifiers: Control, Shift, Alt, Meta'),
+        includeSnapshot: includeSnapshotSchema,
+    },
+    blockedByDialog: true,
+    handler: async (request, response) => {
+        const page = request.page;
+        const tokens = parseKey(request.params.key);
+        const [key, ...modifiers] = tokens;
+        const result = await page.waitForEventsAfterAction(async () => {
+            for (const modifier of modifiers) {
+                await page.pptrPage.keyboard.down(modifier);
+            }
+            await page.pptrPage.keyboard.press(key);
+            for (const modifier of modifiers.toReversed()) {
+                await page.pptrPage.keyboard.up(modifier);
+            }
+        });
+        response.appendResponseLine(`Successfully pressed key: ${request.params.key}`);
+        response.attachWaitForResult(result);
+        if (request.params.includeSnapshot) {
+            response.includeSnapshot();
+        }
+    },
+});
+//# sourceMappingURL=input.js.map

package/build/src/tools/lighthouse.js

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import path from 'node:path';
+import { snapshot, navigation, generateReport, zod, } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { startTrace } from './performance.js';
+import { definePageTool } from './ToolDefinition.js';
+export const lighthouseAudit = definePageTool({
+    name: 'lighthouse_audit',
+    description: `Get Lighthouse score and reports for accessibility, SEO, best practices, and agentic browsing. This excludes performance. For performance audits, run ${startTrace.name}`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+    },
+    schema: {
+        mode: zod
+            .enum(['navigation', 'snapshot'])
+            .default('navigation')
+            .describe('"navigation" reloads & audits. "snapshot" analyzes current state.'),
+        device: zod
+            .enum(['desktop', 'mobile'])
+            .default('desktop')
+            .describe('Device to emulate.'),
+        outputDirPath: zod
+            .string()
+            .optional()
+            .describe('Directory for reports. If omitted, uses temporary files.'),
+    },
+    blockedByDialog: true,
+    handler: async (request, response, context) => {
+        const page = request.page;
+        const categories = [
+            'accessibility',
+            'seo',
+            'best-practices',
+            'agentic-browsing',
+        ];
+        const formats = ['json', 'html'];
+        const { mode = 'navigation', device = 'desktop', outputDirPath, } = request.params;
+        context.validatePath(outputDirPath);
+        const flags = {
+            onlyCategories: categories,
+            output: formats,
+            // Default 30 second timeout for page load.
+            maxWaitForLoad: 30_000,
+        };
+        if (device === 'desktop') {
+            flags.formFactor = 'desktop';
+            flags.screenEmulation = {
+                mobile: false,
+                width: 1350,
+                height: 940,
+                deviceScaleFactor: 1,
+                disabled: false,
+            };
+        }
+        else {
+            flags.formFactor = 'mobile';
+            flags.screenEmulation = {
+                mobile: true,
+                width: 412,
+                height: 823,
+                deviceScaleFactor: 1.75,
+                disabled: false,
+            };
+        }
+        let result;
+        try {
+            if (mode === 'navigation') {
+                result = await navigation(page.pptrPage, page.pptrPage.url(), {
+                    flags,
+                });
+            }
+            else {
+                result = await snapshot(page.pptrPage, {
+                    flags,
+                });
+            }
+            if (!result) {
+                throw new Error('Lighthouse audit failed.');
+            }
+        }
+        finally {
+            await context.restoreEmulation(page);
+        }
+        const lhr = result.lhr;
+        const reportPaths = [];
+        const encoder = new TextEncoder();
+        for (const format of formats) {
+            const report = generateReport(lhr, format);
+            const data = encoder.encode(report);
+            if (outputDirPath) {
+                const reportPath = path.join(outputDirPath, `report`);
+                const { filename } = await context.saveFile(data, reportPath, `.${format}`);
+                reportPaths.push(filename);
+            }
+            else {
+                const { filepath } = await context.saveTemporaryFile(data, `report.${format}`);
+                reportPaths.push(filepath);
+            }
+        }
+        const categoryScores = Object.values(lhr.categories).map(c => ({
+            id: c.id,
+            title: c.title,
+            score: c.score,
+        }));
+        const failedAudits = Object.values(lhr.audits).filter(a => a.score !== null && a.score < 1).length;
+        const passedAudits = Object.values(lhr.audits).filter(a => a.score === 1).length;
+        const output = {
+            summary: {
+                mode,
+                device,
+                url: lhr.mainDocumentUrl,
+                scores: categoryScores,
+                audits: {
+                    failed: failedAudits,
+                    passed: passedAudits,
+                },
+                timing: {
+                    total: lhr.timing.total,
+                },
+            },
+            reports: reportPaths,
+        };
+        response.attachLighthouseResult(output);
+    },
+});
+//# sourceMappingURL=lighthouse.js.map

package/build/src/tools/memory.js

@@ -0,0 +1,106 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ensureExtension } from '../utils/files.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool, defineTool } from './ToolDefinition.js';
+export const takeMemorySnapshot = definePageTool({
+    name: 'take_memory_snapshot',
+    description: `Capture a heap snapshot of the currently selected page. Use to analyze the memory distribution of JavaScript objects and debug memory leaks.`,
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: false,
+    },
+    schema: {
+        filePath: zod
+            .string()
+            .describe('A path to a .heapsnapshot file to save the heapsnapshot to.'),
+    },
+    blockedByDialog: true,
+    handler: async (request, response, context) => {
+        const page = request.page;
+        context.validatePath(request.params.filePath);
+        await page.pptrPage.captureHeapSnapshot({
+            path: ensureExtension(request.params.filePath, '.heapsnapshot'),
+        });
+        response.appendResponseLine(`Heap snapshot saved to ${request.params.filePath}`);
+    },
+});
+export const exploreMemorySnapshot = defineTool({
+    name: 'load_memory_snapshot',
+    description: 'Loads a memory heapsnapshot and returns snapshot summary stats.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['experimentalMemory'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+    },
+    blockedByDialog: false,
+    handler: async (request, response, context) => {
+        context.validatePath(request.params.filePath);
+        const stats = await context.getHeapSnapshotStats(request.params.filePath);
+        const staticData = await context.getHeapSnapshotStaticData(request.params.filePath);
+        response.setHeapSnapshotStats(stats, staticData);
+    },
+});
+export const getMemorySnapshotDetails = defineTool({
+    name: 'get_memory_snapshot_details',
+    description: 'Loads a memory heapsnapshot and returns all available information including statistics, static data, and aggregated node information. Supports pagination for aggregates.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['experimentalMemory'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        pageIdx: zod
+            .number()
+            .optional()
+            .describe('The page index for pagination of aggregates.'),
+        pageSize: zod
+            .number()
+            .optional()
+            .describe('The page size for pagination of aggregates.'),
+    },
+    blockedByDialog: false,
+    handler: async (request, response, context) => {
+        context.validatePath(request.params.filePath);
+        const aggregates = await context.getHeapSnapshotAggregates(request.params.filePath);
+        response.setHeapSnapshotAggregates(aggregates, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+});
+export const getNodesByClass = defineTool({
+    name: 'get_nodes_by_class',
+    description: 'Loads a memory heapsnapshot and returns instances of a specific class with their stable IDs.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['experimentalMemory'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        uid: zod
+            .number()
+            .describe('The unique UID for the class, obtained from aggregates listing.'),
+        pageIdx: zod.number().optional().describe('The page index for pagination.'),
+        pageSize: zod.number().optional().describe('The page size for pagination.'),
+    },
+    blockedByDialog: false,
+    handler: async (request, response, context) => {
+        context.validatePath(request.params.filePath);
+        const nodes = await context.getHeapSnapshotNodesByUid(request.params.filePath, request.params.uid);
+        response.setHeapSnapshotNodes(nodes, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+});
+//# sourceMappingURL=memory.js.map