chrome-ai-bridge 1.0.0

package/build/src/main.js

@@ -0,0 +1,268 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Mock browser globals for chrome-devtools-frontend (Node.js environment)
+// NOTE: chrome-devtools-frontend expects browser globals (location, self, localStorage)
+// These are only needed for trace-processing modules, not for core MCP functionality
+if (typeof globalThis.location === 'undefined') {
+    globalThis.location = {
+        search: '',
+        href: '',
+        protocol: 'file:',
+        host: '',
+        hostname: '',
+        port: '',
+        pathname: '',
+        hash: '',
+    };
+}
+if (typeof globalThis.self === 'undefined') {
+    globalThis.self = globalThis;
+}
+if (typeof globalThis.localStorage === 'undefined') {
+    globalThis.localStorage = {
+        getItem: () => null,
+        setItem: () => { },
+        removeItem: () => { },
+        clear: () => { },
+        key: () => null,
+        length: 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, RootsListChangedNotificationSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { resolveBrowser } from './browser.js';
+import { parseArguments } from './cli.js';
+import { setupGraceful } from './graceful.js';
+import { logger, saveLogsToFile } from './logger.js';
+import { McpContext } from './McpContext.js';
+import { McpResponse } from './McpResponse.js';
+import { Mutex } from './Mutex.js';
+import { ToolRegistry, PluginLoader } from './plugin-api.js';
+import { setProjectRoot } from './project-root-state.js';
+import { resolveRoots } from './roots-manager.js';
+import { registerCoreTools, getCoreToolCount } from './tools/core-tools.js';
+import { registerOptionalTools, WEB_LLM_TOOLS_INFO, } from './tools/optional-tools.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-ai-bridge');
+        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 for Extension Development v${version}`);
+const server = new McpServer({
+    name: 'chrome-ai-bridge',
+    title: 'Chrome DevTools MCP for Extension Development',
+    version,
+}, { capabilities: { logging: {} } });
+server.server.setRequestHandler(SetLevelRequestSchema, () => {
+    return {};
+});
+// Handle roots/list_changed notification
+server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+    logger('[roots] Received roots/list_changed notification - roots have changed');
+    // Invalidate cached roots info
+    cachedRootsInfo = null;
+    logger('[roots] Cached roots cleared - will re-fetch on next browser launch');
+});
+let context;
+const uiHealthCheckRun = false; // Track if UI health check has been run
+let cachedRootsInfo = null; // Cache roots info
+let initializationComplete = false; // Track if MCP initialization is complete
+// Setup graceful shutdown
+const graceful = setupGraceful({
+    getBrowser: () => context?.browser,
+    onBeforeExit: async () => {
+        logger('[graceful] Running pre-exit cleanup...');
+        // Close log file if exists
+        if (logFile) {
+            logFile.close();
+        }
+    },
+});
+async function getContext() {
+    // Wait for initialization to complete before resolving roots
+    if (!initializationComplete) {
+        logger('[roots] Waiting for MCP initialization to complete...');
+        await new Promise(resolve => setTimeout(resolve, 100)); // Brief wait
+        if (!initializationComplete) {
+            logger('[roots] WARNING: MCP not yet initialized, proceeding without roots');
+        }
+    }
+    // Resolve roots info (cached or fresh)
+    if (!cachedRootsInfo) {
+        cachedRootsInfo = await resolveRoots(server.server, {
+            cliProjectRoot: args.projectRoot,
+            envProjectRoot: process.env.MCP_PROJECT_ROOT,
+            autoCwd: process.cwd(),
+        });
+    }
+    // Initialize project root for profile isolation
+    // Priority: CLI flag > MCP_PROJECT_ROOT env > Roots protocol > cwd
+    const rootFromRoots = cachedRootsInfo?.rootsUris?.[0]
+        ? cachedRootsInfo.rootsUris[0].replace('file://', '')
+        : undefined;
+    const projectRootToSet = args.projectRoot ||
+        process.env.MCP_PROJECT_ROOT ||
+        rootFromRoots ||
+        process.cwd();
+    setProjectRoot(projectRootToSet);
+    logger(`[project-root] Initialized: ${projectRootToSet}`);
+    const browserOptions = {
+        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,
+        chromeProfile: args.chromeProfile,
+        userDataDir: args.userDataDir,
+        logFile,
+        rootsInfo: cachedRootsInfo, // Pass roots info to browser
+    };
+    const browser = await resolveBrowser(browserOptions);
+    // Announce browser PID for graceful shutdown
+    const browserPid = browser.process()?.pid;
+    if (browserPid) {
+        await graceful.announceBrowserPid(browserPid);
+    }
+    // Browser factory function for reconnection
+    const browserFactory = async () => {
+        logger('Reconnecting browser...');
+        return await resolveBrowser(browserOptions);
+    };
+    // Always recreate context if browser reference changed or context doesn't exist
+    if (!context || context.browser !== browser) {
+        // Connection manager options with reconnect callback
+        const connectionOptions = {
+            onReconnect: async (newBrowser) => {
+                logger('Updating context with reconnected browser...');
+                await context.updateBrowser(newBrowser);
+            },
+        };
+        context = await McpContext.from(browser, logger, browserFactory, connectionOptions);
+        // UI health check disabled - causes duplicate ChatGPT tabs
+        // TODO: Re-enable after fixing tab management
+        // if (!uiHealthCheckRun) {
+        //   uiHealthCheckRun = true;
+        //   runStartupCheck(browser).catch(err => {
+        //     logger(`Startup check failed: ${err}`);
+        //   });
+        // }
+    }
+    return context;
+}
+const logDisclaimers = () => {
+    console.error(`chrome-ai-bridge 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);
+                // Detect browser closed error and provide helpful message
+                if (errorText.includes('Target closed') ||
+                    errorText.includes('Session closed')) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Browser connection lost. The Chrome instance was closed or disconnected.\n\nPlease restart the MCP server to reconnect.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: errorText,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        }
+        finally {
+            guard.dispose();
+        }
+    });
+}
+// v0.26.0: Use ToolRegistry for plugin architecture
+const toolRegistry = new ToolRegistry();
+// Register core tools (stable, site-independent)
+registerCoreTools(toolRegistry);
+logger(`[tools] Registered ${getCoreToolCount()} core tools`);
+// Register optional tools (web-llm, site-dependent)
+const optionalCount = registerOptionalTools(toolRegistry);
+if (optionalCount > 0) {
+    logger(`[tools] ${WEB_LLM_TOOLS_INFO.disclaimer}`);
+}
+// Load external plugins from MCP_PLUGINS environment variable
+const pluginList = process.env.MCP_PLUGINS;
+if (pluginList) {
+    const pluginLoader = new PluginLoader(toolRegistry, logger);
+    const { loaded, failed } = await pluginLoader.loadFromList(pluginList);
+    if (loaded.length > 0) {
+        logger(`[plugins] Successfully loaded: ${loaded.join(', ')}`);
+    }
+    if (failed.length > 0) {
+        logger(`[plugins] Failed to load: ${failed.join(', ')}`);
+    }
+}
+// Register all tools with MCP server
+for (const tool of toolRegistry.getAll()) {
+    registerTool(tool);
+}
+logger(`[tools] Total registered: ${toolRegistry.size} tools`);
+// Set initialization callback
+server.server.oninitialized = () => {
+    initializationComplete = true;
+    logger('[roots] MCP initialization complete');
+};
+const transport = new StdioServerTransport();
+await server.connect(transport);
+logger('Chrome DevTools MCP Server connected');
+logDisclaimers();

