@yusufffararatt/dombridge-mcp 2.7.5

package/src/utils/logger.js

@@ -0,0 +1,31 @@
+/**
+ * MCP-compliant logger
+ *
+ * MCP stdio transport uses stdout exclusively for JSON-RPC messages.
+ * ALL diagnostic output MUST go to stderr — never stdout.
+ *
+ * Levels:
+ *   info  — startup, lifecycle events (always visible)
+ *   warn  — recoverable issues (always visible)
+ *   error — failures (always visible)
+ *   debug — verbose detail (only when MCP_DEBUG=1)
+ */
+
+const isDebug = () => process.env.MCP_DEBUG === '1';
+
+const PREFIX = '[MCP]';
+
+function fmt(level, context, ...args) {
+  const tag = context ? `${PREFIX}[${context}]` : PREFIX;
+  process.stderr.write(`${tag} ${level} ${args.map(a =>
+    a instanceof Error ? a.stack || a.message :
+    typeof a === 'object' ? JSON.stringify(a) : String(a)
+  ).join(' ')}\n`);
+}
+
+export const logger = {
+  info:  (context, ...args) => fmt('INFO ', context, ...args),
+  warn:  (context, ...args) => fmt('WARN ', context, ...args),
+  error: (context, ...args) => fmt('ERROR', context, ...args),
+  debug: (context, ...args) => isDebug() && fmt('DEBUG', context, ...args),
+};

package/src/utils/paginate-detector.js

@@ -0,0 +1,24 @@
+/**
+ * Pagination Strategy Detector
+ *
+ * Detects the best pagination strategy for a page based on probed page state,
+ * next button presence, and infinite scroll detection.
+ *
+ * Used by tools/paginate.js when strategy='auto' to avoid defaulting to scroll
+ * when the page has explicit URL-based pagination metadata (Trendyol, etc.).
+ */
+
+export function detectPaginationStrategy({ pageState, nextButtonSelector, hasInfiniteScroll } = {}) {
+  if (nextButtonSelector) return 'button';
+
+  const totalPages = pageState?.widgetList?.totalPages
+    || pageState?.__NEXT_DATA__?.props?.pageProps?.totalPages
+    || pageState?.pagination?.totalPages
+    || 0;
+
+  if (totalPages > 1) return 'url_increment';
+
+  if (hasInfiniteScroll) return 'scroll';
+
+  return 'auto';
+}

package/src/utils/rate-limiter.js

