chrome-devtools-mcp-for-extension 0.5.0

package/build/src/cli.js

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+// Auto-detection functions for zero-config setup
+function getDefaultUserDataDir() {
+    return path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', 'chrome-profile');
+}
+function getDefaultExtensionsDir() {
+    const currentDir = process.cwd();
+    const extensionsDir = path.join(currentDir, 'extensions');
+    // Check if extensions directory exists and has valid extensions
+    if (fs.existsSync(extensionsDir)) {
+        try {
+            const entries = fs.readdirSync(extensionsDir, { withFileTypes: true });
+            const hasValidExtensions = entries.some(entry => {
+                if (entry.isDirectory()) {
+                    const manifestPath = path.join(extensionsDir, entry.name, 'manifest.json');
+                    if (fs.existsSync(manifestPath)) {
+                        try {
+                            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                            return manifest.manifest_version;
+                        }
+                        catch {
+                            return false;
+                        }
+                    }
+                }
+                return false;
+            });
+            if (hasValidExtensions) {
+                return extensionsDir;
+            }
+        }
+        catch {
+            // Ignore errors and return undefined
+        }
+    }
+    return undefined;
+}
+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',
+        coerce: (url) => {
+            new URL(url);
+            return url;
+        },
+    },
+    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',
+        alias: 'e',
+    },
+    isolated: {
+        type: 'boolean',
+        description: 'If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed.',
+        default: false,
+    },
+    customDevtools: {
+        type: 'string',
+        description: 'Path to custom DevTools.',
+        hidden: true,
+        conflicts: 'browserUrl',
+        alias: 'd',
+    },
+    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', 'executablePath'],
+    },
+    loadExtension: {
+        type: 'string',
+        description: 'Load an unpacked Chrome extension from the specified directory path.',
+        conflicts: 'browserUrl',
+    },
+    loadExtensionsDir: {
+        type: 'string',
+        description: 'Load all unpacked Chrome extensions from the specified directory. Each subdirectory with manifest.json will be loaded as an extension.',
+        conflicts: 'browserUrl',
+    },
+    loadSystemExtensions: {
+        type: 'boolean',
+        description: 'Automatically discover and load extensions installed in the system Chrome profile. This includes extensions from Chrome Web Store and sideloaded extensions.',
+        default: false,
+        conflicts: 'browserUrl',
+    },
+    userDataDir: {
+        type: 'string',
+        description: 'Specify a custom user data directory for Chrome to use instead of the default. Auto-detected if not specified.',
+        conflicts: 'browserUrl',
+    },
+    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.',
+    },
+};
+export function parseArguments(version, argv = process.argv) {
+    const yargsInstance = yargs(hideBin(argv))
+        .scriptName('npx chrome-devtools-mcp@latest')
+        .options(cliOptions)
+        .check(args => {
+        // Auto-configuration for zero-config setup
+        if (!args.channel && !args.browserUrl && !args.executablePath) {
+            args.channel = 'stable';
+        }
+        // Don't set userDataDir here - let browser.ts handle auto-detection
+        // This allows browser.ts to detect and use the system Chrome profile
+        // Auto-detect extensions directory if not specified
+        if (!args.loadExtensionsDir && !args.browserUrl) {
+            const autoExtensionsDir = getDefaultExtensionsDir();
+            if (autoExtensionsDir) {
+                args.loadExtensionsDir = autoExtensionsDir;
+                console.error(`🔧 Auto-detected extensions directory: ${autoExtensionsDir}`);
+            }
+        }
+        return true;
+    })
+        .example([
+        [
+            '$0',
+            'Zero-config startup: auto-detects extensions, bookmarks, and profile',
+        ],
+        [
+            '$0 --browserUrl http://127.0.0.1:9222',
+            'Connect to an existing browser instance',
+        ],
+        ['$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 --loadSystemExtensions', 'Auto-discover and load system Chrome extensions'],
+        ['$0 --loadExtensionsDir ./extensions --loadSystemExtensions', 'Load both development and system extensions'],
+        ['$0 --logFile /tmp/log.txt', 'Save logs to a file'],
+        ['$0 --help', 'Print CLI options'],
+    ]);
+    return yargsInstance
+        .wrap(Math.min(120, yargsInstance.terminalWidth()))
+        .help()
+        .version(version)
+        .parseSync();
+}

package/build/src/formatters/consoleFormatter.js

