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

package/build/src/tools/ToolDefinition.js

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+export function defineTool(definition) {
+    return definition;
+}
+export function definePageTool(definition) {
+    return (args) => {
+        const tool = definition(args);
+        return {
+            ...tool,
+            schema: {
+                ...(args.pageIdRouting && !args.slim ? pageIdSchema : {}),
+                ...tool.schema,
+            },
+            pageScoped: true,
+        };
+    };
+}
+export const CLOSE_PAGE_ERROR = 'The last open page cannot be closed. It is fine to keep it open.';
+export const pageIdSchema = {
+    pageId: zod.number().describe('Targets a specific page by ID.'),
+};
+export const timeoutSchema = {
+    timeout: zod
+        .number()
+        .int()
+        .transform(value => {
+        return value <= 0 ? undefined : value;
+    })
+        .optional()
+        .describe(`Maximum wait time in milliseconds. If set to 0, the default timeout will be used.`),
+};
+export function viewportTransform(arg) {
+    if (!arg) {
+        return undefined;
+    }
+    const [dimensions, ...tags] = arg.split(',');
+    const isMobile = tags.includes('mobile');
+    const hasTouch = tags.includes('touch');
+    const isLandscape = tags.includes('landscape');
+    const [width, height, dpr] = dimensions.split('x').map(Number);
+    if (!Number.isFinite(width) || width <= 0) {
+        throw new Error(`Invalid viewport width "${width}". Expected format '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]' with a positive width.`);
+    }
+    if (!Number.isFinite(height) || height <= 0) {
+        throw new Error(`Invalid viewport height "${height}". Expected format '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]' with a positive height.`);
+    }
+    if (dpr !== undefined && (!Number.isFinite(dpr) || dpr <= 0)) {
+        throw new Error(`Invalid devicePixelRatio "${dpr}". Expected a positive number.`);
+    }
+    return {
+        width,
+        height,
+        deviceScaleFactor: dpr,
+        isMobile: isMobile,
+        isLandscape: isLandscape,
+        hasTouch: hasTouch,
+    };
+}
+export function geolocationTransform(arg) {
+    if (!arg) {
+        return undefined;
+    }
+    const [latitude, longitude] = arg.split(',').map(Number);
+    if (!Number.isFinite(latitude) || latitude < -90 || latitude > 90) {
+        throw new Error(`Invalid latitude "${latitude}". Latitude must be a number between -90 and 90.`);
+    }
+    if (!Number.isFinite(longitude) || longitude < -180 || longitude > 180) {
+        throw new Error(`Invalid longitude "${longitude}". Longitude must be a number between -180 and 180.`);
+    }
+    return {
+        latitude,
+        longitude,
+    };
+}
+//# sourceMappingURL=ToolDefinition.js.map

package/build/src/tools/categories.js

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export var ToolCategory;
+(function (ToolCategory) {
+    ToolCategory["INPUT"] = "input";
+    ToolCategory["NAVIGATION"] = "navigation";
+    ToolCategory["EMULATION"] = "emulation";
+    ToolCategory["PERFORMANCE"] = "performance";
+    ToolCategory["NETWORK"] = "network";
+    ToolCategory["DEBUGGING"] = "debugging";
+    ToolCategory["EXTENSIONS"] = "extensions";
+    ToolCategory["THIRD_PARTY"] = "experimentalThirdParty";
+    ToolCategory["MEMORY"] = "memory";
+    ToolCategory["WEBMCP"] = "experimentalWebmcp";
+    ToolCategory["PWA"] = "pwa";
+})(ToolCategory || (ToolCategory = {}));
+export const labels = {
+    [ToolCategory.INPUT]: 'Input automation',
+    [ToolCategory.NAVIGATION]: 'Navigation automation',
+    [ToolCategory.EMULATION]: 'Emulation',
+    [ToolCategory.PERFORMANCE]: 'Performance',
+    [ToolCategory.NETWORK]: 'Network',
+    [ToolCategory.DEBUGGING]: 'Debugging',
+    [ToolCategory.EXTENSIONS]: 'Extensions',
+    [ToolCategory.THIRD_PARTY]: 'Third-party',
+    [ToolCategory.MEMORY]: 'Memory',
+    [ToolCategory.WEBMCP]: 'WebMCP',
+    [ToolCategory.PWA]: 'Progressive Web Apps',
+};
+//# sourceMappingURL=categories.js.map

