browser-debug-mcp-bridge 1.4.0 → 1.5.0

package/README.md

@@ -1,94 +1,204 @@
 # Browser Debug MCP Bridge
 
-Chrome Extension + local Node.js MCP server that captures browser debugging telemetry from a real user session and exposes it through MCP tools.
+Chrome Extension + local Node.js MCP runtime for real-browser debugging.
 
-## Why this project exists
+It captures telemetry from an actual browser session (console, network, navigation, UI events), stores it locally, and exposes debugging tools through MCP to your AI client.
 
-- Debug with real browser context (logged-in sessions, feature flags, extensions)
-- Store lightweight telemetry continuously, request heavy DOM data on demand
-- Keep privacy-first defaults with safe mode, allowlists, and redaction
+## What You Can Do
 
-## Prerequisites
+- Inspect real sessions instead of synthetic test runs
+- Query recent errors, failed requests, and event timelines
+- Run targeted live capture (DOM subtree/document, styles, layout)
+- Correlate user actions with network/runtime failures
+- Keep privacy controls enabled (safe mode, allowlist, redaction)
 
-- Node.js 20+
-- pnpm 9+
-- Chrome (for the extension)
+## How It Works
 
-## Quick start
+1. Chrome extension captures session telemetry.
+2. Local server ingests via HTTP/WebSocket on `127.0.0.1:8065`.
+3. Data is persisted in local SQLite.
+4. MCP stdio server exposes tools to your AI client.
+
+## Requirements
+
+- Node.js `>=20`
+- pnpm `>=9` (for local repo mode)
+- Chrome (Developer Mode to load unpacked extension)
+
+## Setup Modes
+
+### Recommended: Full Local Setup (MCP + Extension)
+
+Use this when you want the full product (including extension).
 
 ```bash
+git clone https://github.com/RobertoM80/browser-debug-mcp-bridge.git
+cd browser-debug-mcp-bridge
 pnpm install
-pnpm nx serve mcp-server
-pnpm nx build chrome-extension --watch
+pnpm nx build mcp-server
+pnpm nx build chrome-extension
 ```
 
-Run unified ingest + MCP stdio runtime (for external MCP clients):
+Load extension:
+
+1. Open `chrome://extensions`
+2. Enable Developer mode
+3. Click **Load unpacked**
+4. Select `dist/apps/chrome-extension`
+
+Start MCP runtime:
 
 ```bash
-pnpm install
 node scripts/mcp-start.cjs
 ```
 
-Quick npm MCP launch (marketplace-style, after publish):
+### Quick Runtime (MCP server launcher only)
+
+If you already have extension/runtime assets aligned, you can launch from npm:
 
 ```bash
 npx -y browser-debug-mcp-bridge
 ```
 
-Note: npm mode starts the MCP server runtime. The Chrome extension still needs to be built/loaded separately (see "Load the extension").
-
-GitHub fallback launch (if npm package is not available yet):
+GitHub fallback (if npm registry package is unavailable):
 
 ```bash
 npx -y --package=github:RobertoM80/browser-debug-mcp-bridge browser-debug-mcp-bridge
 ```
 
-Optional one-step setup scripts:
+Important:
+
+- This only starts the runtime.
+- You still need a compatible extension connected to `127.0.0.1:8065`.
+
+## MCP Client Configuration
+
+Generate ready-to-paste snippets:
 
 ```bash
-# Windows (PowerShell)
-./install.ps1
+pnpm mcp:print-config
+```
 
-# macOS/Linux
-bash ./install.sh
+### OpenAI (Codex CLI / Codex in VS Code)
+
+Edit `~/.codex/config.toml` (Windows: `C:\Users\<you>\.codex\config.toml`) and add:
+
+```toml
+[mcp_servers.browser_debug]
+command = "node"
+args = ["C:\\ABSOLUTE\\PATH\\TO\\browser-debug-mcp-bridge\\scripts\\mcp-start.cjs"]
+```
+
+npm quick mode:
+
+```toml
+[mcp_servers.browser_debug]
+command = "npx"
+args = ["-y", "browser-debug-mcp-bridge"]
+```
+
+### OpenCode
+
+Use JSON MCP config:
+
+```json
+{
+  "mcpServers": {
+    "browser-debug": {
+      "command": "node",
+      "args": [
+        "C:\\ABSOLUTE\\PATH\\TO\\browser-debug-mcp-bridge\\scripts\\mcp-start.cjs"
+      ]
+    }
+  }
+}
+```
+
+### VS Code (any MCP host expecting command/args)
+
+Use the same values:
+
+- `command`: `node`
+- `args`: `[
+  "<ABSOLUTE_PATH>/scripts/mcp-start.cjs"
+]`
+
+If your VS Code MCP host uses JSON, reuse the OpenCode JSON block above.
+
+## First End-to-End Check
+
+- Start MCP host/client (so it launches this server).
+- Open extension popup, allowlist domain, start a session.
+- Ask your AI client to run:
+
+```json
+{ "name": "list_sessions", "arguments": { "sinceMinutes": 60 } }
+```
+
+- Pick a session where `liveConnection.connected` is `true`.
+- Run query tools first (`get_session_summary`, `get_recent_events`, `get_network_failures`).
+- Use live tools (`get_dom_document`, `capture_ui_snapshot`) only on connected sessions.
+
+## Port and Startup Behavior
+
+Default port is `8065`.
+
+- On Windows, launcher tries automatic stale bridge recovery first.
+- If port is still occupied, startup fails with `MCP_STARTUP_PORT_IN_USE`.
+- In that case, free/reserve port `8065` for this bridge and restart.
+- In `mcp-stdio` mode, bridge lifecycle is tied to the host and should stop when host transport closes.
+- If a stale process still remains, stop it explicitly with `node scripts/mcp-start.cjs --stop`.
+
+Useful Windows command:
+
+```powershell
+netstat -ano | findstr :8065
 ```
 