@@ -0,0 +1,73 @@
+/**
+ * @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(() => {
+        // Ignore errors
+    })));
+    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;
+}

package/build/src/index.js

@@ -0,0 +1,13 @@
+#!/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 < 22 || (major === 22 && minor < 12)) {
+    console.error(`ERROR: \`chrome-devtools-mcp\` does not support Node ${process.version}. Please upgrade to Node 22.12.0 or newer.`);
+    process.exit(1);
+}
+await import('./main.js');

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 'debug';
+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.log(`Error when opening/writing to log file: ${error.message}`);
+        logFile.end();
+        process.exit(1);
+    });
+    return logFile;
+}
+export const logger = debug(mcpDebugNamespace);

package/build/src/main.js

@@ -0,0 +1,139 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { resolveBrowser } from './browser.js';
+import { parseArguments } from './cli.js';
+import { logger, saveLogsToFile } from './logger.js';
+import { McpContext } from './McpContext.js';
+import { McpResponse } from './McpResponse.js';
+import { Mutex } from './Mutex.js';
+import * as bookmarkTools from './tools/bookmarks.js';
+import * as consoleTools from './tools/console.js';
+import * as emulationTools from './tools/emulation.js';
+import * as extensionTools from './tools/extensions.js';
+import * as inputTools from './tools/input.js';
+import * as networkTools from './tools/network.js';
+import * as pagesTools from './tools/pages.js';
+import * as performanceTools from './tools/performance.js';
+import * as screenshotTools from './tools/screenshot.js';
+import * as scriptTools from './tools/script.js';
+import * as snapshotTools from './tools/snapshot.js';
+function readPackageJson() {
+    const currentDir = import.meta.dirname;
+    const packageJsonPath = path.join(currentDir, '..', '..', 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return {};
+    }
+    try {
+        const json = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        assert.strict(json['name'], 'chrome-devtools-mcp');
+        return json;
+    }
+    catch {
+        return {};
+    }
+}
+const version = readPackageJson().version ?? 'unknown';
+export const args = parseArguments(version);
+const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+logger(`Starting Chrome DevTools MCP Server v${version}`);
+const server = new McpServer({
+    name: 'chrome_devtools',
+    title: 'Chrome DevTools MCP server',
+    version,
+}, { capabilities: { logging: {} } });
+server.server.setRequestHandler(SetLevelRequestSchema, () => {
+    return {};
+});
+let context;
+async function getContext() {
+    const browser = await resolveBrowser({
+        browserUrl: args.browserUrl,
+        headless: args.headless,
+        executablePath: args.executablePath,
+        customDevTools: args.customDevtools,
+        channel: args.channel,
+        isolated: args.isolated,
+        loadExtension: args.loadExtension,
+        loadExtensionsDir: args.loadExtensionsDir,
+        loadSystemExtensions: args.loadSystemExtensions,
+        userDataDir: args.userDataDir,
+        logFile,
+    });
+    if (context?.browser !== browser) {
+        context = await McpContext.from(browser, logger);
+    }
+    return context;
+}
+const logDisclaimers = () => {
+    console.error(`chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
+debug, and modify any data in the browser or DevTools.
+Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`);
+};
+const toolMutex = new Mutex();
+function registerTool(tool) {
+    server.registerTool(tool.name, {
+        description: tool.description,
+        inputSchema: tool.schema,
+        annotations: tool.annotations,
+    }, async (params) => {
+        const guard = await toolMutex.acquire();
+        try {
+            logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
+            const context = await getContext();
+            const response = new McpResponse();
+            await tool.handler({
+                params,
+            }, response, context);
+            try {
+                const content = await response.handle(tool.name, context);
+                return {
+                    content,
+                };
+            }
+            catch (error) {
+                const errorText = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: errorText,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        finally {
+            guard.dispose();
+        }
+    });
+}
+const tools = [
+    ...Object.values(bookmarkTools),
+    ...Object.values(consoleTools),
+    ...Object.values(emulationTools),
+    ...Object.values(extensionTools),
+    ...Object.values(inputTools),
+    ...Object.values(networkTools),
+    ...Object.values(pagesTools),
+    ...Object.values(performanceTools),
+    ...Object.values(screenshotTools),
+    ...Object.values(scriptTools),
+    ...Object.values(snapshotTools),
+];
+for (const tool of tools) {
+    registerTool(tool);
+}
+const transport = new StdioServerTransport();
+await server.connect(transport);
+logger('Chrome DevTools MCP Server connected');
+logDisclaimers();