package/build/src/tools/comments.js

@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } from './ToolDefinition.js';
+export const openDevtools = definePageTool(() => ({
+    name: 'open_devtools',
+    description: 'Open a DevTools window for the selected page.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+        conditions: ['devtoolsComments'],
+    },
+    schema: {},
+    blockedByDialog: false,
+    verifyFilesSchema: [],
+    handler: async (request, response) => {
+        const page = request.page;
+        try {
+            await page.openDevTools();
+            response.appendResponseLine('DevTools window opened successfully.');
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            response.appendResponseLine(`Failed to open DevTools: ${message}`);
+        }
+        response.setIncludePages(true);
+    },
+}));
+export const getDevtoolsComments = definePageTool(() => ({
+    name: 'get_devtools_comments',
+    description: 'Retrieve user comments from the DevTools window for the page.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+        conditions: ['devtoolsComments'],
+    },
+    schema: {},
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
+        const page = request.page;
+        const devtoolsPage = await page.getDevToolsPage();
+        if (!devtoolsPage) {
+            response.appendResponseLine('DevTools window is not open for this page. Call open_devtools first to open DevTools.');
+            return;
+        }
+        const bridge = await page.ensureDevToolsCommentBridge(devtoolsPage);
+        const threads = await bridge.getComments(devtoolsPage);
+        response.setDevToolsComments(threads);
+    },
+}));
+export const resolveDevtoolsComment = definePageTool(() => ({
+    name: 'resolve_devtools_comment',
+    description: 'Append an agent reply to a DevTools comment thread and mark it as resolved.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: false,
+        conditions: ['devtoolsComments'],
+    },
+    schema: {
+        threadId: zod
+            .string()
+            .describe('The unique identifier of the comment thread to resolve (e.g. "comment-1").'),
+        replyText: zod
+            .string()
+            .optional()
+            .describe('Optional reply explanation from the AI agent to append to the resolved comment thread.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
+        const page = request.page;
+        const devtoolsPage = await page.getDevToolsPage();
+        if (!devtoolsPage) {
+            response.appendResponseLine('DevTools window is not open for this page. Call open_devtools first to open DevTools.');
+            return;
+        }
+        const { threadId, replyText } = request.params;
+        const success = await devtoolsPage.evaluate((id, reply) => {
+            return (window.universe?.cd4aBridge?.resolveCommentThread(id, reply) ?? false);
+        }, threadId, replyText);
+        if (success) {
+            response.appendResponseLine(`Comment thread ${threadId} resolved successfully.`);
+            if (replyText) {
+                response.appendResponseLine(`Agent reply added: "${replyText}"`);
+            }
+        }
+        else {
+            response.appendResponseLine(`Failed to resolve comment thread "${threadId}". Thread not found.`);
+        }
+    },
+}));
+export const revealInDevtools = definePageTool(() => ({
+    name: 'reveal_in_devtools',
+    description: 'Navigate DevTools to a specified panel and highlight a target DOM node or network request. The parameters uid and reqid are mutually exclusive.',
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+        conditions: ['devtoolsComments'],
+    },
+    schema: {
+        panelName: zod
+            .string()
+            .optional()
+            .describe('The target DevTools panel (e.g. "elements", "network", "sources", "console").'),
+        uid: zod
+            .string()
+            .optional()
+            .describe('Optional snapshot element UID to reveal in the Elements panel.'),
+        reqid: zod
+            .number()
+            .optional()
+            .describe('Optional network request ID to reveal in the Network panel.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
+        const page = request.page;
+        const devtoolsPage = await page.getDevToolsPage();
+        if (!devtoolsPage) {
+            response.appendResponseLine('DevTools window is not open for this page. Call open_devtools first to open DevTools.');
+            return;
+        }
+        const { panelName, uid, reqid } = request.params;
+        let backendNodeId;
+        let targetId;
+        let networkRequestId;
+        if (uid) {
+            const resolved = await page.resolveUidToBackendNodeId(uid);
+            if (resolved) {
+                backendNodeId = resolved.backendNodeId;
+                targetId = resolved.targetId;
+            }
+            else {
+                response.appendResponseLine(`Warning: Could not resolve snapshot UID "${uid}" to a backend DOM node ID.`);
+            }
+        }
+        if (reqid !== undefined) {
+            const resolvedCdpRequestId = page.resolveReqidToCdpRequestId(reqid);
+            if (resolvedCdpRequestId !== undefined) {
+                networkRequestId = resolvedCdpRequestId;
+            }
+            else {
+                response.appendResponseLine(`Warning: Could not resolve network request ID ${reqid} to a CDP request ID.`);
+            }
+        }
+        await devtoolsPage.evaluate(async (panel, target) => {
+            await window.universe?.cd4aBridge?.reveal(panel, target);
+        }, panelName, { backendNodeId, targetId, networkRequestId });
+        let targetDesc = '';
+        if (uid && backendNodeId !== undefined) {
+            targetDesc = ` (revealing element ${uid} [backend node ${backendNodeId}])`;
+        }
+        else if (reqid !== undefined && networkRequestId) {
+            targetDesc = ` (revealing network request ${reqid} [${networkRequestId}])`;
+        }
+        if (panelName) {
+            response.appendResponseLine(`Navigated to ${panelName} panel${targetDesc} in DevTools.`);
+        }
+        else {
+            response.appendResponseLine(`Revealed target${targetDesc} in DevTools.`);
+        }
+    },
+}));
+//# sourceMappingURL=comments.js.map

