browser-debug-mcp-bridge 1.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# 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.
+
+## Why this project exists
+
+- 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
+
+## Prerequisites
+
+- Node.js 20+
+- pnpm 9+
+- Chrome (for the extension)
+
+## Quick start
+
+```bash
+pnpm install
+pnpm nx serve mcp-server
+pnpm nx build chrome-extension --watch
+```
+
+Run unified ingest + MCP stdio runtime (for external MCP clients):
+
+```bash
+pnpm install
+node scripts/mcp-start.cjs
+```
+
+Quick npm MCP launch (marketplace-style, after publish):
+
+```bash
+npx -y browser-debug-mcp-bridge
+```
+
+GitHub fallback launch (if npm package is not available yet):
+
+```bash
+npx -y --package=github:RobertoM80/browser-debug-mcp-bridge browser-debug-mcp-bridge
+```
+
+Optional one-step setup scripts:
+
+```bash
+# Windows (PowerShell)
+./install.ps1
+
+# macOS/Linux
+bash ./install.sh
+```
+
+Useful workspace commands:
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm nx run-many -t lint
+pnpm nx run-many -t build
+```
+
+Enable local pre-commit checks (typecheck + lint + test before each commit):
+
+```bash
+pnpm hooks:install
+```
+
+## Load the extension
+
+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`
+
+## Main 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`
+
+## Repository layout
+
+```text
+apps/
+  mcp-server/         Fastify + WebSocket ingest + MCP server
+  chrome-extension/   MV3 extension (background/content/injected)
+  viewer/             Optional UI
+libs/
+  shared/             Shared schemas/types/utils
+  redaction/          Privacy redaction engine
+  selectors/          Robust selector generation
+  mcp-contracts/      MCP tool contracts and schemas
+```

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

