ideamans-chrome-devtools-mcp 0.11.2

package/build/src/cli.js

@@ -0,0 +1,213 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { yargs, hideBin } from './third_party/index.js';
+export const cliOptions = {
+    browserUrl: {
+        type: 'string',
+        description: 'Connect to a running Chrome instance using port forwarding. For more details see: https://developer.chrome.com/docs/devtools/remote-debugging/local-server.',
+        alias: 'u',
+        conflicts: 'wsEndpoint',
+        coerce: (url) => {
+            if (!url) {
+                return;
+            }
+            try {
+                new URL(url);
+            }
+            catch {
+                throw new Error(`Provided browserUrl ${url} is not valid URL.`);
+            }
+            return url;
+        },
+    },
+    wsEndpoint: {
+        type: 'string',
+        description: 'WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.',
+        alias: 'w',
+        conflicts: 'browserUrl',
+        coerce: (url) => {
+            if (!url) {
+                return;
+            }
+            try {
+                const parsed = new URL(url);
+                if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+                    throw new Error(`Provided wsEndpoint ${url} must use ws:// or wss:// protocol.`);
+                }
+                return url;
+            }
+            catch (error) {
+                if (error.message.includes('ws://')) {
+                    throw error;
+                }
+                throw new Error(`Provided wsEndpoint ${url} is not valid URL.`);
+            }
+        },
+    },
+    wsHeaders: {
+        type: 'string',
+        description: 'Custom headers for WebSocket connection in JSON format (e.g., \'{"Authorization":"Bearer token"}\'). Only works with --wsEndpoint.',
+        implies: 'wsEndpoint',
+        coerce: (val) => {
+            if (!val) {
+                return;
+            }
+            try {
+                const parsed = JSON.parse(val);
+                if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+                    throw new Error('Headers must be a JSON object');
+                }
+                return parsed;
+            }
+            catch (error) {
+                throw new Error(`Invalid JSON for wsHeaders: ${error.message}`);
+            }
+        },
+    },
+    headless: {
+        type: 'boolean',
+        description: 'Whether to run in headless (no UI) mode.',
+        default: false,
+    },
+    executablePath: {
+        type: 'string',
+        description: 'Path to custom Chrome executable.',
+        conflicts: ['browserUrl', 'wsEndpoint'],
+        alias: 'e',
+    },
+    isolated: {
+        type: 'boolean',
+        description: 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.',
+    },
+    userDataDir: {
+        type: 'string',
+        description: 'Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE',
+        conflicts: ['browserUrl', 'wsEndpoint', 'isolated'],
+    },
+    channel: {
+        type: 'string',
+        description: 'Specify a different Chrome channel that should be used. The default is the stable channel version.',
+        choices: ['stable', 'canary', 'beta', 'dev'],
+        conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],
+    },
+    logFile: {
+        type: 'string',
+        describe: 'Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.',
+    },
+    viewport: {
+        type: 'string',
+        describe: 'Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.',
+        coerce: (arg) => {
+            if (arg === undefined) {
+                return;
+            }
+            const [width, height] = arg.split('x').map(Number);
+            if (!width || !height || Number.isNaN(width) || Number.isNaN(height)) {
+                throw new Error('Invalid viewport. Expected format is `1280x720`.');
+            }
+            return {
+                width,
+                height,
+            };
+        },
+    },
+    proxyServer: {
+        type: 'string',
+        description: `Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.`,
+    },
+    acceptInsecureCerts: {
+        type: 'boolean',
+        description: `If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.`,
+    },
+    experimentalDevtools: {
+        type: 'boolean',
+        describe: 'Whether to enable automation over DevTools targets',
+        hidden: true,
+    },
+    experimentalIncludeAllPages: {
+        type: 'boolean',
+        describe: 'Whether to include all kinds of pages such as webviews or background pages as pages.',
+        hidden: true,
+    },
+    chromeArg: {
+        type: 'array',
+        describe: 'Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.',
+    },
+    categoryEmulation: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to emulation.',
+    },
+    categoryPerformance: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to performance.',
+    },
+    categoryNetwork: {
+        type: 'boolean',
+        default: true,
+        describe: 'Set to false to exclude tools related to network.',
+    },
+};
+export function parseArguments(version, argv = process.argv) {
+    const yargsInstance = yargs(hideBin(argv))
+        .scriptName('npx chrome-devtools-mcp@latest')
+        .options(cliOptions)
+        .check(args => {
+        // We can't set default in the options else
+        // Yargs will complain
+        if (!args.channel &&
+            !args.browserUrl &&
+            !args.wsEndpoint &&
+            !args.executablePath) {
+            args.channel = 'stable';
+        }
+        return true;
+    })
+        .example([
+        [
+            '$0 --browserUrl http://127.0.0.1:9222',
+            'Connect to an existing browser instance via HTTP',
+        ],
+        [
+            '$0 --wsEndpoint ws://127.0.0.1:9222/devtools/browser/abc123',
+            'Connect to an existing browser instance via WebSocket',
+        ],
+        [
+            `$0 --wsEndpoint ws://127.0.0.1:9222/devtools/browser/abc123 --wsHeaders '{"Authorization":"Bearer token"}'`,
+            'Connect via WebSocket with custom headers',
+        ],
+        ['$0 --channel beta', 'Use Chrome Beta installed on this system'],
+        ['$0 --channel canary', 'Use Chrome Canary installed on this system'],
+        ['$0 --channel dev', 'Use Chrome Dev installed on this system'],
+        ['$0 --channel stable', 'Use stable Chrome installed on this system'],
+        ['$0 --logFile /tmp/log.txt', 'Save logs to a file'],
+        ['$0 --help', 'Print CLI options'],
+        [
+            '$0 --viewport 1280x720',
+            'Launch Chrome with the initial viewport size of 1280x720px',
+        ],
+        [
+            `$0 --chrome-arg='--no-sandbox' --chrome-arg='--disable-setuid-sandbox'`,
+            'Launch Chrome without sandboxes. Use with caution.',
+        ],
+        ['$0 --no-category-emulation', 'Disable tools in the emulation category'],
+        [
+            '$0 --no-category-performance',
+            'Disable tools in the performance category',
+        ],
+        ['$0 --no-category-network', 'Disable tools in the network category'],
+        [
+            '$0 --user-data-dir=/tmp/user-data-dir',
+            'Use a custom user data directory',
+        ],
+    ]);
+    return yargsInstance
+        .wrap(Math.min(120, yargsInstance.terminalWidth()))
+        .help()
+        .version(version)
+        .parseSync();
+}