@@ -0,0 +1,244 @@
+/**
+ * Rate Limiter & Retry Strategy
+ * Implements exponential backoff with jitter to prevent rapid sequential calls
+ *
+ * Best Practices:
+ * - Exponential backoff: 1s, 2s, 4s, 8s
+ * - Jitter: +/- 20% randomization
+ * - Per-tool rate limits
+ * - Retry-After header support
+ *
+ * References:
+ * - https://docs.anthropic.com/en/api/rate-limits
+ * - https://www.anthropic.com/engineering/code-execution-with-mcp
+ */
+
+/**
+ * Rate limit configuration per tool
+ */
+const RATE_LIMITS = {
+  // Discovery tools
+  'get_selected_element': { minInterval: 500, maxRetries: 5 },
+  'get_network_trace': { minInterval: 1000, maxRetries: 3 },
+  'get_websocket_trace': { minInterval: 1000, maxRetries: 3 },
+
+  // Low-frequency tools (expensive operations)
+  'execute_js': { minInterval: 2000, maxRetries: 3 },
+  'debug_mcp_state': { minInterval: 100, maxRetries: 2 },
+
+  // Default fallback
+  'default': { minInterval: 1000, maxRetries: 3 }
+};
+
+/**
+ * Track last execution time per tool
+ */
+const lastExecutionTime = new Map();
+
+/**
+ * Track retry counts per tool
+ */
+const retryCount = new Map();
+
+/**
+ * Rate Limiter Class
+ */
+export class RateLimiter {
+  /**
+   * Execute a function with rate limiting and retry logic
+   * @param {string} toolName - Name of the tool
+   * @param {Function} handler - Async function to execute
+   * @param {object} options - { maxRetries, minInterval, onRetry }
+   * @returns {Promise<any>} - Handler result
+   */
+  static async executeWithRetry(toolName, handler, options = {}) {
+    const config = RATE_LIMITS[toolName] || RATE_LIMITS.default;
+    const maxRetries = options.maxRetries ?? config?.maxRetries ?? 3;
+    const minInterval = options.minInterval ?? config?.minInterval ?? 1000;
+
+    let attempt = 0;
+    let lastError = null;
+
+    while (attempt < maxRetries) {
+      try {
+        // Rate limiting: wait if called too soon
+        await this.enforceRateLimit(toolName, minInterval);
+
+        // Execute handler
+        const result = await handler();
+
+        // Success: reset retry count
+        retryCount.delete(toolName);
+
+        return result;
+
+      } catch (error) {
+        lastError = error;
+        attempt++;
+
+        // Check if error is retryable
+        if (!this.isRetryableError(error) || attempt >= maxRetries) {
+          throw error;
+        }
+
+        // Calculate backoff delay
+        const delay = this.calculateBackoff(attempt, minInterval);
+
+        // Call retry callback if provided
+        if (options.onRetry) {
+          options.onRetry(attempt, delay, error);
+        }
+
+        // Wait before retrying
+        await this.sleep(delay);
+      }
+    }
+
+    // All retries exhausted
+    throw new Error(`${toolName} failed after ${maxRetries} attempts: ${lastError?.message || 'Unknown error'}`);
+  }
+
+  /**
+   * Enforce rate limit for a tool
+   * @param {string} toolName - Tool name
+   * @param {number} minInterval - Minimum interval in ms
+   */
+  static async enforceRateLimit(toolName, minInterval) {
+    const lastTime = lastExecutionTime.get(toolName);
+
+    if (lastTime) {
+      const elapsed = Date.now() - lastTime;
+      const remaining = minInterval - elapsed;
+
+      if (remaining > 0) {
+        await this.sleep(remaining);
+      }
+    }
+
+    // Update last execution time
+    lastExecutionTime.set(toolName, Date.now());
+  }
+
+  /**
+   * Calculate exponential backoff with jitter
+   * @param {number} attempt - Retry attempt number (1-indexed)
+   * @param {number} baseDelay - Base delay in ms
+   * @returns {number} - Delay in ms
+   */
+  static calculateBackoff(attempt, baseDelay = 1000) {
+    // Exponential backoff: baseDelay * 2^(attempt-1)
+    // attempt 1: 1s, attempt 2: 2s, attempt 3: 4s, attempt 4: 8s
+    const exponential = baseDelay * Math.pow(2, attempt - 1);
+
+    // Add jitter: +/- 20%
+    const jitter = exponential * 0.2 * (Math.random() * 2 - 1);
+
+    // Cap at 30 seconds
+    const delay = Math.min(exponential + jitter, 30000);
+
+    return Math.floor(delay);
+  }
+
+  /**
+   * Check if error is retryable
+   * @param {Error} error - Error object
+   * @returns {boolean}
+   */
+  static isRetryableError(error) {
+    const message = error?.message?.toLowerCase() || '';
+
+    // Retryable errors:
+    // - Timeout errors
+    // - Connection errors
+    // - Rate limit errors (429)
+    // - Server errors (5xx)
+    // - "Waiting for extension" errors
+    const retryablePatterns = [
+      'timeout',
+      'timed out',
+      'connection',
+      'network',
+      'rate limit',
+      'too many requests',
+      'server error',
+      '5xx',
+      'waiting for',
+      'no data',
+      'not ready'
+    ];
+
+    const isRetryable = retryablePatterns.some(pattern => message.includes(pattern));
+
+    // Non-retryable errors:
+    // - Validation errors
+    // - Missing prerequisites
+    // - Invalid arguments
+    const nonRetryablePatterns = [
+      'invalid',
+      'missing required',
+      'prerequisite',
+      'not allowed',
+      'forbidden'
+    ];
+
+    const isNonRetryable = nonRetryablePatterns.some(pattern => message.includes(pattern));
+
+    return isRetryable && !isNonRetryable;
+  }
+
+  /**
+   * Sleep utility
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  static sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Get rate limit stats
+   * @returns {object} - Stats object
+   */
+  static getStats() {
+    return {
+      lastExecutionTimes: Object.fromEntries(lastExecutionTime),
+      retryCounts: Object.fromEntries(retryCount)
+    };
+  }
+
+  /**
+   * Reset rate limiter state
+   * @param {string|null} toolName - Tool name to reset, or null for all
+   */
+  static reset(toolName = null) {
+    if (toolName) {
+      lastExecutionTime.delete(toolName);
+      retryCount.delete(toolName);
+    } else {
+      lastExecutionTime.clear();
+      retryCount.clear();
+    }
+  }
+}
+
+/**
+ * Simple helper: wait with validation
+ * @param {number} ms - Milliseconds
+ * @param {BridgeClient|object} bridgeClient - State source to check
+ * @param {Function} validation - Validation function that returns boolean
+ * @param {number} maxWait - Maximum wait time in ms
+ * @returns {Promise<boolean>} - True if validation passed, false if timeout
+ */
+export async function waitForCondition(ms, bridgeClient, validation, maxWait = 5000) {
+  const startTime = Date.now();
+
+  while (Date.now() - startTime < maxWait) {
+    if (validation(bridgeClient)) {
+      return true;
+    }
+
+    await RateLimiter.sleep(ms);
+  }
+
+  return false;
+}

