chrome-devtools-mcp-for-extension 0.5.0

package/build/src/WaitForHelper.js

@@ -0,0 +1,134 @@
+import { logger } from './logger.js';
+export class WaitForHelper {
+    #abortController = new AbortController();
+    #page;
+    #stableDomTimeout;
+    #stableDomFor;
+    #expectNavigationIn;
+    #navigationTimeout;
+    constructor(page, cpuTimeoutMultiplier, networkTimeoutMultiplier) {
+        this.#stableDomTimeout = 3000 * cpuTimeoutMultiplier;
+        this.#stableDomFor = 100 * cpuTimeoutMultiplier;
+        this.#expectNavigationIn = 100 * cpuTimeoutMultiplier;
+        this.#navigationTimeout = 3000 * networkTimeoutMultiplier;
+        this.#page = page;
+    }
+    /**
+     * A wrapper that executes a action and waits for
+     * a potential navigation, after which it waits
+     * for the DOM to be stable before returning.
+     */
+    async waitForStableDom() {
+        const stableDomObserver = await this.#page.evaluateHandle(timeout => {
+            let timeoutId;
+            function callback() {
+                clearTimeout(timeoutId);
+                timeoutId = setTimeout(() => {
+                    domObserver.resolver.resolve();
+                    domObserver.observer.disconnect();
+                }, timeout);
+            }
+            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;
+        }, this.#stableDomFor);
+        this.#abortController.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;
+            }),
+            this.timeout(this.#stableDomTimeout).then(() => {
+                throw new Error('Timeout');
+            }),
+        ]);
+    }
+    async waitForNavigationStarted() {
+        // 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);
+            };
+            this.#page._client().on('Page.frameStartedNavigating', listener);
+            this.#abortController.signal.addEventListener('abort', () => {
+                resolve(false);
+                this.#page._client().off('Page.frameStartedNavigating', listener);
+            });
+        });
+        return await Promise.race([
+            navigationStartedPromise,
+            this.timeout(this.#expectNavigationIn).then(() => false),
+        ]);
+    }
+    timeout(time) {
+        return new Promise(res => {
+            const id = setTimeout(res, time);
+            this.#abortController.signal.addEventListener('abort', () => {
+                res();
+                clearTimeout(id);
+            });
+        });
+    }
+    async waitForEventsAfterAction(action) {
+        const navigationFinished = this.waitForNavigationStarted()
+            .then(navigationStated => {
+            if (navigationStated) {
+                return this.#page.waitForNavigation({
+                    timeout: this.#navigationTimeout,
+                    signal: this.#abortController.signal,
+                });
+            }
+            return;
+        })
+            .catch(error => logger(error));
+        try {
+            await action();
+        }
+        catch (error) {
+            // Clear up pending promises
+            this.#abortController.abort();
+            throw error;
+        }
+        try {
+            await navigationFinished;
+            // Wait for stable dom after navigation so we execute in
+            // the correct context
+            await this.waitForStableDom();
+        }
+        catch (error) {
+            logger(error);
+        }
+        finally {
+            this.#abortController.abort();
+        }
+    }
+}

package/build/src/browser.js

