@yusufffararatt/dombridge-mcp 2.7.5

package/src/state/extension-state.js

@@ -0,0 +1,321 @@
+/**
+ * Extension State Management
+ * Chrome extension'dan gelen gerçek verileri merkezi olarak saklar
+ *
+ * Phase 1.1: Persistence hooks integrated — every state mutation
+ * schedules a debounced write to bridge-state.json via bridge-persistence.js.
+ */
+
+import { schedulePersist } from './bridge-persistence.js';
+
+// Shared state across MCP instances via HTTP
+
+export const extensionData = {
+  // Son seçilen element
+  selectedElement: null,
+
+  // Network trace sonuçları
+  networkTrace: {
+    timestamp: null,
+    tabId: null,
+    totalMatches: 0,
+    matches: [],
+    elementValue: null,
+    values: [] // Multi-value filtering için
+  },
+
+  // WebSocket trace sonuçları (NEW v2.3)
+  websocketTrace: {
+    timestamp: null,
+    tabId: null,
+    totalMatches: 0,
+    matches: [],
+    elementValue: null,
+    filterValues: [],
+    connectionsAnalyzed: 0,
+    totalMessagesAnalyzed: 0
+  },
+
+  // Raw WebSocket connections data (NEW - from interceptor)
+  websocketConnections: {
+    timestamp: null,
+    tabId: null,
+    connections: [],
+    totalConnections: 0,
+    totalMessages: 0
+  },
+
+  // Kaydedilmiş seçimler
+  savedSelections: [],
+
+  // Sayfa veri kaynağı analizi
+  pageAnalysis: {
+    timestamp: null,
+    ssrDetected: false,
+    initialStateDetected: false,
+    embeddedDataDetected: false,
+    networkCaptureRate: 0,
+    totalNetworkRequests: 0,
+    capturedResponseBodies: 0,
+    detectedDataSources: [],
+    recommendation: null
+  },
+
+  // Aktif tab URL'i (heartbeat'ten gelir, domain tespiti için kullanılır)
+  activeTabUrl: '',
+
+  // Extension'ın aktif olup olmadığı
+  isConnected: false,
+
+  // Tab navigasyonu sırasında soft disconnect — isConnected false yapılmaz
+  pendingNavigation: false,
+  lastUpdateTime: null,
+
+  // Oturum takibi (sayfa yenilemelerini reconnect olarak tespit eder)
+  currentSessionId: null,
+  sessionStartedAt: null,
+
+  // JS Execution request/result (polling için)
+  jsExecutionRequest: null,
+  jsExecutionResult: null,        // ESKİ: tekli result — kaldırılmayacak (backward compat)
+  jsExecutionResults: {},         // YENİ: requestId-keyed Map (race-condition fix)
+
+  // RPA Action request/result
+  actionExecutionRequest: null,
+  actionExecutionResult: null,
+
+  // Screenshot request/result
+  captureScreenshotRequest: null,
+  captureScreenshotResult: null,
+
+  // Raw network discovery queue/results (discover_apis tool)
+  rawNetworkRequests: [],
+  rawNetworkResults: {},
+
+  // Captured API endpoints from discover_apis (NEW — for manage_site_profile save flow)
+  // Each entry: { domain, method, url, status, contentType, firstSeenAt, lastSeenAt }
+  apiEndpoints: [],
+
+  // Analyze page queue/results
+  analyzePageRequests: [],
+  analyzePageResults: {},
+
+  // Programmatic element selection request/result (select_element tool)
+  selectElementRequest: null,
+  selectElementResult: null,
+
+  // Export session request/result
+  exportSessionRequest: null,
+  exportSessionResult: null,
+
+  // Tab list request/result (for multi-tab support)
+  tabsRequest: null,
+  tabsResult: null,
+
+  // Insight tracking: execute_js disambiguation fırsatları vs save_site_profile çağrıları
+  // { "x.com": 3 } formatında — domain başına sayaç
+  insightOpportunities: {},
+  profileSaves: {},
+
+  // Restart signal: MCP server reads this via /api/state to decide whether to exit
+  // Set by bridge daemon on POST /api/restart, cleared by MCP server on startup
+  restartRequestedAt: null,
+};
+
+/**
+ * Extension state güncelleme fonksiyonları
+ */
+export const updateSelectedElement = (data) => {
+  const { cssSelector, xpath, outerHTML, tagName, attributes, sessionInfo, stableSelector, stableSelectorMeta, pageURL, pageTitle } = data;
+
+  extensionData.selectedElement = {
+    cssSelector,
+    xpath,
+    outerHTML,
+    tagName,
+    attributes,
+    sessionInfo: sessionInfo || null,
+    stableSelector: stableSelector || null,
+    stableSelectorMeta: stableSelectorMeta || null,
+    pageUrl: pageURL || null,
+    pageTitle: pageTitle || null,
+    timestamp: Date.now()
+  };
+
+  extensionData.isConnected = true;
+  extensionData.lastUpdateTime = Date.now();
+  schedulePersist(extensionData);
+};
+
+export const updateNetworkTrace = (data) => {
+  const { totalMatches, matches, elementValue, values, tabId } = data;
+
+  extensionData.networkTrace = {
+    timestamp: Date.now(),
+    tabId: tabId || null,
+    totalMatches,
+    matches: matches || [],
+    elementValue,
+    values: values || []
+  };
+
+  extensionData.lastUpdateTime = Date.now();
+  schedulePersist(extensionData);
+};
+
+export const updateWebSocketTrace = (data) => {
+  // Support both raw WebSocket data (from interceptor) and processed trace data
+  if (data.connections !== undefined) {
+    // Raw WebSocket data from interceptor
+    extensionData.websocketConnections = {
+      timestamp: Date.now(),
+      tabId: data.tabId || null,
+      connections: data.connections || [],
+      totalConnections: data.totalConnections || 0,
+      totalMessages: data.totalMessages || 0
+    };
+  } else {
+    // Processed trace data (legacy format with matches)
+    const { totalMatches, matches, elementValue, filterValues, connectionsAnalyzed, totalMessagesAnalyzed, tabId } = data;
+    extensionData.websocketTrace = {
+      timestamp: Date.now(),
+      tabId: tabId || null,
+      totalMatches: totalMatches || 0,
+      matches: matches || [],
+      elementValue: elementValue || null,
+      filterValues: filterValues || [],
+      connectionsAnalyzed: connectionsAnalyzed || 0,
+      totalMessagesAnalyzed: totalMessagesAnalyzed || 0
+    };
+  }
+
+  extensionData.lastUpdateTime = Date.now();
+  schedulePersist(extensionData);
+};
+
+export const updateSavedSelections = (savedSelections) => {
+  extensionData.savedSelections = savedSelections || [];
+  extensionData.lastUpdateTime = Date.now();
+};
+
+export const updatePageAnalysis = (data) => {
+  const {
+    ssrDetected,
+    initialStateDetected,
+    embeddedDataDetected,
+    networkCaptureRate,
+    totalNetworkRequests,
+    capturedResponseBodies,
+    detectedDataSources,
+    recommendation
+  } = data;
+
+  extensionData.pageAnalysis = {
+    timestamp: Date.now(),
+    ssrDetected: ssrDetected || false,
+    initialStateDetected: initialStateDetected || false,
+    embeddedDataDetected: embeddedDataDetected || false,
+    networkCaptureRate: networkCaptureRate || 0,
+    totalNetworkRequests: totalNetworkRequests || 0,
+    capturedResponseBodies: capturedResponseBodies || 0,
+    detectedDataSources: detectedDataSources || [],
+    recommendation: recommendation || null
+  };
+
+  extensionData.lastUpdateTime = Date.now();
+  schedulePersist(extensionData);
+};
+
+export const syncAll = (data) => {
+  const { selectedElement, networkTrace, savedSelections } = data;
+
+  if (selectedElement) {
+    updateSelectedElement(selectedElement);
+  }
+
+  if (networkTrace) {
+    updateNetworkTrace(networkTrace);
+  }
+
+  if (savedSelections) {
+    updateSavedSelections(savedSelections);
+  }
+
+  extensionData.isConnected = true;
+  extensionData.lastUpdateTime = Date.now();
+};
+
+export const updateConnection = (sessionId = null) => {
+  const isNewSession = sessionId && sessionId !== extensionData.currentSessionId;
+  if (isNewSession) {
+    extensionData.currentSessionId = sessionId;
+    extensionData.sessionStartedAt = Date.now();
+  }
+  extensionData.isConnected = true;
+  extensionData.lastUpdateTime = Date.now();
+  schedulePersist(extensionData);
+};
+
+export const updateDisconnect = (reason = 'explicit') => {
+  void reason; // reason bilgisi connectionHealth event'larında tutuluyor
+  extensionData.isConnected = false;
+  extensionData.lastUpdateTime = Date.now();
+};
+
+/**
+ * Clear all content-script-processed pending requests.
+ * Called when extension connection is lost (stale/timeout) to prevent orphan requests
+ * from causing tool timeouts. Mirrors the logic in /api/clear-all-requests route.
+ */
+export const clearAllPendingRequests = (data = extensionData) => {
+  data.jsExecutionRequest = null;
+  data.actionExecutionRequest = null;
+  data.captureScreenshotRequest = null;
+  data.rawNetworkRequests = [];
+  data.analyzePageRequests = [];
+  data.selectElementRequest = null;
+};
+
+/**
+ * Add a captured API endpoint to extension state for later profile persistence.
+ * Dedup by (domain, method, url). Called by discover_apis tool.
+ * @param {{domain: string, method: string, url: string, status?: number, contentType?: string}} endpoint
+ */
+export const addCapturedEndpoint = (endpoint) => {
+  if (!endpoint || !endpoint.domain || !endpoint.url) return;
+  const key = `${endpoint.domain}::${(endpoint.method || 'GET').toUpperCase()}::${endpoint.url}`;
+  const exists = extensionData.apiEndpoints.some(
+    (e) => `${e.domain}::${(e.method || 'GET').toUpperCase()}::${e.url}` === key
+  );
+  if (exists) {
+    // Update timestamp + status if changed
+    const idx = extensionData.apiEndpoints.findIndex(
+      (e) => `${e.domain}::${(e.method || 'GET').toUpperCase()}::${e.url}` === key
+    );
+    extensionData.apiEndpoints[idx] = {
+      ...extensionData.apiEndpoints[idx],
+      ...endpoint,
+      lastSeenAt: Date.now()
+    };
+  } else {
+    const now = Date.now();
+    extensionData.apiEndpoints.push({
+      ...endpoint,
+      method: (endpoint.method || 'GET').toUpperCase(),
+      firstSeenAt: now,
+      lastSeenAt: now
+    });
+  }
+  extensionData.lastUpdateTime = Date.now();
+  schedulePersist(extensionData);
+};
+
+/**
+ * Get captured endpoints filtered by domain. Used by manage_site_profile save action.
+ * @param {string} domain
+ * @returns {Array}
+ */
+export const getCapturedEndpoints = (domain) => {
+  if (!domain) return extensionData.apiEndpoints;
+  return extensionData.apiEndpoints.filter((e) => e.domain === domain);
+};