package/src/utils/run-script.js

@@ -0,0 +1,37 @@
+/**
+ * runScript — execute_js pipeline shared helper
+ * Tüm tool'lar bu helper'ı kullanır: extract_data, check_site_changes, vb.
+ *
+ * Phase 2.4: Refactored from (code, extensionData, httpPort, ...) to (code, bridgeClient, ...).
+ * Now uses bridgeClient.queueRequest() and bridgeClient.waitForResult() instead of
+ * direct HTTP fetch and in-memory result polling.
+ */
+
+export async function runScript(code, bridgeClient, timeoutMs = 12000, options = {}) {
+    const requestId = `script-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+    await bridgeClient.queueRequest('execute-js', {
+        code,
+        timeout: timeoutMs,
+        id: requestId,
+        ...(options.tabId !== undefined ? { tabId: options.tabId } : {})
+    });
+
+    const resultItem = await bridgeClient.waitForResult('js-execution', requestId, timeoutMs + 3000);
+
+    if (!resultItem) {
+        throw new Error('Timeout');
+    }
+
+    // CSP auto-bypass wraps result in { _cspBypassed, result }. Unwrap it.
+    let rawResult = resultItem.result;
+    if (rawResult && rawResult._cspBypassed !== undefined && rawResult.result !== undefined) {
+        rawResult = rawResult.result;
+    }
+
+    if (rawResult && rawResult.error) {
+        throw new Error(rawResult.error);
+    }
+
+    return rawResult;
+}

package/src/utils/selector-validator.js

@@ -0,0 +1,95 @@
+/**
+ * Shared selector validation script.
+ * Injected into page context to check element existence, visibility, and suggest alternatives.
+ * Used by execute_action (pre-action) and get_element (post-failure).
+ */
+
+export const VALIDATION_SCRIPT = (css) => `(function() {
+    var all = document.querySelectorAll(${JSON.stringify(css)});
+    var matchCount = all.length;
+    var el = all[0];
+    if (!el) {
+        var tagMatch = ${JSON.stringify(css)}.match(/^[a-zA-Z]*/);
+        var tag = (tagMatch && tagMatch[0]) ? tagMatch[0] : '*';
+        var STRUCTURAL_TAGS = ['html','head','body','script','style','meta','link','noscript','title','base','template'];
+        var similar = Array.from(document.querySelectorAll(tag))
+            .filter(function(e) { return STRUCTURAL_TAGS.indexOf(e.tagName.toLowerCase()) === -1; })
+            .slice(0, 3)
+            .map(function(e) {
+                return {
+                    tag: e.tagName.toLowerCase(),
+                    id: e.id || null,
+                    cls: Array.from(e.classList).slice(0, 3).join('.'),
+                    text: (e.textContent || '').trim().substring(0, 40)
+                };
+            });
+        return { found: false, matchCount: 0, alternatives: similar };
+    }
+    var rect = el.getBoundingClientRect();
+    var visible = rect.width > 0 && rect.height > 0 && el.offsetParent !== null;
+    var cx = rect.left + rect.width / 2;
+    var cy = rect.top + rect.height / 2;
+    var topEl = document.elementFromPoint(cx, cy);
+    var occluded = topEl !== null && topEl !== el && !el.contains(topEl);
+    return {
+        found: true,
+        matchCount: matchCount,
+        visible: visible,
+        occluded: occluded,
+        occluder: occluded ? (topEl.className || topEl.tagName.toLowerCase()) : null,
+        disabled: !!(el.disabled || el.getAttribute('aria-disabled') === 'true')
+    };
+})()`;
+
+/**
+ * Format alternatives list from VALIDATION_SCRIPT result.
+ * @param {Array} alternatives
+ * @returns {string}
+ */
+export function formatAlternatives(alternatives) {
+    if (!alternatives || alternatives.length === 0) return '';
+    // Bug #2 fix: dedup by tag#id.class key to avoid duplicate similar-element lines
+    const seen = new Set();
+    const unique = alternatives.filter(a => {
+        const key = `${a.tag}${a.id ? '#' + a.id : ''}${a.cls ? '.' + a.cls : ''}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+    });
+    return unique.map(a =>
+        `  - \`${a.tag}${a.id ? '#' + a.id : ''}${a.cls ? '.' + a.cls : ''}\` — "${a.text}"`
+    ).join('\n');
+}
+
+/**
+ * Rank similar element candidates by semantic relevance.
+ * Penalizes hidden/cookie/OneTrust patterns and rewards search/semantic
+ * indicators (placeholder, aria-label, type=search, name=q, etc.).
+ *
+ * @param {Array} candidates - Array of { selector, text, attributes } objects.
+ * @param {string} originalSelector - The CSS selector that failed (context hint).
+ * @returns {Array} New array sorted by descending relevance score.
+ */
+export function rankSimilarElements(candidates, _originalSelector) {
+    const score = (c) => {
+        let s = 0;
+        const sel = c.selector || '';
+        const attrs = c.attributes || {};
+
+        // Penalize hidden/cookie/OT patterns
+        if (/type=["']?(hidden|checkbox)["']?/i.test(sel)) s -= 50;
+        if (/ot-group-id|onetrust|cookie|category-switch-handler/i.test(sel)) s -= 40;
+        if (/type=["']?submit["']?/i.test(sel)) s -= 30;
+
+        // Reward search/semantic
+        if (attrs.placeholder || /placeholder/i.test(sel)) s += 30;
+        if (attrs['aria-label'] || /aria-label/i.test(sel)) s += 20;
+        if (attrs.type === 'search' || /type=["']?search["']?/i.test(sel)) s += 25;
+        if (attrs.name === 'q' || /name=["']?q["']?/i.test(sel)) s += 20;
+        if (/search|ara|query|find/i.test(sel)) s += 15;
+
+        return s;
+    };
+
+    return [...candidates].sort((a, b) => score(b) - score(a));
+}