Add WebDriver BiDi support for real-time browser diagnostics

Automatically enables BiDi when starting a browser session to passively
capture console logs, JavaScript errors, and network activity in the
background. Falls back silently if the browser/driver doesn't support it.

New tools:
- get_console_logs: retrieve captured console messages (log, warn, error)
- get_page_errors: retrieve JS errors/exceptions with stack traces
- get_network_logs: retrieve network responses and failed requests

Design decisions:
- No opt-in flag — BiDi is an implementation detail, not a user choice
- Graceful fallback — older browsers work exactly as before
- All BiDi event callbacks wrapped in try/catch to prevent server crashes
- Per-session log buffers, cleaned up automatically on close

Closes #55

Author: angiejones

README.md

@@ -23,6 +23,10 @@ A Model Context Protocol (MCP) server implementation for Selenium WebDriver, ena
 - Upload files
 - Support for headless mode
 - Manage browser cookies (add, get, delete)
+- **Real-time diagnostics** via WebDriver BiDi:
+  - Console log capture (info, warn, error)
+  - JavaScript error detection with stack traces
+  - Network request monitoring (successes and failures)
 
 ## Supported Browsers
 
@@ -791,6 +795,67 @@ Deletes cookies from the current browser session. Deletes a specific cookie by n
 }
 ```
 
+### get_console_logs
+Retrieves captured browser console messages (log, warn, error, etc.). Console logs are automatically captured in the background via WebDriver BiDi when the browser supports it — no configuration needed.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| clear | boolean | No | Clear the captured logs after retrieving them (default: false) |
+
+**Example:**
+```json
+{
+  "tool": "get_console_logs",
+  "parameters": {}
+}
+```
+
+### get_page_errors
+Retrieves captured JavaScript errors and uncaught exceptions with full stack traces. Errors are automatically captured in the background via WebDriver BiDi.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| clear | boolean | No | Clear the captured errors after retrieving them (default: false) |
+
+**Example:**
+```json
+{
+  "tool": "get_page_errors",
+  "parameters": {}
+}
+```
+
+### get_network_logs
+Retrieves captured network activity including successful responses and failed requests. Network logs are automatically captured in the background via WebDriver BiDi.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| clear | boolean | No | Clear the captured logs after retrieving them (default: false) |
+
+**Example:**
+```json
+{
+  "tool": "get_network_logs",
+  "parameters": {}
+}
+```
+
+---
+
+## Diagnostics (WebDriver BiDi)
+
+The server automatically enables [WebDriver BiDi](https://w3c.github.io/webdriver-bidi/) when starting a browser session. BiDi provides real-time, passive capture of browser diagnostics — console messages, JavaScript errors, and network activity are collected in the background without any extra configuration.
+
+This is especially useful for AI agents: when something goes wrong on a page, the agent can check `get_console_logs` and `get_page_errors` to understand *why*, rather than relying solely on screenshots.
+
+- **Automatic**: BiDi is enabled by default when the browser supports it
+- **Graceful fallback**: If the browser or driver doesn't support BiDi, the session starts normally and the diagnostic tools return a helpful message
+- **No performance impact**: Logs are passively captured via event listeners — no polling or extra requests
+- **Per-session**: Each browser session has its own log buffers, cleaned up automatically on session close
+
 ## License
 
 MIT

src/lib/server.js

@@ -10,6 +10,18 @@ import { Options as FirefoxOptions } from 'selenium-webdriver/firefox.js';
 import { Options as EdgeOptions } from 'selenium-webdriver/edge.js';
 import { Options as SafariOptions } from 'selenium-webdriver/safari.js';
 
+// BiDi imports — loaded dynamically to avoid hard failures if not available
+let LogInspector, Network;
+try {
+    LogInspector = (await import('selenium-webdriver/bidi/logInspector.js')).default;
+    const networkModule = await import('selenium-webdriver/bidi/network.js');
+    Network = networkModule.Network;
+} catch (_) {
+    // BiDi modules not available in this selenium-webdriver version
+    LogInspector = null;
+    Network = null;
+}
+
 
 // Create an MCP server
 const server = new McpServer({
@@ -20,7 +32,13 @@ const server = new McpServer({
 // Server state
 const state = {
     drivers: new Map(),
-    currentSession: null
+    currentSession: null,
+    bidiAvailable: new Map(),   // sessionId → boolean
+    consoleLogs: new Map(),     // sessionId → Array
+    pageErrors: new Map(),      // sessionId → Array
+    networkLogs: new Map(),     // sessionId → Array
+    logInspectors: new Map(),   // sessionId → LogInspector (for cleanup)
+    networkInspectors: new Map() // sessionId → Network (for cleanup)
 };
 
 // Helper functions
@@ -69,6 +87,12 @@ server.tool(
             let builder = new Builder();
             let driver;
             let warnings = [];
+
+            // Enable BiDi websocket if the modules are available
+            if (LogInspector && Network) {
+                builder = builder.withCapabilities({ 'webSocketUrl': true });
+            }
+
             switch (browser) {
                 case 'chrome': {
                     const chromeOptions = new ChromeOptions();
@@ -134,7 +158,89 @@ server.tool(
             state.drivers.set(sessionId, driver);
             state.currentSession = sessionId;
 
+            // Attempt to enable BiDi for real-time log capture
+            let bidiEnabled = false;
+            if (LogInspector && Network) {
+                try {
+                    state.consoleLogs.set(sessionId, []);
+                    state.pageErrors.set(sessionId, []);
+                    state.networkLogs.set(sessionId, []);
+
+                    const logInspector = await LogInspector(driver);
+                    await logInspector.onConsoleEntry((entry) => {
+                        try {
+                            const logs = state.consoleLogs.get(sessionId);
+                            if (logs) {
+                                logs.push({
+                                    level: entry.level,
+                                    text: entry.text,
+                                    timestamp: entry.timestamp,
+                                    type: entry.type,
+                                    method: entry.method,
+                                    args: entry.args
+                                });
+                            }
+                        } catch (_) { /* ignore malformed entry */ }
+                    });
+                    await logInspector.onJavascriptLog((entry) => {
+                        try {
+                            const errors = state.pageErrors.get(sessionId);
+                            if (errors) {
+                                errors.push({
+                                    level: entry.level,
+                                    text: entry.text,
+                                    timestamp: entry.timestamp,
+                                    type: entry.type,
+                                    stackTrace: entry.stackTrace
+                                });
+                            }
+                        } catch (_) { /* ignore malformed entry */ }
+                    });
+                    state.logInspectors.set(sessionId, logInspector);
+
+                    const network = await Network(driver);
+                    await network.responseCompleted((event) => {
+                        try {
+                            const logs = state.networkLogs.get(sessionId);
+                            if (logs) {
+                                logs.push({
+                                    type: 'response',
+                                    url: event.request?.url,
+                                    status: event.response?.status,
+                                    method: event.request?.method,
+                                    mimeType: event.response?.mimeType,
+                                    timestamp: Date.now()
+                                });
+                            }
+                        } catch (_) { /* ignore malformed event */ }
+                    });
+                    await network.fetchError((event) => {
+                        try {
+                            const logs = state.networkLogs.get(sessionId);
+                            if (logs) {
+                                logs.push({
+                                    type: 'error',
+                                    url: event.request?.url,
+                                    method: event.request?.method,
+                                    errorText: event.errorText,
+                                    timestamp: Date.now()
+                                });
+                            }
+                        } catch (_) { /* ignore malformed event */ }
+                    });
+                    state.networkInspectors.set(sessionId, network);
+
+                    bidiEnabled = true;
+                } catch (_) {
+                    // BiDi not supported by this browser/driver — continue without it
+                }
+            }
+            state.bidiAvailable.set(sessionId, bidiEnabled);
+
             let message = `Browser started with session_id: ${sessionId}`;
+            if (bidiEnabled) {
+                message += ' (BiDi enabled: console logs, JS errors, and network activity are being captured)';
+            }
             if (warnings.length > 0) {
                 message += `\nWarnings: ${warnings.join(' ')}`;
             }
@@ -473,9 +579,16 @@ server.tool(
     async () => {
         try {
             const driver = getDriver();
-            await driver.quit();
-            state.drivers.delete(state.currentSession);
             const sessionId = state.currentSession;
+            await driver.quit();
+            state.drivers.delete(sessionId);
+            // Clean up BiDi state
+            state.bidiAvailable.delete(sessionId);
+            state.consoleLogs.delete(sessionId);
+            state.pageErrors.delete(sessionId);
+            state.networkLogs.delete(sessionId);
+            state.logInspectors.delete(sessionId);
+            state.networkInspectors.delete(sessionId);
             state.currentSession = null;
             return {
                 content: [{ type: 'text', text: `Browser session ${sessionId} closed` }]
@@ -957,6 +1070,109 @@ server.tool(
     }
 );
 
+// BiDi Diagnostic Tools
+server.tool(
+    "get_console_logs",
+    "returns browser console messages (log, warn, info, debug) captured via WebDriver BiDi. Useful for debugging page behavior, seeing application output, and catching warnings.",
+    {
+        clear: z.boolean().optional().describe("Clear the logs after returning them (default: false)")
+    },
+    async ({ clear = false }) => {
+        try {
+            getDriver(); // ensure active session
+            const sessionId = state.currentSession;
+            if (!state.bidiAvailable.get(sessionId)) {
+                return {
+                    content: [{ type: 'text', text: 'Console log capture is not available (BiDi not supported by this browser/driver)' }]
+                };
+            }
+            const logs = state.consoleLogs.get(sessionId) || [];
+            const result = logs.length === 0
+                ? 'No console logs captured'
+                : JSON.stringify(logs, null, 2);
+            if (clear) {
+                state.consoleLogs.set(sessionId, []);
+            }
+            return {
+                content: [{ type: 'text', text: result }]
+            };
+        } catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error getting console logs: ${e.message}` }],
+                isError: true
+            };
+        }
+    }
+);
+
+server.tool(
+    "get_page_errors",
+    "returns JavaScript errors and exceptions captured via WebDriver BiDi. Includes stack traces when available. Essential for diagnosing why a page is broken or a feature isn't working.",
+    {
+        clear: z.boolean().optional().describe("Clear the errors after returning them (default: false)")
+    },
+    async ({ clear = false }) => {
+        try {
+            getDriver(); // ensure active session
+            const sessionId = state.currentSession;
+            if (!state.bidiAvailable.get(sessionId)) {
+                return {
+                    content: [{ type: 'text', text: 'Page error capture is not available (BiDi not supported by this browser/driver)' }]
+                };
+            }
+            const errors = state.pageErrors.get(sessionId) || [];
+            const result = errors.length === 0
+                ? 'No page errors captured'
+                : JSON.stringify(errors, null, 2);
+            if (clear) {
+                state.pageErrors.set(sessionId, []);
+            }
+            return {
+                content: [{ type: 'text', text: result }]
+            };
+        } catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error getting page errors: ${e.message}` }],
+                isError: true
+            };
+        }
+    }
+);
+
+server.tool(
+    "get_network_logs",
+    "returns network activity (completed responses and failed requests) captured via WebDriver BiDi. Shows HTTP status codes, URLs, methods, and error details. Useful for diagnosing failed API calls and broken resources.",
+    {
+        clear: z.boolean().optional().describe("Clear the logs after returning them (default: false)")
+    },
+    async ({ clear = false }) => {
+        try {
+            getDriver(); // ensure active session
+            const sessionId = state.currentSession;
+            if (!state.bidiAvailable.get(sessionId)) {
+                return {
+                    content: [{ type: 'text', text: 'Network log capture is not available (BiDi not supported by this browser/driver)' }]
+                };
+            }
+            const logs = state.networkLogs.get(sessionId) || [];
+            const result = logs.length === 0
+                ? 'No network activity captured'
+                : JSON.stringify(logs, null, 2);
+            if (clear) {
+                state.networkLogs.set(sessionId, []);
+            }
+            return {
+                content: [{ type: 'text', text: result }]
+            };
+        } catch (e) {
+            return {
+                content: [{ type: 'text', text: `Error getting network logs: ${e.message}` }],
+                isError: true
+            };
+        }
+    }
+);
+
 // Resources
 server.resource(
     "browser-status",
@@ -986,6 +1202,12 @@ async function cleanup() {
         }
     }
     state.drivers.clear();
+    state.bidiAvailable.clear();
+    state.consoleLogs.clear();
+    state.pageErrors.clear();
+    state.networkLogs.clear();
+    state.logInspectors.clear();
+    state.networkInspectors.clear();
     state.currentSession = null;
     process.exit(0);
 }