-Useful workspace commands:
+Stop command:
 
 ```bash
-pnpm typecheck
-pnpm test
-pnpm nx run-many -t lint
-pnpm nx run-many -t build
+node scripts/mcp-start.cjs --stop
 ```
 
-Enable local pre-commit checks (typecheck + lint + test before each commit):
+## Common Failure Signals
+
+- `LIVE_SESSION_DISCONNECTED`: session exists in DB but no active extension transport. Fix: restart/reconnect extension session, then use a `liveConnection.connected = true` session id.
+- `MCP_STARTUP_PORT_IN_USE`: required MCP port is blocked. Fix: stop the process using that port and restart bridge.
+
+## Useful Commands
 
 ```bash
-pnpm hooks:install
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm build
+pnpm docs:ci
+pnpm verify
+node scripts/mcp-start.cjs --stop
 ```
 
-## Load the extension
+Optional one-shot local setup:
 
-1. Build the extension: `pnpm nx build chrome-extension`
-2. Open Chrome -> `chrome://extensions`
-3. Enable Developer mode
-4. Click **Load unpacked**
-5. Select `dist/apps/chrome-extension`
+```powershell
+# Windows
+./install.ps1
+```
+
+```bash
+# macOS/Linux
+bash ./install.sh
+```
 
-## Main docs
+## Tooling Docs
 
