chrome-devtools-mcp-for-extension 0.5.0

package/build/src/McpContext.js

@@ -0,0 +1,283 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { NetworkCollector, PageCollector } from './PageCollector.js';
+import { listPages } from './tools/pages.js';
+import { CLOSE_PAGE_ERROR } from './tools/ToolDefinition.js';
+import { WaitForHelper } from './WaitForHelper.js';
+const DEFAULT_TIMEOUT = 5_000;
+const NAVIGATION_TIMEOUT = 10_000;
+function getNetworkMultiplierFromString(condition) {
+    const puppeteerCondition = condition;
+    switch (puppeteerCondition) {
+        case 'Fast 4G':
+            return 1;
+        case 'Slow 4G':
+            return 2.5;
+        case 'Fast 3G':
+            return 5;
+        case 'Slow 3G':
+            return 10;
+    }
+    return 1;
+}
+export class McpContext {
+    browser;
+    logger;
+    // The most recent page state.
+    #pages = [];
+    #selectedPageIdx = 0;
+    // The most recent snapshot.
+    #textSnapshot = null;
+    #networkCollector;
+    #consoleCollector;
+    #isRunningTrace = false;
+    #networkConditionsMap = new WeakMap();
+    #cpuThrottlingRateMap = new WeakMap();
+    #dialog;
+    #nextSnapshotId = 1;
+    #traceResults = [];
+    constructor(browser, logger) {
+        this.browser = browser;
+        this.logger = logger;
+        this.#networkCollector = new NetworkCollector(this.browser, (page, collect) => {
+            page.on('request', request => {
+                collect(request);
+            });
+        });
+        this.#consoleCollector = new PageCollector(this.browser, (page, collect) => {
+            page.on('console', event => {
+                collect(event);
+            });
+            page.on('pageerror', event => {
+                collect(event);
+            });
+        });
+    }
+    async #init() {
+        await this.createPagesSnapshot();
+        this.setSelectedPageIdx(0);
+        await this.#networkCollector.init();
+        await this.#consoleCollector.init();
+    }
+    static async from(browser, logger) {
+        const context = new McpContext(browser, logger);
+        await context.#init();
+        return context;
+    }
+    getNetworkRequests() {
+        const page = this.getSelectedPage();
+        return this.#networkCollector.getData(page);
+    }
+    getConsoleData() {
+        const page = this.getSelectedPage();
+        return this.#consoleCollector.getData(page);
+    }
+    async newPage() {
+        const page = await this.browser.newPage();
+        const pages = await this.createPagesSnapshot();
+        this.setSelectedPageIdx(pages.indexOf(page));
+        this.#networkCollector.addPage(page);
+        this.#consoleCollector.addPage(page);
+        return page;
+    }
+    async closePage(pageIdx) {
+        if (this.#pages.length === 1) {
+            throw new Error(CLOSE_PAGE_ERROR);
+        }
+        const page = this.getPageByIdx(pageIdx);
+        this.setSelectedPageIdx(0);
+        await page.close({ runBeforeUnload: false });
+    }
+    getNetworkRequestByUrl(url) {
+        const requests = this.getNetworkRequests();
+        if (!requests.length) {
+            throw new Error('No requests found for selected page');
+        }
+        for (const request of requests) {
+            if (request.url() === url) {
+                return request;
+            }
+        }
+        throw new Error('Request not found for selected page');
+    }
+    setNetworkConditions(conditions) {
+        const page = this.getSelectedPage();
+        if (conditions === null) {
+            this.#networkConditionsMap.delete(page);
+        }
+        else {
+            this.#networkConditionsMap.set(page, conditions);
+        }
+        this.#updateSelectedPageTimeouts();
+    }
+    getNetworkConditions() {
+        const page = this.getSelectedPage();
+        return this.#networkConditionsMap.get(page) ?? null;
+    }
+    setCpuThrottlingRate(rate) {
+        const page = this.getSelectedPage();
+        this.#cpuThrottlingRateMap.set(page, rate);
+        this.#updateSelectedPageTimeouts();
+    }
+    getCpuThrottlingRate() {
+        const page = this.getSelectedPage();
+        return this.#cpuThrottlingRateMap.get(page) ?? 1;
+    }
+    setIsRunningPerformanceTrace(x) {
+        this.#isRunningTrace = x;
+    }
+    isRunningPerformanceTrace() {
+        return this.#isRunningTrace;
+    }
+    getDialog() {
+        return this.#dialog;
+    }
+    clearDialog() {
+        this.#dialog = undefined;
+    }
+    getSelectedPage() {
+        const page = this.#pages[this.#selectedPageIdx];
+        if (!page) {
+            throw new Error('No page selected');
+        }
+        if (page.isClosed()) {
+            throw new Error(`The selected page has been closed. Call ${listPages.name} to see open pages.`);
+        }
+        return page;
+    }
+    getPageByIdx(idx) {
+        const pages = this.#pages;
+        const page = pages[idx];
+        if (!page) {
+            throw new Error('No page found');
+        }
+        return page;
+    }
+    getSelectedPageIdx() {
+        return this.#selectedPageIdx;
+    }
+    #dialogHandler = (dialog) => {
+        this.#dialog = dialog;
+    };
+    setSelectedPageIdx(idx) {
+        const oldPage = this.getSelectedPage();
+        oldPage.off('dialog', this.#dialogHandler);
+        this.#selectedPageIdx = idx;
+        const newPage = this.getSelectedPage();
+        newPage.on('dialog', this.#dialogHandler);
+        this.#updateSelectedPageTimeouts();
+    }
+    #updateSelectedPageTimeouts() {
+        const page = this.getSelectedPage();
+        // For waiters 5sec timeout should be sufficient.
+        // Increased in case we throttle the CPU
+        const cpuMultiplier = this.getCpuThrottlingRate();
+        page.setDefaultTimeout(DEFAULT_TIMEOUT * cpuMultiplier);
+        // 10sec should be enough for the load event to be emitted during
+        // navigations.
+        // Increased in case we throttle the network requests
+        const networkMultiplier = getNetworkMultiplierFromString(this.getNetworkConditions());
+        page.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT * networkMultiplier);
+    }
+    getNavigationTimeout() {
+        const page = this.getSelectedPage();
+        return page.getDefaultNavigationTimeout();
+    }
+    async getElementByUid(uid) {
+        if (!this.#textSnapshot?.idToNode.size) {
+            throw new Error('No snapshot found. Use browser_snapshot to capture one');
+        }
+        const [snapshotId] = uid.split('_');
+        if (this.#textSnapshot.snapshotId !== snapshotId) {
+            throw new Error('This uid is coming from a stale snapshot. Call take_snapshot to get a fresh snapshot.');
+        }
+        const node = this.#textSnapshot?.idToNode.get(uid);
+        if (!node) {
+            throw new Error('No such element found in the snapshot');
+        }
+        const handle = await node.elementHandle();
+        if (!handle) {
+            throw new Error('No such element found in the snapshot');
+        }
+        return handle;
+    }
+    /**
+     * Creates a snapshot of the pages.
+     */
+    async createPagesSnapshot() {
+        this.#pages = await this.browser.pages();
+        return this.#pages;
+    }
+    getPages() {
+        return this.#pages;
+    }
+    /**
+     * Creates a text snapshot of a page.
+     */
+    async createTextSnapshot() {
+        const page = this.getSelectedPage();
+        const rootNode = await page.accessibility.snapshot();
+        if (!rootNode) {
+            return;
+        }
+        const snapshotId = this.#nextSnapshotId++;
+        // Iterate through the whole accessibility node tree and assign node ids that
+        // will be used for the tree serialization and mapping ids back to nodes.
+        let idCounter = 0;
+        const idToNode = new Map();
+        const assignIds = (node) => {
+            const nodeWithId = {
+                ...node,
+                id: `${snapshotId}_${idCounter++}`,
+                children: node.children
+                    ? node.children.map(child => assignIds(child))
+                    : [],
+            };
+            idToNode.set(nodeWithId.id, nodeWithId);
+            return nodeWithId;
+        };
+        const rootNodeWithId = assignIds(rootNode);
+        this.#textSnapshot = {
+            root: rootNodeWithId,
+            snapshotId: String(snapshotId),
+            idToNode,
+        };
+    }
+    getTextSnapshot() {
+        return this.#textSnapshot;
+    }
+    async saveTemporaryFile(data, mimeType) {
+        try {
+            const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'chrome-devtools-mcp-'));
+            const filename = path.join(dir, mimeType == 'image/png' ? `screenshot.png` : 'screenshot.jpg');
+            await fs.writeFile(path.join(dir, `screenshot.png`), data);
+            return { filename };
+        }
+        catch (err) {
+            this.logger(err);
+            throw new Error('Could not save a screenshot to a file');
+        }
+    }
+    storeTraceRecording(result) {
+        this.#traceResults.push(result);
+    }
+    recordedTraces() {
+        return this.#traceResults;
+    }
+    getWaitForHelper(page, cpuMultiplier, networkMultiplier) {
+        return new WaitForHelper(page, cpuMultiplier, networkMultiplier);
+    }
+    waitForEventsAfterAction(action) {
+        const page = this.getSelectedPage();
+        const cpuMultiplier = this.getCpuThrottlingRate();
+        const networkMultiplier = getNetworkMultiplierFromString(this.getNetworkConditions());
+        const waitForHelper = this.getWaitForHelper(page, cpuMultiplier, networkMultiplier);
+        return waitForHelper.waitForEventsAfterAction(action);
+    }
+}

