fix(switch_browser): add timeout to HTTP fetch to prevent infinite hangs

The convertHttpToBrowserUrl() function previously had no timeout on the
fetch() call, which could cause switch_browser to hang indefinitely when
the target browser was unreachable or unresponsive.

Changes:
- Added AbortController with configurable timeout (default 10s)
- Enhanced error messages to distinguish timeout from connection failures
- Added test coverage for HTTP fetch timeout behavior
- Updated documentation to reflect new timeout parameter

Fixes potential infinite hang when using HTTP URLs with unreachable browsers.

Author: elijahr

docs/tool-reference.md

@@ -183,6 +183,7 @@
 
 **Parameters:**
 
+- **timeout** (number) _(optional)_: Connection timeout in milliseconds. Defaults to 10000 (10 seconds). If the connection cannot be established within this time, an error will be thrown.
 - **url** (string) **(required)**: Browser connection URL. Can be an HTTP URL (e.g., http://127.0.0.1:9222) which will be auto-converted to WebSocket, or a direct WebSocket endpoint (e.g., ws://127.0.0.1:52862/devtools/browser/<id>).
 
 ---

src/tools/switch_browser.ts

@@ -14,19 +14,35 @@ import {defineTool} from './ToolDefinition.js';
 
 async function convertHttpToBrowserUrl(
   url: string,
+  timeout: number = 10000,
 ): Promise<string | undefined> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeout);
+
   try {
-    const response = await fetch(`${url}/json/version`);
+    const response = await fetch(`${url}/json/version`, {
+      signal: controller.signal,
+    });
     if (!response.ok) {
       throw new Error(`Failed to fetch browser info: ${response.statusText}`);
     }
     const data = await response.json();
     return data.webSocketDebuggerUrl;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+
+    // Provide clearer error message for timeout/abort
+    if (error instanceof Error && error.name === 'AbortError') {
+      throw new Error(
+        `Connection timeout: Could not reach browser at ${url} within ${timeout}ms. Make sure the browser is running and accessible.`,
+      );
+    }
+
     throw new Error(
       `Could not connect to browser at ${url}: ${message}. Make sure the browser is running and the URL is correct.`,
     );
+  } finally {
+    clearTimeout(timeoutId);
   }
 }
 
@@ -73,7 +89,7 @@ export const switchBrowser = defineTool({
       response.appendResponseLine(
         `Fetching WebSocket endpoint from browser at ${url}...`,
       );
-      wsEndpoint = await convertHttpToBrowserUrl(url);
+      wsEndpoint = await convertHttpToBrowserUrl(url, timeout);
       response.appendResponseLine(`Resolved WebSocket endpoint: ${wsEndpoint}`);
       browserURL = url;
     } else {

tests/tools/switch_browser.test.ts

@@ -369,4 +369,71 @@ describe('switch_browser', () => {
       }
     }
   });
+
+  it('respects timeout parameter for HTTP fetch and fails quickly', async () => {
+    const browser = await puppeteer.launch({
+      executablePath: executablePath(),
+      headless: true,
+    });
+
+    try {
+      await browser.newPage();
+      const context = await McpContext.from(
+        browser,
+        logger('test'),
+        {
+          experimentalDevToolsDebugging: false,
+        },
+        Locator,
+      );
+      const response = new McpResponse();
+
+      setBrowser(browser);
+      setContextInstance(context);
+
+      // Use a non-routable IP address (TEST-NET-1, should timeout not error immediately)
+      // and a very short timeout to verify fetch timeout works
+      const httpUrl = 'http://192.0.2.1:9222';
+      const shortTimeout = 500; // 500ms
+
+      const startTime = Date.now();
+
+      try {
+        await switchBrowser.handler(
+          {params: {url: httpUrl, timeout: shortTimeout}},
+          response,
+          context,
+        );
+        assert.fail('Should have thrown a timeout error');
+      } catch (error) {
+        const elapsed = Date.now() - startTime;
+
+        assert.ok(error instanceof Error);
+
+        // Should fail within reasonable time (timeout + small buffer)
+        // Not strict assertion since network behavior varies
+        assert.ok(
+          elapsed < shortTimeout + 1000,
+          `Should timeout quickly, took ${elapsed}ms`,
+        );
+
+        // Check for timeout-related error message
+        const hasTimeoutMessage =
+          error.message.includes('Connection timeout') ||
+          error.message.includes('Could not connect to browser at');
+
+        assert.ok(
+          hasTimeoutMessage,
+          `Error should mention timeout, got: ${error.message}`,
+        );
+      }
+
+      // Browser was closed by disconnectBrowser
+      context.dispose();
+    } finally {
+      if (browser.connected) {
+        await browser.close();
+      }
+    }
+  });
 });