package/build/src/plugin-api.js

@@ -0,0 +1,189 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Registry for managing MCP tools.
+ * Allows dynamic registration and querying of tools.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    categories = new Map();
+    /**
+     * Register a single tool.
+     * @throws Error if a tool with the same name already exists
+     */
+    register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`Tool "${tool.name}" is already registered`);
+        }
+        this.tools.set(tool.name, tool);
+        // Track by category
+        const category = tool.annotations.category;
+        if (!this.categories.has(category)) {
+            this.categories.set(category, new Set());
+        }
+        this.categories.get(category).add(tool.name);
+    }
+    /**
+     * Register multiple tools at once.
+     */
+    registerBatch(tools) {
+        for (const tool of tools) {
+            this.register(tool);
+        }
+    }
+    /**
+     * Get all registered tools.
+     */
+    getAll() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Get tools by category.
+     */
+    getByCategory(category) {
+        const names = this.categories.get(category);
+        if (!names)
+            return [];
+        return Array.from(names)
+            .map(name => this.tools.get(name))
+            .filter(Boolean);
+    }
+    /**
+     * Get a specific tool by name.
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Check if a tool is registered.
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Get count of registered tools.
+     */
+    get size() {
+        return this.tools.size;
+    }
+    /**
+     * Unregister a tool by name.
+     * Returns true if the tool was removed, false if it didn't exist.
+     */
+    unregister(name) {
+        const tool = this.tools.get(name);
+        if (!tool)
+            return false;
+        this.tools.delete(name);
+        const category = tool.annotations.category;
+        this.categories.get(category)?.delete(name);
+        return true;
+    }
+    /**
+     * Clear all registered tools.
+     */
+    clear() {
+        this.tools.clear();
+        this.categories.clear();
+    }
+}
+/**
+ * Plugin loader for dynamically loading plugins.
+ */
+export class PluginLoader {
+    plugins = new Map();
+    registry;
+    log;
+    config;
+    constructor(registry, log = console.error, config = {}) {
+        this.registry = registry;
+        this.log = log;
+        this.config = config;
+    }
+    /**
+     * Load a plugin from a module path or package name.
+     * @param moduleId - Path to module or npm package name
+     */
+    async load(moduleId) {
+        try {
+            this.log(`[plugins] Loading plugin: ${moduleId}`);
+            // Dynamic import
+            const module = await import(moduleId);
+            const plugin = module.default || module.plugin || module;
+            if (!plugin.id || !plugin.register) {
+                this.log(`[plugins] Invalid plugin (missing id or register): ${moduleId}`);
+                return false;
+            }
+            if (this.plugins.has(plugin.id)) {
+                this.log(`[plugins] Plugin already loaded: ${plugin.id}`);
+                return false;
+            }
+            // Create plugin context
+            const ctx = {
+                registry: this.registry,
+                log: msg => this.log(`[${plugin.id}] ${msg}`),
+                config: this.config,
+            };
+            // Register the plugin
+            await plugin.register(ctx);
+            this.plugins.set(plugin.id, plugin);
+            this.log(`[plugins] Loaded: ${plugin.name} v${plugin.version} (${plugin.id})`);
+            return true;
+        }
+        catch (error) {
+            this.log(`[plugins] Failed to load ${moduleId}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    /**
+     * Load multiple plugins from environment variable or config.
+     * @param pluginIds - Comma-separated list of plugin module IDs
+     */
+    async loadFromList(pluginIds) {
+        const ids = pluginIds
+            .split(',')
+            .map(id => id.trim())
+            .filter(Boolean);
+        const loaded = [];
+        const failed = [];
+        for (const id of ids) {
+            const success = await this.load(id);
+            if (success) {
+                loaded.push(id);
+            }
+            else {
+                failed.push(id);
+            }
+        }
+        return { loaded, failed };
+    }
+    /**
+     * Unload a plugin by ID.
+     */
+    async unload(pluginId) {
+        const plugin = this.plugins.get(pluginId);
+        if (!plugin)
+            return false;
+        try {
+            if (plugin.unload) {
+                await plugin.unload();
+            }
+            this.plugins.delete(pluginId);
+            this.log(`[plugins] Unloaded: ${pluginId}`);
+            return true;
+        }
+        catch (error) {
+            this.log(`[plugins] Failed to unload ${pluginId}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    /**
+     * Get list of loaded plugins.
+     */
+    getLoaded() {
+        return Array.from(this.plugins.values());
+    }
+}

package/build/src/profile-migration.js

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// src/profile-migration.ts
+// Legacy profile migration utilities
+// Creates symlinks from new stable paths to existing legacy paths
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getLegacyIdentityHash } from './stable-identity.js';
+const CACHE_ROOT = path.join(os.homedir(), '.cache', 'chrome-ai-bridge');
+/**
+ * Check if legacy profile exists and create symlink for migration.
+ * This preserves login sessions when upgrading to stable identity.
+ *
+ * @param projectRoot - The project root directory
+ * @param newIdentity - The new stable identity
+ * @param projectName - The sanitized project name
+ * @param clientId - The MCP client ID
+ * @param channel - The Chrome channel
+ */
+export function checkAndMigrateLegacyProfile(projectRoot, newIdentity, projectName, clientId, channel) {
+    // Skip migration if disabled
+    if (process.env.MCP_DISABLE_MIGRATION === 'true') {
+        return { migrated: false, method: 'none', reason: 'MCP_DISABLE_MIGRATION' };
+    }
+    // Skip migration if using directory-fallback (same as legacy)
+    if (newIdentity.source === 'directory-fallback') {
+        return { migrated: false, method: 'none', reason: 'same-as-legacy' };
+    }
+    // Calculate legacy path (realpath-based)
+    const legacyHash = getLegacyIdentityHash(projectRoot);
+    const legacyKey = `${projectName}_${legacyHash}`;
+    const legacyPath = path.join(CACHE_ROOT, 'profiles', legacyKey, clientId, channel);
+    // Calculate new path (stable identity)
+    const newKey = `${projectName}_${newIdentity.id}`;
+    const newPath = path.join(CACHE_ROOT, 'profiles', newKey, clientId, channel);
+    // If paths are the same, no migration needed
+    if (legacyPath === newPath) {
+        return { migrated: false, method: 'none', reason: 'paths-identical' };
+    }
+    // If new path already exists, no migration needed
+    if (fs.existsSync(newPath)) {
+        return { migrated: false, method: 'none', reason: 'new-path-exists' };
+    }
+    // If legacy path doesn't exist, no migration needed
+    if (!fs.existsSync(legacyPath)) {
+        return { migrated: false, method: 'none', reason: 'no-legacy-profile' };
+    }
+    // Legacy exists, new doesn't - create symlink
+    try {
+        console.error(`[migration] Legacy profile detected: ${legacyPath}`);
+        console.error(`[migration] Creating symlink for stable identity: ${newPath}`);
+        // Create parent directories
+        fs.mkdirSync(path.dirname(newPath), { recursive: true });
+        // Create symlink (new -> legacy)
+        fs.symlinkSync(legacyPath, newPath, 'dir');
+        console.error(`[migration] ✅ Migration complete: ${newPath} -> ${legacyPath}`);
+        return {
+            migrated: true,
+            from: legacyPath,
+            to: newPath,
+            method: 'symlink',
+        };
+    }
+    catch (err) {
+        console.error(`[migration] ⚠️ Migration failed: ${err.message}`);
+        return {
+            migrated: false,
+            method: 'none',
+            reason: `symlink-failed: ${err.message}`,
+        };
+    }
+}
+/**
+ * Get profile path for a given project key.
+ */
+export function getProfilePath(projectKey, clientId, channel) {
+    return path.join(CACHE_ROOT, 'profiles', projectKey, clientId, channel);
+}