chrome-devtools-mcp-for-extension 0.5.0

package/build/src/tools/extensions.js

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { defineTool } from './ToolDefinition.js';
+// ========================================
+// Essential User-Facing Tools (3 tools only)
+// ========================================
+export const listExtensions = defineTool({
+    name: 'list_extensions',
+    description: `List all installed Chrome extensions with their status, version, and ability to reload or debug them.`,
+    annotations: {
+        category: ToolCategories.EXTENSION_DEVELOPMENT,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response, context) => {
+        const page = context.getSelectedPage();
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto('chrome://extensions/', { waitUntil: 'networkidle0' });
+            const extensions = await page.evaluate(() => {
+                const extensionCards = document.querySelectorAll('extensions-item');
+                const results = [];
+                Array.from(extensionCards).forEach(card => {
+                    const shadowRoot = card.shadowRoot;
+                    if (shadowRoot) {
+                        const name = shadowRoot.querySelector('#name')?.textContent?.trim() ||
+                            'Unknown';
+                        const description = shadowRoot.querySelector('#description')?.textContent?.trim() ||
+                            '';
+                        const version = shadowRoot.querySelector('#version')?.textContent?.trim() || '';
+                        const enabled = !shadowRoot
+                            .querySelector('#enable-toggle')
+                            ?.hasAttribute('disabled');
+                        const id = card.getAttribute('id') || 'unknown';
+                        const errorsBadge = shadowRoot.querySelector('#errors-button .badge');
+                        const hasErrors = errorsBadge ? parseInt(errorsBadge.textContent?.trim() || '0') > 0 : false;
+                        results.push({
+                            id,
+                            name,
+                            enabled,
+                            version,
+                            description,
+                            hasErrors,
+                        });
+                    }
+                });
+                return results;
+            });
+            response.appendResponseLine('Installed Chrome Extensions:');
+            response.appendResponseLine('');
+            if (extensions.length === 0) {
+                response.appendResponseLine('No extensions found.');
+            }
+            else {
+                extensions.forEach((ext, index) => {
+                    response.appendResponseLine(`${index + 1}. **${ext.name}** v${ext.version}`);
+                    response.appendResponseLine(`   ID: ${ext.id}`);
+                    response.appendResponseLine(`   Status: ${ext.enabled ? '✅ Enabled' : '❌ Disabled'}${ext.hasErrors ? ' ⚠️ Has errors' : ''}`);
+                    if (ext.description) {
+                        response.appendResponseLine(`   ${ext.description}`);
+                    }
+                    response.appendResponseLine('');
+                });
+                response.appendResponseLine('💡 Use `reload_extension` to reload or `inspect_service_worker` to debug');
+            }
+        });
+    },
+});
+export const reloadExtension = defineTool({
+    name: 'reload_extension',
+    description: `Reload a Chrome extension to apply changes during development.`,
+    annotations: {
+        category: ToolCategories.EXTENSION_DEVELOPMENT,
+        readOnlyHint: false,
+    },
+    schema: {
+        extensionName: z
+            .string()
+            .describe('The name or partial name of the extension to reload'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        const { extensionName } = request.params;
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto('chrome://extensions/', { waitUntil: 'networkidle0' });
+            const reloadResult = await page.evaluate((searchName) => {
+                const extensionCards = document.querySelectorAll('extensions-item');
+                for (const card of Array.from(extensionCards)) {
+                    const shadowRoot = card.shadowRoot;
+                    if (shadowRoot) {
+                        const name = shadowRoot.querySelector('#name')?.textContent?.trim() || '';
+                        if (name.toLowerCase().includes(searchName.toLowerCase())) {
+                            const reloadButton = shadowRoot.querySelector('#reload-button');
+                            if (reloadButton && !reloadButton.hasAttribute('hidden')) {
+                                reloadButton.click();
+                                return { success: true, extensionName: name };
+                            }
+                            else {
+                                return {
+                                    success: false,
+                                    reason: 'Reload button not available (extension not in developer mode)',
+                                };
+                            }
+                        }
+                    }
+                }
+                return { success: false, reason: 'Extension not found' };
+            }, extensionName);
+            if (reloadResult.success) {
+                response.appendResponseLine(`✅ Reloaded: ${reloadResult.extensionName}`);
+            }
+            else {
+                response.appendResponseLine(`❌ Failed: ${reloadResult.reason}`);
+            }
+        });
+    },
+});
+export const inspectServiceWorker = defineTool({
+    name: 'inspect_service_worker',
+    description: `Open DevTools for an extension's service worker to debug background scripts.`,
+    annotations: {
+        category: ToolCategories.EXTENSION_DEVELOPMENT,
+        readOnlyHint: false,
+    },
+    schema: {
+        extensionName: z
+            .string()
+            .describe('The name or partial name of the extension to debug'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        const { extensionName } = request.params;
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto('chrome://extensions/', { waitUntil: 'networkidle0' });
+            const inspectResult = await page.evaluate((searchName) => {
+                const extensionCards = document.querySelectorAll('extensions-item');
+                for (const card of Array.from(extensionCards)) {
+                    const shadowRoot = card.shadowRoot;
+                    if (shadowRoot) {
+                        const name = shadowRoot.querySelector('#name')?.textContent?.trim() || '';
+                        if (name.toLowerCase().includes(searchName.toLowerCase())) {
+                            // Look for service worker link
+                            const serviceWorkerLink = shadowRoot.querySelector('a[href*="service_worker"]');
+                            if (serviceWorkerLink) {
+                                serviceWorkerLink.click();
+                                return {
+                                    success: true,
+                                    extensionName: name,
+                                    type: 'service_worker',
+                                };
+                            }
+                            // Look for background page link
+                            const backgroundLink = shadowRoot.querySelector('a[href*="background"]');
+                            if (backgroundLink) {
+                                backgroundLink.click();
+                                return {
+                                    success: true,
+                                    extensionName: name,
+                                    type: 'background_page',
+                                };
+                            }
+                            return {
+                                success: false,
+                                reason: 'No service worker or background page found',
+                            };
+                        }
+                    }
+                }
+                return { success: false, reason: 'Extension not found' };
+            }, extensionName);
+            if (inspectResult.success) {
+                response.appendResponseLine(`✅ Opened DevTools for ${inspectResult.type} of: ${inspectResult.extensionName}`);
+            }
+            else {
+                response.appendResponseLine(`❌ Failed: ${inspectResult.reason}`);
+            }
+        });
+    },
+});