-- Project spec: `PROJECT_INFOS.md`
-- Full beginner setup guide: `HOW_TO_USE_BROWSER_DEBUG_MCP_BRIDGE.md`
-- MCP tools reference: `docs/MCP_TOOLS.md`
-- MCP client setup (Codex/Claude/Cursor/Windsurf): `docs/MCP_CLIENT_SETUP.md`
-- GitHub Actions explained: `docs/GITHUB_ACTIONS.md`
-- Security and privacy controls: `SECURITY.md`
-- Troubleshooting guide: `docs/TROUBLESHOOTING.md`
-- Architecture overview: `docs/ARCHITECTURE.md`
-- Architecture decisions: `docs/ARCHITECTURE_DECISIONS.md`
+- [MCP tools reference](https://github.com/RobertoM80/browser-debug-mcp-bridge/blob/main/docs/MCP_TOOLS.md)
+- [MCP client setup](https://github.com/RobertoM80/browser-debug-mcp-bridge/blob/main/docs/MCP_CLIENT_SETUP.md)
+- [Troubleshooting](https://github.com/RobertoM80/browser-debug-mcp-bridge/blob/main/docs/TROUBLESHOOTING.md)
+- [Architecture](https://github.com/RobertoM80/browser-debug-mcp-bridge/blob/main/docs/ARCHITECTURE.md)
+- [Security and privacy](https://github.com/RobertoM80/browser-debug-mcp-bridge/blob/main/SECURITY.md)
 
-## Repository layout
+## Repository Layout
 
 ```text
 apps/
@@ -98,6 +208,6 @@ apps/
 libs/
   shared/             Shared schemas/types/utils
   redaction/          Privacy redaction engine
-  selectors/          Robust selector generation
-  mcp-contracts/      MCP tool contracts and schemas 
+  selectors/          Selector generation
+  mcp-contracts/      MCP tool contracts and schemas
 ```

package/apps/mcp-server/dist/mcp/server.js

@@ -225,6 +225,7 @@ const DEFAULT_EVENT_LIMIT = 50;
 const MAX_LIMIT = 200;
 const DEFAULT_SNAPSHOT_ASSET_CHUNK_BYTES = 64 * 1024;
 const MAX_SNAPSHOT_ASSET_CHUNK_BYTES = 256 * 1024;
+const LIVE_SESSION_DISCONNECTED_CODE = 'LIVE_SESSION_DISCONNECTED';
 const NETWORK_DOMAIN_GROUP_SQL = `
   CASE
     WHEN instr(replace(replace(url, 'https://', ''), 'http://', ''), '/') > 0
@@ -236,6 +237,16 @@ const NETWORK_DOMAIN_GROUP_SQL = `
     ELSE replace(replace(url, 'https://', ''), 'http://', '')
   END
 `;
+class LiveSessionDisconnectedError extends Error {
+    code = LIVE_SESSION_DISCONNECTED_CODE;
+    constructor(sessionId, reason) {
+        const normalizedReason = typeof reason === 'string' && reason.trim().length > 0
+            ? reason.trim()
+            : 'Extension connection is stale or unavailable';
+        super(`${LIVE_SESSION_DISCONNECTED_CODE}: Session ${sessionId} is not connected to a live extension target. ${normalizedReason}. Start a fresh session in the extension and retry with a connected sessionId from list_sessions.`);
+        this.name = 'LiveSessionDisconnectedError';
+    }
+}
 function resolveLimit(value, fallback) {
     if (typeof value !== 'number' || !Number.isFinite(value)) {
         return fallback;
@@ -517,13 +528,42 @@ function asStringArray(value, maxItems) {
         .filter((entry) => typeof entry === 'string' && entry.length > 0)
         .slice(0, maxItems);
 }
-function ensureCaptureSuccess(result) {
+function isLiveSessionDisconnectedMessage(message) {
+    const normalized = message.toLowerCase();
+    return normalized.includes('no active extension connection')
+        || normalized.includes('receiving end does not exist')
+        || normalized.includes('could not establish connection')
+        || normalized.includes('connection closed before capture completed')
+        || normalized.includes('websocket manager closed')
+        || normalized.includes('extension target is unavailable')
+        || normalized.includes('target tab for this session is unavailable');
+}
+function normalizeCaptureError(sessionId, error) {
+    const fallback = error instanceof Error ? error : new Error(String(error));
+    const message = fallback.message ?? '';
+    if (isLiveSessionDisconnectedMessage(message)) {
+        return new LiveSessionDisconnectedError(sessionId, message);
+    }
+    return fallback;
+}
+function isLiveSessionDisconnectedError(error) {
+    return error instanceof LiveSessionDisconnectedError;
+}
+async function executeLiveCapture(captureClient, sessionId, command, payload, timeoutMs) {
+    try {
+        return await captureClient.execute(sessionId, command, payload, timeoutMs);
+    }
+    catch (error) {
+        throw normalizeCaptureError(sessionId, error);
+    }
+}
+function ensureCaptureSuccess(result, sessionId) {
     if (!result.ok) {
-        throw new Error(result.error ?? 'Capture command failed');
+        throw normalizeCaptureError(sessionId, new Error(result.error ?? 'Capture command failed'));
     }
     return result.payload ?? {};
 }
-export function createV1ToolHandlers(getDb) {
+export function createV1ToolHandlers(getDb, getSessionConnectionState) {
     return {
         list_sessions: async (input) => {
             const db = getDb();
@@ -577,6 +617,23 @@ export function createV1ToolHandlers(getDb) {
                 dpr: row.dpr ?? undefined,
                 safeMode: row.safe_mode === 1,
                 pinned: row.pinned === 1,
+                liveConnection: (() => {
+                    const state = getSessionConnectionState?.(row.session_id);
+                    if (!state) {
+                        return {
+                            connected: false,
+                            lastHeartbeatAt: undefined,
+                            disconnectReason: row.ended_at ? 'manual_stop' : undefined,
+                        };
+                    }
+                    return {
+                        connected: state.connected,
+                        connectedAt: state.connectedAt,
+                        lastHeartbeatAt: state.lastHeartbeatAt,
+                        disconnectedAt: state.disconnectedAt,
+                        disconnectReason: state.disconnectReason,
+                    };
+                })(),
             }));
             return {
                 ...createBaseResponse(),
@@ -1373,14 +1430,14 @@ export function createV2ToolHandlers(captureClient) {
             }
             const maxDepth = resolveCaptureDepth(input.maxDepth, 3);
             const maxBytes = resolveCaptureBytes(input.maxBytes, 50_000);
-            const capture = await captureClient.execute(sessionId, 'CAPTURE_DOM_SUBTREE', { selector, maxDepth, maxBytes }, 4_000);
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_DOM_SUBTREE', { selector, maxDepth, maxBytes }, 4_000);
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
                     maxResults: maxBytes,
                     truncated: capture.truncated ?? false,
                 },
-                ...ensureCaptureSuccess(capture),
+                ...ensureCaptureSuccess(capture, sessionId),
             };
         },
         get_dom_document: async (input) => {
@@ -1392,21 +1449,22 @@ export function createV2ToolHandlers(captureClient) {
             const maxBytes = resolveCaptureBytes(input.maxBytes, 200_000);
             const maxDepth = resolveCaptureDepth(input.maxDepth, 4);
             try {
-                const capture = await captureClient.execute(sessionId, 'CAPTURE_DOM_DOCUMENT', { mode, maxBytes, maxDepth }, 4_000);
+                const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_DOM_DOCUMENT', { mode, maxBytes, maxDepth }, 4_000);
                 return {
                     ...createBaseResponse(sessionId),
                     limitsApplied: {
                         maxResults: maxBytes,
                         truncated: capture.truncated ?? false,
                     },
-                    ...ensureCaptureSuccess(capture),
+                    ...ensureCaptureSuccess(capture, sessionId),
                 };
             }
             catch (error) {
-                if (mode !== 'html') {
-                    throw error;
+                const normalized = normalizeCaptureError(sessionId, error);
+                if (mode !== 'html' || isLiveSessionDisconnectedError(normalized)) {
+                    throw normalized;
                 }
-                const fallback = await captureClient.execute(sessionId, 'CAPTURE_DOM_DOCUMENT', { mode: 'outline', maxBytes, maxDepth }, 4_000);
+                const fallback = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_DOM_DOCUMENT', { mode: 'outline', maxBytes, maxDepth }, 4_000);
                 return {
                     ...createBaseResponse(sessionId),
                     limitsApplied: {
@@ -1414,7 +1472,7 @@ export function createV2ToolHandlers(captureClient) {
                         truncated: true,
                     },
                     fallbackReason: 'timeout',
-                    ...ensureCaptureSuccess(fallback),
+                    ...ensureCaptureSuccess(fallback, sessionId),
                 };
             }
         },
@@ -1428,14 +1486,14 @@ export function createV2ToolHandlers(captureClient) {
                 throw new Error('selector is required');
             }
             const properties = asStringArray(input.properties, 64);
-            const capture = await captureClient.execute(sessionId, 'CAPTURE_COMPUTED_STYLES', { selector, properties }, 3_000);
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_COMPUTED_STYLES', { selector, properties }, 3_000);
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
                     maxResults: properties.length || 8,
                     truncated: capture.truncated ?? false,
                 },
-                ...ensureCaptureSuccess(capture),
+                ...ensureCaptureSuccess(capture, sessionId),
             };
         },
         get_layout_metrics: async (input) => {
@@ -1444,14 +1502,14 @@ export function createV2ToolHandlers(captureClient) {
                 throw new Error('sessionId is required');
             }
             const selector = typeof input.selector === 'string' ? input.selector : undefined;
-            const capture = await captureClient.execute(sessionId, 'CAPTURE_LAYOUT_METRICS', { selector }, 3_000);
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_LAYOUT_METRICS', { selector }, 3_000);
             return {
                 ...createBaseResponse(sessionId),
                 limitsApplied: {
                     maxResults: 1,
                     truncated: capture.truncated ?? false,
                 },
-                ...ensureCaptureSuccess(capture),
+                ...ensureCaptureSuccess(capture, sessionId),
             };
         },
         capture_ui_snapshot: async (input) => {
@@ -1473,7 +1531,7 @@ export function createV2ToolHandlers(captureClient) {
             const maxDepth = resolveCaptureDepth(input.maxDepth, 3);
             const maxBytes = resolveCaptureBytes(input.maxBytes, 50_000);
             const maxAncestors = resolveCaptureAncestors(input.maxAncestors, 4);
-            const capture = await captureClient.execute(sessionId, 'CAPTURE_UI_SNAPSHOT', {
+            const capture = await executeLiveCapture(captureClient, sessionId, 'CAPTURE_UI_SNAPSHOT', {
                 selector,
                 trigger,
                 mode,
@@ -1490,7 +1548,7 @@ export function createV2ToolHandlers(captureClient) {
                     maxResults: maxBytes,
                     truncated: capture.truncated ?? false,
                 },
-                ...ensureCaptureSuccess(capture),
+                ...ensureCaptureSuccess(capture, sessionId),
             };
         },
     };
@@ -1542,7 +1600,7 @@ export function createMCPServer(overrides = {}, options = {}) {
     const logger = options.logger ?? createDefaultMcpLogger();
     const v2Handlers = options.captureClient ? createV2ToolHandlers(options.captureClient) : {};
     const tools = createToolRegistry({
-        ...createV1ToolHandlers(() => getConnection().db),
+        ...createV1ToolHandlers(() => getConnection().db, options.getSessionConnectionState),
         ...v2Handlers,
         ...overrides,
     });