package/build/src/features.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+let issuesEnabled = false;
+export const features = {
+    get issues() {
+        return issuesEnabled;
+    },
+};
+export function setIssuesEnabled(value) {
+    issuesEnabled = value;
+}

package/build/src/formatters/consoleFormatter.js

@@ -0,0 +1,121 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// The short format for a console message, based on a previous format.
+export function formatConsoleEventShort(msg) {
+    if (msg.type === 'issue') {
+        return `msgid=${msg.consoleMessageStableId} [${msg.type}] ${msg.message} (count: ${msg.count})`;
+    }
+    return `msgid=${msg.consoleMessageStableId} [${msg.type}] ${msg.message} (${msg.args?.length ?? 0} args)`;
+}
+function getArgs(msg) {
+    const args = [...(msg.args ?? [])];
+    // If there is no text, the first argument serves as text (see formatMessage).
+    if (!msg.message) {
+        args.shift();
+    }
+    return args;
+}
+// The verbose format for a console message, including all details.
+export function formatConsoleEventVerbose(msg, context) {
+    const aggregatedIssue = msg.item;
+    const result = [
+        `ID: ${msg.consoleMessageStableId}`,
+        `Message: ${msg.type}> ${aggregatedIssue ? formatIssue(aggregatedIssue, msg.description, context) : msg.message}`,
+        aggregatedIssue ? undefined : formatArgs(msg),
+    ].filter(line => !!line);
+    return result.join('\n');
+}
+function formatArg(arg) {
+    return typeof arg === 'object' ? JSON.stringify(arg) : String(arg);
+}
+function formatArgs(consoleData) {
+    const args = getArgs(consoleData);
+    if (!args.length) {
+        return '';
+    }
+    const result = ['### Arguments'];
+    for (const [key, arg] of args.entries()) {
+        result.push(`Arg #${key}: ${formatArg(arg)}`);
+    }
+    return result.join('\n');
+}
+export function formatIssue(issue, description, context) {
+    const result = [];
+    let processedMarkdown = description?.trim();
+    // Remove heading in order not to conflict with the whole console message response markdown
+    if (processedMarkdown?.startsWith('# ')) {
+        processedMarkdown = processedMarkdown.substring(2).trimStart();
+    }
+    if (processedMarkdown)
+        result.push(processedMarkdown);
+    const links = issue.getDescription()?.links;
+    if (links && links.length > 0) {
+        result.push('Learn more:');
+        for (const link of links) {
+            result.push(`[${link.linkTitle}](${link.link})`);
+        }
+    }
+    const issues = issue.getAllIssues();
+    const affectedResources = [];
+    for (const singleIssue of issues) {
+        const details = singleIssue.details();
+        if (!details)
+            continue;
+        // We send the remaining details as untyped JSON because the DevTools
+        // frontend code is currently not re-usable.
+        // eslint-disable-next-line
+        const data = structuredClone(details);
+        let uid;
+        let request;
+        if ('violatingNodeId' in details && details.violatingNodeId && context) {
+            uid = context.resolveCdpElementId(details.violatingNodeId);
+            delete data.violatingNodeId;
+        }
+        if ('nodeId' in details && details.nodeId && context) {
+            uid = context.resolveCdpElementId(details.nodeId);
+            delete data.nodeId;
+        }
+        if ('documentNodeId' in details && details.documentNodeId && context) {
+            uid = context.resolveCdpElementId(details.documentNodeId);
+            delete data.documentNodeId;
+        }
+        if ('request' in details && details.request) {
+            request = details.request.url;
+            if (details.request.requestId && context) {
+                const resolvedId = context.resolveCdpRequestId(details.request.requestId);
+                if (resolvedId) {
+                    request = resolvedId;
+                    delete data.request.requestId;
+                }
+            }
+        }
+        // These fields has no use for the MCP client (redundant or irrelevant).
+        delete data.errorType;
+        delete data.frameId;
+        affectedResources.push({
+            uid,
+            data: data,
+            request,
+        });
+    }
+    if (affectedResources.length) {
+        result.push('### Affected resources');
+    }
+    result.push(...affectedResources.map(item => {
+        const details = [];
+        if (item.uid)
+            details.push(`uid=${item.uid}`);
+        if (item.request) {
+            details.push((typeof item.request === 'number' ? `reqid=` : 'url=') + item.request);
+        }
+        if (item.data)
+            details.push(`data=${JSON.stringify(item.data)}`);
+        return details.join(' ');
+    }));
+    if (result.length === 0)
+        return 'No affected resources found';
+    return result.join('\n');
+}