package/src/tools/action_tools.js

@@ -0,0 +1,218 @@
+/**
+ * Action Tools for AI RPA Integration
+ * Yapay zeka asistanlarının DOM üzerinde otonom işlemler (tıklama, doldurma) yapmasını sağlar
+ *
+ * Phase 2.4: Refactored from (args, extensionData, httpPort) to (args, bridgeClient).
+ */
+
+import { runScript } from '../utils/run-script.js';
+import { VALIDATION_SCRIPT, formatAlternatives, rankSimilarElements } from '../utils/selector-validator.js';
+import { StateValidator } from '../utils/state-validator.js';
+
+export const executeActionTool = {
+    name: 'execute_action',
+    description: `This is a tool from the dombridge MCP server.
+Perform safe, autonomous interactions with a Chrome tab (click, type, scroll).
+
+WORKFLOW POSITION: 🟠 Third Step - Use after getting elements
+
+PREREQUISITES:
+- ✅ Extension must be connected
+- Appropriate element selectors (from get_element or execute_js)
+
+MULTI-TAB: Call debug_mcp_state() first to get tab IDs, then pass tabId to target a specific tab.
+
+SECURITY & LIMITS:
+- 🛡️ Automatically blocked on banking/crypto domains (Garanti, İş Bankası, Binance, etc.).
+- 🛡️ Password and hidden inputs are always blocked.
+- ⏱️ Operations are queued and executed via isolated action-engine.
+
+PARAMETERS:
+- actionType: 'click', 'type', 'pressKey', or 'scroll'
+- selectorInfo: Object with 'css', 'xpath', or 'text' selector
+- text:
+  - For 'type': text to enter
+  - For 'pressKey': key name e.g. 'Enter', 'Tab', 'Escape'
+  - For 'scroll': "y" pixels (e.g. "500") or "x,y" (e.g. "0,800"). selectorInfo is optional for scroll.
+- url: Current page URL (for domain safety validation — REQUIRED)
+
+pressKey dispatches a full keydown/keypress/keyup sequence compatible with React SPA event systems.
+For React forms, use pressKey with key='Enter' to submit instead of native form.submit().
+
+BEST PRACTICES:
+- ⚠️ PREFER 'css' or 'xpath' selectors. 'text' selectors may fail on complex/nested DOM.
+- CSS selectors are pre-validated before the action fires — no need for a separate execute_js check step.
+- Use skipValidation: true only if the element appears after a dynamic event (animation, lazy-load).
+
+WORKFLOW:
+1. execute_action → selector is auto-validated (exists, visible, not occluded) before firing
+
+EXAMPLES:
+execute_action({ actionType: 'click', selectorInfo: { css: 'button.submit' }, url: 'https://example.com' })
+execute_action({ actionType: 'scroll', selectorInfo: { css: 'body' }, text: '800', url: 'https://example.com' })
+`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            actionType: {
+                type: 'string',
+                enum: ['click', 'type', 'pressKey', 'scroll', 'navigate'],
+                description: 'Type of action to perform. navigate: go to a URL in the current tab (pass target URL in text parameter)'
+            },
+            selectorInfo: {
+                type: 'object',
+                properties: {
+                    css: { type: 'string' },
+                    xpath: { type: 'string' },
+                    text: { type: 'string', description: '⚠️ UNRELIABLE on nested DOM. Use xpath or css instead.' }
+                },
+                description: 'Selector to find the element. Provide at least one valid locator. PREFER xpath or css over text.'
+            },
+            text: {
+                type: 'string',
+                description: 'The text to enter (type), key name (pressKey), scroll amount px (scroll), or target URL (navigate)'
+            },
+            url: {
+                type: 'string',
+                description: 'The target URL of the active tab for domain safety check'
+            },
+            tabId: {
+                type: 'number',
+                description: 'Target tab ID (optional). Omit to use active tab. Get IDs from debug_mcp_state().'
+            },
+            skipValidation: {
+                type: 'boolean',
+                description: 'Skip pre-action selector validation (default: false). Use only when element appears after a dynamic event (animation, lazy-load) that the validator cannot see.',
+                default: false
+            }
+        },
+        required: ['actionType', 'url']
+    },
+    handler: async (args, bridgeClient) => {
+        // Connection check — use same StateValidator as execute_js for consistency
+        const connValidation = StateValidator.validateConnection(bridgeClient);
+        if (!connValidation.valid) {
+            return StateValidator.formatValidationError(connValidation);
+        }
+
+        const { actionType, selectorInfo, url, tabId, skipValidation = false } = args;
+        const text = args.text || ''; // Prevent undefined → Chrome can't serialize undefined
+        const normalizedSelectorInfo = selectorInfo || {};
+        const requestId = `action-${Date.now()}-${Math.floor(Math.random() * 1000)}`;
+
+        // Pre-action selector validation (CSS only, skip for scroll + body/html structural elements)
+        const css = normalizedSelectorInfo.css;
+        if (css && !skipValidation && actionType !== 'scroll') {
+            try {
+                const v = await runScript(VALIDATION_SCRIPT(css), bridgeClient, 5000, { tabId });
+                if (v && !v.found) {
+                    // Map alternatives to a unified shape, rank by semantic relevance,
+                    // then format. VALIDATION_SCRIPT returns {tag, id, cls, text}; we
+                    // convert to {selector, text, attributes} so the ranker can score
+                    // by placeholder/aria-label/search indicators.
+                    const candidates = (v.alternatives || []).map(a => ({
+                        selector: `${a.tag}${a.id ? '#' + a.id : ''}${a.cls ? '.' + a.cls : ''}`,
+                        text: a.text || '',
+                        attributes: {}
+                    }));
+                    const similarList = rankSimilarElements(candidates, css);
+                    const similarForFormat = similarList.map(c => ({
+                        tag: c.selector.split(/[#.]/)[0],
+                        id: (c.selector.match(/#([^.#]+)/) || [])[1] || null,
+                        cls: c.selector.split('.').slice(1).join('.'),
+                        text: c.text
+                    }));
+                    const altLines = formatAlternatives(similarForFormat);
+                    return {
+                        isError: true,
+                        content: [{ type: 'text', text:
+                            `❌ Error: Selector not found: \`${css}\`\nREQUIRED STEPS:\n1. Verify: \`execute_js({ code: "document.querySelector('${css}')" })\`\n2. Use \`get_element()\` to find the correct selector${altLines ? '\n\nSimilar elements on page:\n' + altLines : ''}`
+                        }]
+                    };
+                }
+                if (v && v.found && !v.visible) {
+                    const ambiguityNote = (v.matchCount || 0) > 1
+                        ? `\n\nℹ️  Note: \`${css}\` matches ${v.matchCount} elements. \`querySelector\` returns the first one — if that's the wrong element, narrow the selector (e.g. \`${css}:nth-of-type(1)\` or a class/id-based selector).`
+                        : '';
+                    return {
+                        isError: true,
+                        content: [{ type: 'text', text:
+                            `❌ Error: Element exists but is not visible: \`${css}\`\nREQUIRED STEPS:\n1. Scroll to it: \`execute_action({ actionType: 'scroll', text: '500', url: '${url}' })\`\n2. Or use \`execute_js\` to check why it is hidden (display:none, visibility:hidden, zero dimensions)${ambiguityNote}`
+                        }]
+                    };
+                }
+                if (v && v.found && v.occluded) {
+                    return {
+                        isError: true,
+                        content: [{ type: 'text', text:
+                            `❌ Error: Element is blocked by \`${v.occluder || 'another element'}\`\nREQUIRED STEPS:\n1. Close the overlay/modal first\n2. Or use \`execute_js\` to dismiss it`
+                        }]
+                    };
+                }
+                // disabled: warn but proceed (state can change on focus)
+            } catch (_) {
+                // Validation failure is non-blocking — proceed with action
+            }
+        }
+
+        try {
+            // Send action request via bridge daemon
+            await bridgeClient.queueRequest('execute-action', {
+                actionType,
+                selectorInfo: normalizedSelectorInfo,
+                text,
+                url,
+                id: requestId,
+                ...(tabId !== undefined ? { tabId } : {})
+            });
+
+            // Wait for extension to process and return result
+            const timeout = 10000;
+            const resultItem = await bridgeClient.waitForResult('action-execution', requestId, timeout + 3000);
+
+            if (resultItem) {
+                if (resultItem.result && resultItem.result.error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `❌ Action Error: ${resultItem.result.error}\n\nReview safety-guard restrictions or element selectors.`
+                            }
+                        ],
+                        isError: true
+                    };
+                }
+
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `✅ Action executed successfully:\n\n${JSON.stringify(resultItem.result, null, 2)}`
+                        }
+                    ]
+                };
+            }
+
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Action Timeout: The extension did not report back within ${timeout}ms. Check if the page is still loading or if Chrome disconnected.`
+                    }
+                ],
+                isError: true
+            };
+
+        } catch (e) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `❌ Server Error: ${e.message}`
+                    }
+                ],
+                isError: true
+            };
+        }
+    }
+};