@@ -0,0 +1,42 @@
+import Database from 'better-sqlite3';
+import { join } from 'path';
+import { dirname } from 'path';
+import { mkdirSync } from 'fs';
+let connection = null;
+export function getDatabasePath() {
+    const dataDir = process.env.DATA_DIR || join(process.cwd(), 'data');
+    return join(dataDir, 'browser-debug.db');
+}
+export function createConnection(dbPath) {
+    const path = dbPath || getDatabasePath();
+    if (path !== ':memory:') {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    const db = new Database(path);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    return {
+        db,
+        isConnected: true
+    };
+}
+export function getConnection() {
+    if (!connection) {
+        connection = createConnection();
+    }
+    return connection;
+}
+export function closeConnection() {
+    if (connection) {
+        connection.db.close();
+        connection = null;
+    }
+}
+export function isConnected() {
+    return connection !== null && connection.isConnected;
+}
+export function resetConnection() {
+    closeConnection();
+    connection = null;
+}
+//# sourceMappingURL=connection.js.map

package/apps/mcp-server/dist/db/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAO/B,IAAI,UAAU,GAA8B,IAAI,CAAC;AAEjD,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;IACpE,OAAO,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAe;IAC9C,MAAM,IAAI,GAAG,MAAM,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QACxB,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;IAE9B,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAE/B,OAAO;QACL,EAAE;QACF,WAAW,EAAE,IAAI;KAClB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,UAAU,GAAG,gBAAgB,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,IAAI,UAAU,EAAE,CAAC;QACf,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QACtB,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,UAAU,KAAK,IAAI,IAAI,UAAU,CAAC,WAAW,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,eAAe,EAAE,CAAC;IAClB,UAAU,GAAG,IAAI,CAAC;AACpB,CAAC"}

package/apps/mcp-server/dist/db/error-fingerprints.js

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto';
+function normalizeText(value) {
+    return value.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+export function createErrorFingerprint(message, stack) {
+    const normalizedMessage = normalizeText(message || 'unknown error');
+    const normalizedStack = normalizeText(stack || '');
+    const source = `${normalizedMessage}\n${normalizedStack}`;
+    const digest = createHash('sha256').update(source).digest('hex').slice(0, 16);
+    return `fp-${digest}`;
+}
+export function resolveErrorFingerprint(data) {
+    const provided = typeof data.fingerprint === 'string' ? data.fingerprint.trim() : '';
+    if (provided) {
+        return provided;
+    }
+    const message = typeof data.message === 'string' ? data.message : 'Unknown error';
+    const stack = typeof data.stack === 'string' ? data.stack : undefined;
+    return createErrorFingerprint(message, stack);
+}
+//# sourceMappingURL=error-fingerprints.js.map

package/apps/mcp-server/dist/db/error-fingerprints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-fingerprints.js","sourceRoot":"","sources":["../../src/db/error-fingerprints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,OAAe,EAAE,KAAc;IACpE,MAAM,iBAAiB,GAAG,aAAa,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC;IACpE,MAAM,eAAe,GAAG,aAAa,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,GAAG,iBAAiB,KAAK,eAAe,EAAE,CAAC;IAC1D,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9E,OAAO,MAAM,MAAM,EAAE,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAA6B;IACnE,MAAM,QAAQ,GAAG,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrF,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IAClF,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAEtE,OAAO,sBAAsB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/apps/mcp-server/dist/db/events-repository.js

@@ -0,0 +1,109 @@
+import { resolveErrorFingerprint } from './error-fingerprints';
+import { getDatabasePath } from './connection';
+import { writeSnapshot } from '../retention';
+export class EventsRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    insertEventsBatch(messages) {
+        if (messages.length === 0) {
+            return;
+        }
+        const insert = this.db.prepare(`
+      INSERT INTO events (event_id, session_id, ts, type, payload_json)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+        const insertNetwork = this.db.prepare(`
+      INSERT INTO network (
+        request_id, session_id, ts_start, duration_ms, method, url, status, initiator, error_class, response_size_est
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const upsertFingerprint = this.db.prepare(`
+      INSERT INTO error_fingerprints (
+        fingerprint, session_id, count, sample_message, sample_stack, first_seen_at, last_seen_at
+      ) VALUES (?, ?, 1, ?, ?, ?, ?)
+      ON CONFLICT(fingerprint) DO UPDATE SET
+        count = count + 1,
+        last_seen_at = excluded.last_seen_at,
+        sample_message = COALESCE(error_fingerprints.sample_message, excluded.sample_message),
+        sample_stack = COALESCE(error_fingerprints.sample_stack, excluded.sample_stack)
+    `);
+        const runBatch = this.db.transaction((batch) => {
+            for (const message of batch) {
+                const eventId = `${message.sessionId}-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+                const dbEventType = this.mapEventType(message.eventType);
+                insert.run(eventId, message.sessionId, message.timestamp ?? Date.now(), dbEventType, JSON.stringify(message.data));
+                if (message.eventType === 'error') {
+                    this.upsertErrorFingerprintPrepared(upsertFingerprint, message.sessionId, message.data);
+                }
+                if (message.eventType === 'network') {
+                    this.insertNetworkEventPrepared(insertNetwork, message.sessionId, message.data);
+                }
+                if (message.eventType === 'ui_snapshot') {
+                    this.insertSnapshotPrepared(message.sessionId, eventId, message.data);
+                }
+            }
+        });
+        runBatch(messages);
+    }
+    createSession(message) {
+        const insert = this.db.prepare(`
+      INSERT INTO sessions (
+        session_id, created_at, tab_id, window_id, url_start, url_last,
+        user_agent, viewport_w, viewport_h, dpr, safe_mode, allowlist_hash
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const now = Date.now();
+        insert.run(message.sessionId, now, message.tabId ?? null, message.windowId ?? null, message.url, message.url, message.userAgent ?? null, message.viewport?.width ?? null, message.viewport?.height ?? null, message.dpr ?? null, message.safeMode ? 1 : 0, null);
+    }
+    endSession(message) {
+        const update = this.db.prepare(`
+      UPDATE sessions 
+      SET ended_at = ?
+      WHERE session_id = ?
+    `);
+        update.run(Date.now(), message.sessionId);
+    }
+    insertEvent(message) {
+        this.insertEventsBatch([message]);
+    }
+    mapEventType(eventType) {
+        const mapping = {
+            'navigation': 'nav',
+            'console': 'console',
+            'error': 'error',
+            'network': 'network',
+            'click': 'ui',
+            'scroll': 'ui',
+            'input': 'ui',
+            'change': 'ui',
+            'submit': 'ui',
+            'focus': 'ui',
+            'blur': 'ui',
+            'keydown': 'ui',
+            'ui_snapshot': 'ui',
+            'custom': 'ui',
+        };
+        return mapping[eventType] || 'ui';
+    }
+    upsertErrorFingerprintPrepared(statement, sessionId, data) {
+        const fingerprint = resolveErrorFingerprint(data);
+        if (!fingerprint)
+            return;
+        const now = Date.now();
+        statement.run(fingerprint, sessionId, data.message ?? 'Unknown error', data.stack ?? null, now, now);
+    }
+    insertNetworkEventPrepared(statement, sessionId, data) {
+        const requestId = `${sessionId}-net-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+        statement.run(requestId, sessionId, data.timestamp ?? Date.now(), data.duration ?? null, data.method ?? 'GET', data.url ?? '', data.status ?? null, data.initiator ?? 'other', data.errorType ?? null, data.responseSize ?? null);
+    }
+    insertSnapshotPrepared(sessionId, triggerEventId, data) {
+        writeSnapshot(this.db, getDatabasePath(), sessionId, data, triggerEventId);
+    }
+    sessionExists(sessionId) {
+        const result = this.db.prepare('SELECT 1 FROM sessions WHERE session_id = ?').get(sessionId);
+        return !!result;
+    }
+}
+//# sourceMappingURL=events-repository.js.map

package/apps/mcp-server/dist/db/events-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events-repository.js","sourceRoot":"","sources":["../../src/db/events-repository.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,4 @@
+export * from './connection';
+export * from './schema';
+export * from './migrations';
+//# sourceMappingURL=index.js.map

package/apps/mcp-server/dist/db/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC"}

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

@@ -0,0 +1,101 @@
+import { initializeSchema, getSchemaVersion, clearDatabase, SCHEMA_VERSION } from './schema';
+const migrations = [
+    {
+        version: 1,
+        name: 'initial_schema',
+        up: initializeSchema
+    },
+    {
+        version: 2,
+        name: 'retention_and_pinning',
+        up: (db) => {
+            const hasPinnedColumn = db.prepare("PRAGMA table_info('sessions')").all().some((column) => column.name === 'pinned');
+            if (!hasPinnedColumn) {
+                db.exec(`
+          ALTER TABLE sessions ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0;
+        `);
+            }
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_sessions_pinned_created_at ON sessions(pinned, created_at);
+      `);
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS server_settings (
+          id INTEGER PRIMARY KEY CHECK (id = 1),
+          retention_days INTEGER NOT NULL DEFAULT 30,
+          max_db_mb INTEGER NOT NULL DEFAULT 1024,
+          max_sessions INTEGER NOT NULL DEFAULT 10000,
+          cleanup_interval_minutes INTEGER NOT NULL DEFAULT 60,
+          last_cleanup_at INTEGER,
+          export_path_override TEXT
+        );
+      `);
+            db.exec(`
+        INSERT OR IGNORE INTO server_settings (
+          id,
+          retention_days,
+          max_db_mb,
+          max_sessions,
+          cleanup_interval_minutes,
+          last_cleanup_at,
+          export_path_override
+        ) VALUES (1, 30, 1024, 10000, 60, NULL, NULL);
+      `);
+        }
+    },
+    {
+        version: 3,
+        name: 'snapshots_storage',
+        up: (db) => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS snapshots (
+          snapshot_id TEXT PRIMARY KEY,
+          session_id TEXT NOT NULL,
+          trigger_event_id TEXT,
+          ts INTEGER NOT NULL,
+          trigger TEXT NOT NULL,
+          selector TEXT,
+          url TEXT,
+          mode TEXT NOT NULL,
+          style_mode TEXT,
+          dom_json TEXT,
+          styles_json TEXT,
+          png_path TEXT,
+          png_mime TEXT,
+          png_bytes INTEGER,
+          dom_truncated INTEGER NOT NULL DEFAULT 0,
+          styles_truncated INTEGER NOT NULL DEFAULT 0,
+          png_truncated INTEGER NOT NULL DEFAULT 0,
+          created_at INTEGER NOT NULL,
+          FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE,
+          FOREIGN KEY (trigger_event_id) REFERENCES events(event_id) ON DELETE SET NULL
+        );
+      `);
+            db.exec(`
+        CREATE INDEX IF NOT EXISTS idx_snapshots_session_ts ON snapshots(session_id, ts);
+        CREATE INDEX IF NOT EXISTS idx_snapshots_session_trigger_ts ON snapshots(session_id, trigger, ts);
+        CREATE INDEX IF NOT EXISTS idx_snapshots_png_path ON snapshots(png_path);
+      `);
+        },
+    }
+];
+export function runMigrations(db) {
+    const currentVersion = getSchemaVersion(db) || 0;
+    const pendingMigrations = migrations.filter(m => m.version > currentVersion);
+    for (const migration of pendingMigrations) {
+        migration.up(db);
+        const insertVersion = db.prepare(`
+      INSERT INTO schema_version (version, applied_at)
+      VALUES (?, ?)
+    `);
+        insertVersion.run(migration.version, Date.now());
+    }
+}
+export function initializeDatabase(db) {
+    runMigrations(db);
+}
+export function resetDatabase(db) {
+    clearDatabase(db);
+    initializeDatabase(db);
+}
+export { getSchemaVersion, clearDatabase, SCHEMA_VERSION };
+//# sourceMappingURL=migrations.js.map

package/apps/mcp-server/dist/db/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../../src/db/migrations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAQ7F,MAAM,UAAU,GAAgB;IAC9B;QACE,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,gBAAgB;QACtB,EAAE,EAAE,gBAAgB;KACrB;IACD;QACE,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,uBAAuB;QAC7B,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;YACT,MAAM,eAAe,GAAI,EAAE,CAAC,OAAO,CAAC,+BAA+B,CAAC,CAAC,GAAG,EAA8B,CAAC,IAAI,CACzG,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,CACrC,CAAC;YACF,IAAI,CAAC,eAAe,EAAE,CAAC;gBACrB,EAAE,CAAC,IAAI,CAAC;;SAEP,CAAC,CAAC;YACL,CAAC;YACD,EAAE,CAAC,IAAI,CAAC;;OAEP,CAAC,CAAC;YACH,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;OAUP,CAAC,CAAC;YACH,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;OAUP,CAAC,CAAC;QACL,CAAC;KACF;IACD;QACE,OAAO,EAAE,CAAC;QACV,IAAI,EAAE,mBAAmB;QACzB,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE;YACT,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;OAuBP,CAAC,CAAC;YACH,EAAE,CAAC,IAAI,CAAC;;;;OAIP,CAAC,CAAC;QACL,CAAC;KACF;CACF,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,EAAY;IACxC,MAAM,cAAc,GAAG,gBAAgB,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAEjD,MAAM,iBAAiB,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,cAAc,CAAC,CAAC;IAE7E,KAAK,MAAM,SAAS,IAAI,iBAAiB,EAAE,CAAC;QAC1C,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAEjB,MAAM,aAAa,GAAG,EAAE,CAAC,OAAO,CAAC;;;KAGhC,CAAC,CAAC;QACH,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,EAAY;IAC7C,aAAa,CAAC,EAAE,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAY;IACxC,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,kBAAkB,CAAC,EAAE,CAAC,CAAC;AACzB,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,CAAC"}

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

@@ -0,0 +1,157 @@
+export const SCHEMA_VERSION = 3;
+export const CREATE_TABLES_SQL = `
+-- Sessions table
+CREATE TABLE IF NOT EXISTS sessions (
+  session_id TEXT PRIMARY KEY,
+  created_at INTEGER NOT NULL,
+  ended_at INTEGER,
+  tab_id INTEGER,
+  window_id INTEGER,
+  url_start TEXT,
+  url_last TEXT,
+  user_agent TEXT,
+  viewport_w INTEGER,
+  viewport_h INTEGER,
+  dpr REAL,
+  safe_mode INTEGER NOT NULL DEFAULT 0,
+  allowlist_hash TEXT,
+  pinned INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_created_at ON sessions(created_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_ended_at ON sessions(ended_at);
+CREATE INDEX IF NOT EXISTS idx_sessions_pinned_created_at ON sessions(pinned, created_at);
+
+-- Server settings table
+CREATE TABLE IF NOT EXISTS server_settings (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  retention_days INTEGER NOT NULL DEFAULT 30,
+  max_db_mb INTEGER NOT NULL DEFAULT 1024,
+  max_sessions INTEGER NOT NULL DEFAULT 10000,
+  cleanup_interval_minutes INTEGER NOT NULL DEFAULT 60,
+  last_cleanup_at INTEGER,
+  export_path_override TEXT
+);
+
+INSERT OR IGNORE INTO server_settings (
+  id,
+  retention_days,
+  max_db_mb,
+  max_sessions,
+  cleanup_interval_minutes,
+  last_cleanup_at,
+  export_path_override
+) VALUES (1, 30, 1024, 10000, 60, NULL, NULL);
+
+-- Events table
+CREATE TABLE IF NOT EXISTS events (
+  event_id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  ts INTEGER NOT NULL,
+  type TEXT NOT NULL CHECK(type IN ('console', 'error', 'network', 'nav', 'ui', 'element_ref')),
+  payload_json TEXT NOT NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_session_id ON events(session_id);
+CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts);
+CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
+CREATE INDEX IF NOT EXISTS idx_events_session_type ON events(session_id, type);
+
+-- Network table
+CREATE TABLE IF NOT EXISTS network (
+  request_id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  ts_start INTEGER NOT NULL,
+  duration_ms INTEGER,
+  method TEXT NOT NULL,
+  url TEXT NOT NULL,
+  status INTEGER,
+  initiator TEXT CHECK(initiator IN ('fetch', 'xhr', 'img', 'script', 'other')),
+  error_class TEXT CHECK(error_class IN ('timeout', 'cors', 'dns', 'blocked', 'http_error', 'unknown')),
+  response_size_est INTEGER,
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_network_session_id ON network(session_id);
+CREATE INDEX IF NOT EXISTS idx_network_url ON network(url);
+CREATE INDEX IF NOT EXISTS idx_network_ts_start ON network(ts_start);
+CREATE INDEX IF NOT EXISTS idx_network_error_class ON network(error_class);
+CREATE INDEX IF NOT EXISTS idx_network_session_error ON network(session_id, error_class);
+
+-- Error fingerprints table
+CREATE TABLE IF NOT EXISTS error_fingerprints (
+  fingerprint TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  count INTEGER NOT NULL DEFAULT 1,
+  sample_message TEXT NOT NULL,
+  sample_stack TEXT,
+  first_seen_at INTEGER NOT NULL,
+  last_seen_at INTEGER NOT NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_error_fingerprints_session_id ON error_fingerprints(session_id);
+CREATE INDEX IF NOT EXISTS idx_error_fingerprints_count ON error_fingerprints(count);
+CREATE INDEX IF NOT EXISTS idx_error_fingerprints_last_seen ON error_fingerprints(last_seen_at);
+
+-- UI snapshots table
+CREATE TABLE IF NOT EXISTS snapshots (
+  snapshot_id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  trigger_event_id TEXT,
+  ts INTEGER NOT NULL,
+  trigger TEXT NOT NULL,
+  selector TEXT,
+  url TEXT,
+  mode TEXT NOT NULL,
+  style_mode TEXT,
+  dom_json TEXT,
+  styles_json TEXT,
+  png_path TEXT,
+  png_mime TEXT,
+  png_bytes INTEGER,
+  dom_truncated INTEGER NOT NULL DEFAULT 0,
+  styles_truncated INTEGER NOT NULL DEFAULT 0,
+  png_truncated INTEGER NOT NULL DEFAULT 0,
+  created_at INTEGER NOT NULL,
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE,
+  FOREIGN KEY (trigger_event_id) REFERENCES events(event_id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_snapshots_session_ts ON snapshots(session_id, ts);
+CREATE INDEX IF NOT EXISTS idx_snapshots_session_trigger_ts ON snapshots(session_id, trigger, ts);
+CREATE INDEX IF NOT EXISTS idx_snapshots_png_path ON snapshots(png_path);
+
+-- Schema version tracking
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY,
+  applied_at INTEGER NOT NULL
+);
+`;
+export function initializeSchema(db) {
+    db.exec(CREATE_TABLES_SQL);
+}
+export function getSchemaVersion(db) {
+    const tableExists = db.prepare(`
+    SELECT name FROM sqlite_master 
+    WHERE type='table' AND name='schema_version'
+  `).get();
+    if (!tableExists) {
+        return null;
+    }
+    const result = db.prepare('SELECT version FROM schema_version ORDER BY version DESC LIMIT 1').get();
+    return result?.version ?? null;
+}
+export function clearDatabase(db) {
+    db.exec(`
+    DELETE FROM error_fingerprints;
+    DELETE FROM network;
+    DELETE FROM snapshots;
+    DELETE FROM events;
+    DELETE FROM sessions;
+    DELETE FROM server_settings;
+    DELETE FROM schema_version;
+  `);
+}
+//# sourceMappingURL=schema.js.map

package/apps/mcp-server/dist/db/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/db/schema.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAEhC,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiIhC,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,EAAY;IAC3C,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,EAAY;IAC3C,MAAM,WAAW,GAAG,EAAE,CAAC,OAAO,CAAC;;;GAG9B,CAAC,CAAC,GAAG,EAAE,CAAC;IAET,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,EAAE,CAAC,OAAO,CAAC,kEAAkE,CAAC,CAAC,GAAG,EAAqC,CAAC;IACvI,OAAO,MAAM,EAAE,OAAO,IAAI,IAAI,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,EAAY;IACxC,EAAE,CAAC,IAAI,CAAC;;;;;;;;GAQP,CAAC,CAAC;AACL,CAAC"}