chrome-devtools-mcp 0.0.1 → 0.1.0

package/build/src/McpResponse.js

@@ -0,0 +1,178 @@
+import { getFormattedHeaderValue, getShortDescriptionForRequest, getStatusFromRequest, } from './formatters/networkFormatter.js';
+import { formatA11ySnapshot } from './formatters/snapshotFormatter.js';
+import { formatConsoleEvent } from './formatters/consoleFormatter.js';
+export class McpResponse {
+    #includePages = false;
+    #includeSnapshot = false;
+    #includeNetworkRequests = false;
+    #attachedNetworkRequestUrl;
+    #includeConsoleData = false;
+    #textResponseLines = [];
+    #formatedConsoleData;
+    #images = [];
+    setIncludePages(value) {
+        this.#includePages = value;
+    }
+    setIncludeSnapshot(value) {
+        this.#includeSnapshot = value;
+    }
+    setIncludeNetworkRequests(value) {
+        this.#includeNetworkRequests = value;
+    }
+    setIncludeConsoleData(value) {
+        this.#includeConsoleData = value;
+    }
+    attachNetworkRequest(url) {
+        this.#attachedNetworkRequestUrl = url;
+    }
+    get includePages() {
+        return this.#includePages;
+    }
+    get includeNetworkRequests() {
+        return this.#includeNetworkRequests;
+    }
+    get includeConsoleData() {
+        return this.#includeConsoleData;
+    }
+    get attachedNetworkRequestUrl() {
+        return this.#attachedNetworkRequestUrl;
+    }
+    appendResponseLine(value) {
+        this.#textResponseLines.push(value);
+    }
+    attachImage(value) {
+        this.#images.push(value);
+    }
+    get responseLines() {
+        return this.#textResponseLines;
+    }
+    get images() {
+        return this.#images;
+    }
+    get includeSnapshot() {
+        return this.#includeSnapshot;
+    }
+    async handle(toolName, context) {
+        if (this.#includePages) {
+            await context.createPagesSnapshot();
+        }
+        if (this.#includeSnapshot) {
+            await context.createTextSnapshot();
+        }
+        let formattedConsoleMessages;
+        if (this.#includeConsoleData) {
+            const consoleMessages = context.getConsoleData();
+            if (consoleMessages) {
+                formattedConsoleMessages = await Promise.all(consoleMessages.map(message => formatConsoleEvent(message)));
+                this.#formatedConsoleData = formattedConsoleMessages;
+            }
+        }
+        return this.format(toolName, context);
+    }
+    format(toolName, context) {
+        const response = [`# ${toolName} response`];
+        for (const line of this.#textResponseLines) {
+            response.push(line);
+        }
+        const networkConditions = context.getNetworkConditions();
+        if (networkConditions) {
+            response.push(`## Network emulation`);
+            response.push(`Emulating: ${networkConditions}`);
+        }
+        const cpuThrottlingRate = context.getCpuThrottlingRate();
+        if (cpuThrottlingRate > 1) {
+            response.push(`## CPU emulation`);
+            response.push(`Emulating: ${cpuThrottlingRate}x slowdown`);
+        }
+        const dialog = context.getDialog();
+        if (dialog) {
+            response.push(`# Open dialog
+${dialog.type()}: ${dialog.message()} (default value: ${dialog.message()}).
+Call browser_handle_dialog to handle it before continuing.`);
+        }
+        if (this.#includePages) {
+            const parts = [`## Pages`];
+            let idx = 0;
+            for (const page of context.getPages()) {
+                parts.push(`${idx}: ${page.url()}${idx === context.getSelectedPageIdx() ? ' [selected]' : ''}`);
+                idx++;
+            }
+            response.push(...parts);
+        }
+        if (this.#includeSnapshot) {
+            const rootNode = context.getTextSnapshot();
+            if (rootNode) {
+                const formattedSnapshot = formatA11ySnapshot(rootNode);
+                response.push('## Page content');
+                response.push(formattedSnapshot);
+            }
+        }
+        response.push(...this.#getIncludeNetworkRequestsData(context));
+        if (this.#includeNetworkRequests) {
+            const requests = context.getNetworkRequests();
+            response.push('## Network requests');
+            if (requests.length) {
+                for (const request of requests) {
+                    response.push(getShortDescriptionForRequest(request));
+                }
+            }
+            else {
+                response.push('No requests found.');
+            }
+        }
+        if (this.#includeConsoleData && this.#formatedConsoleData) {
+            response.push('## Console messages');
+            response.push(...this.#formatedConsoleData);
+        }
+        const text = {
+            type: 'text',
+            text: response.join('\n'),
+        };
+        const images = this.#images.map(imageData => {
+            return {
+                type: 'image',
+                ...imageData,
+            };
+        });
+        return [text, ...images];
+    }
+    #getIncludeNetworkRequestsData(context) {
+        const response = [];
+        const url = this.#attachedNetworkRequestUrl;
+        if (!url) {
+            return response;
+        }
+        const httpRequest = context.getNetworkRequestByUrl(url);
+        response.push(`## Request ${httpRequest.url()}`);
+        response.push(`Status:  ${getStatusFromRequest(httpRequest)}`);
+        response.push(`### Request Headers`);
+        for (const line of getFormattedHeaderValue(httpRequest.headers())) {
+            response.push(line);
+        }
+        const httpResponse = httpRequest.response();
+        if (httpResponse) {
+            response.push(`### Response Headers`);
+            for (const line of getFormattedHeaderValue(httpResponse.headers())) {
+                response.push(line);
+            }
+        }
+        const httpFailure = httpRequest.failure();
+        if (httpFailure) {
+            response.push(`### Request failed with`);
+            response.push(httpFailure.errorText);
+        }
+        const redirectChain = httpRequest.redirectChain();
+        if (redirectChain.length) {
+            response.push(`### Redirect chain`);
+            let indent = 0;
+            for (const request of redirectChain.reverse()) {
+                response.push(`${'  '.repeat(indent)}${getShortDescriptionForRequest(request)}`);
+                indent++;
+            }
+        }
+        return response;
+    }
+    resetResponseLineForTesting() {
+        this.#textResponseLines = [];
+    }
+}