package/build/src/formatters/networkFormatter.js

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isUtf8 } from 'node:buffer';
+const BODY_CONTEXT_SIZE_LIMIT = 10000;
+export function getShortDescriptionForRequest(request, id, selectedInDevToolsUI = false) {
+    // TODO truncate the URL
+    return `reqid=${id} ${request.method()} ${request.url()} ${getStatusFromRequest(request)}${selectedInDevToolsUI ? ` [selected in the DevTools Network panel]` : ''}`;
+}
+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;
+}
+export async function getFormattedResponseBody(httpResponse, sizeLimit = BODY_CONTEXT_SIZE_LIMIT) {
+    try {
+        const responseBuffer = await httpResponse.buffer();
+        if (isUtf8(responseBuffer)) {
+            const responseAsTest = responseBuffer.toString('utf-8');
+            if (responseAsTest.length === 0) {
+                return `<empty response>`;
+            }
+            return `${getSizeLimitedString(responseAsTest, sizeLimit)}`;
+        }
+        return `<binary data>`;
+    }
+    catch {
+        return `<not available anymore>`;
+    }
+}
+export async function getFormattedRequestBody(httpRequest, sizeLimit = BODY_CONTEXT_SIZE_LIMIT) {
+    if (httpRequest.hasPostData()) {
+        const data = httpRequest.postData();
+        if (data) {
+            return `${getSizeLimitedString(data, sizeLimit)}`;
+        }
+        try {
+            const fetchData = await httpRequest.fetchPostData();
+            if (fetchData) {
+                return `${getSizeLimitedString(fetchData, sizeLimit)}`;
+            }
+        }
+        catch {
+            return `<not available anymore>`;
+        }
+    }
+    return;
+}
+function getSizeLimitedString(text, sizeLimit) {
+    if (text.length > sizeLimit) {
+        return `${text.substring(0, sizeLimit) + '... <truncated>'}`;
+    }
+    return `${text}`;
+}

