chrome-devtools-mcp 0.0.1 → 0.1.0

package/build/src/tools/pages.js

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { defineTool } from './ToolDefinition.js';
+import { ToolCategories } from './categories.js';
+import { waitForEventsAfterAction } from '../waitForHelpers.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.`,
+    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) => {
+        const page = context.getPageByIdx(request.params.pageIdx);
+        context.setSelectedPageIdx(0);
+        await page.close({ runBeforeUnload: false });
+        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 waitForEventsAfterAction(page, 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 waitForEventsAfterAction(page, 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);
+    },
+});

package/build/src/tools/performance.js

@@ -0,0 +1,116 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { defineTool } from './ToolDefinition.js';
+import { insightOutput, parseRawTraceBuffer } from '../trace-processing/parse.js';
+import { logger } from '../logger.js';
+import { ToolCategories } from './categories.js';
+export const startTrace = defineTool({
+    name: 'performance_start_trace',
+    description: 'Starts a performance trace recording',
+    annotations: {
+        category: ToolCategories.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {
+        reload: z
+            .boolean()
+            .describe('Determines if, once tracing has started, the page should be automatically reloaded'),
+        autoStop: z
+            .boolean()
+            .describe('Determines if the trace recording should be automatically stopped.'),
+    },
+    handler: async (request, response, context) => {
+        if (context.isRunningPerformanceTrace()) {
+            response.appendResponseLine('Error: a performance trace is already running. Use performance_stop_trace to stop it. Only one trace can be running at any given time.');
+            return;
+        }
+        context.setIsRunningPerformanceTrace(true);
+        const page = context.getSelectedPage();
+        const pageUrlForTracing = page.url();
+        if (request.params.reload) {
+            // Before starting the recording, navigate to about:blank to clear out any state.
+            await page.goto('about:blank', {
+                waitUntil: ['networkidle0'],
+            });
+        }
+        // Keep in sync with the categories arrays in:
+        // https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/timeline/TimelineController.ts
+        // https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/gather/gatherers/trace.js
+        const categories = [
+            '-*',
+            'blink.console',
+            'blink.user_timing',
+            'devtools.timeline',
+            'disabled-by-default-devtools.screenshot',
+            'disabled-by-default-devtools.timeline',
+            'disabled-by-default-devtools.timeline.invalidationTracking',
+            'disabled-by-default-devtools.timeline.frame',
+            'disabled-by-default-devtools.timeline.stack',
+            'disabled-by-default-v8.cpu_profiler',
+            'disabled-by-default-v8.cpu_profiler.hires',
+            'latencyInfo',
+            'loading',
+            'disabled-by-default-lighthouse',
+            'v8.execute',
+            'v8',
+        ];
+        await page.tracing.start({
+            categories,
+        });
+        if (request.params.reload) {
+            await page.goto(pageUrlForTracing, {
+                waitUntil: ['load'],
+            });
+        }
+        if (request.params.autoStop) {
+            await new Promise(resolve => setTimeout(resolve, 5_000));
+            await stopTracingAndAppendOutput(page, response, context);
+        }
+        else {
+            response.appendResponseLine(`The performance trace is being recorded. Use performance_stop_trace to stop it.`);
+        }
+    },
+});
+export const stopTrace = defineTool({
+    name: 'performance_stop_trace',
+    description: 'Stops the active performance trace recording',
+    annotations: {
+        category: ToolCategories.PERFORMANCE,
+        readOnlyHint: true,
+    },
+    schema: {},
+    handler: async (_request, response, context) => {
+        if (!context.isRunningPerformanceTrace) {
+            return;
+        }
+        const page = context.getSelectedPage();
+        await stopTracingAndAppendOutput(page, response, context);
+    },
+});
+async function stopTracingAndAppendOutput(page, response, context) {
+    try {
+        const traceEventsBuffer = await page.tracing.stop();
+        const result = await parseRawTraceBuffer(traceEventsBuffer);
+        response.appendResponseLine('The performance trace has been stopped.');
+        if (result) {
+            const insightText = insightOutput(result);
+            if (insightText) {
+                response.appendResponseLine('Insights with performance opportunities:');
+                response.appendResponseLine(insightText);
+            }
+            else {
+                response.appendResponseLine('No insights have been found. The performance looks good!');
+            }
+        }
+    }
+    catch (e) {
+        logger(`Error stopping performance trace: ${e instanceof Error ? e.message : JSON.stringify(e)}`);
+    }
+    finally {
+        context.setIsRunningPerformanceTrace(false);
+    }
+}

package/build/src/tools/screenshot.js

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

package/build/src/tools/script.js

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import z from 'zod';
+import { defineTool } from './ToolDefinition.js';
+import { ToolCategories } from './categories.js';
+import { waitForEventsAfterAction } from '../waitForHelpers.js';
+export const evaluateScript = defineTool({
+    name: 'evaluate_script',
+    description: `Evaluate a JavaScript function inside the currently selected page. Returns the response as JSON.`,
+    annotations: {
+        category: ToolCategories.DEBUGGING,
+        readOnlyHint: false,
+    },
+    schema: {
+        function: z
+            .string()
+            .describe('A JavaScript function to run in the currently selected page. Example: `() => {return document.title}` or `async () => {return await fetch("example.com")}`'),
+    },
+    handler: async (request, response, context) => {
+        const page = context.getSelectedPage();
+        const script = `(async () => {
+      return JSON.stringify(await (${request.params.function})());
+    })()`;
+        await waitForEventsAfterAction(page, async () => {
+            const result = await page.evaluate(script);
+            response.appendResponseLine('Script ran on page and returned:');
+            response.appendResponseLine('```json');
+            response.appendResponseLine(`${result}`);
+            response.appendResponseLine('```');
+        });
+    },
+});

package/build/src/tools/snapshot.js

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

package/build/src/trace-processing/parse.js

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { PerformanceInsightFormatter } from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.js';
+import * as TraceEngine from '../../node_modules/chrome-devtools-frontend/front_end/models/trace/trace.js';
+import { logger } from '../logger.js';
+const engine = TraceEngine.TraceModel.Model.createWithAllHandlers();
+export async function parseRawTraceBuffer(buffer) {
+    engine.resetProcessor();
+    if (!buffer) {
+        return null;
+    }
+    const asString = new TextDecoder().decode(buffer);
+    if (!asString) {
+        return null;
+    }
+    try {
+        const data = JSON.parse(asString);
+        const events = Array.isArray(data) ? data : data.traceEvents;
+        await engine.parse(events);
+        const parsedTrace = engine.parsedTrace();
+        if (!parsedTrace) {
+            return null;
+        }
+        const insights = parsedTrace?.insights;
+        if (!insights) {
+            return null;
+        }
+        return {
+            parsedTrace,
+            insights,
+        };
+    }
+    catch (e) {
+        if (e instanceof Error) {
+            logger(`Error parsing trace: ${e.message}`);
+        }
+        else {
+            logger(`Error parsing trace: ${JSON.stringify(e)}`);
+        }
+        return null;
+    }
+}
+// TODO(jactkfranklin): move the formatters from DevTools to use here.
+// This is a very temporary helper to output some text from the tool call to aid development.
+export function insightOutput(result) {
+    const mainNavigationId = result.parsedTrace.data.Meta.mainFrameNavigations.at(0)?.args.data
+        ?.navigationId;
+    if (!mainNavigationId) {
+        return '';
+    }
+    let text = '';
+    const insightsForNav = result.insights.get(mainNavigationId);
+    if (!insightsForNav) {
+        text += 'No Performance insights were found for this trace.';
+        return text;
+    }
+    const failingInsightKeys = Object.keys(insightsForNav.model).filter(insightKey => {
+        const key = insightKey;
+        const data = insightsForNav.model[key] ?? null;
+        return data?.state === 'fail';
+    });
+    logger(`Found failing Insight keys: ${failingInsightKeys.join(', ')}`);
+    for (const failingKey of failingInsightKeys) {
+        const modelData = insightsForNav.model[failingKey];
+        const formatter = new PerformanceInsightFormatter(result.parsedTrace, modelData);
+        const output = formatter.formatInsight();
+        text += `${output}\n`;
+    }
+    return text;
+}

package/build/src/waitForHelpers.js

@@ -0,0 +1,109 @@
+import { logger } from './logger.js';
+async function waitForStableDom(page, signal) {
+    const stableDomObserver = await page.evaluateHandle(() => {
+        let timeoutId;
+        function callback() {
+            clearTimeout(timeoutId);
+            timeoutId = setTimeout(() => {
+                domObserver.resolver.resolve();
+                domObserver.observer.disconnect();
+            }, 100);
+        }
+        const domObserver = {
+            resolver: Promise.withResolvers(),
+            observer: new MutationObserver(callback),
+        };
+        // It's possible that the DOM is not gonna change so we
+        // need to start the timeout initially.
+        callback();
+        domObserver.observer.observe(document.body, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+        });
+        return domObserver;
+    });
+    signal.addEventListener('abort', async () => {
+        try {
+            await stableDomObserver.evaluate(observer => {
+                observer.observer.disconnect();
+                observer.resolver.resolve();
+            });
+            await stableDomObserver.dispose();
+        }
+        catch {
+            // Ignored cleanup errors
+        }
+    });
+    return Promise.race([
+        stableDomObserver.evaluate(async (observer) => {
+            return await observer.resolver.promise;
+        }),
+        timeout(3000, signal).then(() => {
+            throw new Error('Timeout');
+        }),
+    ]);
+}
+async function waitForNavigationStarted(page, signal) {
+    // Currently Puppeteer does not have API
+    // For when a navigation is about to start
+    const navigationStartedPromise = new Promise(resolve => {
+        const listener = (event) => {
+            if ([
+                'historySameDocument',
+                'historyDifferentDocument',
+                'sameDocument',
+            ].includes(event.navigationType)) {
+                resolve(false);
+                return;
+            }
+            resolve(true);
+        };
+        page._client().on('Page.frameStartedNavigating', listener);
+        signal.addEventListener('abort', () => {
+            resolve(false);
+            page._client().off('Page.frameStartedNavigating', listener);
+        });
+    });
+    return await Promise.race([
+        navigationStartedPromise,
+        timeout(100).then(() => false),
+    ]);
+}
+function timeout(time, signal) {
+    return new Promise(res => {
+        const id = setTimeout(res, time);
+        signal?.addEventListener('abort', () => {
+            res();
+            clearTimeout(id);
+        });
+    });
+}
+/**
+ * A wrapper that executes a action and waits for
+ * a potential navigation, after which it waits
+ * for the DOM to be stable before returning.
+ */
+export async function waitForEventsAfterAction(page, callback) {
+    const controller = new AbortController();
+    const navigationStartedPromise = waitForNavigationStarted(page, controller.signal);
+    await callback();
+    try {
+        const navigationStated = await navigationStartedPromise;
+        if (navigationStated) {
+            await page.waitForNavigation({
+                timeout: 3000,
+                signal: controller.signal,
+            });
+        }
+        // Wait for stable dom after navigation so we execute in
+        // the correct context
+        await waitForStableDom(page, controller.signal);
+    }
+    catch (error) {
+        logger(error);
+    }
+    finally {
+        controller.abort();
+    }
+}

