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

package/build/src/tools/lighthouse.js

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import path from 'node:path';
+import { lighthouseRunner, generateReport, zod, } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { startTrace } from './performance.js';
+import { definePageTool } from './ToolDefinition.js';
+// Kept in sync with `constants.userAgents` in Lighthouse's
+// core/config/constants.js, which `lighthouse:default` and the `desktop`
+// preset use. The bundle in src/third_party only re-exports the runner
+// entrypoints, so these cannot be imported and are mirrored here alongside the
+// screen emulation metrics below. Refresh via scripts/update-lighthouse.ts.
+const MOBILE_USER_AGENT = 'Mozilla/5.0 (Linux; Android 11; moto g power (2022)) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Mobile Safari/537.36';
+const DESKTOP_USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36';
+export const lighthouseAudit = definePageTool((args) => ({
+    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(args).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,
+    verifyFilesSchema: {
+        outputDirPath: 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;
+        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,
+            };
+            flags.emulatedUserAgent = DESKTOP_USER_AGENT;
+        }
+        else {
+            flags.formFactor = 'mobile';
+            flags.screenEmulation = {
+                mobile: true,
+                width: 412,
+                height: 823,
+                deviceScaleFactor: 1.75,
+                disabled: false,
+            };
+            flags.emulatedUserAgent = MOBILE_USER_AGENT;
+        }
+        let result;
+        try {
+            if (mode === 'navigation') {
+                result = await lighthouseRunner.navigation(page.pptrPage, page.pptrPage.url(), {
+                    flags,
+                });
+            }
+            else {
+                result = await lighthouseRunner.snapshot(page.pptrPage, {
+                    flags,
+                });
+            }
+            if (!result) {
+                throw new Error('Lighthouse audit failed.');
+            }
+        }
+        finally {
+            await page.restoreEmulation();
+        }
+        const lhr = result.lhr;
+        const reportPaths = [];
+        const encoder = new TextEncoder();
+        const savePromises = formats.map(async (format) => {
+            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}`);
+                return filename;
+            }
+            const { filepath } = await context.saveTemporaryFile(data, `report.${format}`);
+            return filepath;
+        });
+        const results = await Promise.allSettled(savePromises);
+        for (const res of results) {
+            if (res.status === 'rejected') {
+                throw res.reason;
+            }
+            reportPaths.push(res.value);
+        }
+        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,
+                // `mainDocumentUrl` is only set for navigations, whereas
+                // `finalDisplayedUrl` is populated for every gather mode.
+                url: lhr.finalDisplayedUrl,
+                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,424 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { byteSizeRangeSchema } from '../utils/bytes.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool, defineTool } from './ToolDefinition.js';
+const HEAP_SNAPSHOT_FILTERS = [
+    'objectsRetainedByDetachedDomNodes',
+    'objectsRetainedByConsole',
+    'objectsRetainedByEventHandlers',
+    'objectsRetainedByContexts',
+    'sharedNativeContext',
+    'noNativeContext',
+    'attributedToSpecificNativeContext',
+];
+export const takeHeapSnapshot = definePageTool(() => ({
+    name: 'take_heapsnapshot',
+    description: `Capture a heap snapshot of the target 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,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    handler: async (request, response, context) => {
+        const page = request.page;
+        const snapshotPath = await context.ensureExtension(request.params.filePath, '.heapsnapshot');
+        await page.pptrPage.captureHeapSnapshot({
+            path: snapshotPath,
+        });
+        response.appendResponseLine(`Heap snapshot saved to ${snapshotPath}`);
+    },
+}));
+export const getHeapSnapshotSummary = defineTool(() => ({
+    name: 'get_heapsnapshot_summary',
+    description: 'Loads a memory heapsnapshot and returns snapshot summary stats, including native contexts and their sizes, and retained by context summary.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    handler: async (request, response, context) => {
+        const stats = await context.getHeapSnapshotStats(request.params.filePath);
+        const staticData = await context.getHeapSnapshotStaticData(request.params.filePath);
+        const nativeContextSizes = await context.getHeapSnapshotNativeContextSizes(request.params.filePath);
+        const retainedByContextSummary = await context.getHeapSnapshotRetainedByContextSummary(request.params.filePath);
+        response.setHeapSnapshotStats(stats, staticData, nativeContextSizes, retainedByContextSummary);
+    },
+}));
+export const getHeapSnapshotDetails = defineTool(() => ({
+    name: 'get_heapsnapshot_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: ['memoryDebugging'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        filterName: zod
+            .enum(HEAP_SNAPSHOT_FILTERS)
+            .optional()
+            .describe('An optional filter to apply to the aggregates.'),
+        objectId: zod
+            .number()
+            .optional()
+            .describe('The object ID (nodeId) of the specific native context to filter by when filterName is attributedToSpecificNativeContext.'),
+        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,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    handler: async (request, response, context) => {
+        const aggregates = await context.getHeapSnapshotAggregates(request.params.filePath, request.params.filterName, request.params.objectId);
+        response.setHeapSnapshotAggregates(aggregates, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+}));
+export const getHeapSnapshotClassNodes = defineTool(() => ({
+    name: 'get_heapsnapshot_class_nodes',
+    description: 'Loads a memory heapsnapshot and returns instances of a specific class with their IDs.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        id: zod.number().describe('The ID for the class, obtained from details.'),
+        filterName: zod
+            .enum(HEAP_SNAPSHOT_FILTERS)
+            .optional()
+            .describe('An optional filter to apply to the nodes.'),
+        objectId: zod
+            .number()
+            .optional()
+            .describe('The object ID (nodeId) of the specific native context to filter by when filterName is attributedToSpecificNativeContext.'),
+        pageIdx: zod.number().optional().describe('The page index for pagination.'),
+        pageSize: zod.number().optional().describe('The page size for pagination.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    handler: async (request, response, context) => {
+        const nodes = await context.getHeapSnapshotNodesById(request.params.filePath, request.params.id, request.params.filterName, request.params.objectId);
+        response.setHeapSnapshotNodes(nodes, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+}));
+export const getHeapSnapshotRetainers = defineTool(() => ({
+    name: 'get_heapsnapshot_retainers',
+    description: 'Loads a memory heapsnapshot and returns retainers for a specific node ID.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        nodeId: zod.number().describe('The node ID to get retainers for.'),
+        pageIdx: zod.number().optional().describe('The page index for pagination.'),
+        pageSize: zod.number().optional().describe('The page size for pagination.'),
+    },
+    handler: async (request, response, context) => {
+        const retainers = await context.getHeapSnapshotRetainers(request.params.filePath, request.params.nodeId);
+        response.setHeapSnapshotNodes(retainers, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+}));
+export const closeHeapSnapshot = defineTool(() => ({
+    name: 'close_heapsnapshot',
+    description: 'Closes a previously loaded memory heapsnapshot, freeing its memory.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: false,
+        conditions: ['memoryDebugging'],
+    },
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    schema: {
+        filePath: zod
+            .string()
+            .describe('A path to the .heapsnapshot file to close.'),
+    },
+    blockedByDialog: false,
+    handler: async (request, response, context) => {
+        const closed = await context.closeHeapSnapshot(request.params.filePath);
+        if (!closed) {
+            throw new Error(`Failed to close heap snapshot: ${request.params.filePath} was not loaded.`);
+        }
+        response.appendResponseLine(`Closed heap snapshot: ${request.params.filePath}`);
+    },
+}));
+export const getHeapSnapshotRetainingPaths = defineTool(() => ({
+    name: 'get_heapsnapshot_retaining_paths',
+    description: 'Loads a memory heapsnapshot and returns retaining paths for a specific node ID. This helps to understand why a node is not being garbage collected.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    blockedByDialog: false,
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        nodeId: zod.number().describe('The node ID to get retaining paths for.'),
+        maxDepth: zod
+            .number()
+            .optional()
+            .describe('The maximum depth to search for retaining paths.'),
+        maxNodes: zod
+            .number()
+            .optional()
+            .describe('The maximum number of nodes to return.'),
+        maxSiblings: zod
+            .number()
+            .optional()
+            .describe('The maximum number of siblings to return.'),
+    },
+    handler: async (request, response, context) => {
+        const retainingPaths = await context.getHeapSnapshotRetainingPaths(request.params.filePath, request.params.nodeId, request.params.maxDepth, request.params.maxNodes, request.params.maxSiblings);
+        response.setHeapSnapshotRetainingPaths(retainingPaths);
+    },
+}));
+export const getHeapSnapshotEdges = defineTool(() => ({
+    name: 'get_heapsnapshot_edges',
+    description: 'Loads a memory heapsnapshot and returns outgoing edges (references) for a specific node ID.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        nodeId: zod.number().describe('The node ID to get outgoing edges for.'),
+        sortBy: zod
+            .enum(['retainedSize', 'selfSize', 'name'])
+            .optional()
+            .describe('Sort order for edges. Default is retainedSize.'),
+        retainedSize: byteSizeRangeSchema('Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-") for target nodes. A single value is treated as a minimum. Currently, only the lower bound is applied.').optional(),
+        excludePrimitives: zod
+            .boolean()
+            .optional()
+            .describe('Whether to exclude primitive target nodes. Default is true.'),
+        pageIdx: zod.number().optional().describe('The page index for pagination.'),
+        pageSize: zod.number().optional().describe('The page size for pagination.'),
+    },
+    handler: async (request, response, context) => {
+        const edges = await context.getHeapSnapshotEdges(request.params.filePath, request.params.nodeId, {
+            sortBy: request.params.sortBy ?? 'retainedSize',
+            // DevTools currently only supports a lower retained-size bound here.
+            minRetainedSize: request.params.retainedSize?.min,
+            excludePrimitives: request.params.excludePrimitives ?? true,
+        });
+        response.setHeapSnapshotNodes(edges, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+}));
+export const getHeapSnapshotDominators = defineTool(() => ({
+    name: 'get_heapsnapshot_dominators',
+    description: 'Loads a memory heapsnapshot and returns the dominator chain for a specific node ID. This helps to identify which objects are keeping the target node alive.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        nodeId: zod
+            .number()
+            .describe('The node ID to get the dominator chain for.'),
+    },
+    handler: async (request, response, context) => {
+        const dominators = await context.getHeapSnapshotDominators(request.params.filePath, request.params.nodeId);
+        response.setHeapSnapshotDominators(dominators);
+    },
+}));
+export const compareHeapSnapshots = defineTool(() => ({
+    name: 'compare_heapsnapshots',
+    description: 'Loads two memory heapsnapshots and returns the comparison. If classIndex is provided, returns detailed diff for that class, otherwise returns summary diff.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    verifyFilesSchema: {
+        baseFilePath: true,
+        currentFilePath: true,
+    },
+    schema: {
+        baseFilePath: zod
+            .string()
+            .describe('A path to the base .heapsnapshot file (earlier snapshot).'),
+        currentFilePath: zod
+            .string()
+            .describe('A path to the current .heapsnapshot file (later snapshot).'),
+        classIndex: zod
+            .number()
+            .optional()
+            .describe('Optional 0-based index of the class in the summary list to filter results, showing individual objects.'),
+    },
+    blockedByDialog: false,
+    handler: async (request, response, context) => {
+        if (request.params.classIndex !== undefined) {
+            const classDiffResult = await context.getHeapSnapshotDetailedClassDiff(request.params.baseFilePath, request.params.currentFilePath, request.params.classIndex);
+            response.setHeapSnapshotDetailedClassDiff(classDiffResult);
+        }
+        else {
+            const diff = await context.getHeapSnapshotClassDiffs(request.params.baseFilePath, request.params.currentFilePath);
+            response.setHeapSnapshotClassDiffs(diff);
+        }
+    },
+}));
+export const getHeapSnapshotDuplicateStrings = defineTool(() => ({
+    name: 'get_heapsnapshot_duplicate_strings',
+    description: 'Loads a memory heapsnapshot and returns duplicate strings grouped by their value.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        pageIdx: zod.number().optional().describe('The page index for pagination.'),
+        pageSize: zod.number().optional().describe('The page size for pagination.'),
+    },
+    handler: async (request, response, context) => {
+        const duplicateStrings = await context.getHeapSnapshotDuplicateStrings(request.params.filePath);
+        response.setHeapSnapshotDuplicateStrings(duplicateStrings, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+}));
+export const getHeapSnapshotObjectDetails = defineTool(() => ({
+    name: 'get_heapsnapshot_object_details',
+    description: 'Loads a memory heapsnapshot and returns detailed information about a specific object by its node ID, including size, type, distance, and DOM detachedness.',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        filePath: true,
+    },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        nodeId: zod.number().describe('The node ID to get object details for.'),
+    },
+    handler: async (request, response, context) => {
+        const objectInfo = await context.getHeapSnapshotObjectDetails(request.params.filePath, request.params.nodeId);
+        response.setHeapSnapshotObjectDetails(objectInfo);
+    },
+}));
+export const queryHeapSnapshotObjects = defineTool(() => ({
+    name: 'query_heapsnapshot_objects',
+    description: 'Loads a memory heapsnapshot and queries objects matching specific filters (className, propertyName, nodeType, retainedSize, selfSize, isDetached, sortBy).',
+    annotations: {
+        category: ToolCategory.MEMORY,
+        readOnlyHint: true,
+        conditions: ['memoryDebugging'],
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: { filePath: true },
+    schema: {
+        filePath: zod.string().describe('A path to a .heapsnapshot file to read.'),
+        className: zod
+            .string()
+            .optional()
+            .describe('Optional regex or text matching object class name.'),
+        propertyName: zod
+            .string()
+            .optional()
+            .describe('Optional property name filter for outgoing reference edges.'),
+        nodeType: zod
+            .string()
+            .optional()
+            .describe('Optional V8 node type filter (e.g. object, closure, string, array, code).'),
+        retainedSize: byteSizeRangeSchema('Inclusive retained size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.').optional(),
+        selfSize: byteSizeRangeSchema('Inclusive self size range (e.g. "1MB-2MB", "-1MB", or "1MB-"). A single value is treated as a minimum.').optional(),
+        isDetached: zod
+            .boolean()
+            .optional()
+            .describe('Whether to filter for detached DOM nodes.'),
+        sortBy: zod
+            .enum(['retainedSize', 'selfSize', 'id'])
+            .optional()
+            .describe('Sort order for results. Default is retainedSize.'),
+        pageIdx: zod.number().optional().describe('The page index for pagination.'),
+        pageSize: zod.number().optional().describe('The page size for pagination.'),
+    },
+    handler: async (request, response, context) => {
+        const range = await context.queryHeapSnapshotObjects(request.params.filePath, {
+            className: request.params.className,
+            propertyName: request.params.propertyName,
+            nodeType: request.params.nodeType,
+            minRetainedSize: request.params.retainedSize?.min,
+            maxRetainedSize: request.params.retainedSize?.max,
+            minSelfSize: request.params.selfSize?.min,
+            maxSelfSize: request.params.selfSize?.max,
+            isDetached: request.params.isDetached,
+            sortBy: request.params.sortBy,
+        });
+        response.setHeapSnapshotNodes(range, {
+            pageIdx: request.params.pageIdx,
+            pageSize: request.params.pageSize,
+        });
+    },
+}));
+//# sourceMappingURL=memory.js.map