package/build/src/tools/console.js

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } from './ToolDefinition.js';
+const FILTERABLE_MESSAGE_TYPES = [
+    'log',
+    'debug',
+    'info',
+    'error',
+    'warn',
+    'dir',
+    'dirxml',
+    'table',
+    'trace',
+    'clear',
+    'startGroup',
+    'startGroupCollapsed',
+    'endGroup',
+    'assert',
+    'profile',
+    'profileEnd',
+    'count',
+    'timeEnd',
+    'verbose',
+    'issue',
+];
+const LIST_CONSOLE_MESSAGES_TOOL_NAME = 'list_console_messages';
+export const listConsoleMessages = definePageTool((cliArgs) => {
+    return {
+        name: LIST_CONSOLE_MESSAGES_TOOL_NAME,
+        description: `List all console messages for the target page since the last navigation.${cliArgs?.categoryExtensions ? ' This includes console messages originating from extensions content scripts.' : ''}`,
+        annotations: {
+            category: ToolCategory.DEBUGGING,
+            readOnlyHint: true,
+        },
+        schema: {
+            pageSize: zod
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Maximum number of messages to return. When omitted, returns all messages.'),
+            pageIdx: zod
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Page number to return (0-based). When omitted, returns the first page.'),
+            types: zod
+                .array(zod.enum(FILTERABLE_MESSAGE_TYPES))
+                .optional()
+                .describe('Filter messages to only return messages of the specified resource types. When omitted or empty, returns all messages.'),
+            includePreservedMessages: zod
+                .boolean()
+                .default(false)
+                .optional()
+                .describe('Set to true to return the preserved messages over the last 3 navigations.'),
+            includeStackTraces: zod
+                .boolean()
+                .default(false)
+                .optional()
+                .describe('Set to true to include the stack trace for each message when available. Increases the response size.'),
+            serviceWorkerId: zod
+                .string()
+                .optional()
+                .describe('Filter messages to only return messages of the specified service worker.'),
+        },
+        blockedByDialog: false,
+        verifyFilesSchema: {},
+        handler: async (request, response) => {
+            response.setIncludeConsoleData(true, {
+                pageSize: request.params.pageSize,
+                pageIdx: request.params.pageIdx,
+                types: request.params.types,
+                includePreservedMessages: request.params.includePreservedMessages,
+                includeStackTraces: request.params.includeStackTraces,
+                serviceWorkerId: request.params.serviceWorkerId,
+            });
+        },
+    };
+});
+export const getConsoleMessage = definePageTool(() => ({
+    name: 'get_console_message',
+    description: `Gets a console message by its ID. You can get all messages by calling ${LIST_CONSOLE_MESSAGES_TOOL_NAME}.`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {
+        msgid: zod
+            .number()
+            .describe('The msgid of a console message on the page from the listed console messages'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
+        response.attachConsoleMessage(request.params.msgid);
+    },
+}));
+//# sourceMappingURL=console.js.map

package/build/src/tools/css.js

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { zod } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool } from './ToolDefinition.js';
+export const getCssStyles = definePageTool(() => ({
+    name: 'get_css_styles',
+    description: `Retrieve matched CSS rules, inline styles, inherited styles, and cascade information for an element identified by its UID.
+Use this tool to debug why specific CSS properties are applied, overridden, or conflicting. Results are paginated and return 10 rules per page by default; use pageIdx to page through the remaining rules. Requires a UID from take_snapshot.`,
+    annotations: {
+        category: ToolCategory.DEBUGGING,
+        readOnlyHint: true,
+    },
+    schema: {
+        uid: zod
+            .string()
+            .describe('The uid of the element on the page from the page content snapshot to inspect CSS styles for'),
+        pageSize: zod
+            .number()
+            .int()
+            .positive()
+            .default(10)
+            .describe('Maximum number of CSS rules to return per page. Defaults to 10.'),
+        pageIdx: zod
+            .number()
+            .int()
+            .min(0)
+            .default(0)
+            .describe('Page number to return (0-based). Defaults to 0 (the first page).'),
+    },
+    blockedByDialog: true,
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
+        const matchedStyles = await request.page.getMatchedStylesForUid(request.params.uid);
+        response.setIncludeCssStyles(matchedStyles, {
+            uid: request.params.uid,
+            pageSize: request.params.pageSize,
+            pageIdx: request.params.pageIdx,
+        });
+    },
+}));
+//# sourceMappingURL=css.js.map