package/package.json

@@ -1,12 +1,59 @@
 {
   "name": "chrome-devtools-mcp",
-  "version": "0.0.1",
+  "version": "0.1.0",
+  "description": "MCP server for Chrome DevTools",
+  "type": "module",
+  "bin": {
+    "chrome-devtools-mcp": "./build/src/index.js"
+  },
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc && node --experimental-strip-types scripts/post-build.ts",
+    "format": "eslint --cache --fix . ;prettier --write --cache .",
+    "check-format": "eslint --cache .; prettier --check --cache .;",
+    "generate-docs": "npm run build && node --experimental-strip-types scripts/generate-docs.ts",
+    "start": "npm run build && node build/src/index.js",
+    "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js",
+    "test": "npm run build && node --test-reporter spec --test-force-exit --test 'build/tests/**/*.test.js'",
+    "test:only": "npm run build && node --test-reporter spec --test-force-exit --test --test-only 'build/tests/**/*.test.js'",
+    "test:only:no-build": "node --test-reporter spec --test-force-exit --test --test-only 'build/tests/**/*.test.js'",
+    "prepare": "node --experimental-strip-types scripts/prepare.ts"
+  },
+  "files": [
+    "build/src",
+    "build/node_modules",
+    "LICENSE",
+    "!*.tsbuildinfo"
+  ],
+  "repository": "ChromeDevTools/chrome-devtools-mcp",
+  "author": "Google LLC",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/ChromeDevTools/chrome-devtools-mcp/issues"
+  },
+  "homepage": "https://github.com/ChromeDevTools/chrome-devtools-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.18.0",
+    "debug": "4.4.3",
+    "puppeteer-core": "24.21.0",
+    "yargs": "18.0.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": ""
+  "devDependencies": {
+    "@eslint/js": "^9.35.0",
+    "@types/debug": "^4.1.12",
+    "@types/filesystem": "^0.0.36",
+    "@types/node": "^24.3.3",
+    "@types/sinon": "^17.0.4",
+    "@types/yargs": "^17.0.33",
+    "@typescript-eslint/eslint-plugin": "^8.43.0",
+    "@typescript-eslint/parser": "^8.43.0",
+    "chrome-devtools-frontend": "1.0.1514545",
+    "eslint": "^9.35.0",
+    "globals": "^16.4.0",
+    "prettier": "^3.6.2",
+    "puppeteer": "24.21.0",
+    "sinon": "^21.0.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.43.0"
+  }
 }