package/build/src/formatters/snapshotFormatter.js

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export function formatSnapshotNode(root, snapshot, depth = 0) {
+    const chunks = [];
+    if (depth === 0) {
+        // Top-level content of the snapshot.
+        if (snapshot?.verbose &&
+            snapshot?.hasSelectedElement &&
+            !snapshot.selectedElementUid) {
+            chunks.push(`Note: there is a selected element in the DevTools Elements panel but it is not included into the current a11y tree snapshot.
+Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
+        }
+    }
+    const attributes = getAttributes(root);
+    const line = ' '.repeat(depth * 2) +
+        attributes.join(' ') +
+        (root.id === snapshot?.selectedElementUid
+            ? ' [selected in the DevTools Elements panel]'
+            : '') +
+        '\n';
+    chunks.push(line);
+    for (const child of root.children) {
+        chunks.push(formatSnapshotNode(child, snapshot, depth + 1));
+    }
+    return chunks.join('');
+}
+function getAttributes(serializedAXNodeRoot) {
+    const attributes = [`uid=${serializedAXNodeRoot.id}`];
+    if (serializedAXNodeRoot.role) {
+        // To match representation in DevTools.
+        attributes.push(serializedAXNodeRoot.role === 'none'
+            ? 'ignored'
+            : serializedAXNodeRoot.role);
+    }
+    if (serializedAXNodeRoot.name) {
+        attributes.push(`"${serializedAXNodeRoot.name}"`);
+    }
+    const excluded = new Set([
+        'id',
+        'role',
+        'name',
+        'elementHandle',
+        'children',
+        'backendNodeId',
+    ]);
+    const booleanPropertyMap = {
+        disabled: 'disableable',
+        expanded: 'expandable',
+        focused: 'focusable',
+        selected: 'selectable',
+    };
+    for (const attr of Object.keys(serializedAXNodeRoot).sort()) {
+        if (excluded.has(attr)) {
+            continue;
+        }
+        const value = serializedAXNodeRoot[attr];
+        if (typeof value === 'boolean') {
+            if (booleanPropertyMap[attr]) {
+                attributes.push(booleanPropertyMap[attr]);
+            }
+            if (value) {
+                attributes.push(attr);
+            }
+        }
+        else if (typeof value === 'string' || typeof value === 'number') {
+            attributes.push(`${attr}="${value}"`);
+        }
+    }
+    return attributes;
+}

package/build/src/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { version } from 'node:process';
+const [major, minor] = version.substring(1).split('.').map(Number);
+if (major === 20 && minor < 19) {
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+if (major === 22 && minor < 12) {
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 22.12.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+if (major < 20) {
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 20.19.0 LTS or a newer LTS.`);
+    process.exit(1);
+}
+await import('./main.js');

package/build/src/issue-descriptions.js

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DESCRIPTIONS_PATH = path.join(import.meta.dirname, '../node_modules/chrome-devtools-frontend/front_end/models/issues_manager/descriptions');
+let issueDescriptions = {};
+/**
+ * Reads all issue descriptions from the filesystem into memory.
+ */
+export async function loadIssueDescriptions() {
+    if (Object.keys(issueDescriptions).length > 0) {
+        return;
+    }
+    const files = await fs.promises.readdir(DESCRIPTIONS_PATH);
+    const descriptions = {};
+    for (const file of files) {
+        if (!file.endsWith('.md')) {
+            continue;
+        }
+        const content = await fs.promises.readFile(path.join(DESCRIPTIONS_PATH, file), 'utf-8');
+        descriptions[file] = content;
+    }
+    issueDescriptions = descriptions;
+}
+/**
+ * Gets an issue description from the in-memory cache.
+ * @param fileName The file name of the issue description.
+ * @returns The description of the issue, or null if it doesn't exist.
+ */
+export function getIssueDescription(fileName) {
+    return issueDescriptions[fileName] ?? null;
+}
+export const ISSUE_UTILS = {
+    loadIssueDescriptions,
+    getIssueDescription,
+};

package/build/src/logger.js

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import { debug } from './third_party/index.js';
+const mcpDebugNamespace = 'mcp:log';
+const namespacesToEnable = [
+    mcpDebugNamespace,
+    ...(process.env['DEBUG'] ? [process.env['DEBUG']] : []),
+];
+export function saveLogsToFile(fileName) {
+    // Enable overrides everything so we need to add them
+    debug.enable(namespacesToEnable.join(','));
+    const logFile = fs.createWriteStream(fileName, { flags: 'a+' });
+    debug.log = function (...chunks) {
+        logFile.write(`${chunks.join(' ')}\n`);
+    };
+    logFile.on('error', function (error) {
+        console.error(`Error when opening/writing to log file: ${error.message}`);
+        logFile.end();
+        process.exit(1);
+    });
+    return logFile;
+}
+export const logger = debug(mcpDebugNamespace);