package/build/src/McpResponse.js

@@ -0,0 +1,223 @@
+import { formatConsoleEvent } from './formatters/consoleFormatter.js';
+import { getFormattedHeaderValue, getShortDescriptionForRequest, getStatusFromRequest, } from './formatters/networkFormatter.js';
+import { formatA11ySnapshot } from './formatters/snapshotFormatter.js';
+import { paginate } from './utils/pagination.js';
+export class McpResponse {
+    #includePages = false;
+    #includeSnapshot = false;
+    #attachedNetworkRequestUrl;
+    #includeConsoleData = false;
+    #textResponseLines = [];
+    #formattedConsoleData;
+    #images = [];
+    #networkRequestsOptions;
+    setIncludePages(value) {
+        this.#includePages = value;
+    }
+    setIncludeSnapshot(value) {
+        this.#includeSnapshot = value;
+    }
+    setIncludeNetworkRequests(value, options) {
+        if (!value) {
+            this.#networkRequestsOptions = undefined;
+            return;
+        }
+        this.#networkRequestsOptions = {
+            include: value,
+            pagination: options?.pageSize || options?.pageIdx
+                ? {
+                    pageSize: options.pageSize,
+                    pageIdx: options.pageIdx,
+                }
+                : undefined,
+            resourceTypes: options?.resourceTypes,
+        };
+    }
+    setIncludeConsoleData(value) {
+        this.#includeConsoleData = value;
+    }
+    attachNetworkRequest(url) {
+        this.#attachedNetworkRequestUrl = url;
+    }
+    get includePages() {
+        return this.#includePages;
+    }
+    get includeNetworkRequests() {
+        return this.#networkRequestsOptions?.include ?? false;
+    }
+    get includeConsoleData() {
+        return this.#includeConsoleData;
+    }
+    get attachedNetworkRequestUrl() {
+        return this.#attachedNetworkRequestUrl;
+    }
+    get networkRequestsPageIdx() {
+        return this.#networkRequestsOptions?.pagination?.pageIdx;
+    }
+    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.#formattedConsoleData = 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}`);
+            response.push(`Navigation timeout set to ${context.getNavigationTimeout()} ms`);
+        }
+        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 snapshot = context.getTextSnapshot();
+            if (snapshot) {
+                const formattedSnapshot = formatA11ySnapshot(snapshot.root);
+                response.push('## Page content');
+                response.push(formattedSnapshot);
+            }
+        }
+        response.push(...this.#getIncludeNetworkRequestsData(context));
+        if (this.#networkRequestsOptions?.include) {
+            let requests = context.getNetworkRequests();
+            // Apply resource type filtering if specified
+            if (this.#networkRequestsOptions.resourceTypes?.length) {
+                const normalizedTypes = new Set(this.#networkRequestsOptions.resourceTypes);
+                requests = requests.filter(request => {
+                    const type = request.resourceType();
+                    return normalizedTypes.has(type);
+                });
+            }
+            response.push('## Network requests');
+            if (requests.length) {
+                const paginationResult = paginate(requests, this.#networkRequestsOptions.pagination);
+                if (paginationResult.invalidPage) {
+                    response.push('Invalid page number provided. Showing first page.');
+                }
+                const { startIndex, endIndex, currentPage, totalPages } = paginationResult;
+                response.push(`Showing ${startIndex + 1}-${endIndex} of ${requests.length} (Page ${currentPage + 1} of ${totalPages}).`);
+                if (this.#networkRequestsOptions.pagination) {
+                    if (paginationResult.hasNextPage) {
+                        response.push(`Next page: ${currentPage + 1}`);
+                    }
+                    if (paginationResult.hasPreviousPage) {
+                        response.push(`Previous page: ${currentPage - 1}`);
+                    }
+                }
+                for (const request of paginationResult.items) {
+                    response.push(getShortDescriptionForRequest(request));
+                }
+            }
+            else {
+                response.push('No requests found.');
+            }
+        }
+        if (this.#includeConsoleData && this.#formattedConsoleData) {
+            response.push('## Console messages');
+            if (this.#formattedConsoleData.length) {
+                response.push(...this.#formattedConsoleData);
+            }
+            else {
+                response.push('<no console messages found>');
+            }
+        }
+        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)));
+    }
+}