package/build/src/Mutex.js

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google Inc.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class Mutex {
+    static Guard = class Guard {
+        #mutex;
+        #onRelease;
+        constructor(mutex, onRelease) {
+            this.#mutex = mutex;
+            this.#onRelease = onRelease;
+        }
+        dispose() {
+            this.#onRelease?.();
+            return this.#mutex.release();
+        }
+    };
+    #locked = false;
+    #acquirers = [];
+    // This is FIFO.
+    async acquire(onRelease) {
+        if (!this.#locked) {
+            this.#locked = true;
+            return new Mutex.Guard(this);
+        }
+        const { resolve, promise } = Promise.withResolvers();
+        this.#acquirers.push(resolve);
+        await promise;
+        return new Mutex.Guard(this, onRelease);
+    }
+    release() {
+        const resolve = this.#acquirers.shift();
+        if (!resolve) {
+            this.#locked = false;
+            return;
+        }
+        resolve();
+    }
+}

package/build/src/PageCollector.js

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export class PageCollector {
+    #browser;
+    #initializer;
+    storage = new WeakMap();
+    constructor(browser, initializer) {
+        this.#browser = browser;
+        this.#initializer = initializer;
+    }
+    async init() {
+        const pages = await this.#browser.pages();
+        for (const page of pages) {
+            this.#initializePage(page);
+        }
+        this.#browser.on('targetcreated', async (target) => {
+            const page = await target.page();
+            if (!page) {
+                return;
+            }
+            this.#initializePage(page);
+        });
+    }
+    addPage(page) {
+        this.#initializePage(page);
+    }
+    #initializePage(page) {
+        if (this.storage.has(page)) {
+            return;
+        }
+        page.on('framenavigated', frame => {
+            // Only reset the storage on main frame navigation
+            if (frame !== page.mainFrame()) {
+                return;
+            }
+            this.cleanup(page);
+        });
+        this.#initializer(page, value => {
+            const stored = this.storage.get(page) ?? [];
+            stored.push(value);
+            this.storage.set(page, stored);
+        });
+    }
+    cleanup(page) {
+        const collection = this.storage.get(page) ?? [];
+        // Keep the reference alive
+        collection.length = 0;
+    }
+    getData(page) {
+        return this.storage.get(page) ?? [];
+    }
+}
+export class NetworkCollector extends PageCollector {
+    cleanup(page) {
+        const requests = this.storage.get(page) ?? [];
+        const lastRequestIdx = requests.findLastIndex(request => {
+            return request.frame() === page.mainFrame()
+                ? request.isNavigationRequest()
+                : false;
+        });
+        // Keep all requests since the last navigation request including that
+        // navigation request itself.
+        this.storage.set(page, requests.slice(Math.max(lastRequestIdx, 0)));
+    }
+}

