@yusufffararatt/dombridge-mcp 2.7.5

package/src/mcp-bridge.js

@@ -0,0 +1,136 @@
+/**
+ * MCP Bridge Module
+ * Extension'dan MCP server'a veri gönderen helper fonksiyonları
+ * Bu dosyayı extension'da import etmek için kullanın
+ */
+
+const MCP_SERVER_URL = 'http://localhost:3101';
+
+export const MCPBridge = {
+  /**
+   * Seçili elementi MCP server'a gönder
+   */
+  async sendSelectedElement(elementData) {
+    try {
+      const response = await fetch(`${MCP_SERVER_URL}/api/element-selected`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(elementData)
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      return await response.json();
+    } catch (error) {
+      console.warn('[MCP Bridge] ❌ Could not reach MCP server:', error.message);
+      return { success: false, error: error.message };
+    }
+  },
+
+  /**
+   * Network trace'i MCP server'a gönder
+   */
+  async sendNetworkTrace(traceData) {
+    try {
+      const response = await fetch(`${MCP_SERVER_URL}/api/network-trace`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(traceData)
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      return await response.json();
+    } catch (error) {
+      console.warn('[MCP Bridge] ❌ Could not reach MCP server:', error.message);
+      return { success: false, error: error.message };
+    }
+  },
+
+  /**
+   * Kaydedilmiş seçimleri MCP server'a gönder
+   */
+  async sendSavedSelections(savedSelections) {
+    try {
+      const response = await fetch(`${MCP_SERVER_URL}/api/saved-selections`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({ savedSelections })
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      return await response.json();
+    } catch (error) {
+      console.warn('[MCP Bridge] ❌ Could not reach MCP server:', error.message);
+      return { success: false, error: error.message };
+    }
+  },
+
+  /**
+   * Tüm state'i bir seferde sync et
+   */
+  async syncAll(data) {
+    try {
+      const response = await fetch(`${MCP_SERVER_URL}/api/sync-all`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(data)
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      return await response.json();
+    } catch (error) {
+      console.warn('[MCP Bridge] ❌ Could not reach MCP server:', error.message);
+      return { success: false, error: error.message };
+    }
+  },
+
+  /**
+   * MCP server'ın çalışıp çalışmadığını kontrol et
+   */
+  async ping() {
+    try {
+      const response = await fetch(`${MCP_SERVER_URL}/api/ping`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        }
+      });
+
+      return response.ok;
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Health check
+   */
+  async checkHealth() {
+    try {
+      const response = await fetch(`${MCP_SERVER_URL}/health`);
+      if (!response.ok) return null;
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+};

package/src/metrics/error-codes.js

@@ -0,0 +1,44 @@
+/**
+ * Error Code Catalog
+ * Standardized error codes for tool_calls.error_code field
+ */
+export const ErrorCodes = {
+  E_TIMEOUT: 'E_TIMEOUT',
+  E_CSP_BLOCKED: 'E_CSP_BLOCKED',
+  E_NOT_FOUND: 'E_NOT_FOUND',
+  E_NOT_VISIBLE: 'E_NOT_VISIBLE',
+  E_SELECTOR_INVALID: 'E_SELECTOR_INVALID',
+  E_VALIDATION: 'E_VALIDATION',
+  E_RATE_LIMITED: 'E_RATE_LIMITED',
+  E_CIRCUIT_OPEN: 'E_CIRCUIT_OPEN',
+  E_STALE_CONNECTION: 'E_STALE_CONNECTION',
+  E_BRIDGE_DOWN: 'E_BRIDGE_DOWN',
+  E_DATA_DROPPED: 'E_DATA_DROPPED',
+  E_SECURITY: 'E_SECURITY',
+  E_UNKNOWN: 'E_UNKNOWN',
+};
+
+export const ResultTypes = {
+  SUCCESS: 'success',
+  ERROR: 'error',
+  TIMEOUT: 'timeout',
+  CIRCUIT_OPEN: 'circuit_open',
+  NULL_RESULT: 'null_result',
+  STALE_CONNECTION: 'stale_connection',
+  DATA_DROPPED: 'data_dropped',
+};
+
+export const ConnectionEventTypes = {
+  DISCONNECTED: 'disconnected',
+  RECONNECTING: 'reconnecting',
+  RECONNECTED: 'reconnected',
+  HEARTBEAT_TIMEOUT: 'heartbeat_timeout',
+  STALE_DETECTED: 'stale_detected',
+  CIRCUIT_BREAKER_OPEN: 'circuit_breaker_open',
+  CIRCUIT_BREAKER_CLOSE: 'circuit_breaker_close',
+  FULL_SYNC_FAILED: 'full_sync_failed',
+  POLLING_STALL: 'polling_stall',
+  BRIDGE_SPAWN: 'bridge_spawn',
+  BRIDGE_CRASH: 'bridge_crash',
+  DATA_DROPPED: 'data_dropped',
+};

package/src/metrics/index.js

@@ -0,0 +1,3 @@
+export { MetricsDB } from './metrics-db.js';
+export { withMetrics, setMetricsDB } from './metrics-recorder.js';
+export { ErrorCodes, ResultTypes, ConnectionEventTypes } from './error-codes.js';

package/src/metrics/metrics-db.js

@@ -0,0 +1,269 @@
+/**
+ * MetricsDB — SQLite interface for tool analytics
+ *
+ * Stores every MCP tool call result and connection event.
+ * Uses WAL mode for concurrent reads/writes.
+ * Graceful degradation: if SQLite init fails, metrics are silently skipped.
+ */
+import Database from 'better-sqlite3';
+import { mkdirSync, existsSync } from 'fs';
+import { dirname } from 'path';
+import { homedir } from 'os';
+import { join } from 'path';
+import { logger } from '../utils/logger.js';
+
+const DEFAULT_DB_PATH = join(homedir(), '.dombridge', 'metrics.db');
+
+const CREATE_TOOL_CALLS = `
+CREATE TABLE IF NOT EXISTS tool_calls (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL,
+  domain TEXT,
+  tool TEXT NOT NULL,
+  action TEXT,
+  success INTEGER NOT NULL,
+  result_type TEXT NOT NULL,
+  error_code TEXT,
+  error_message TEXT,
+  duration_ms INTEGER,
+  selector TEXT,
+  retry_count INTEGER DEFAULT 0,
+  circuit_breaker_state TEXT,
+  tab_id INTEGER,
+  metadata TEXT,
+  extension_version TEXT,
+  bridge_connected INTEGER DEFAULT 1
+)`;
+
+const CREATE_CONNECTION_EVENTS = `
+CREATE TABLE IF NOT EXISTS connection_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  duration_ms INTEGER,
+  retry_count INTEGER,
+  failure_reason TEXT,
+  metadata TEXT
+)`;
+
+const CREATE_TOOL_SNAPSHOTS = `
+CREATE TABLE IF NOT EXISTS tool_snapshots (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  date TEXT NOT NULL,
+  tool TEXT NOT NULL,
+  domain TEXT,
+  total_calls INTEGER,
+  success_count INTEGER,
+  fail_count INTEGER,
+  null_count INTEGER,
+  timeout_count INTEGER,
+  circuit_open_count INTEGER,
+  data_dropped_count INTEGER,
+  avg_duration_ms INTEGER,
+  max_duration_ms INTEGER,
+  p95_duration_ms INTEGER,
+  error_breakdown TEXT,
+  result_type_breakdown TEXT,
+  UNIQUE(date, tool, domain)
+)`;
+
+const CREATE_INDEXES = [
+  'CREATE INDEX IF NOT EXISTS idx_tc_tool ON tool_calls(tool)',
+  'CREATE INDEX IF NOT EXISTS idx_tc_domain ON tool_calls(domain)',
+  'CREATE INDEX IF NOT EXISTS idx_tc_timestamp ON tool_calls(timestamp)',
+  'CREATE INDEX IF NOT EXISTS idx_tc_result_type ON tool_calls(result_type)',
+  'CREATE INDEX IF NOT EXISTS idx_tc_tool_success ON tool_calls(tool, success)',
+  'CREATE INDEX IF NOT EXISTS idx_ce_event_type ON connection_events(event_type)',
+  'CREATE INDEX IF NOT EXISTS idx_ce_timestamp ON connection_events(timestamp)',
+  'CREATE INDEX IF NOT EXISTS idx_ts_date ON tool_snapshots(date)',
+  'CREATE INDEX IF NOT EXISTS idx_ts_tool ON tool_snapshots(tool)',
+];
+
+export class MetricsDB {
+  constructor(dbPath = DEFAULT_DB_PATH) {
+    this.available = false;
+    this.db = null;
+    this._stmts = null;
+
+    try {
+      const dir = dirname(dbPath);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      this.db = new Database(dbPath);
+      this.db.pragma('journal_mode = WAL');
+      this.db.pragma('synchronous = NORMAL');
+      this._initTables();
+      this._prepareStatements();
+      this.available = true;
+      logger.info('Metrics', `SQLite initialized at ${dbPath}`);
+    } catch (err) {
+      logger.warn('Metrics', `SQLite init failed, metrics will be skipped: ${err.message}`);
+    }
+  }
+
+  _initTables() {
+    this.db.exec(CREATE_TOOL_CALLS);
+    this.db.exec(CREATE_CONNECTION_EVENTS);
+    this.db.exec(CREATE_TOOL_SNAPSHOTS);
+    for (const sql of CREATE_INDEXES) {
+      this.db.exec(sql);
+    }
+  }
+
+  _prepareStatements() {
+    this._stmts = {
+      insertToolCall: this.db.prepare(`
+        INSERT INTO tool_calls (timestamp, domain, tool, action, success, result_type,
+          error_code, error_message, duration_ms, selector, retry_count,
+          circuit_breaker_state, tab_id, metadata, extension_version, bridge_connected)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `),
+      insertConnectionEvent: this.db.prepare(`
+        INSERT INTO connection_events (timestamp, event_type, duration_ms, retry_count, failure_reason, metadata)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `),
+    };
+  }
+
+  recordToolCall(data) {
+    if (!this.available) return;
+    try {
+      this._stmts.insertToolCall.run(
+        data.timestamp || new Date().toISOString(),
+        data.domain || null,
+        data.tool,
+        data.action || null,
+        data.success ? 1 : 0,
+        data.result_type || 'error',
+        data.error_code || null,
+        (data.error_message || '').slice(0, 200),
+        data.duration_ms || null,
+        data.selector || null,
+        data.retry_count || 0,
+        data.circuit_breaker_state || null,
+        data.tab_id || null,
+        data.metadata || null,
+        data.extension_version || null,
+        data.bridge_connected !== undefined ? (data.bridge_connected ? 1 : 0) : 1,
+      );
+    } catch (err) {
+      logger.warn('Metrics', `Failed to record tool call: ${err.message}`);
+    }
+  }
+
+  recordConnectionEvent(data) {
+    if (!this.available) return;
+    try {
+      this._stmts.insertConnectionEvent.run(
+        data.timestamp || new Date().toISOString(),
+        data.event_type,
+        data.duration_ms || null,
+        data.retry_count || null,
+        data.failure_reason || null,
+        data.metadata || null,
+      );
+    } catch (err) {
+      logger.warn('Metrics', `Failed to record connection event: ${err.message}`);
+    }
+  }
+
+  generateSnapshot(date) {
+    if (!this.available) return;
+    try {
+      const nextDay = new Date(date);
+      nextDay.setDate(nextDay.getDate() + 1);
+      const nextDayStr = nextDay.toISOString().slice(0, 10);
+
+      const rows = this.db.prepare(`
+        SELECT tool, domain, success, result_type, duration_ms, error_code
+        FROM tool_calls
+        WHERE timestamp >= ? AND timestamp < ?
+      `).all(date, nextDayStr);
+
+      const groups = {};
+      for (const row of rows) {
+        const key = `${row.tool}::${row.domain || '(none)'}`;
+        if (!groups[key]) {
+          groups[key] = {
+            tool: row.tool, domain: row.domain, total: 0, success: 0, fail: 0,
+            null_result: 0, timeout: 0, circuit_open: 0, data_dropped: 0,
+            durations: [], errors: {}, resultTypes: {},
+          };
+        }
+        const g = groups[key];
+        g.total++;
+        if (row.success) g.success++;
+        else g.fail++;
+        g.resultTypes[row.result_type] = (g.resultTypes[row.result_type] || 0) + 1;
+        if (row.result_type === 'null_result') g.null_result++;
+        if (row.result_type === 'timeout') g.timeout++;
+        if (row.result_type === 'circuit_open') g.circuit_open++;
+        if (row.result_type === 'data_dropped') g.data_dropped++;
+        if (row.duration_ms != null) g.durations.push(row.duration_ms);
+        if (row.error_code) g.errors[row.error_code] = (g.errors[row.error_code] || 0) + 1;
+      }
+
+      const upsert = this.db.prepare(`
+        INSERT INTO tool_snapshots (date, tool, domain, total_calls, success_count, fail_count,
+          null_count, timeout_count, circuit_open_count, data_dropped_count,
+          avg_duration_ms, max_duration_ms, p95_duration_ms, error_breakdown, result_type_breakdown)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(date, tool, domain) DO UPDATE SET
+          total_calls=excluded.total_calls, success_count=excluded.success_count,
+          fail_count=excluded.fail_count, null_count=excluded.null_count,
+          timeout_count=excluded.timeout_count, circuit_open_count=excluded.circuit_open_count,
+          data_dropped_count=excluded.data_dropped_count,
+          avg_duration_ms=excluded.avg_duration_ms, max_duration_ms=excluded.max_duration_ms,
+          p95_duration_ms=excluded.p95_duration_ms, error_breakdown=excluded.error_breakdown,
+          result_type_breakdown=excluded.result_type_breakdown
+      `);
+
+      for (const g of Object.values(groups)) {
+        const durations = g.durations.sort((a, b) => a - b);
+        const p95 = durations.length > 0 ? durations[Math.floor(durations.length * 0.95)] : null;
+        const avg = durations.length > 0 ? Math.round(durations.reduce((a, b) => a + b, 0) / durations.length) : null;
+        const max = durations.length > 0 ? durations[durations.length - 1] : null;
+
+        upsert.run(date, g.tool, g.domain, g.total, g.success, g.fail,
+          g.null_result, g.timeout, g.circuit_open, g.data_dropped,
+          avg, max, p95,
+          JSON.stringify(g.errors), JSON.stringify(g.resultTypes));
+      }
+    } catch (err) {
+      logger.warn('Metrics', `Failed to generate snapshot: ${err.message}`);
+    }
+  }
+
+  query(filters = {}) {
+    if (!this.available) return [];
+    try {
+      const conditions = [];
+      const params = [];
+      if (filters.tool) { conditions.push('tool = ?'); params.push(filters.tool); }
+      if (filters.domain) { conditions.push('domain = ?'); params.push(filters.domain); }
+      if (filters.success !== undefined) { conditions.push('success = ?'); params.push(filters.success ? 1 : 0); }
+      if (filters.result_type) { conditions.push('result_type = ?'); params.push(filters.result_type); }
+      if (filters.days) {
+        const since = new Date(Date.now() - filters.days * 86400000).toISOString();
+        conditions.push('timestamp >= ?'); params.push(since);
+      }
+      if (filters.today) {
+        const today = new Date().toISOString().slice(0, 10);
+        conditions.push('timestamp >= ?'); params.push(today);
+      }
+
+      const where = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+      return this.db.prepare(`SELECT * FROM tool_calls ${where} ORDER BY timestamp DESC LIMIT 1000`).all(...params);
+    } catch (err) {
+      logger.warn('Metrics', `Query failed: ${err.message}`);
+      return [];
+    }
+  }
+
+  close() {
+    if (this.db) {
+      try { this.db.close(); } catch { /* ignore */ }
+    }
+  }
+}

package/src/metrics/metrics-recorder.js

@@ -0,0 +1,240 @@
+/**
+ * Metrics Recorder — withMetrics wrapper for tool handlers
+ *
+ * Wraps tool handlers to record success/fail/timeout/circuit_open/stale
+ * results into SQLite via MetricsDB. Normalizes inconsistent isError
+ * usage across tools into consistent result_type values.
+ */
+import { ErrorCodes, ResultTypes } from './error-codes.js';
+
+let metricsDB = null;
+
+/**
+ * Inject the MetricsDB instance. Called once at startup.
+ */
+export function setMetricsDB(db) {
+  metricsDB = db;
+}
+
+/**
+ * Normalize result_type from inconsistent tool handler responses.
+ *
+ * Tool handlers return isError inconsistently:
+ * - Some set isError: true for errors
+ * - Some return timeout messages without isError
+ * - Some throw Error objects
+ *
+ * This function normalizes them into a consistent result_type.
+ */
+function normalizeResultType(result, error) {
+  if (error) {
+    const msg = error.message || '';
+    if (msg.includes('Circuit breaker OPEN') || msg.includes('Circuit breaker HALF_OPEN')) {
+      return ResultTypes.CIRCUIT_OPEN;
+    }
+    return ResultTypes.ERROR;
+  }
+
+  if (!result) {
+    return ResultTypes.NULL_RESULT;
+  }
+
+  const text = result.content?.[0]?.text || '';
+
+  if (result.isError) {
+    if (text.includes('did not respond within') || text.includes('Timeout') || text.includes('timeout')) {
+      return ResultTypes.TIMEOUT;
+    }
+    if (text.includes('not connected') || text.includes('Extension not connected')) {
+      return ResultTypes.STALE_CONNECTION;
+    }
+    return ResultTypes.ERROR;
+  }
+
+  // Defensive fallback: even if isError:true is missing, detect error text patterns.
+  // Some tool handlers (e.g. execute-js.js hard guards) returned { content: [...] }
+  // without isError flag, causing false-success in metrics. See CHANGELOG fix.
+  if (text.startsWith('Security Error:') || text.startsWith('Error:') ||
+      text.includes('\n❌ Error:') || text.startsWith('Validation') ||
+      text.startsWith('⛔')) {
+    return ResultTypes.ERROR;
+  }
+
+  return ResultTypes.SUCCESS;
+}
+
+/**
+ * Extract error code from result or error.
+ */
+function extractErrorCode(result, error) {
+  if (error) {
+    const msg = error.message || '';
+    if (msg.includes('Circuit breaker OPEN') || msg.includes('Circuit breaker HALF_OPEN')) return ErrorCodes.E_CIRCUIT_OPEN;
+    if (msg.includes('not connected')) return ErrorCodes.E_STALE_CONNECTION;
+    return ErrorCodes.E_UNKNOWN;
+  }
+
+  if (!result) return null;
+
+  const text = result.content?.[0]?.text || '';
+
+  if (text.includes('did not respond within') || text.includes('Timeout') || text.includes('timeout')) return ErrorCodes.E_TIMEOUT;
+  if (text.includes('CSP') || text.includes('Content Security Policy')) return ErrorCodes.E_CSP_BLOCKED;
+  if (text.includes('not found') || text.includes('not visible') || text.includes('occluded')) return ErrorCodes.E_NOT_FOUND;
+  if (text.includes('not visible') || text.includes('blocked by')) return ErrorCodes.E_NOT_VISIBLE;
+  if (text.includes('Invalid selector') || text.includes('selector')) return ErrorCodes.E_SELECTOR_INVALID;
+  if (text.includes('Validation') || text.includes('validation') || text.includes('required')) return ErrorCodes.E_VALIDATION;
+  if (text.includes('Rate limit') || text.includes('rate limit')) return ErrorCodes.E_RATE_LIMITED;
+  if (text.includes('Security') || text.includes('blocked') || text.includes('not allowed')) return ErrorCodes.E_SECURITY;
+
+  return ErrorCodes.E_UNKNOWN;
+}
+
+/**
+ * Extract domain from a URL string.
+ */
+function domainFromUrl(url) {
+  if (!url) return null;
+  try { return new URL(url).hostname; } catch { return null; }
+}
+
+/**
+ * Extract domain for a tool call.
+ *
+ * Priority: bridgeClient.activeTabUrl → args.url → args.tabUrl → null
+ * Most tool calls don't receive a `url` arg directly; the active tab's URL
+ * from bridge state is the authoritative source for which site the tool
+ * was operating on.
+ */
+function extractDomain(args, bridgeClient) {
+  return domainFromUrl(bridgeClient?.activeTabUrl) ||
+         domainFromUrl(args?.url) ||
+         domainFromUrl(args?.tabUrl) ||
+         null;
+}
+
+/**
+ * Extract metadata specific to each tool.
+ */
+function extractMetadata(toolName, args) {
+  const meta = {};
+
+  if (toolName === 'execute_js' && args.code) {
+    meta.code_size = args.code.length;
+    if (args.cspBypass !== undefined) meta.csp_bypass = args.cspBypass;
+    if (args.context) meta.context = args.context;
+  }
+
+  if (toolName === 'execute_action') {
+    if (args.selectorInfo) {
+      meta.selector_type = args.selectorInfo.css ? 'css' : args.selectorInfo.xpath ? 'xpath' : args.selectorInfo.text ? 'text' : 'unknown';
+    }
+    if (args.skipValidation !== undefined) meta.skip_validation = args.skipValidation;
+  }
+
+  if (toolName === 'extract_data') {
+    if (args.verbose !== undefined) meta.verbose = args.verbose;
+  }
+
+  if (toolName === 'get_element' && args.selectorInfo) {
+    meta.selection_method = args.selectorInfo.css ? 'css' : args.selectorInfo.xpath ? 'xpath' : args.selectorInfo.text ? 'text' : 'manual';
+  }
+
+  return Object.keys(meta).length > 0 ? JSON.stringify(meta) : null;
+}
+
+/**
+ * Get extension version from package.json or bridge client.
+ */
+function getExtensionVersion() {
+  // Version will be replaced by actual version lookup from bridge client state
+  return '2.7.5';
+}
+
+/**
+ * Wrap a tool handler with metrics recording.
+ *
+ * @param {string} toolName - Tool name (e.g., 'execute_js')
+ * @param {Function} handler - Original async handler (args, bridgeClient) => result
+ * @returns {Function} Wrapped handler
+ */
+export function withMetrics(toolName, handler) {
+  return async function wrappedHandler(args, bridgeClient) {
+    if (!metricsDB || !metricsDB.available) {
+      // Metrics not available — pass through without recording
+      return handler(args, bridgeClient);
+    }
+
+    const start = Date.now();
+    const bridgeConnected = bridgeClient?.isConnected ?? true;
+    const circuitBreakerState = bridgeClient?.circuitBreakers?.[toolName]?.state || null;
+
+    let result = null;
+    let error = null;
+
+    try {
+      result = await handler(args, bridgeClient);
+    } catch (err) {
+      error = err;
+    }
+
+    const duration_ms = Date.now() - start;
+    const resultType = normalizeResultType(result, error);
+    const errorCode = extractErrorCode(result, error);
+    const domain = extractDomain(args, bridgeClient);
+    const action = args.actionType || null;
+    const selector = args.selectorInfo?.css || args.selectorInfo?.xpath || args.selectorInfo?.text || null;
+    const metadata = extractMetadata(toolName, args);
+    const errorMessage = error ? error.message : (result?.content?.[0]?.text || '');
+    const extensionVersion = getExtensionVersion();
+
+    // If handler threw, wrap it as MCP error response
+    if (error) {
+      metricsDB.recordToolCall({
+        timestamp: new Date().toISOString(),
+        domain,
+        tool: toolName,
+        action,
+        success: 0,
+        result_type: resultType,
+        error_code: errorCode,
+        error_message: errorMessage.slice(0, 200),
+        duration_ms,
+        selector,
+        retry_count: 0,
+        circuit_breaker_state: circuitBreakerState || 'not_used',
+        tab_id: args.tabId || null,
+        metadata,
+        extension_version: extensionVersion,
+        bridge_connected: bridgeConnected ? 1 : 0,
+      });
+
+      // Return MCP error format
+      return {
+        content: [{ type: 'text', text: `❌ Error: ${error.message}` }],
+        isError: true,
+      };
+    }
+
+    metricsDB.recordToolCall({
+      timestamp: new Date().toISOString(),
+      domain,
+      tool: toolName,
+      action,
+      success: resultType === ResultTypes.SUCCESS ? 1 : 0,
+      result_type: resultType,
+      error_code: resultType !== ResultTypes.SUCCESS ? errorCode : null,
+      error_message: resultType !== ResultTypes.SUCCESS ? errorMessage.slice(0, 200) : null,
+      duration_ms,
+      selector,
+      retry_count: 0,
+      circuit_breaker_state: circuitBreakerState || 'not_used',
+      tab_id: args.tabId || null,
+      metadata,
+      extension_version: extensionVersion,
+      bridge_connected: bridgeConnected ? 1 : 0,
+    });
+
+    return result;
+  };
+}