fix: fall back to auto connect after browser url

Author: bertrand319

src/bin/chrome-devtools-mcp-cli-options.ts

@@ -300,9 +300,8 @@ export function parseArguments(version: string, argv = process.argv) {
       // Yargs will complain
       if (
         !args.channel &&
-        !args.browserUrl &&
-        !args.wsEndpoint &&
-        !args.executablePath
+        (args.autoConnect ||
+          (!args.browserUrl && !args.wsEndpoint && !args.executablePath))
       ) {
         args.channel = 'stable';
       }

src/browser.ts

@@ -43,10 +43,24 @@ function makeTargetFilter(enableExtensions = false) {
   };
 }
 
+function toPuppeteerChannel(channel: Channel): ChromeReleaseChannel {
+  switch (channel) {
+    case 'canary':
+      return 'chrome-canary';
+    case 'dev':
+      return 'chrome-dev';
+    case 'beta':
+      return 'chrome-beta';
+    case 'stable':
+      return 'chrome';
+  }
+}
+
 export async function ensureBrowserConnected(options: {
   browserURL?: string;
   wsEndpoint?: string;
   wsHeaders?: Record<string, string>;
+  autoConnect?: boolean;
   devtools: boolean;
   channel?: Channel;
   userDataDir?: string;
@@ -57,24 +71,62 @@ export async function ensureBrowserConnected(options: {
     return browser;
   }
 
-  const connectOptions: Parameters<typeof puppeteer.connect>[0] = {
-    targetFilter: makeTargetFilter(enableExtensions),
-    defaultViewport: null,
-    handleDevToolsAsPage: true,
+  const createConnectOptions = (): Parameters<typeof puppeteer.connect>[0] => {
+    return {
+      targetFilter: makeTargetFilter(enableExtensions),
+      defaultViewport: null,
+      handleDevToolsAsPage: true,
+    };
+  };
+
+  const connect = async (
+    connectOptions: Parameters<typeof puppeteer.connect>[0],
+  ): Promise<Browser> => {
+    logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
+    const connectedBrowser = await puppeteer.connect(connectOptions);
+    logger('Connected Puppeteer');
+    return connectedBrowser;
   };
 
-  let autoConnect = false;
-  if (options.wsEndpoint) {
-    connectOptions.browserWSEndpoint = options.wsEndpoint;
-    if (options.wsHeaders) {
-      connectOptions.headers = options.wsHeaders;
+  const connectionError = (autoConnect: boolean, cause: unknown): Error => {
+    return new Error(
+      `Could not connect to Chrome. ${autoConnect ? `Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.` : `Check if Chrome is running.`}`,
+      {
+        cause,
+      },
+    );
+  };
+
+  if (options.wsEndpoint || options.browserURL) {
+    const connectOptions = createConnectOptions();
+    if (options.wsEndpoint) {
+      connectOptions.browserWSEndpoint = options.wsEndpoint;
+      if (options.wsHeaders) {
+        connectOptions.headers = options.wsHeaders;
+      }
+    } else {
+      connectOptions.browserURL = options.browserURL;
     }
-  } else if (options.browserURL) {
-    connectOptions.browserURL = options.browserURL;
-  } else if (channel || options.userDataDir) {
+    try {
+      browser = await connect(connectOptions);
+      return browser;
+    } catch (error) {
+      if (!options.autoConnect) {
+        throw connectionError(false, error);
+      }
+      logger(
+        'Direct browser connection failed; falling back to auto-connect',
+        error,
+      );
+    }
+  }
+
+  const connectOptions = createConnectOptions();
+  let autoConnect = false;
+  if (channel || options.userDataDir || options.autoConnect) {
     const userDataDir = options.userDataDir;
+    autoConnect = true;
     if (userDataDir) {
-      autoConnect = true;
       // TODO: re-expose this logic via Puppeteer.
       const portPath = path.join(userDataDir, 'DevToolsActivePort');
       try {
@@ -105,31 +157,19 @@ export async function ensureBrowserConnected(options: {
         );
       }
     } else {
-      if (!channel) {
-        throw new Error('Channel must be provided if userDataDir is missing');
-      }
-      connectOptions.channel = (
-        channel === 'stable' ? 'chrome' : `chrome-${channel}`
-      ) as ChromeReleaseChannel;
+      connectOptions.channel = toPuppeteerChannel(channel ?? 'stable');
     }
   } else {
     throw new Error(
       'Either browserURL, wsEndpoint, channel or userDataDir must be provided',
     );
   }
 
-  logger('Connecting Puppeteer to ', JSON.stringify(connectOptions));
   try {
-    browser = await puppeteer.connect(connectOptions);
+    browser = await connect(connectOptions);
   } catch (err) {
-    throw new Error(
-      `Could not connect to Chrome. ${autoConnect ? `Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.` : `Check if Chrome is running.`}`,
-      {
-        cause: err,
-      },
-    );
+    throw connectionError(autoConnect, err);
   }
-  logger('Connected Puppeteer');
   return browser;
 }
 

src/index.ts

@@ -30,6 +30,20 @@ import {pageIdSchema} from './tools/ToolDefinition.js';
 import {createTools} from './tools/tools.js';
 import {VERSION} from './version.js';
 
+function resolveChannel(channel: unknown): Channel {
+  switch (channel) {
+    case 'canary':
+      return 'canary';
+    case 'dev':
+      return 'dev';
+    case 'beta':
+      return 'beta';
+    case 'stable':
+    default:
+      return 'stable';
+  }
+}
+
 export async function createMcpServer(
   serverArgs: ReturnType<typeof parseArguments>,
   options: {
@@ -106,9 +120,10 @@ export async function createMcpServer(
             browserURL: serverArgs.browserUrl,
             wsEndpoint: serverArgs.wsEndpoint,
             wsHeaders: serverArgs.wsHeaders,
+            autoConnect: serverArgs.autoConnect,
             // Important: only pass channel, if autoConnect is true.
             channel: serverArgs.autoConnect
-              ? (serverArgs.channel as Channel)
+              ? resolveChannel(serverArgs.channel)
               : undefined,
             userDataDir: serverArgs.userDataDir,
             devtools,

tests/browser.test.ts

@@ -7,13 +7,19 @@
 import assert from 'node:assert';
 import os from 'node:os';
 import path from 'node:path';
-import {describe, it} from 'node:test';
+import {afterEach, describe, it} from 'node:test';
 
 import {executablePath} from 'puppeteer';
+import sinon from 'sinon';
 
 import {detectDisplay, ensureBrowserConnected, launch} from '../src/browser.js';
+import {puppeteer} from '../src/third_party/index.js';
 
 describe('browser', () => {
+  afterEach(() => {
+    sinon.restore();
+  });
+
   it('detects display does not crash', () => {
     detectDisplay();
   });
@@ -100,4 +106,29 @@ describe('browser', () => {
       await browser.close();
     }
   });
+
+  it('falls back to auto-connect when browser url cannot connect', async () => {
+    const connect = sinon.stub(puppeteer, 'connect');
+    connect.onFirstCall().rejects(new Error('port unavailable'));
+    connect.onSecondCall().rejects(new Error('auto-connect unavailable'));
+
+    await assert.rejects(
+      ensureBrowserConnected({
+        browserURL: 'http://127.0.0.1:9222',
+        autoConnect: true,
+        channel: 'stable',
+        devtools: false,
+      }),
+      /Could not connect to Chrome/,
+    );
+
+    assert.strictEqual(connect.callCount, 2);
+    assert.strictEqual(
+      connect.firstCall.args[0].browserURL,
+      'http://127.0.0.1:9222',
+    );
+    assert.strictEqual(connect.firstCall.args[0].channel, undefined);
+    assert.strictEqual(connect.secondCall.args[0].browserURL, undefined);
+    assert.strictEqual(connect.secondCall.args[0].channel, 'chrome');
+  });
 });

tests/cli.test.ts

@@ -255,6 +255,28 @@ describe('cli args parsing', () => {
     });
   });
 
+  it('uses stable channel for browser url with auto-connect fallback', async () => {
+    const args = parseArguments('1.0.0', [
+      'node',
+      'main.js',
+      '--browserUrl',
+      'http://127.0.0.1:9222',
+      '--auto-connect',
+    ]);
+    assert.deepStrictEqual(args, {
+      ...defaultArgs,
+      _: [],
+      headless: false,
+      $0: 'npx chrome-devtools-mcp@latest',
+      'browser-url': 'http://127.0.0.1:9222',
+      browserUrl: 'http://127.0.0.1:9222',
+      u: 'http://127.0.0.1:9222',
+      channel: 'stable',
+      'auto-connect': true,
+      autoConnect: true,
+    });
+  });
+
   it('parses usage statistics flag', async () => {
     // Test default (should be true).
     const defaultArgs = parseArguments('1.0.0', ['node', 'main.js']);