package/build/src/browser.js

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import puppeteer from 'puppeteer-core';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'fs';
+let browser;
+const ignoredPrefixes = new Set([
+    'chrome://',
+    'chrome-extension://',
+    'chrome-untrusted://',
+    'devtools://',
+]);
+function targetFilter(target) {
+    if (target.url() === 'chrome://newtab/') {
+        return true;
+    }
+    for (const prefix of ignoredPrefixes) {
+        if (target.url().startsWith(prefix)) {
+            return false;
+        }
+    }
+    return true;
+}
+const connectOptions = {
+    targetFilter,
+    // We do not expect any single CDP command to take more than 10sec.
+    protocolTimeout: 10_000,
+};
+async function ensureBrowserConnected(browserURL) {
+    if (browser?.connected) {
+        return browser;
+    }
+    browser = await puppeteer.connect({
+        ...connectOptions,
+        browserURL,
+        defaultViewport: null,
+    });
+    return browser;
+}
+export async function launch(options) {
+    const { channel, executablePath, customDevTools, headless, isolated } = options;
+    const profileDirName = channel && channel !== 'stable' ? `mcp-profile-${channel}` : 'mcp-profile';
+    let userDataDir = options.userDataDir;
+    if (!isolated && !userDataDir) {
+        userDataDir = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', profileDirName);
+        await fs.promises.mkdir(userDataDir, {
+            recursive: true,
+        });
+    }
+    const args = [
+        '--remote-debugging-pipe',
+        '--no-first-run',
+        '--hide-crash-restore-bubble',
+    ];
+    if (customDevTools) {
+        args.push(`--custom-devtools-frontend=file://${customDevTools}`);
+    }
+    let puppeterChannel;
+    if (!executablePath) {
+        puppeterChannel =
+            channel && channel !== 'stable'
+                ? `chrome-${channel}`
+                : 'chrome';
+    }
+    try {
+        return await puppeteer.launch({
+            ...connectOptions,
+            channel: puppeterChannel,
+            executablePath,
+            defaultViewport: null,
+            userDataDir,
+            pipe: true,
+            headless,
+            args,
+        });
+    }
+    catch (error) {
+        // TODO: check browser logs for `Failed to create a ProcessSingleton for
+        // your profile directory` instead.
+        if (userDataDir &&
+            error.message.includes('The browser is already running')) {
+            throw new Error(`The browser is already running for ${userDataDir}. Use --isolated to run multiple browser instances.`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}
+async function ensureBrowserLaunched(options) {
+    if (browser?.connected) {
+        return browser;
+    }
+    browser = await launch(options);
+    return browser;
+}
+export async function resolveBrowser(options) {
+    const browser = options.browserUrl
+        ? await ensureBrowserConnected(options.browserUrl)
+        : await ensureBrowserLaunched(options);
+    return browser;
+}

package/build/src/formatters/consoleFormatter.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logLevels = {
+    log: 'Log',
+    info: 'Info',
+    warning: 'Warning',
+    error: 'Error',
+    exception: 'Exception',
+    assert: 'Assert',
+};
+export async function formatConsoleEvent(event) {
+    // Check if the event object has the .type() method, which is unique to ConsoleMessage
+    if ('type' in event) {
+        return await formatConsoleMessage(event);
+    }
+    return `Error: ${event.message}`;
+}
+async function formatConsoleMessage(msg) {
+    const logLevel = logLevels[msg.type()];
+    const args = msg.args();
+    if (logLevel === 'Error') {
+        let message = `${logLevel}> `;
+        if (msg.text() === 'JSHandle@error') {
+            const errorHandle = args[0];
+            message += await errorHandle
+                .evaluate(error => {
+                return error.toString();
+            })
+                .catch(() => {
+                return 'Error occured';
+            });
+            void errorHandle.dispose().catch();
+            const formattedArgs = await formatArgs(args.slice(1));
+            if (formattedArgs) {
+                message += ` ${formattedArgs}`;
+            }
+        }
+        else {
+            message += msg.text();
+            const formattedArgs = await formatArgs(args);
+            if (formattedArgs) {
+                message += ` ${formattedArgs}`;
+            }
+            for (const frame of msg.stackTrace()) {
+                message += '\n' + formatStackFrame(frame);
+            }
+        }
+        return message;
+    }
+    const formattedArgs = await formatArgs(args);
+    const text = msg.text();
+    return `${logLevel}> ${formatStackFrame(msg.location())}: ${text} ${formattedArgs}`.trim();
+}
+async function formatArgs(args) {
+    const argValues = await Promise.all(args.map(arg => arg.jsonValue().catch(() => { })));
+    return argValues
+        .map(value => {
+        return typeof value === 'object' ? JSON.stringify(value) : String(value);
+    })
+        .join(' ');
+}
+function formatStackFrame(stackFrame) {
+    if (!stackFrame?.url) {
+        return '<unknown>';
+    }
+    const filename = stackFrame.url.replace(/^.*\//, '');
+    return `${filename}:${stackFrame.lineNumber}:${stackFrame.columnNumber}`;
+}

package/build/src/formatters/networkFormatter.js

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function getShortDescriptionForRequest(request) {
+    return `${request.url()} ${request.method()} ${getStatusFromRequest(request)}`;
+}
+export function getStatusFromRequest(request) {
+    const httpResponse = request.response();
+    const failure = request.failure();
+    let status;
+    if (httpResponse) {
+        const responseStatus = httpResponse.status();
+        status =
+            responseStatus >= 200 && responseStatus <= 299
+                ? `[success - ${responseStatus}]`
+                : `[failed - ${responseStatus}]`;
+    }
+    else if (failure) {
+        status = `[failed - ${failure.errorText}]`;
+    }
+    else {
+        status = '[pending]';
+    }
+    return status;
+}
+export function getFormattedHeaderValue(headers) {
+    const response = [];
+    for (const [name, value] of Object.entries(headers)) {
+        response.push(`- ${name}:${value}`);
+    }
+    return response;
+}

package/build/src/formatters/snapshotFormatter.js

@@ -0,0 +1,75 @@
+export function formatA11ySnapshot(serializedAXNodeRoot, depth = 0) {
+    let result = '';
+    const attributes = getAttributes(serializedAXNodeRoot);
+    const line = ' '.repeat(depth * 2) + attributes.join(' ') + '\n';
+    result += line;
+    for (const child of serializedAXNodeRoot.children) {
+        result += formatA11ySnapshot(child, depth + 1);
+    }
+    return result;
+}
+function getAttributes(serializedAXNodeRoot) {
+    const attributes = [
+        `uid=${serializedAXNodeRoot.id}`,
+        serializedAXNodeRoot.role,
+        `"${serializedAXNodeRoot.name || ''}"`, // Corrected: Added quotes around name
+    ];
+    // Value properties
+    const valueProperties = [
+        'value',
+        'valuetext',
+        'valuemin',
+        'valuemax',
+        'level',
+        'autocomplete',
+        'haspopup',
+        'invalid',
+        'orientation',
+        'description',
+        'keyshortcuts',
+        'roledescription',
+    ];
+    for (const property of valueProperties) {
+        if (property in serializedAXNodeRoot &&
+            serializedAXNodeRoot[property] !== undefined) {
+            attributes.push(`${property}="${serializedAXNodeRoot[property]}"`);
+        }
+    }
+    // Boolean properties that also have an 'able' attribute
+    const booleanPropertyMap = {
+        disabled: 'disableable',
+        expanded: 'expandable',
+        focused: 'focusable',
+        selected: 'selectable',
+    };
+    for (const [property, ableAttribute] of Object.entries(booleanPropertyMap)) {
+        if (property in serializedAXNodeRoot) {
+            attributes.push(ableAttribute);
+            if (serializedAXNodeRoot[property]) {
+                attributes.push(property);
+            }
+        }
+    }
+    const booleanProperties = [
+        'modal',
+        'multiline',
+        'readonly',
+        'required',
+        'multiselectable',
+    ];
+    for (const property of booleanProperties) {
+        if (property in serializedAXNodeRoot && serializedAXNodeRoot[property]) {
+            attributes.push(property);
+        }
+    }
+    // Mixed boolean/string attributes
+    for (const property of ['pressed', 'checked']) {
+        if (property in serializedAXNodeRoot) {
+            attributes.push(property);
+            if (serializedAXNodeRoot[property]) {
+                attributes.push(`${property}="${serializedAXNodeRoot[property]}"`);
+            }
+        }
+    }
+    return attributes;
+}