@@ -0,0 +1,493 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import fs from 'node:fs';
+import { promises as fsPromises } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import puppeteer from 'puppeteer-core';
+import { detectSystemChromeProfile, detectAnySystemChromeProfile, } from './system-profile.js';
+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;
+}
+function scanExtensionsDirectory(extensionsDir) {
+    const extensionPaths = [];
+    try {
+        if (!fs.existsSync(extensionsDir)) {
+            console.warn(`Extensions directory not found: ${extensionsDir}`);
+            return extensionPaths;
+        }
+        const entries = fs.readdirSync(extensionsDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const extensionPath = path.join(extensionsDir, entry.name);
+                const manifestPath = path.join(extensionPath, 'manifest.json');
+                // First, check if manifest.json exists in the root directory
+                if (fs.existsSync(manifestPath)) {
+                    try {
+                        const manifestContent = fs.readFileSync(manifestPath, 'utf-8');
+                        const manifest = JSON.parse(manifestContent);
+                        if (manifest.manifest_version) {
+                            extensionPaths.push(extensionPath);
+                            console.error(`Found extension: ${entry.name} (v${manifest.version || 'unknown'})`);
+                        }
+                    }
+                    catch (error) {
+                        console.warn(`Invalid manifest.json in ${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
+                else {
+                    // If not found in root, check common subdirectories
+                    const subDirs = ['extension', 'dist', 'dist-simple', 'build', 'src'];
+                    for (const subDir of subDirs) {
+                        const subPath = path.join(extensionPath, subDir);
+                        const subManifestPath = path.join(subPath, 'manifest.json');
+                        if (fs.existsSync(subManifestPath)) {
+                            try {
+                                const manifestContent = fs.readFileSync(subManifestPath, 'utf-8');
+                                const manifest = JSON.parse(manifestContent);
+                                if (manifest.manifest_version) {
+                                    extensionPaths.push(subPath);
+                                    console.error(`Found extension: ${entry.name}/${subDir} (v${manifest.version || 'unknown'})`);
+                                    break; // Use the first valid subdirectory found
+                                }
+                            }
+                            catch (error) {
+                                console.warn(`Invalid manifest.json in ${entry.name}/${subDir}: ${error instanceof Error ? error.message : String(error)}`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        console.error(`Scanned ${extensionsDir}: found ${extensionPaths.length} valid extensions`);
+    }
+    catch (error) {
+        console.error(`Error scanning extensions directory ${extensionsDir}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return extensionPaths;
+}
+/**
+ * Get the Chrome extensions directory path for the current platform
+ */
+function getChromeExtensionsDirectory(channel) {
+    const homeDir = os.homedir();
+    const platform = os.platform();
+    let chromeDataPath;
+    let profileName = 'Default';
+    if (platform === 'darwin') {
+        // macOS
+        chromeDataPath = path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome');
+        if (channel === 'canary') {
+            chromeDataPath = path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome Canary');
+        }
+        else if (channel === 'beta') {
+            chromeDataPath = path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome Beta');
+        }
+        else if (channel === 'dev') {
+            chromeDataPath = path.join(homeDir, 'Library', 'Application Support', 'Google', 'Chrome Dev');
+        }
+    }
+    else if (platform === 'win32') {
+        // Windows
+        chromeDataPath = path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome', 'User Data');
+        if (channel === 'canary') {
+            chromeDataPath = path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome SxS', 'User Data');
+        }
+        else if (channel === 'beta') {
+            chromeDataPath = path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome Beta', 'User Data');
+        }
+        else if (channel === 'dev') {
+            chromeDataPath = path.join(homeDir, 'AppData', 'Local', 'Google', 'Chrome Dev', 'User Data');
+        }
+    }
+    else {
+        // Linux
+        chromeDataPath = path.join(homeDir, '.config', 'google-chrome');
+        if (channel === 'canary') {
+            chromeDataPath = path.join(homeDir, '.config', 'google-chrome-unstable');
+        }
+        else if (channel === 'beta') {
+            chromeDataPath = path.join(homeDir, '.config', 'google-chrome-beta');
+        }
+        else if (channel === 'dev') {
+            chromeDataPath = path.join(homeDir, '.config', 'google-chrome-unstable');
+        }
+    }
+    return path.join(chromeDataPath, profileName, 'Extensions');
+}
+function validateExtensionManifest(manifestPath) {
+    try {
+        if (!fs.existsSync(manifestPath)) {
+            return null;
+        }
+        const manifestContent = fs.readFileSync(manifestPath, 'utf-8');
+        const manifest = JSON.parse(manifestContent);
+        // Basic validation
+        if (!manifest.manifest_version || !manifest.name || !manifest.version) {
+            return null;
+        }
+        // Ensure it's a valid manifest version (2 or 3)
+        if (manifest.manifest_version !== 2 && manifest.manifest_version !== 3) {
+            return null;
+        }
+        return manifest;
+    }
+    catch (error) {
+        console.warn(`Invalid manifest.json at ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Discover Chrome extensions installed in the system
+ */
+function discoverSystemExtensions(channel) {
+    const extensionPaths = [];
+    const extensionsDir = getChromeExtensionsDirectory(channel);
+    console.error(`🔍 Discovering system Chrome extensions in: ${extensionsDir}`);
+    try {
+        if (!fs.existsSync(extensionsDir)) {
+            console.warn(`System Chrome extensions directory not found: ${extensionsDir}`);
+            return extensionPaths;
+        }
+        const extensionIds = fs.readdirSync(extensionsDir, { withFileTypes: true });
+        for (const extensionEntry of extensionIds) {
+            if (!extensionEntry.isDirectory())
+                continue;
+            const extensionIdPath = path.join(extensionsDir, extensionEntry.name);
+            try {
+                // Each extension ID directory contains version subdirectories
+                const versions = fs.readdirSync(extensionIdPath, { withFileTypes: true });
+                // Find the latest/most recent version
+                let latestVersion = '';
+                let latestPath = '';
+                for (const versionEntry of versions) {
+                    if (!versionEntry.isDirectory())
+                        continue;
+                    const versionPath = path.join(extensionIdPath, versionEntry.name);
+                    const manifestPath = path.join(versionPath, 'manifest.json');
+                    const manifest = validateExtensionManifest(manifestPath);
+                    if (manifest) {
+                        // Use the first valid version found (Chrome keeps the latest active)
+                        if (!latestVersion || versionEntry.name > latestVersion) {
+                            latestVersion = versionEntry.name;
+                            latestPath = versionPath;
+                        }
+                    }
+                }
+                if (latestPath && latestVersion) {
+                    const manifest = validateExtensionManifest(path.join(latestPath, 'manifest.json'));
+                    if (manifest) {
+                        extensionPaths.push(latestPath);
+                        console.error(`  ✅ Found: ${manifest.name} v${manifest.version} (Manifest v${manifest.manifest_version})`);
+                    }
+                }
+            }
+            catch (error) {
+                console.warn(`Error processing extension ${extensionEntry.name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        console.error(`📦 System extension discovery complete: ${extensionPaths.length} valid extensions found`);
+    }
+    catch (error) {
+        console.error(`Error discovering system extensions: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return extensionPaths;
+}
+export async function launch(options) {
+    const { channel, executablePath, customDevTools, headless, isolated, loadExtension, loadExtensionsDir, loadSystemExtensions, } = options;
+    const profileDirName = channel && channel !== 'stable'
+        ? `chrome-profile-${channel}`
+        : 'chrome-profile';
+    let userDataDir = options.userDataDir;
+    let usingSystemProfile = false;
+    if (!isolated && !userDataDir) {
+        // Try to use system Chrome profile directly
+        const systemProfile = detectSystemChromeProfile(channel) || detectAnySystemChromeProfile();
+        if (systemProfile) {
+            // Use system profile directly for better user experience
+            userDataDir = systemProfile.path;
+            usingSystemProfile = true;
+            console.error(`✅ Using system Chrome profile: ${systemProfile.channel}`);
+            console.error(`   Path: ${userDataDir}`);
+            console.error(`   ⚠️  Note: Close regular Chrome if you encounter issues`);
+        }
+        else {
+            // Fallback to isolated profile if no system Chrome found
+            userDataDir = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', profileDirName);
+            await fs.promises.mkdir(userDataDir, {
+                recursive: true,
+            });
+            console.error(`📁 Using isolated profile (no system Chrome found)`);
+        }
+    }
+    const args = [
+        '--hide-crash-restore-bubble',
+        '--profile-directory=Default', // Ensure we use the Default profile
+    ];
+    if (customDevTools) {
+        args.push(`--custom-devtools-frontend=file://${customDevTools}`);
+    }
+    // Collect all extension paths
+    const extensionPaths = [];
+    if (loadExtension) {
+        // Validate single extension path
+        if (fs.existsSync(loadExtension)) {
+            const manifestPath = path.join(loadExtension, 'manifest.json');
+            if (fs.existsSync(manifestPath)) {
+                try {
+                    const manifestContent = fs.readFileSync(manifestPath, 'utf-8');
+                    const manifest = JSON.parse(manifestContent);
+                    if (manifest.manifest_version) {
+                        extensionPaths.push(loadExtension);
+                        console.error(`✅ Single extension validated: ${loadExtension}`);
+                    }
+                    else {
+                        console.error(`❌ Invalid manifest.json in ${loadExtension}: missing manifest_version`);
+                    }
+                }
+                catch (error) {
+                    console.error(`❌ Invalid manifest.json in ${loadExtension}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            else {
+                console.error(`❌ Extension path missing manifest.json: ${loadExtension}`);
+            }
+        }
+        else {
+            console.error(`❌ Extension path does not exist: ${loadExtension}`);
+        }
+    }
+    if (loadExtensionsDir) {
+        const scannedExtensions = scanExtensionsDirectory(loadExtensionsDir);
+        extensionPaths.push(...scannedExtensions);
+    }
+    // System extension discovery
+    if (loadSystemExtensions) {
+        const systemExtensions = discoverSystemExtensions(channel);
+        if (systemExtensions.length > 0) {
+            extensionPaths.push(...systemExtensions);
+            console.error(`🔗 Integrated ${systemExtensions.length} system extensions with development extensions`);
+        }
+        else {
+            console.warn(`⚠️  No system extensions found or accessible`);
+        }
+    }
+    if (extensionPaths.length > 0) {
+        args.push(`--load-extension=${extensionPaths.join(',')}`);
+        args.push('--enable-experimental-extension-apis');
+        // Fix for Chrome 137+ where --load-extension is disabled by default
+        args.push('--disable-features=DisableLoadExtensionCommandLineSwitch');
+        console.error(`Loading ${extensionPaths.length} Chrome extension(s):`);
+        extensionPaths.forEach((path, index) => {
+            console.error(`  ${index + 1}. ${path}`);
+        });
+        console.error(`Chrome args will include: --load-extension=${extensionPaths.join(',')}`);
+        console.error('Applied Chrome 137+ extension loading fix');
+    }
+    // Add Google login automation detection bypass
+    args.push('--disable-blink-features=AutomationControlled');
+    console.error('Added Google login bypass: --disable-blink-features=AutomationControlled');
+    let puppeterChannel;
+    if (!executablePath) {
+        puppeterChannel =
+            channel && channel !== 'stable'
+                ? `chrome-${channel}`
+                : 'chrome';
+    }
+    // Log complete Chrome configuration before launch
+    console.error('Chrome Launch Configuration:');
+    console.error(`  Channel: ${puppeterChannel || 'default'}`);
+    console.error(`  Executable: ${executablePath || 'auto-detected'}`);
+    console.error(`  User Data Dir: ${userDataDir || 'temporary'}`);
+    console.error(`  Profile Type: ${usingSystemProfile ? 'System Profile (auto-detected)' : 'Custom Profile'}`);
+    console.error(`  Headless: ${headless}`);
+    console.error(`  Args: ${JSON.stringify(args, null, 2)}`);
+    console.error(`  Ignored Default Args: ${extensionPaths.length > 0 ? '["--disable-extensions"]' : 'none'}`);
+    try {
+        const browser = await puppeteer.launch({
+            ...connectOptions,
+            channel: puppeterChannel,
+            executablePath,
+            defaultViewport: null,
+            userDataDir,
+            pipe: true,
+            headless,
+            args,
+            ignoreDefaultArgs: extensionPaths.length > 0 ? ['--disable-extensions', '--enable-automation'] : ['--enable-automation'],
+        });
+        if (options.logFile) {
+            // FIXME: we are probably subscribing too late to catch startup logs. We
+            // should expose the process earlier or expose the getRecentLogs() getter.
+            browser.process()?.stderr?.pipe(options.logFile);
+            browser.process()?.stdout?.pipe(options.logFile);
+        }
+        // Apply Google login automation detection bypass to all pages
+        browser.on('targetcreated', async (target) => {
+            if (target.type() === 'page') {
+                try {
+                    const page = await target.page();
+                    if (page) {
+                        await page.evaluateOnNewDocument(() => {
+                            Object.defineProperty(window.navigator, 'webdriver', {
+                                get: () => undefined,
+                                configurable: true
+                            });
+                        });
+                        console.error('Applied navigator.webdriver bypass to new page');
+                    }
+                }
+                catch (error) {
+                    console.error('Failed to apply webdriver bypass:', error);
+                }
+            }
+        });
+        // Apply bypass to existing pages
+        const initialPages = await browser.pages();
+        for (const page of initialPages) {
+            await page.evaluateOnNewDocument(() => {
+                Object.defineProperty(window.navigator, 'webdriver', {
+                    get: () => undefined,
+                    configurable: true
+                });
+            });
+            console.error('Applied navigator.webdriver bypass to existing page');
+        }
+        // Verify extensions were loaded by checking chrome://extensions/
+        if (extensionPaths.length > 0) {
+            console.error('🔍 Verifying extension loading...');
+            try {
+                const pages = await browser.pages();
+                const page = pages[0] || await browser.newPage();
+                // Add a small delay to ensure Chrome is fully started
+                await new Promise(resolve => setTimeout(resolve, 2000));
+                await page.goto('chrome://extensions/', { waitUntil: 'networkidle0' });
+                const loadedExtensions = await page.evaluate(() => {
+                    const extensionCards = document.querySelectorAll('extensions-item');
+                    const results = [];
+                    Array.from(extensionCards).forEach(card => {
+                        const shadowRoot = card.shadowRoot;
+                        if (shadowRoot) {
+                            const name = shadowRoot.querySelector('#name')?.textContent?.trim() || 'Unknown';
+                            const enabled = !shadowRoot.querySelector('#enable-toggle')?.hasAttribute('disabled');
+                            const id = card.getAttribute('id') || 'unknown';
+                            results.push({ name, id, enabled });
+                        }
+                    });
+                    return results;
+                });
+                console.error(`✅ Extensions verification complete. Found ${loadedExtensions.length} extensions:`);
+                loadedExtensions.forEach((ext, index) => {
+                    console.error(`  ${index + 1}. ${ext.name} (${ext.enabled ? 'enabled' : 'disabled'}) - ID: ${ext.id}`);
+                });
+                if (loadedExtensions.length === 0) {
+                    console.error('⚠️  No extensions found in chrome://extensions/ - this may indicate loading failure');
+                }
+            }
+            catch (verificationError) {
+                console.error(`⚠️  Extension verification failed: ${verificationError}`);
+            }
+        }
+        return browser;
+    }
+    catch (error) {
+        // When system profile is already in use, create a minimal copy for automation
+        if (usingSystemProfile &&
+            (error.message.includes('The browser is already running') ||
+                error.message.includes('Target closed') ||
+                error.message.includes('Connection closed'))) {
+            console.error(`⚠️  Chrome is already running with system profile.`);
+            console.error(`📋 Creating a temporary copy of system profile for automation...`);
+            // Create a temporary copy of the system profile
+            const tempProfileDir = path.join(os.tmpdir(), `chrome-mcp-${Date.now()}`);
+            try {
+                // Copy only essential data (bookmarks, extensions) without locking files
+                await fsPromises.mkdir(tempProfileDir, { recursive: true });
+                // Copy bookmarks if they exist
+                const bookmarksPath = path.join(userDataDir, 'Default', 'Bookmarks');
+                try {
+                    await fsPromises.access(bookmarksPath);
+                    const bookmarksDestDir = path.join(tempProfileDir, 'Default');
+                    await fsPromises.mkdir(bookmarksDestDir, { recursive: true });
+                    await fsPromises.copyFile(bookmarksPath, path.join(bookmarksDestDir, 'Bookmarks'));
+                    console.error(`✅ Bookmarks copied from system profile`);
+                }
+                catch {
+                    // Bookmarks don't exist or can't be accessed, skip
+                }
+                // Retry with the temporary profile by recursively calling launch
+                console.error(`🔄 Retrying with temporary profile copy...`);
+                const retryOptions = { ...options };
+                retryOptions.userDataDir = tempProfileDir;
+                return launch(retryOptions);
+            }
+            catch (copyError) {
+                console.error(`❌ Failed to create temporary profile copy: ${copyError}`);
+                // Fall through to regular error handling
+            }
+        }
+        // For non-system profiles, maintain the blocking behavior
+        if (!usingSystemProfile &&
+            userDataDir &&
+            (error.message.includes('The browser is already running') ||
+                error.message.includes('Target closed') ||
+                error.message.includes('Connection closed'))) {
+            throw new Error(`The browser is already running for custom profile: ${userDataDir}. Use --isolated to run multiple browser instances.`, {
+                cause: error,
+            });
+        }
+        // If system profile failed for other reasons, suggest fallback options
+        if (usingSystemProfile) {
+            console.error(`❌ Failed to launch Chrome with system profile: ${userDataDir}`);
+            console.error(`💡 Suggestion: Try with --isolated flag for temporary profile, or --userDataDir to specify custom location`);
+        }
+        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;
+}
+export { scanExtensionsDirectory, discoverSystemExtensions, getChromeExtensionsDirectory, validateExtensionManifest };