package/build/src/tools/emulation.js

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ */
+import { zod, PredefinedNetworkConditions } from '../third_party/index.js';
+import { ToolCategory } from './categories.js';
+import { definePageTool, geolocationTransform, viewportTransform, } from './ToolDefinition.js';
+function headerStringTransform(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === '') {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed !== 'object' ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            throw new Error('Headers must be a JSON object');
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON for headers: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+const throttlingOptions = [
+    'Offline',
+    ...Object.keys(PredefinedNetworkConditions),
+];
+export const emulate = definePageTool(() => ({
+    name: 'emulate',
+    description: `Emulates various features on the target page.`,
+    annotations: {
+        category: ToolCategory.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        networkConditions: zod
+            .enum(throttlingOptions)
+            .optional()
+            .describe(`Throttle network. Omit to disable throttling.`),
+        cpuThrottlingRate: zod
+            .number()
+            .min(1)
+            .max(20)
+            .optional()
+            .describe('Represents the CPU slowdown factor. Omit or set the rate to 1 to disable throttling'),
+        geolocation: zod
+            .string()
+            .transform(geolocationTransform)
+            .optional()
+            .describe('Geolocation (`<latitude>,<longitude>`) to emulate. Latitude between -90 and 90. Longitude between -180 and 180. Omit to clear the geolocation override.'),
+        userAgent: zod
+            .string()
+            .optional()
+            .describe('User agent to emulate. Set to empty string to clear the user agent override.'),
+        colorScheme: zod
+            .enum(['dark', 'light', 'auto'])
+            .optional()
+            .describe('Emulate the dark or the light mode. Set to "auto" to reset to the default.'),
+        viewport: zod
+            .string()
+            .transform(viewportTransform)
+            .optional()
+            .describe(`Emulate device viewports '<width>x<height>x<devicePixelRatio>[,mobile][,touch][,landscape]'. 'touch' and 'mobile' to emulate mobile devices. 'landscape' to emulate landscape mode.`),
+        extraHttpHeaders: zod
+            .string()
+            .transform(headerStringTransform)
+            .optional()
+            .describe('Extra HTTP headers as a JSON string object, e.g. {"X-Custom": "value", "Authorization": "Bearer token"}. Headers are included into every HTTP request originating from the page and persist across navigations until cleared. Pass an empty string to clear all extra headers.'),
+    },
+    blockedByDialog: true,
+    verifyFilesSchema: {},
+    handler: async (request, response) => {
+        const page = request.page;
+        await page.emulate(request.params);
+        response.appendResponseLine('Emulation configured successfully');
+    },
+}));
+//# sourceMappingURL=emulation.js.map

package/build/src/tools/extensions.js

@@ -0,0 +1,103 @@
+/**
+ * @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';
+export const installExtension = defineTool(() => ({
+    name: 'install_extension',
+    description: 'Installs a Chrome extension from the given path.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+    },
+    schema: {
+        path: zod
+            .string()
+            .describe('Absolute path to the unpacked extension folder.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {
+        path: { local: true },
+    },
+    handler: async (request, response, context) => {
+        const { path } = request.params;
+        const id = await context.installExtension(path);
+        response.appendResponseLine(`Extension installed. Id: ${id}`);
+    },
+}));
+export const uninstallExtension = defineTool(() => ({
+    name: 'uninstall_extension',
+    description: 'Uninstalls a Chrome extension by its ID.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+    },
+    schema: {
+        id: zod.string().describe('ID of the extension to uninstall.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { id } = request.params;
+        await context.uninstallExtension(id);
+        response.appendResponseLine(`Extension uninstalled. Id: ${id}`);
+    },
+}));
+export const listExtensions = defineTool(() => ({
+    name: 'list_extensions',
+    description: 'Lists all the Chrome extensions installed in the browser. This includes their name, ID, version, and enabled status.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: true,
+    },
+    schema: {},
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (_request, response) => {
+        response.setListExtensions();
+    },
+}));
+export const reloadExtension = defineTool(() => ({
+    name: 'reload_extension',
+    description: 'Reloads an unpacked Chrome extension by its ID.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+    },
+    schema: {
+        id: zod.string().describe('ID of the extension to reload.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { id } = request.params;
+        const extension = await context.getExtension(id);
+        if (!extension) {
+            throw new Error(`Extension with ID ${id} not found.`);
+        }
+        await context.installExtension(extension.path);
+        response.appendResponseLine('Extension reloaded.');
+    },
+}));
+export const triggerExtensionAction = defineTool(() => ({
+    name: 'trigger_extension_action',
+    description: 'Triggers the default action of an extension by its ID.',
+    annotations: {
+        category: ToolCategory.EXTENSIONS,
+        readOnlyHint: false,
+    },
+    schema: {
+        id: zod.string().describe('ID of the extension to trigger the action for.'),
+    },
+    blockedByDialog: false,
+    verifyFilesSchema: {},
+    handler: async (request, response, context) => {
+        const { id } = request.params;
+        await context.triggerExtensionAction(id);
+        response.appendResponseLine(`Extension action triggered for ID ${id}`);
+    },
+}));
+//# sourceMappingURL=extensions.js.map