browsertrack 0.2.1 → 0.2.3

package/packages/daemon/src/storage/db.ts

@@ -18,6 +18,7 @@ import type {
   ScenarioOverview,
   ScenarioDetail,
 } from '../../../core/src/index.js';
+import { safeJsonParse, safeJsonStringify } from '../../../core/src/index.js';
 
 export class StorageDB {
   private db: Database.Database;
@@ -29,6 +30,7 @@ export class StorageDB {
     this.db = new Database(dbPath);
     this.db.pragma('journal_mode = WAL');
     this.db.pragma('synchronous = NORMAL');
+    this.db.pragma('busy_timeout = 5000');
     this.initTables();
   }
 
@@ -161,18 +163,38 @@ export class StorageDB {
       CREATE INDEX IF NOT EXISTS idx_incidents_project ON incidents(project_id, status);
       CREATE INDEX IF NOT EXISTS idx_incidents_fp ON incidents(fingerprint);
       CREATE INDEX IF NOT EXISTS idx_notes_project ON notes(project_id, status);
-      CREATE INDEX IF NOT EXISTS idx_notes_scenario ON notes(scenario_id, step_number);
     `);
 
-    // Schema migrations for scenario fields
+    // Schema migrations for scenario fields on existing databases
     try {
-      this.db.exec('ALTER TABLE notes ADD COLUMN scenario_id TEXT;');
-    } catch {}
-    try {
-      this.db.exec('ALTER TABLE notes ADD COLUMN step_number INTEGER;');
-    } catch {}
+      const columns = (this.db.prepare('PRAGMA table_info(notes)').all() as Array<{ name: string }>).map(
+        (c) => c.name
+      );
+      if (!columns.includes('scenario_id')) {
+        this.db.exec('ALTER TABLE notes ADD COLUMN scenario_id TEXT;');
+      }
+      if (!columns.includes('step_number')) {
+        this.db.exec('ALTER TABLE notes ADD COLUMN step_number INTEGER;');
+      }
+      if (!columns.includes('scenario_title')) {
+        this.db.exec('ALTER TABLE notes ADD COLUMN scenario_title TEXT;');
+      }
+    } catch {
+      // Fallback try-catch
+      try {
+        this.db.exec('ALTER TABLE notes ADD COLUMN scenario_id TEXT;');
+      } catch {}
+      try {
+        this.db.exec('ALTER TABLE notes ADD COLUMN step_number INTEGER;');
+      } catch {}
+      try {
+        this.db.exec('ALTER TABLE notes ADD COLUMN scenario_title TEXT;');
+      } catch {}
+    }
+
+    // Create scenario index after columns are guaranteed to exist
     try {
-      this.db.exec('ALTER TABLE notes ADD COLUMN scenario_title TEXT;');
+      this.db.exec('CREATE INDEX IF NOT EXISTS idx_notes_scenario ON notes(scenario_id, step_number);');
     } catch {}
   }
 
@@ -375,7 +397,7 @@ export class StorageDB {
       id: r.id,
       sessionId: r.session_id,
       eventType: r.event_type,
-      payload: JSON.parse(r.payload),
+      payload: safeJsonParse(r.payload, {}),
       timestamp: r.timestamp,
       route: r.route,
       url: r.url,
@@ -445,9 +467,9 @@ export class StorageDB {
         incident.occurrences,
         incident.status,
         incident.stack || null,
-        JSON.stringify(incident.breadcrumbs || []),
-        JSON.stringify(incident.networkFailures || []),
-        incident.lastElement ? JSON.stringify(incident.lastElement) : null,
+        safeJsonStringify(incident.breadcrumbs || []),
+        safeJsonStringify(incident.networkFailures || []),
+        incident.lastElement ? safeJsonStringify(incident.lastElement) : null,
         incident.screenshots?.error || null
       );
   }
@@ -475,8 +497,8 @@ export class StorageDB {
         update.lastSeen,
         update.occurrences,
         update.route,
-        JSON.stringify(update.breadcrumbs || []),
-        update.lastElement ? JSON.stringify(update.lastElement) : null,
+        safeJsonStringify(update.breadcrumbs || []),
+        update.lastElement ? safeJsonStringify(update.lastElement) : null,
         update.stack || null,
         incidentId
       );
@@ -500,8 +522,8 @@ export class StorageDB {
         occurrence.route,
         occurrence.url,
         occurrence.stack || null,
-        JSON.stringify(occurrence.breadcrumbs || []),
-        occurrence.lastElement ? JSON.stringify(occurrence.lastElement) : null
+        safeJsonStringify(occurrence.breadcrumbs || []),
+        occurrence.lastElement ? safeJsonStringify(occurrence.lastElement) : null
       );
   }
 
@@ -525,7 +547,7 @@ export class StorageDB {
         v.id,
         v.incidentId,
         v.status,
-        JSON.stringify(v.checks),
+        safeJsonStringify(v.checks),
         v.beforeScreenshot || null,
         v.afterScreenshot || null,
         v.message || null,
@@ -539,7 +561,7 @@ export class StorageDB {
     return {
       incidentId: row.incident_id,
       status: row.status as IncidentStatus,
-      checks: JSON.parse(row.checks || '[]'),
+      checks: safeJsonParse(row.checks, []),
       screenshots: {
         before: row.before_screenshot || undefined,
         after: row.after_screenshot || undefined,
@@ -567,11 +589,11 @@ export class StorageDB {
         note.message,
         note.route,
         note.url,
-        JSON.stringify(note.viewport),
-        JSON.stringify(note.scroll),
-        note.target ? JSON.stringify(note.target) : null,
-        note.elementContext ? JSON.stringify(note.elementContext) : null,
-        note.region ? JSON.stringify(note.region) : null,
+        safeJsonStringify(note.viewport),
+        safeJsonStringify(note.scroll),
+        note.target ? safeJsonStringify(note.target) : null,
+        note.elementContext ? safeJsonStringify(note.elementContext) : null,
+        note.region ? safeJsonStringify(note.region) : null,
         note.screenshots?.original || null,
         note.incidentId || null,
         note.scenarioId || null,
@@ -739,8 +761,8 @@ export class StorageDB {
         `nver_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
         v.noteId,
         v.status,
-        JSON.stringify(v.checks),
-        v.geometryDiff ? JSON.stringify(v.geometryDiff) : null,
+        safeJsonStringify(v.checks),
+        v.geometryDiff ? safeJsonStringify(v.geometryDiff) : null,
         v.screenshots?.before || null,
         v.screenshots?.after || null,
         v.message || null,
@@ -754,8 +776,8 @@ export class StorageDB {
     return {
       noteId: row.note_id,
       status: row.status as NoteStatus,
-      checks: JSON.parse(row.checks || '[]'),
-      geometryDiff: row.geometry_diff ? JSON.parse(row.geometry_diff) : undefined,
+      checks: safeJsonParse(row.checks, []),
+      geometryDiff: safeJsonParse(row.geometry_diff, undefined),
       screenshots: {
         before: row.before_screenshot || undefined,
         after: row.after_screenshot || undefined,
@@ -798,9 +820,9 @@ export class StorageDB {
       occurrences: row.occurrences,
       status: row.status as IncidentStatus,
       stack: row.stack || undefined,
-      breadcrumbs: JSON.parse(row.breadcrumbs || '[]'),
-      networkFailures: JSON.parse(row.network_failures || '[]'),
-      lastElement: row.last_element ? JSON.parse(row.last_element) : undefined,
+      breadcrumbs: safeJsonParse(row.breadcrumbs, []),
+      networkFailures: safeJsonParse(row.network_failures, []),
+      lastElement: safeJsonParse(row.last_element, undefined),
       screenshots: row.screenshot_path
         ? {
             error: row.screenshot_path,
@@ -818,11 +840,11 @@ export class StorageDB {
       message: row.message,
       route: row.route,
       url: row.url,
-      viewport: JSON.parse(row.viewport_json || '{}'),
-      scroll: JSON.parse(row.scroll_json || '{}'),
-      target: row.target_json ? JSON.parse(row.target_json) : undefined,
-      elementContext: row.element_context_json ? JSON.parse(row.element_context_json) : undefined,
-      region: row.region_json ? JSON.parse(row.region_json) : undefined,
+      viewport: safeJsonParse(row.viewport_json, { width: 0, height: 0, devicePixelRatio: 1 }),
+      scroll: safeJsonParse(row.scroll_json, { scrollX: 0, scrollY: 0 }),
+      target: safeJsonParse(row.target_json, undefined),
+      elementContext: safeJsonParse(row.element_context_json, undefined),
+      region: safeJsonParse(row.region_json, undefined),
       status: row.status as NoteStatus,
       incidentId: row.incident_id || undefined,
       scenarioId: row.scenario_id || undefined,

package/packages/mcp/src/handlers.ts

@@ -9,6 +9,120 @@ export interface McpContext {
   verificationEngine?: VerificationEngine;
   noteVerificationEngine?: NoteVerificationEngine;
   daemonUrl?: string;
+  daemonInitPromise?: Promise<void>;
+}
+
+async function sendSessionCommand(ctx: McpContext, sessionId: string | undefined, command: any, timeoutMs = 5000): Promise<any> {
+  if (ctx.daemonInitPromise) {
+    try {
+      await Promise.race([ctx.daemonInitPromise, new Promise((r) => setTimeout(r, 2000))]);
+    } catch {}
+  }
+
+  // 1. In-process session manager (if active sockets exist)
+  if (ctx.sessionManager && ctx.sessionManager.getActiveCount() > 0) {
+    const targetSession = sessionId ? ctx.db.getSession(sessionId) : ctx.sessionManager.getAnyActiveSession();
+    if (targetSession) {
+      const res = await ctx.sessionManager.sendCommand(targetSession.id, command, timeoutMs);
+      if (!res.ok) {
+        throw new Error(res.error || res.reason || `Command ${command.type} failed`);
+      }
+      return res;
+    }
+  }
+
+  // 2. Multi-process proxy to running daemon HTTP server
+  if (ctx.daemonUrl) {
+    try {
+      const resp = await fetch(`${ctx.daemonUrl}/api/command`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ sessionId, command, timeoutMs }),
+        signal: AbortSignal.timeout(timeoutMs + 2000),
+      });
+      if (resp.ok) {
+        const res = await resp.json();
+        if (!res.ok) {
+          throw new Error(res.error || res.reason || `Command ${command.type} failed`);
+        }
+        return res;
+      }
+      const errJson = await resp.json().catch(() => ({}));
+      if (errJson.error) {
+        throw new Error(errJson.error);
+      }
+    } catch (err: any) {
+      if (err.message && !err.message.includes('fetch failed') && !err.message.includes('ECONNREFUSED')) {
+        throw err;
+      }
+    }
+  }
+
+  throw new Error(
+    'No active browser session connected. Please ensure the BrowserTrack daemon is running ("browsertrack start") and your application tab is open in the browser.'
+  );
+}
+
+async function runVerifyIncident(ctx: McpContext, incidentId: string, options: any): Promise<any> {
+  if (ctx.verificationEngine && ctx.sessionManager && ctx.sessionManager.getActiveCount() > 0) {
+    return await ctx.verificationEngine.verifyIncident(incidentId, options);
+  }
+
+  if (ctx.daemonUrl) {
+    try {
+      const timeoutMs = (options?.observationWindowMs || 3000) + 7000;
+      const resp = await fetch(`${ctx.daemonUrl}/api/verify/incident`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ incidentId, options }),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (resp.ok) {
+        const data = await resp.json();
+        if (data.ok) return data.result;
+        throw new Error(data.error);
+      }
+    } catch (err: any) {
+      if (err.message && !err.message.includes('fetch failed') && !err.message.includes('ECONNREFUSED')) {
+        throw err;
+      }
+    }
+  }
+
+  throw new Error(
+    'Verification failed: No active browser session connected. Please ensure the BrowserTrack daemon is running ("browsertrack start") and your application tab is open in the browser.'
+  );
+}
+
+async function runVerifyNote(ctx: McpContext, noteId: string, options: any): Promise<any> {
+  if (ctx.noteVerificationEngine && ctx.sessionManager && ctx.sessionManager.getActiveCount() > 0) {
+    return await ctx.noteVerificationEngine.verifyNote(noteId, options);
+  }
+
+  if (ctx.daemonUrl) {
+    try {
+      const timeoutMs = (options?.observationWindowMs || 3000) + 7000;
+      const resp = await fetch(`${ctx.daemonUrl}/api/verify/note`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ noteId, options }),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      if (resp.ok) {
+        const data = await resp.json();
+        if (data.ok) return data.result;
+        throw new Error(data.error);
+      }
+    } catch (err: any) {
+      if (err.message && !err.message.includes('fetch failed') && !err.message.includes('ECONNREFUSED')) {
+        throw err;
+      }
+    }
+  }
+
+  throw new Error(
+    'Verification failed: No active browser session connected. Please ensure the BrowserTrack daemon is running ("browsertrack start") and your application tab is open in the browser.'
+  );
 }
 
 export async function handleToolCall(name: string, args: any, ctx: McpContext): Promise<any> {
@@ -181,43 +295,20 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
     }
 
     case 'get_page_state': {
-      if (!sessionManager) {
-        throw new Error('Live browser connection not available: Daemon session manager not attached.');
-      }
-      let session = args.sessionId ? db.getSession(args.sessionId) : sessionManager.getAnyActiveSession();
-      if (!session) {
-        throw new Error('No active browser session connected.');
-      }
-
-      const cmdRes = await sessionManager.sendCommand(session.id, {
+      const cmdRes = await sendSessionCommand(ctx, args.sessionId, {
         id: `cmd_mcp_${Date.now()}`,
         type: 'get_page_state',
       });
-
-      if (!cmdRes.ok) {
-        throw new Error(cmdRes.error || 'Failed to retrieve page state from browser.');
-      }
       return cmdRes.result;
     }
 
     case 'capture_element': {
-      if (!sessionManager) {
-        throw new Error('Live browser connection not available: Daemon session manager not attached.');
-      }
-      let session = args.sessionId ? db.getSession(args.sessionId) : sessionManager.getAnyActiveSession();
-      if (!session) {
-        throw new Error('No active browser session connected.');
-      }
-
-      const cmdRes = await sessionManager.sendCommand(session.id, {
+      const cmdRes = await sendSessionCommand(ctx, args.sessionId, {
         id: `cmd_mcp_${Date.now()}`,
         type: 'capture_element',
         params: { selector: args.selector },
       });
 
-      if (!cmdRes.ok) {
-        throw new Error(cmdRes.error || cmdRes.reason || 'Failed to capture element screenshot.');
-      }
       return {
         ok: true,
         format: cmdRes.result?.format || 'webp',
@@ -228,11 +319,7 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
     }
 
     case 'verify_incident': {
-      if (!verificationEngine) {
-        throw new Error('Verification engine not available: Daemon session manager not attached.');
-      }
-
-      const res = await verificationEngine.verifyIncident(args.incidentId, {
+      const res = await runVerifyIncident(ctx, args.incidentId, {
         route: args.route,
         targetSelector: args.targetSelector,
         expect: args.expect,
@@ -399,10 +486,7 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
     }
 
     case 'verify_note': {
-      if (!noteVerificationEngine) {
-        throw new Error('Note verification engine not available: Daemon session manager not attached.');
-      }
-      const res = await noteVerificationEngine.verifyNote(args.noteId, {
+      const res = await runVerifyNote(ctx, args.noteId, {
         observationWindowMs: args.observationWindowMs,
       });
       return res;
@@ -417,27 +501,19 @@ export async function handleToolCall(name: string, args: any, ctx: McpContext):
     }
 
     case 'capture_note_context': {
-      if (!sessionManager) {
-        throw new Error('Live browser connection not available: Daemon session manager not attached.');
-      }
-      let session = args.sessionId ? db.getSession(args.sessionId) : sessionManager.getAnyActiveSession();
-      if (!session) {
-        throw new Error('No active browser session connected.');
-      }
-
-      const queryCmd = await sessionManager.sendCommand(session.id, {
+      const queryCmd = await sendSessionCommand(ctx, args.sessionId, {
         id: `cmd_ctx_${Date.now()}`,
         type: 'query_element',
         params: { selector: args.selector },
       });
 
-      const overflowCmd = await sessionManager.sendCommand(session.id, {
+      const overflowCmd = await sendSessionCommand(ctx, args.sessionId, {
         id: `cmd_ovf_${Date.now()}`,
         type: 'check_overflow',
         params: { selector: args.selector },
       });
 
-      const styleCmd = await sessionManager.sendCommand(session.id, {
+      const styleCmd = await sendSessionCommand(ctx, args.sessionId, {
         id: `cmd_sty_${Date.now()}`,
         type: 'get_element_style',
         params: { selector: args.selector },

package/packages/mcp/src/server.ts

@@ -1,3 +1,7 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
@@ -7,18 +11,98 @@ import { ScreenshotStore } from '../../daemon/src/storage/screenshot-store.js';
 import { SessionManager } from '../../daemon/src/session/manager.js';
 import { NotesEngine } from '../../daemon/src/notes/engine.js';
 import { NoteVerificationEngine } from '../../daemon/src/notes/verification.js';
-import { VerificationEngine } from '../../daemon/src/verification/engine.js';
+import { VerificationEngine, createDaemon } from '../../daemon/src/index.js';
 import type { McpContext } from './handlers.js';
 import { handleToolCall } from './handlers.js';
 import { TOOLS } from './tools.js';
 
+export async function isDaemonRunning(host: string, port: number): Promise<boolean> {
+  try {
+    const res = await fetch(`http://${host}:${port}/health`, {
+      signal: AbortSignal.timeout(600),
+    });
+    if (res.ok) {
+      const data = (await res.json().catch(() => ({}))) as any;
+      return data?.name === 'browsertrack';
+    }
+  } catch {}
+  return false;
+}
+
+function resolveCliPath(): string | null {
+  if (process.argv[1]) {
+    const candidate = process.argv[1];
+    if (
+      candidate.endsWith('cli/index.js') ||
+      candidate.endsWith('browsertrack') ||
+      candidate.endsWith('bin/browsertrack.js') ||
+      candidate.endsWith('dist/cli/index.js')
+    ) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
+  try {
+    const currentDir = path.dirname(fileURLToPath(import.meta.url));
+    const paths = [
+      path.resolve(currentDir, '../cli/index.js'),
+      path.resolve(currentDir, '../../cli/index.js'),
+      path.resolve(currentDir, '../../dist/cli/index.js'),
+    ];
+    for (const p of paths) {
+      if (fs.existsSync(p)) return p;
+    }
+  } catch {}
+
+  return null;
+}
+
+function acquireBootLock(lockFile: string): boolean {
+  try {
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    const fd = fs.openSync(lockFile, 'wx');
+    fs.writeSync(fd, String(process.pid));
+    fs.closeSync(fd);
+    return true;
+  } catch {
+    try {
+      const stats = fs.statSync(lockFile);
+      // If older than 5 seconds, assume stale lock and break it
+      if (Date.now() - stats.mtimeMs > 5000) {
+        fs.unlinkSync(lockFile);
+        const fd = fs.openSync(lockFile, 'wx');
+        fs.writeSync(fd, String(process.pid));
+        fs.closeSync(fd);
+        return true;
+      }
+    } catch {}
+    return false;
+  }
+}
+
+function releaseBootLock(lockFile: string): void {
+  try {
+    if (fs.existsSync(lockFile)) {
+      fs.unlinkSync(lockFile);
+    }
+  } catch {}
+}
+
 export interface McpServerOptions {
   dbPath?: string;
   context?: Partial<McpContext>;
+  autoStartDaemon?: boolean;
+  port?: number;
+  host?: string;
+  detached?: boolean;
 }
 
 export function createMcpServer(options: McpServerOptions = {}) {
-  const config = getDaemonConfig({ dbPath: options.dbPath });
+  const config = getDaemonConfig({
+    dbPath: options.dbPath,
+    port: options.port,
+    host: options.host,
+  });
   const db = options.context?.db || new StorageDB(config.dbPath);
   const screenshotStore = new ScreenshotStore(config.screenshotsDir);
   const sessionManager = options.context?.sessionManager || new SessionManager(db);
@@ -35,6 +119,121 @@ export function createMcpServer(options: McpServerOptions = {}) {
     ...options.context,
   };
 
+  let embeddedDaemon: any = null;
+
+  async function ensureDaemon(): Promise<void> {
+    if (options.autoStartDaemon === false || options.context?.sessionManager) {
+      return;
+    }
+
+    // 1. Fast path: check if a singleton daemon is already running
+    if (await isDaemonRunning(config.host, config.port)) {
+      console.error(`[BrowserTrack MCP] Connected to active singleton daemon at http://${config.host}:${config.port}`);
+      return;
+    }
+
+    // 2. Concurrency lock to guarantee only ONE daemon is ever started across multiple IDE sessions
+    const lockFile = path.join(config.dataDir, 'daemon_boot.lock');
+    const hasLock = acquireBootLock(lockFile);
+
+    if (!hasLock) {
+      // Another session is currently booting the daemon, wait for it
+      for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 100));
+        if (await isDaemonRunning(config.host, config.port)) {
+          console.error(`[BrowserTrack MCP] Connected to shared singleton daemon at http://${config.host}:${config.port}`);
+          return;
+        }
+      }
+    }
+
+    try {
+      // 3. Double-check before starting
+      if (await isDaemonRunning(config.host, config.port)) {
+        console.error(`[BrowserTrack MCP] Connected to shared singleton daemon at http://${config.host}:${config.port}`);
+        return;
+      }
+
+      // 4. Detached background process (singleton daemon that survives across IDE windows/sessions)
+      if (options.detached !== false) {
+        const cliPath = resolveCliPath();
+        if (cliPath && fs.existsSync(cliPath)) {
+          try {
+            const nodePaths = [
+              '/usr/local/bin',
+              '/opt/homebrew/bin',
+              process.env.HOME ? `${process.env.HOME}/.nvm/versions/node/v20.19.5/bin` : '',
+              process.env.HOME ? `${process.env.HOME}/.nvm/versions/node/v23.1.0/bin` : '',
+            ].filter(Boolean);
+            const extendedPath = `${process.env.PATH || ''}:${nodePaths.join(':')}`;
+
+            const child = spawn(
+              process.execPath,
+              [cliPath, 'start', '--port', String(config.port), '--host', config.host],
+              {
+                detached: true,
+                stdio: 'ignore',
+                env: { ...process.env, PATH: extendedPath, BROWSERTRACK_DAEMON_DETACHED: '1' },
+              }
+            );
+            child.unref();
+
+            for (let i = 0; i < 30; i++) {
+              await new Promise((r) => setTimeout(r, 100));
+              if (await isDaemonRunning(config.host, config.port)) {
+                console.error(
+                  `[BrowserTrack MCP] Started singleton background daemon on http://${config.host}:${config.port}`
+                );
+                return;
+              }
+            }
+          } catch (spawnErr: any) {
+            console.error(
+              `[BrowserTrack MCP] Detached daemon spawn failed (${spawnErr?.message}), falling back to in-process daemon.`
+            );
+          }
+        }
+      }
+
+      // 5. In-process fallback (used when detached is false or in test runners)
+      embeddedDaemon = createDaemon({
+        host: config.host,
+        port: config.port,
+        dbPath: config.dbPath,
+        screenshotsDir: config.screenshotsDir,
+        verbose: false,
+      });
+      await embeddedDaemon.start();
+      console.error(`[BrowserTrack MCP] Started singleton daemon on http://${config.host}:${config.port}`);
+
+      ctx.db = embeddedDaemon.db;
+      ctx.sessionManager = embeddedDaemon.sessionManager;
+      ctx.verificationEngine = embeddedDaemon.verificationEngine;
+      ctx.noteVerificationEngine = embeddedDaemon.noteVerificationEngine;
+
+      const cleanup = () => {
+        if (embeddedDaemon) {
+          try {
+            embeddedDaemon.stop();
+          } catch {}
+          embeddedDaemon = null;
+        }
+      };
+
+      process.on('exit', cleanup);
+      process.on('SIGINT', cleanup);
+      process.on('SIGTERM', cleanup);
+    } catch (err: any) {
+      console.error(
+        `[BrowserTrack MCP] Note: Daemon startup skipped (${err?.message}). Running MCP in standalone database mode.`
+      );
+    } finally {
+      if (hasLock) {
+        releaseBootLock(lockFile);
+      }
+    }
+  }
+
   const server = new Server(
     {
       name: 'browsertrack-mcp',
@@ -54,7 +253,11 @@ export function createMcpServer(options: McpServerOptions = {}) {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     try {
-      const result = await handleToolCall(name, args || {}, ctx);
+      // 20-second safety timeout so tool execution never hangs indefinitely
+      const timeoutPromise = new Promise((_, reject) =>
+        setTimeout(() => reject(new Error(`Tool execution timed out after 20s: ${name}`)), 20000)
+      );
+      const result = await Promise.race([handleToolCall(name, args || {}, ctx), timeoutPromise]);
       return {
         content: [
           {
@@ -78,9 +281,24 @@ export function createMcpServer(options: McpServerOptions = {}) {
 
   return {
     server,
+    ctx,
+    ensureDaemon,
+    async stopDaemon() {
+      if (embeddedDaemon) {
+        await embeddedDaemon.stop();
+        embeddedDaemon = null;
+      }
+    },
     async startStdio() {
+      // Connect stdio transport immediately so client handshakes are answered instantly
       const transport = new StdioServerTransport();
       await server.connect(transport);
+
+      // Start daemon verification / auto-boot asynchronously in background so client handshakes never block
+      const daemonInitPromise = ensureDaemon().catch((err) => {
+        console.error(`[BrowserTrack MCP] Daemon background init note: ${err?.message || err}`);
+      });
+      ctx.daemonInitPromise = daemonInitPromise;
     },
   };
 }