chrome-devtools-mcp-for-extension 0.14.0 → 0.15.0

package/build/src/McpContext.js

@@ -44,6 +44,9 @@ export class McpContext {
     #dialog;
     #nextSnapshotId = 1;
     #traceResults = [];
+    // CDP Session management (v0.8.4+)
+    #browserSession;
+    #pageSessions = new Map();
     constructor(browser, logger, browserFactory, connectionOptions) {
         this.browser = browser;
         this.logger = logger;
@@ -77,29 +80,38 @@ export class McpContext {
         await context.#init();
         return context;
     }
+    /**
+     * Dispose all CDP sessions to prevent memory leaks
+     */
+    async #disposeSessions() {
+        await Promise.allSettled([
+            this.#browserSession?.detach(),
+            ...[...this.#pageSessions.values()].map(s => s.detach())
+        ]);
+        this.#browserSession = undefined;
+        this.#pageSessions.clear();
+    }
     /**
      * Reinitialize CDP protocol domains after reconnection
      * This ensures proper CDP event handling after browser restart
      */
     async reinitializeCDP() {
         try {
-            // Get CDP client from the browser
-            const client = await this.browser._client();
-            if (!client) {
-                this.logger('Warning: Unable to get CDP client for reinitialization');
-                return;
-            }
-            // 1. Enable Target discovery and auto-attach
-            // This is critical for multi-target scenarios (iframes, workers, etc.)
+            // 1. Dispose old sessions to prevent leaks
+            await this.#disposeSessions();
+            // 2. Create browser-level CDP session (public API, not _client())
+            this.#browserSession = await this.browser.target().createCDPSession();
+            this.logger('CDP: Browser-level session created');
+            // 3. Enable Target discovery and auto-attach
             try {
-                await client.send('Target.setDiscoverTargets', { discover: true });
+                await this.#browserSession.send('Target.setDiscoverTargets', { discover: true });
                 this.logger('CDP: Target discovery enabled');
             }
             catch (err) {
                 this.logger('Warning: Failed to enable target discovery:', err);
             }
             try {
-                await client.send('Target.setAutoAttach', {
+                await this.#browserSession.send('Target.setAutoAttach', {
                     autoAttach: true,
                     waitForDebuggerOnStart: false,
                     flatten: true
@@ -109,24 +121,29 @@ export class McpContext {
             catch (err) {
                 this.logger('Warning: Failed to configure auto-attach:', err);
             }
-            // 2. Enable essential CDP domains for each page
-            const pages = await this.browser.pages();
-            for (const page of pages) {
-                try {
-                    const pageClient = page._client();
-                    if (pageClient) {
-                        // Enable Network domain for request interception
-                        await pageClient.send('Network.enable');
-                        // Enable Runtime domain for console messages and exceptions
-                        await pageClient.send('Runtime.enable');
-                        // Enable Log domain for browser logs
-                        await pageClient.send('Log.enable');
-                        this.logger(`CDP domains enabled for page: ${page.url()}`);
+            // 4. Enable essential CDP domains for all targets
+            for (const target of this.browser.targets()) {
+                const type = target.type();
+                if (type === 'page') {
+                    const page = await target.page();
+                    if (!page)
+                        continue;
+                    try {
+                        const session = await page.createCDPSession();
+                        await Promise.allSettled([
+                            session.send('Network.enable'),
+                            session.send('Runtime.enable'),
+                            session.send('Log.enable'),
+                        ]);
+                        this.#pageSessions.set(page, session);
+                        this.logger(`CDP domains enabled for ${type}: ${page.url()}`);
+                    }
+                    catch (err) {
+                        this.logger(`Warning: Failed to enable CDP domains for ${type} ${page.url()}:`, err);
                     }
                 }
-                catch (err) {
-                    this.logger(`Warning: Failed to enable CDP domains for page ${page.url()}:`, err);
-                }
+                // Service Worker / Worker support can be added here if needed
+                // if (type === 'service_worker' || type === 'worker') { ... }
             }
             this.logger('CDP protocol reinitialization completed');
         }
@@ -140,6 +157,8 @@ export class McpContext {
      * Update browser instance after reconnection
      */
     async updateBrowser(newBrowser) {
+        // Dispose old sessions first
+        await this.#disposeSessions();
         this.browser = newBrowser;
         this.connectionManager.setBrowser(newBrowser, async () => newBrowser);
         // Reinitialize CDP protocol domains BEFORE collectors

package/build/src/browser-connection-manager.js

@@ -11,6 +11,7 @@ const DEFAULT_OPTIONS = {
     maxReconnectAttempts: 3,
     initialRetryDelay: 1000, // 1 second
     maxRetryDelay: 10000, // 10 seconds
+    reconnectOverallTimeoutMs: 30000, // 30 seconds
     enableLogging: true,
     onReconnect: undefined,
 };
@@ -43,6 +44,13 @@ export class BrowserConnectionManager {
     reconnectSequenceInFlight = null;
     /** Current connection state */
     state = ConnectionState.CLOSED;
+    /** Disconnected event handler (arrow function to preserve 'this') */
+    onDisconnected = () => {
+        this.log('Browser disconnected');
+        this.setState(ConnectionState.RECONNECTING);
+        // Trigger immediate reconnection (single-flight prevents duplicates)
+        void this.triggerReconnect('event:disconnected');
+    };
     constructor(options = {}) {
         this.options = { ...DEFAULT_OPTIONS, ...options };
     }
@@ -53,15 +61,15 @@ export class BrowserConnectionManager {
      * @param factory - Factory function to create new browser instances on reconnection
      */
     setBrowser(browser, factory) {
+        // Remove old listener to prevent memory leak
+        if (this.browser) {
+            this.browser.off('disconnected', this.onDisconnected);
+        }
         this.browser = browser;
         this.browserFactory = factory;
         this.state = ConnectionState.CONNECTED;
         // Event-driven detection: hook into browser 'disconnected' event
-        this.browser.on('disconnected', () => {
-            this.log('Browser disconnected event fired');
-            this.setState(ConnectionState.CLOSED);
-            // Trigger immediate reconnection (will be handled by next operation)
-        });
+        this.browser.on('disconnected', this.onDisconnected);
         this.log('Browser instance set, state: CONNECTED');
     }
     /**
@@ -80,71 +88,81 @@ export class BrowserConnectionManager {
         }
     }
     /**
-     * Retry operation with exponential backoff and jitter
+     * Trigger reconnection sequence
      *
-     * Implements single-flight pattern at the sequence level:
-     * - Multiple concurrent operations share the same reconnection sequence
-     * - Only one reconnection sequence runs at a time
-     * - All waiting operations retry after the shared sequence completes
+     * Can be called from events (disconnected) or operations (executeWithRetry).
+     * Uses single-flight pattern to prevent duplicate reconnections.
      *
-     * Adds ±20% randomness to retry delays to prevent thundering herd problem.
+     * @param reason - Reason for triggering reconnection
+     * @returns Promise that resolves when reconnection completes
+     */
+    async triggerReconnect(reason) {
+        // Single-flight: return existing sequence if already running
+        if (this.reconnectSequenceInFlight) {
+            this.log(`Reconnection already in progress (${reason}), waiting...`);
+            return this.reconnectSequenceInFlight;
+        }
+        this.log(`Triggering reconnection: ${reason}`);
+        // Overall timeout with AbortController
+        const abortController = new AbortController();
+        const overallTimeout = this.options.reconnectOverallTimeoutMs ?? 30000;
+        const timeoutId = setTimeout(() => {
+            abortController.abort();
+            this.log(`Reconnection overall timeout (${overallTimeout}ms) exceeded`);
+        }, overallTimeout);
+        // Start reconnection sequence
+        this.reconnectSequenceInFlight = this._runReconnectionSequence(abortController.signal)
+            .finally(() => {
+            clearTimeout(timeoutId);
+            this.reconnectSequenceInFlight = null;
+        });
+        return this.reconnectSequenceInFlight;
+    }
+    /**
+     * Retry operation with automatic reconnection
      *
      * @param operation - Operation to retry
      * @param operationName - Name of operation for logging
      * @returns Result of operation
      */
     async retryWithReconnect(operation, operationName) {
-        // Single-flight pattern: if a reconnection sequence is already running,
-        // wait for it to complete, then try the operation once
-        if (this.reconnectSequenceInFlight) {
-            this.log(`${operationName}: Waiting for ongoing reconnection sequence...`);
-            try {
-                await this.reconnectSequenceInFlight;
-                this.log(`${operationName}: Reconnection sequence completed, retrying operation...`);
-                return await operation();
-            }
-            catch (error) {
-                // Reconnection sequence failed, propagate the error
-                throw error;
-            }
-        }
-        // Start a new reconnection sequence
-        this.reconnectSequenceInFlight = this._runReconnectionSequence();
-        try {
-            await this.reconnectSequenceInFlight;
-            this.log(`${operationName}: Reconnection sequence completed, retrying operation...`);
-            return await operation();
-        }
-        catch (error) {
-            throw error;
-        }
-        finally {
-            // Clear the in-flight sequence
-            this.reconnectSequenceInFlight = null;
-        }
+        // Use triggerReconnect for unified reconnection logic
+        await this.triggerReconnect(`operation:${operationName}`);
+        this.log(`${operationName}: Reconnection completed, retrying operation...`);
+        return await operation();
     }
     /**
      * Run a full reconnection sequence with exponential backoff
      *
      * This is the actual retry loop that multiple operations can share.
      *
+     * @param signal - AbortSignal to cancel reconnection
      * @private
      */
-    async _runReconnectionSequence() {
+    async _runReconnectionSequence(signal) {
         const maxAttempts = this.options.maxReconnectAttempts ?? 3;
         const initialDelay = this.options.initialRetryDelay ?? 1000;
         const maxDelay = this.options.maxRetryDelay ?? 10000;
+        const random = this.options.rng ?? Math.random;
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            // Check abort signal
+            if (signal?.aborted) {
+                throw new Error('Reconnection aborted: overall timeout exceeded');
+            }
             this.reconnectAttempts++;
             const attemptNum = attempt + 1;
             this.log(`Reconnect attempt ${attemptNum}/${maxAttempts}...`);
             // Exponential backoff with max delay
             const baseDelay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
             // Add jitter: ±20% randomness to prevent thundering herd
-            const jitter = baseDelay * 0.2 * (Math.random() * 2 - 1);
+            const jitter = baseDelay * 0.2 * (random() * 2 - 1);
             const delay = Math.max(0, baseDelay + jitter);
             this.log(`Waiting ${delay.toFixed(0)}ms before reconnect attempt...`);
             await this.sleep(delay);
+            // Check abort signal after sleep
+            if (signal?.aborted) {
+                throw new Error('Reconnection aborted: overall timeout exceeded');
+            }
             try {
                 await this.reconnectBrowser();
                 this.log(`Reconnection successful`);
@@ -164,7 +182,7 @@ export class BrowserConnectionManager {
      * Check if error is a CDP connection error
      *
      * Uses type-safe error detection with instanceof checks and falls back
-     * to string matching for compatibility.
+     * to string matching for compatibility. Also checks method hints.
      *
      * @param error - Error to check
      * @returns true if error is a CDP connection error
@@ -174,13 +192,17 @@ export class BrowserConnectionManager {
         if (error instanceof ProtocolError || error instanceof TimeoutError) {
             return true;
         }
-        // Fallback: string matching for error messages
-        const errorMessage = error?.message || '';
-        return (errorMessage.includes('Target closed') ||
-            errorMessage.includes('Protocol error') ||
-            errorMessage.includes('Session closed') ||
-            errorMessage.includes('Connection closed') ||
-            errorMessage.includes('WebSocket is not open'));
+        const msg = String(error?.message ?? '').toLowerCase();
+        const method = error?.method?.toString?.().toLowerCase?.() ?? '';
+        // Message hints
+        if (/connection closed|session closed|target closed|websocket is not open/.test(msg)) {
+            return true;
+        }
+        // Method hints (CDP methods like 'Target.*')
+        if (/^target\./.test(method)) {
+            return true;
+        }
+        return false;
     }
     /**
      * Reconnect browser instance with single-flight pattern
@@ -231,10 +253,7 @@ export class BrowserConnectionManager {
         const newBrowser = await this.browserFactory();
         this.browser = newBrowser;
         // Re-attach disconnected event handler
-        this.browser.on('disconnected', () => {
-            this.log('Browser disconnected event fired');
-            this.setState(ConnectionState.CLOSED);
-        });
+        this.browser.on('disconnected', this.onDisconnected);
         this.setState(ConnectionState.CONNECTED);
         this.log('Browser reconnected successfully');
         // Notify callback if provided

package/build/src/browser.js

@@ -7,6 +7,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import puppeteer from 'puppeteer-core';
+import { resolveUserDataDir } from './profile-resolver.js';
 let browser;
 const ignoredPrefixes = new Set([
     'chrome://',
@@ -418,20 +419,36 @@ export async function launch(options) {
     const { channel, executablePath, customDevTools, headless, isolated, loadExtension, loadExtensionsDir, loadSystemExtensions, chromeProfile, } = options;
     // Reset development extension paths
     developmentExtensionPaths = [];
-    const profileDirName = channel && channel !== 'stable'
-        ? `chrome-profile-${channel}`
-        : 'chrome-profile';
-    let userDataDir = options.userDataDir;
+    // Resolve user data directory using new profile resolver (v0.15.0+)
+    const resolved = resolveUserDataDir({
+        cliUserDataDir: options.userDataDir,
+        env: process.env,
+        cwd: process.cwd(),
+        channel: channel || 'stable',
+    });
+    const userDataDir = resolved.path;
+    await fs.promises.mkdir(userDataDir, { recursive: true });
+    // Legacy profile warning (shown if legacy path exists)
+    try {
+        const legacy = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', 'chrome-profile');
+        if (fs.existsSync(legacy)) {
+            console.error(`⚠️  Legacy profile detected: ${legacy}\n` +
+                `ℹ️  New profile location: ${path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', 'profiles', 'project-default', 'stable')}\n` +
+                `💡 To continue using the legacy profile, set: MCP_USER_DATA_DIR=${legacy}`);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    // Profile resolution logs
+    console.error(`[profiles] Using: ${userDataDir}`);
+    console.error(`           Reason: ${resolved.reason}`);
+    console.error(`           Project: ${resolved.projectName} (${resolved.hash})`);
+    if (resolved.reason === 'AUTO') {
+        console.error(`           Root: ${process.cwd()}`);
+    }
     let usingSystemProfile = false;
     let profileDirectory = 'Default';
-    if (!userDataDir) {
-        // Use isolated profile (independent from system Chrome)
-        userDataDir = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp', profileDirName);
-        await fs.promises.mkdir(userDataDir, {
-            recursive: true,
-        });
-        console.error(`📁 Using isolated profile: ${userDataDir}`);
-    }
     const args = [
         '--hide-crash-restore-bubble',
         `--profile-directory=${profileDirectory}`,

package/build/src/profile-resolver.js

@@ -0,0 +1,190 @@
+// src/profile-resolver.ts
+// Phase 1 (v0.15.0)
+// - Hybrid priority (CLI > MCP_USER_DATA_DIR > MCP_PROJECT_ID > AUTO > DEFAULT)
+// - Auto-detection (git root -> nearest package.json -> cwd)
+// - Realpath normalization
+// - Tilde (~) expansion
+// - Short SHA-256 hash (8 chars)
+// - CI detection => ephemeral session profile (unless MCP_PERSIST_PROFILES)
+// - Minimal console.error() logging of decision
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { detectProjectName, detectProjectRoot } from './project-detector.js';
+const CACHE_ROOT = path.join(os.homedir(), '.cache', 'chrome-devtools-mcp');
+// --- Public API ---
+export function resolveUserDataDir(opts) {
+    const channel = opts.channel || 'stable';
+    // 0) CI detection → ephemeral session directory (unless MCP_PERSIST_PROFILES)
+    //    - This happens before other priorities to keep CI clean by default.
+    if (isCI(opts.env) && !opts.env.MCP_PERSIST_PROFILES) {
+        const sessionId = `${process.pid}-${Date.now()}`;
+        const tempPath = realpathSafe(path.join(CACHE_ROOT, 'sessions', sessionId, channel));
+        // best-effort cleanup on exit
+        process.on('exit', () => {
+            try {
+                fs.rmSync(tempPath, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        });
+        const result = {
+            path: tempPath,
+            reason: 'AUTO', // keep enum as specified (no EPHEMERAL type in Phase 1)
+            projectKey: `session-${sessionId}`,
+            projectName: 'ci-session',
+            hash: sessionId,
+            channel,
+        };
+        // concise decision log (resolver-side)
+        console.error(`[profiles] resolved(AUTO, ci-ephemeral): ${result.path} (session=${sessionId})`);
+        return result;
+    }
+    // 1) CLI explicit userDataDir
+    if (opts.cliUserDataDir && opts.cliUserDataDir.trim().length > 0) {
+        const p = realpathOrExpand(opts.cliUserDataDir);
+        const result = {
+            path: p,
+            reason: 'CLI',
+            projectKey: stripHomeForKey(p),
+            projectName: 'cli',
+            hash: shortHash(p),
+            channel,
+        };
+        console.error(`[profiles] resolved(CLI): ${result.path}`);
+        return result;
+    }
+    // 2) ENV: MCP_USER_DATA_DIR (full path)
+    const envUserData = opts.env.MCP_USER_DATA_DIR?.trim();
+    if (envUserData) {
+        const p = realpathOrExpand(envUserData);
+        const result = {
+            path: p,
+            reason: 'MCP_USER_DATA_DIR',
+            projectKey: stripHomeForKey(p),
+            projectName: 'env',
+            hash: shortHash(p),
+            channel,
+        };
+        console.error(`[profiles] resolved(MCP_USER_DATA_DIR): ${result.path}`);
+        return result;
+    }
+    // 3) ENV: MCP_PROJECT_ID (project-scoped persistent profile)
+    const projectId = sanitize(opts.env.MCP_PROJECT_ID || '');
+    if (projectId) {
+        const p = projectProfilePath(projectId, channel);
+        const result = {
+            path: p,
+            reason: 'MCP_PROJECT_ID',
+            projectKey: projectId,
+            projectName: projectId,
+            hash: shortHash(projectId),
+            channel,
+        };
+        console.error(`[profiles] resolved(MCP_PROJECT_ID): ${result.path} (projectId=${projectId})`);
+        return result;
+    }
+    // 4) AUTO: detect by root -> name -> hash
+    try {
+        const root = detectProjectRoot(opts.cwd);
+        const name = detectProjectName(root);
+        const realRoot = realpathSafe(root);
+        const hash = shortHash(realRoot);
+        const key = `${sanitize(name)}_${hash}`;
+        const p = projectProfilePath(key, channel);
+        const result = {
+            path: p,
+            reason: 'AUTO',
+            projectKey: key,
+            projectName: sanitize(name),
+            hash,
+            channel,
+        };
+        console.error(`[profiles] resolved(AUTO): ${result.path} (root=${root}, name=${name}, hash=${hash})`);
+        return result;
+    }
+    catch (e) {
+        // 5) DEFAULT fallback
+        const key = 'project-default';
+        const p = projectProfilePath(key, channel);
+        const result = {
+            path: p,
+            reason: 'DEFAULT',
+            projectKey: key,
+            projectName: key,
+            hash: '00000000',
+            channel,
+        };
+        console.error(`[profiles] resolved(DEFAULT): ${result.path} (reason=${e?.message || 'fallback'})`);
+        return result;
+    }
+}
+// --- Helpers ---
+function isCI(env) {
+    // Common CI signals
+    return env.CI === 'true' || env.GITHUB_ACTIONS === 'true';
+}
+function projectProfilePath(projectKey, channel) {
+    const base = path.join(CACHE_ROOT, 'profiles', projectKey, channel);
+    return pathNormalize(base);
+}
+function shortHash(s) {
+    try {
+        return crypto.createHash('sha256').update(s).digest('hex').slice(0, 8);
+    }
+    catch {
+        // Extremely unlikely; fallback for robustness
+        return '00000000';
+    }
+}
+function sanitize(s) {
+    const base = (s || 'project').toLowerCase().replace(/[^a-z0-9-_]/g, '-');
+    // Avoid empty string after sanitize
+    return base.length ? base : 'project';
+}
+function expandTilde(p) {
+    if (!p)
+        return p;
+    if (p.startsWith('~')) {
+        return path.join(os.homedir(), p.slice(1));
+    }
+    return p;
+}
+function realpathSafe(p) {
+    try {
+        // Use native realpath if available for speed/behavior
+        // (Node 18+ has fs.realpathSync.native)
+        const rp = fs.realpathSync.native
+            ? fs.realpathSync.native(p)
+            : fs.realpathSync(p);
+        return rp;
+    }
+    catch {
+        // The path may not exist yet; normalize current form
+        return pathNormalize(p);
+    }
+}
+function realpathOrExpand(p) {
+    const expanded = expandTilde(p);
+    return realpathSafe(expanded);
+}
+function pathNormalize(p) {
+    // Normalize but do not resolve symlinks here
+    // (realpathSafe is used where resolution is desired)
+    return path.normalize(p);
+}
+/**
+ * Best-effort readable key when user supplied an absolute path.
+ * We do not want slashes in the key, so hash + tail dir name.
+ */
+function stripHomeForKey(absPath) {
+    try {
+        const name = path.basename(absPath);
+        return `${sanitize(name)}_${shortHash(absPath)}`;
+    }
+    catch {
+        return `abs_${shortHash(absPath)}`;
+    }
+}

package/build/src/project-detector.js

@@ -0,0 +1,66 @@
+// src/project-detector.ts
+// Phase 1 (v0.15.0)
+// - detectProjectRoot: git root → nearest package.json → cwd
+// - detectProjectName: package.json "name" → dirname
+// - Use spawnSync with 500ms timeout to avoid blocking long
+// - Realpath normalization
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+export function detectProjectRoot(cwd) {
+    const realCwd = realpathSafe(cwd);
+    // 1) Try 'git rev-parse --show-toplevel' with 500ms timeout
+    const git = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+        cwd: realCwd,
+        timeout: 500,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        windowsHide: true,
+    });
+    if (git.status === 0 && git.stdout) {
+        const out = git.stdout.toString().trim();
+        if (out)
+            return realpathSafe(out);
+    }
+    // If git is not available or command failed/timed out → fall through
+    // 2) Walk up to nearest package.json
+    let cur = realCwd;
+    while (true) {
+        if (fs.existsSync(path.join(cur, 'package.json')))
+            return cur;
+        const next = path.dirname(cur);
+        if (next === cur)
+            break; // reached filesystem root
+        cur = next;
+    }
+    // 3) Fallback to cwd
+    return realCwd;
+}
+export function detectProjectName(root) {
+    const realRoot = realpathSafe(root);
+    const pj = path.join(realRoot, 'package.json');
+    if (fs.existsSync(pj)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pj, 'utf8'));
+            if (pkg && typeof pkg.name === 'string' && pkg.name.trim()) {
+                return String(pkg.name).trim();
+            }
+        }
+        catch {
+            // ignore parse errors and fall back to directory name
+        }
+    }
+    return path.basename(realRoot);
+}
+// --- helpers ---
+function realpathSafe(p) {
+    try {
+        const rp = fs.realpathSync.native
+            ? fs.realpathSync.native(p)
+            : fs.realpathSync(p);
+        return rp;
+    }
+    catch {
+        return path.normalize(p);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-devtools-mcp-for-extension",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "MCP server for Chrome extension development with Web Store automation. Fork of chrome-devtools-mcp with extension-specific tools.",
   "type": "module",
   "bin": "./build/src/index.js",