package/build/src/tools/input.js

@@ -0,0 +1,201 @@
+/**
+ * @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 click = defineTool({
+    name: 'click',
+    description: `Clicks on the provided element`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z
+            .string()
+            .describe('The uid of an element on the page from the page content snapshot'),
+        dblClick: z
+            .boolean()
+            .optional()
+            .describe('Set to true for double clicks. Default is false.'),
+    },
+    handler: async (request, response, context) => {
+        const uid = request.params.uid;
+        const handle = await context.getElementByUid(uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                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.setIncludeSnapshot(true);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const hover = defineTool({
+    name: 'hover',
+    description: `Hover over the provided element`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z
+            .string()
+            .describe('The uid of an element on the page from the page content snapshot'),
+    },
+    handler: async (request, response, context) => {
+        const uid = request.params.uid;
+        const handle = await context.getElementByUid(uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await handle.asLocator().hover();
+            });
+            response.appendResponseLine(`Successfully hovered over the element`);
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const fill = defineTool({
+    name: 'fill',
+    description: `Type text into a input, text area or select an option from a <select> element.`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z
+            .string()
+            .describe('The uid of an element on the page from the page content snapshot'),
+        value: z.string().describe('The value to fill in'),
+    },
+    handler: async (request, response, context) => {
+        const handle = await context.getElementByUid(request.params.uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await handle.asLocator().fill(request.params.value);
+            });
+            response.appendResponseLine(`Successfully filled out the element`);
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});
+export const drag = defineTool({
+    name: 'drag',
+    description: `Drag an element onto another element`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        from_uid: z.string().describe('The uid of the element to drag'),
+        to_uid: z.string().describe('The uid of the element to drop into'),
+    },
+    handler: async (request, response, context) => {
+        const fromHandle = await context.getElementByUid(request.params.from_uid);
+        const toHandle = await context.getElementByUid(request.params.to_uid);
+        try {
+            await context.waitForEventsAfterAction(async () => {
+                await fromHandle.drag(toHandle);
+                await new Promise(resolve => setTimeout(resolve, 50));
+                await toHandle.drop(fromHandle);
+            });
+            response.appendResponseLine(`Successfully dragged an element`);
+            response.setIncludeSnapshot(true);
+        }
+        finally {
+            void fromHandle.dispose();
+            void toHandle.dispose();
+        }
+    },
+});
+export const fillForm = defineTool({
+    name: 'fill_form',
+    description: `Fill out multiple form elements at once`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        elements: z
+            .array(z.object({
+            uid: z.string().describe('The uid of the element to fill out'),
+            value: z.string().describe('Value for the element'),
+        }))
+            .describe('Elements from snapshot to fill out.'),
+    },
+    handler: async (request, response, context) => {
+        for (const element of request.params.elements) {
+            const handle = await context.getElementByUid(element.uid);
+            try {
+                await context.waitForEventsAfterAction(async () => {
+                    await handle.asLocator().fill(element.value);
+                });
+            }
+            finally {
+                void handle.dispose();
+            }
+        }
+        response.appendResponseLine(`Successfully filled out the form`);
+        response.setIncludeSnapshot(true);
+    },
+});
+export const uploadFile = defineTool({
+    name: 'upload_file',
+    description: 'Upload a file through a provided element.',
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        uid: z
+            .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: z.string().describe('The local path of the file to upload'),
+    },
+    handler: async (request, response, context) => {
+        const { uid, filePath } = request.params;
+        const handle = (await context.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 page = await context.getSelectedPage();
+                    const [fileChooser] = await Promise.all([
+                        page.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.`);
+                }
+            }
+            response.setIncludeSnapshot(true);
+            response.appendResponseLine(`File uploaded from ${filePath}.`);
+        }
+        finally {
+            void handle.dispose();
+        }
+    },
+});

package/build/src/tools/network.js

@@ -0,0 +1,77 @@
+/**
+ * @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';
+const FILTERABLE_RESOURCE_TYPES = [
+    'document',
+    'stylesheet',
+    'image',
+    'media',
+    'font',
+    'script',
+    'texttrack',
+    'xhr',
+    'fetch',
+    'prefetch',
+    'eventsource',
+    'websocket',
+    'manifest',
+    'signedexchange',
+    'ping',
+    'cspviolationreport',
+    'preflight',
+    'fedcm',
+    'other',
+];
+export const listNetworkRequests = defineTool({
+    name: 'list_network_requests',
+    description: `List all requests for the currently selected page`,
+    annotations: {
+        category: ToolCategories.NETWORK,
+        readOnlyHint: true,
+    },
+    schema: {
+        pageSize: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Maximum number of requests to return. When omitted, returns all requests.'),
+        pageIdx: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Page number to return (0-based). When omitted, returns the first page.'),
+        resourceTypes: z
+            .array(z.enum(FILTERABLE_RESOURCE_TYPES))
+            .optional()
+            .describe('Filter requests to only return requests of the specified resource types. When omitted or empty, returns all requests.'),
+    },
+    handler: async (request, response) => {
+        response.setIncludeNetworkRequests(true, {
+            pageSize: request.params.pageSize,
+            pageIdx: request.params.pageIdx,
+            resourceTypes: request.params.resourceTypes,
+        });
+    },
+});
+export const getNetworkRequest = defineTool({
+    name: 'get_network_request',
+    description: `Gets a network request by URL. You can get all requests by calling ${listNetworkRequests.name}.`,
+    annotations: {
+        category: ToolCategories.NETWORK,
+        readOnlyHint: true,
+    },
+    schema: {
+        url: z.string().describe('The URL of the request.'),
+    },
+    handler: async (request, response, _context) => {
+        response.attachNetworkRequest(request.params.url);
+        response.setIncludeNetworkRequests(true);
+    },
+});

package/build/src/tools/pages.js

@@ -0,0 +1,188 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { ToolCategories } from './categories.js';
+import { CLOSE_PAGE_ERROR, defineTool } from './ToolDefinition.js';
+export const listPages = defineTool({
+    name: 'list_pages',
+    description: `Get a list of pages open in the browser.`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response) => {
+        response.setIncludePages(true);
+    },
+});
+export const selectPage = defineTool({
+    name: 'select_page',
+    description: `Select a page as a context for future tool calls.`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: true,
+    },
+    schema: {
+        pageIdx: z
+            .number()
+            .describe('The index of the page to select. Call list_pages to list pages.'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getPageByIdx(request.params.pageIdx);
+        await page.bringToFront();
+        context.setSelectedPageIdx(request.params.pageIdx);
+        response.setIncludePages(true);
+    },
+});
+export const closePage = defineTool({
+    name: 'close_page',
+    description: `Closes the page by its index. The last open page cannot be closed.`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        pageIdx: z
+            .number()
+            .describe('The index of the page to close. Call list_pages to list pages.'),
+    },
+    handler: async (request, response, context) => {
+        try {
+            await context.closePage(request.params.pageIdx);
+        }
+        catch (err) {
+            if (err.message === CLOSE_PAGE_ERROR) {
+                response.appendResponseLine(err.message);
+            }
+            else {
+                throw err;
+            }
+        }
+        response.setIncludePages(true);
+    },
+});
+export const newPage = defineTool({
+    name: 'new_page',
+    description: `Creates a new page`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        url: z.string().describe('URL to load in a new page.'),
+    },
+    handler: async (request, response, context) => {
+        const page = await context.newPage();
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto(request.params.url);
+        });
+        response.setIncludePages(true);
+    },
+});
+export const navigatePage = defineTool({
+    name: 'navigate_page',
+    description: `Navigates the currently selected page to a URL.`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        url: z.string().describe('URL to navigate the page to'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        await context.waitForEventsAfterAction(async () => {
+            await page.goto(request.params.url);
+        });
+        response.setIncludePages(true);
+    },
+});
+export const navigatePageHistory = defineTool({
+    name: 'navigate_page_history',
+    description: `Navigates the currently selected page.`,
+    annotations: {
+        category: ToolCategories.NAVIGATION_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        navigate: z
+            .enum(['back', 'forward'])
+            .describe('Whether to navigate back or navigate forward in the selected pages history'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        try {
+            if (request.params.navigate === 'back') {
+                await page.goBack();
+            }
+            else {
+                await page.goForward();
+            }
+        }
+        catch {
+            response.appendResponseLine(`Unable to navigate ${request.params.navigate} in currently selected page.`);
+        }
+        response.setIncludePages(true);
+    },
+});
+export const resizePage = defineTool({
+    name: 'resize_page',
+    description: `Resizes the selected page's window so that the page has specified dimension`,
+    annotations: {
+        category: ToolCategories.EMULATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        width: z.number().describe('Page width'),
+        height: z.number().describe('Page height'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        // @ts-expect-error internal API for now.
+        await page.resize({
+            contentWidth: request.params.width,
+            contentHeight: request.params.height,
+        });
+        response.setIncludePages(true);
+    },
+});
+export const handleDialog = defineTool({
+    name: 'handle_dialog',
+    description: `If a browser dialog was opened, use this command to handle it`,
+    annotations: {
+        category: ToolCategories.INPUT_AUTOMATION,
+        readOnlyHint: false,
+    },
+    schema: {
+        action: z
+            .enum(['accept', 'dismiss'])
+            .describe('Whether to dismiss or accept the dialog'),
+        promptText: z
+            .string()
+            .optional()
+            .describe('Optional prompt text to enter into the dialog.'),
+    },
+    handler: async (request, response, context) => {
+        const dialog = context.getDialog();
+        if (!dialog) {
+            throw new Error('No open dialog found');
+        }
+        switch (request.params.action) {
+            case 'accept': {
+                await dialog.accept(request.params.promptText);
+                response.appendResponseLine('Successfully accepted the dialog');
+                break;
+            }
+            case 'dismiss': {
+                await dialog.dismiss();
+                response.appendResponseLine('Successfully dismissed the dialog');
+                break;
+            }
+        }
+        context.clearDialog();
+        response.setIncludePages(true);
+    },
+});