@dynamicu/chromedebug-mcp 2.2.0

package/src/mcp/handlers/frame-tool-handler.js

@@ -0,0 +1,957 @@
+/**
+ * Frame Tool Handler - Handles frame recording and interaction tools
+ * Extracted from original index.js with preserved functionality and security measures
+ * Now uses HTTP client for authenticated access to recordings
+ */
+
+import { httpClient } from '../../services/http-client.js';
+
+export class FrameToolHandler {
+  constructor(chromeController) {
+    this.chromeController = chromeController;
+    this.useHttpClient = true; // Flag to use HTTP client instead of direct database access
+  }
+
+  /**
+   * Handles frame-related tool calls
+   * @param {string} name - Tool name
+   * @param {Object} args - Tool arguments
+   * @returns {Object} Tool execution result
+   */
+  async handle(name, args) {
+    switch (name) {
+      case 'chromedebug_show_frames':
+        return await this.handleShowFrames(args);
+      
+      case 'get_frame_session_info':
+        return await this.handleGetFrameSessionInfo(args);
+
+      case 'get_frame':
+        return await this.handleGetFrame(args);
+
+      case 'search_frame_logs':
+        return await this.handleSearchFrameLogs(args);
+
+      case 'get_frame_logs_paginated':
+        return await this.handleGetFrameLogsPaginated(args);
+
+      case 'get_frame_screenshot':
+        return await this.handleGetFrameScreenshot(args);
+
+      case 'get_screen_interactions':
+        return await this.handleGetScreenInteractions(args);
+
+      /*
+       * SNAPSHOT FEATURE DISABLED (2025-10-01)
+       * Snapshot case handlers removed - see SNAPSHOT_FEATURE_DISABLED.md
+       */
+      /*
+      case 'take_snapshot':
+        return await this.handleTakeSnapshot(args);
+
+      case 'list_snapshots':
+        return await this.handleListSnapshots(args);
+
+      case 'get_snapshot':
+        return await this.handleGetSnapshot(args);
+
+      case 'search_snapshot_logs':
+        return await this.handleSearchSnapshotLogs(args);
+      */
+
+      default:
+        throw new Error(`Unknown frame tool: ${name}`);
+    }
+  }
+
+  /**
+   * Handle chromedebug_show_frames tool
+   * @param {Object} args - Arguments with sessionId and display options
+   * @returns {Object} Formatted frame display
+   */
+  async handleShowFrames(args) {
+    if (!args.sessionId) {
+      throw new Error('Session ID is required');
+    }
+    
+    const maxFrames = args.maxFrames || 10;
+    const showLogs = args.showLogs !== false;
+    const showInteractions = args.showInteractions !== false;
+    const logLevel = args.logLevel || 'all';
+    const maxLogsPerFrame = args.maxLogsPerFrame || 10;
+    
+    let sessionInfo, availableSessions;
+    
+    try {
+      if (this.useHttpClient) {
+        sessionInfo = await httpClient.getFrameSessionInfo(args.sessionId);
+        if (!sessionInfo) {
+          availableSessions = await httpClient.listFrameSessions();
+        }
+      } else {
+        sessionInfo = await this.chromeController.getFrameSessionInfo(args.sessionId);
+        if (!sessionInfo) {
+          availableSessions = await this.chromeController.listFrameSessions();
+        }
+      }
+    } catch (error) {
+      // Fall back to direct database access if HTTP client fails
+      console.warn('[FrameToolHandler] HTTP client failed, falling back to direct access:', error.message);
+      sessionInfo = await this.chromeController.getFrameSessionInfo(args.sessionId);
+      if (!sessionInfo) {
+        availableSessions = await this.chromeController.listFrameSessions();
+      }
+    }
+    
+    if (!sessionInfo) {
+      const recentSessions = availableSessions ? availableSessions.slice(0, 5) : [];
+      
+      let errorMsg = `Frame session not found: ${args.sessionId}\n\n`;
+      if (recentSessions.length > 0) {
+        errorMsg += 'Available frame sessions:\n';
+        recentSessions.forEach(s => {
+          errorMsg += `  - ${s.sessionId} (${s.totalFrames} frames, ${new Date(s.timestamp).toLocaleString()})\n`;
+        });
+        errorMsg += '\nTip: Use list_workflow_recordings to see all available recordings.';
+      } else {
+        errorMsg += 'No frame sessions found in the database.\n';
+        errorMsg += 'Frame recordings may have been created in a different Chrome Debug instance.';
+      }
+      
+      throw new Error(errorMsg);
+    }
+    
+    // Get only frame metadata without image data to avoid token limits
+    const { database } = await import('../../database.js');
+    const recording = database.getRecording(args.sessionId);
+    if (!recording) {
+      throw new Error('Frame session data not found');
+    }
+    
+    // Get frames without image data
+    const framesMetadataStmt = database.db.prepare(`
+      SELECT frame_index, timestamp, absolute_timestamp
+      FROM frames 
+      WHERE recording_id = ? 
+      ORDER BY frame_index ASC
+      LIMIT ?
+    `);
+    const framesToShow = framesMetadataStmt.all(recording.id, maxFrames);
+    
+    const result = {
+      sessionId: args.sessionId,
+      type: recording.type,
+      created: new Date(sessionInfo.timestamp).toLocaleString(),
+      totalFrames: sessionInfo.totalFrames,
+      showingFrames: framesToShow.length,
+      logFilter: logLevel !== 'all' ? logLevel.toUpperCase() : null,
+      frames: []
+    };
+    
+    // Handle case where recording exists but has no frames
+    if (sessionInfo.totalFrames === 0) {
+      result.status = 'Recording exists but contains no frames';
+      
+      // Check for screen interactions
+      try {
+        const interactionsResult = this.useHttpClient ? 
+          await httpClient.getScreenInteractions(args.sessionId) :
+          await this.chromeController.getScreenInteractions(args.sessionId);
+        
+        const interactions = this.useHttpClient ? interactionsResult.interactions : interactionsResult;
+        
+        if (interactions && interactions.length > 0) {
+          result.interactionsFound = interactions.length;
+          result.note = 'This recording has captured user interactions but no frame data. Use get_screen_interactions to view the captured interactions.';
+        } else {
+          result.note = 'No frame data or interactions found. This may indicate the recording was started but stopped immediately.';
+        }
+      } catch (error) {
+        console.warn('[FrameToolHandler] Failed to check interactions:', error.message);
+        result.note = 'No frame data found. Unable to check for interactions.';
+      }
+      
+      return result;
+    }
+    
+    // Get all interactions for this recording if requested
+    let allInteractions = [];
+    if (showInteractions && !this.useHttpClient) {
+      // Only get all interactions if using direct access (for filtering)
+      allInteractions = await this.chromeController.getScreenInteractions(args.sessionId);
+    }
+    
+    // Process each frame
+    for (const frame of framesToShow) {
+      const frameData = {
+        frameIndex: frame.frame_index,
+        timestamp: `${frame.timestamp}ms`,
+        logs: [],
+        interactions: []
+      };
+      
+      // Get logs for this specific frame if requested
+      if (showLogs) {
+        const frameRowStmt = database.db.prepare(`
+          SELECT id FROM frames 
+          WHERE recording_id = ? AND frame_index = ?
+        `);
+        const frameRow = frameRowStmt.get(recording.id, frame.frame_index);
+        
+        if (frameRow) {
+          let logsQuery = `
+            SELECT level, message, relative_time 
+            FROM console_logs 
+            WHERE frame_id = ?`;
+          let queryParams = [frameRow.id];
+          
+          if (logLevel !== 'all') {
+            logsQuery += ` AND level = ?`;
+            queryParams.push(logLevel);
+          }
+          
+          logsQuery += ` ORDER BY relative_time ASC`;
+          
+          if (maxLogsPerFrame > 0) {
+            logsQuery += ` LIMIT ?`;
+            queryParams.push(maxLogsPerFrame);
+          }
+          
+          const logsStmt = database.db.prepare(logsQuery);
+          const logs = logsStmt.all(...queryParams);
+          
+          frameData.logs = logs.map(log => ({
+            level: log.level.toUpperCase(),
+            message: log.message
+          }));
+          
+          if (maxLogsPerFrame > 0 && logs.length === maxLogsPerFrame) {
+            frameData.logsTruncated = true;
+          }
+        }
+      } else {
+        // Count all logs for this frame to show total
+        const frameRowStmt = database.db.prepare(`
+          SELECT id FROM frames 
+          WHERE recording_id = ? AND frame_index = ?
+        `);
+        const frameRow = frameRowStmt.get(recording.id, frame.frame_index);
+        let totalLogCount = 0;
+        
+        if (frameRow) {
+          let countQuery = `SELECT COUNT(*) as count FROM console_logs WHERE frame_id = ?`;
+          let countParams = [frameRow.id];
+          
+          if (logLevel !== 'all') {
+            countQuery += ` AND level = ?`;
+            countParams.push(logLevel);
+          }
+          
+          const countStmt = database.db.prepare(countQuery);
+          totalLogCount = countStmt.get(...countParams).count;
+        }
+        
+        frameData.totalLogs = totalLogCount;
+      }
+      
+      // Show interactions for this frame
+      if (showInteractions) {
+        try {
+          // Get frame details with enhanced interaction data
+          const frameDetails = this.useHttpClient ?
+            await httpClient.getFrame(args.sessionId, frame.frame_index) :
+            await this.chromeController.getFrame(args.sessionId, frame.frame_index);
+
+          if (frameDetails) {
+            // Legacy embedded interactions
+            const embeddedInteractions = frameDetails.interactions || [];
+            // New timestamp-associated interactions
+            const associatedInteractions = frameDetails.associatedInteractions || [];
+
+            frameData.interactions = embeddedInteractions.map(interaction =>
+              this.formatInteraction(interaction)
+            );
+            frameData.associatedInteractions = associatedInteractions.map(interaction =>
+              this.formatInteraction(interaction)
+            );
+            frameData.interactionMetadata = frameDetails.interactionMetadata || {
+              totalFound: 0,
+              displayed: 0,
+              timeWindow: 500
+            };
+          } else {
+            frameData.interactions = [];
+            frameData.associatedInteractions = [];
+            frameData.interactionMetadata = { totalFound: 0, displayed: 0, timeWindow: 500 };
+          }
+        } catch (error) {
+          console.warn('[FrameToolHandler] Failed to get frame interactions:', error.message);
+          frameData.interactions = [];
+          frameData.associatedInteractions = [];
+          frameData.interactionMetadata = { totalFound: 0, displayed: 0, timeWindow: 500 };
+        }
+      }
+      
+      result.frames.push(frameData);
+    }
+    
+    if (sessionInfo.totalFrames > maxFrames) {
+      result.hasMoreFrames = true;
+      result.remainingFrames = sessionInfo.totalFrames - maxFrames;
+      result.note = 'Use get_frame with frameIndex to view specific frames';
+    }
+    
+    return result;
+  }
+
+  /**
+   * Handle get_frame_session_info tool
+   * @param {Object} args - Arguments with sessionId
+   * @returns {Object} Session info
+   */
+  async handleGetFrameSessionInfo(args) {
+    if (!args.sessionId) {
+      throw new Error('Session ID is required');
+    }
+    
+    let info, availableSessions;
+    
+    try {
+      if (this.useHttpClient) {
+        info = await httpClient.getFrameSessionInfo(args.sessionId);
+        if (!info) {
+          availableSessions = await httpClient.listFrameSessions();
+        }
+      } else {
+        info = await this.chromeController.getFrameSessionInfo(args.sessionId);
+        if (!info) {
+          availableSessions = await this.chromeController.listFrameSessions();
+        }
+      }
+    } catch (error) {
+      console.warn('[FrameToolHandler] HTTP client failed, falling back to direct access:', error.message);
+      info = await this.chromeController.getFrameSessionInfo(args.sessionId);
+      if (!info) {
+        availableSessions = await this.chromeController.listFrameSessions();
+      }
+    }
+    
+    if (!info) {
+      const recentSessions = availableSessions ? availableSessions.slice(0, 5) : [];
+      
+      let errorMsg = `Frame session not found: ${args.sessionId}\n\n`;
+      if (recentSessions.length > 0) {
+        errorMsg += 'Available frame sessions:\n';
+        recentSessions.forEach(s => {
+          errorMsg += `  - ${s.sessionId} (${s.totalFrames} frames, ${new Date(s.timestamp).toLocaleString()})\n`;
+        });
+        errorMsg += '\nTip: Frame recordings are stored in the local database and may not persist across different Chrome Debug instances.';
+      } else {
+        errorMsg += 'No frame sessions found in the database.\n';
+        errorMsg += 'Frame recordings may have been created in a different Chrome Debug instance or the database may have been reset.';
+      }
+      
+      throw new Error(errorMsg);
+    }
+    
+    // Get interaction summary for this session
+    let interactionSummary = {
+      totalInteractions: 0,
+      interactionTypes: [],
+      embeddedInteractions: 0,
+      timestampAssociated: 0
+    };
+
+    try {
+      if (this.useHttpClient) {
+        const interactionsResult = await httpClient.getScreenInteractions(args.sessionId);
+        const interactions = interactionsResult.interactions || [];
+        interactionSummary.totalInteractions = interactions.length;
+
+        // Count interaction types
+        const typeCount = {};
+        interactions.forEach(interaction => {
+          typeCount[interaction.type] = (typeCount[interaction.type] || 0) + 1;
+        });
+        interactionSummary.interactionTypes = Object.entries(typeCount).map(([type, count]) => `${type}: ${count}`);
+      } else {
+        const interactions = await this.chromeController.getScreenInteractions(args.sessionId);
+        interactionSummary.totalInteractions = interactions.length;
+
+        // Count interaction types
+        const typeCount = {};
+        interactions.forEach(interaction => {
+          typeCount[interaction.type] = (typeCount[interaction.type] || 0) + 1;
+        });
+        interactionSummary.interactionTypes = Object.entries(typeCount).map(([type, count]) => `${type}: ${count}`);
+      }
+    } catch (error) {
+      console.warn('[FrameToolHandler] Failed to get interaction summary:', error.message);
+      // Keep default empty summary
+    }
+
+    return {
+      sessionId: args.sessionId,
+      totalFrames: info.totalFrames,
+      created: new Date(info.timestamp).toISOString(),
+      frameTimestamps: info.frameTimestamps ?
+        info.frameTimestamps.slice(0, 5).join(', ') + (info.frameTimestamps.length > 5 ? '...' : '') :
+        'N/A',
+      interactionSummary: interactionSummary
+    };
+  }
+
+  /**
+   * Handle get_frame tool
+   * @param {Object} args - Arguments with sessionId, frameIndex, and filter options
+   * @returns {Object} Frame data
+   */
+  async handleGetFrame(args) {
+    if (!args.sessionId || args.frameIndex === undefined) {
+      throw new Error('Session ID and frame index are required');
+    }
+    
+    const logLevel = args.logLevel || 'all';
+    const maxLogs = args.maxLogs || 20;
+    const searchLogs = args.searchLogs;
+    
+    let frame;
+    
+    try {
+      if (this.useHttpClient) {
+        frame = await httpClient.getFrame(args.sessionId, args.frameIndex);
+      } else {
+        frame = await this.chromeController.getFrame(args.sessionId, args.frameIndex);
+      }
+    } catch (error) {
+      console.warn('[FrameToolHandler] HTTP client failed, falling back to direct access:', error.message);
+      frame = await this.chromeController.getFrame(args.sessionId, args.frameIndex);
+    }
+    
+    if (!frame) {
+      throw new Error('Frame not found');
+    }
+    
+    // Apply filtering to logs
+    let filteredLogs = frame.logs || [];
+    
+    // Filter by log level
+    if (logLevel !== 'all') {
+      filteredLogs = filteredLogs.filter(log => log.level === logLevel);
+    }
+    
+    // Filter by search text
+    if (searchLogs) {
+      const searchText = searchLogs.toLowerCase();
+      filteredLogs = filteredLogs.filter(log => 
+        log.message.toLowerCase().includes(searchText)
+      );
+    }
+    
+    // Limit the number of logs
+    const totalMatchingLogs = filteredLogs.length;
+    if (maxLogs > 0 && filteredLogs.length > maxLogs) {
+      filteredLogs = filteredLogs.slice(0, maxLogs);
+    }
+    
+    const result = {
+      frameIndex: args.frameIndex,
+      sessionId: args.sessionId,
+      timestamp: `${frame.timestamp}ms`,
+      imageSize: frame.imageData ? `${Math.round(frame.imageData.length / 1024)}KB` : 'N/A',
+      totalLogs: frame.logs ? frame.logs.length : 0,
+      filteredLogs: totalMatchingLogs,
+      showingLogs: filteredLogs.length,
+      logs: filteredLogs.map(log => ({
+        level: log.level.toUpperCase(),
+        message: log.message
+      })),
+      hasImageData: !!frame.imageData
+    };
+
+    if (logLevel !== 'all' || searchLogs) {
+      result.filters = {};
+      if (searchLogs) result.filters.searchText = searchLogs;
+      if (logLevel !== 'all') result.filters.logLevel = logLevel.toUpperCase();
+    }
+
+    if (totalMatchingLogs > 500) {
+      result.warning = `This frame has ${totalMatchingLogs} matching logs! Showing only first ${filteredLogs.length} to prevent output overflow.`;
+      result.recommendation = 'For better navigation, use: get_frame_logs_paginated';
+    }
+
+    if (filteredLogs.length < totalMatchingLogs) {
+      result.hasMoreLogs = true;
+      result.remainingLogs = totalMatchingLogs - filteredLogs.length;
+      if (totalMatchingLogs > 100) {
+        result.tip = 'Use get_frame_logs_paginated for better navigation with large log volumes';
+      } else {
+        result.tip = 'Use maxLogs=0 to see all, or search_frame_logs for cross-frame search';
+      }
+    }
+
+    // Show legacy embedded interactions for backward compatibility
+    if (frame.interactions && frame.interactions.length > 0) {
+      result.interactions = frame.interactions.map(interaction =>
+        this.formatInteraction(interaction)
+      );
+    }
+
+    // Show new timestamp-associated interactions
+    if (frame.associatedInteractions && frame.associatedInteractions.length > 0) {
+      result.associatedInteractions = frame.associatedInteractions.map(interaction =>
+        this.formatInteraction(interaction)
+      );
+    }
+
+    // Include interaction metadata
+    if (frame.interactionMetadata) {
+      result.interactionMetadata = frame.interactionMetadata;
+    }
+
+    return result;
+  }
+
+  /**
+   * Handle search_frame_logs tool
+   * @param {Object} args - Arguments with sessionId, searchText, and filters
+   * @returns {Object} Search results
+   */
+  async handleSearchFrameLogs(args) {
+    if (!args.sessionId || !args.searchText) {
+      throw new Error('Session ID and search text are required');
+    }
+    
+    const logLevel = args.logLevel || 'all';
+    const maxResults = args.maxResults || 50;
+    
+    let results;
+    
+    try {
+      if (this.useHttpClient) {
+        results = await httpClient.searchFrameLogs(args.sessionId, args.searchText, logLevel, maxResults);
+      } else {
+        results = await this.chromeController.searchFrameLogs(args.sessionId, args.searchText, logLevel, maxResults);
+      }
+    } catch (error) {
+      console.warn('[FrameToolHandler] HTTP client failed, falling back to direct access:', error.message);
+      results = await this.chromeController.searchFrameLogs(args.sessionId, args.searchText, logLevel, maxResults);
+    }
+    
+    return {
+      sessionId: args.sessionId,
+      searchText: args.searchText,
+      logLevel: logLevel !== 'all' ? logLevel.toUpperCase() : 'ALL',
+      maxResults: maxResults,
+      foundResults: results.length,
+      results: results.map(result => ({
+        frameIndex: result.frameIndex,
+        level: result.level.toUpperCase(),
+        message: result.message,
+        timestamp: result.timestamp
+      }))
+    };
+  }
+
+  /**
+   * Handle get_frame_logs_paginated tool
+   * @param {Object} args - Arguments with sessionId, frameIndex, pagination, and filters
+   * @returns {Object} Paginated logs
+   */
+  async handleGetFrameLogsPaginated(args) {
+    if (!args.sessionId || args.frameIndex === undefined) {
+      throw new Error('Session ID and frame index are required');
+    }
+    
+    const offset = args.offset || 0;
+    const limit = args.limit || 100;
+    const logLevel = args.logLevel || 'all';
+    const searchText = args.searchText;
+    
+    let results;
+    
+    try {
+      if (this.useHttpClient) {
+        results = await httpClient.getFrameLogsPaginated(args.sessionId, args.frameIndex, offset, limit, logLevel, searchText);
+      } else {
+        results = await this.chromeController.getFrameLogsPaginated(args.sessionId, args.frameIndex, offset, limit, logLevel, searchText);
+      }
+    } catch (error) {
+      console.warn('[FrameToolHandler] HTTP client failed, falling back to direct access:', error.message);
+      results = await this.chromeController.getFrameLogsPaginated(args.sessionId, args.frameIndex, offset, limit, logLevel, searchText);
+    }
+    
+    return {
+      sessionId: args.sessionId,
+      frameIndex: args.frameIndex,
+      offset: offset,
+      limit: limit,
+      logLevel: logLevel !== 'all' ? logLevel.toUpperCase() : 'ALL',
+      searchText: searchText || null,
+      totalLogs: results.total,
+      returnedLogs: results.logs.length,
+      hasMore: offset + results.logs.length < results.total,
+      logs: results.logs.map(log => ({
+        level: log.level.toUpperCase(),
+        message: log.message,
+        relativeTime: log.relative_time
+      }))
+    };
+  }
+
+  /**
+   * Handle get_frame_screenshot tool
+   * @param {Object} args - Arguments with sessionId, frameIndex, and includeMetadata
+   * @returns {Object} Frame screenshot data
+   */
+  async handleGetFrameScreenshot(args) {
+    if (!args.sessionId || args.frameIndex === undefined) {
+      throw new Error('Session ID and frame index are required');
+    }
+    
+    const includeMetadata = args.includeMetadata || false;
+    
+    try {
+      // Get frame data directly from database to access image_data
+      const { database } = await import('../../database.js');
+      const recording = database.getRecording(args.sessionId);
+      
+      if (!recording) {
+        throw new Error(`Frame session not found: ${args.sessionId}`);
+      }
+      
+      // Get the specific frame with image data
+      const frameStmt = database.db.prepare(`
+        SELECT frame_index, timestamp, absolute_timestamp, image_data
+        FROM frames 
+        WHERE recording_id = ? AND frame_index = ?
+      `);
+      const frame = frameStmt.get(recording.id, args.frameIndex);
+      
+      if (!frame) {
+        // Get total frames to provide helpful error
+        const countStmt = database.db.prepare(`SELECT COUNT(*) as count FROM frames WHERE recording_id = ?`);
+        const totalFrames = countStmt.get(recording.id).count;
+        throw new Error(`Frame ${args.frameIndex} not found in session ${args.sessionId}. Available frames: 0-${totalFrames - 1}`);
+      }
+      
+      if (!frame.image_data) {
+        throw new Error(`No screenshot data available for frame ${args.frameIndex} in session ${args.sessionId}`);
+      }
+      
+      const result = {
+        sessionId: args.sessionId,
+        frameIndex: args.frameIndex,
+        timestamp: `${frame.timestamp}ms`,
+        absoluteTimestamp: frame.absolute_timestamp,
+        imageData: frame.image_data, // Base64 encoded image data
+        imageFormat: 'jpeg', // Chrome Debug stores as JPEG by default
+        hasImageData: true
+      };
+      
+      if (includeMetadata) {
+        // Calculate approximate image size
+        const imageSize = Math.round((frame.image_data.length * 3) / 4); // Base64 to bytes conversion
+        result.metadata = {
+          imageSizeBytes: imageSize,
+          imageSizeFormatted: imageSize > 1024 ? `${Math.round(imageSize / 1024)}KB` : `${imageSize}B`,
+          encoding: 'base64',
+          captureTime: new Date(frame.absolute_timestamp).toISOString()
+        };
+      }
+      
+      return result;
+      
+    } catch (error) {
+      if (error.message.includes('not found') || error.message.includes('No screenshot data')) {
+        throw error;
+      }
+      
+      // For other errors, provide more context
+      throw new Error(`Failed to retrieve screenshot for frame ${args.frameIndex}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Handle get_screen_interactions tool
+   * @param {Object} args - Arguments with sessionId and filters
+   * @returns {Object} Screen interactions
+   */
+  async handleGetScreenInteractions(args) {
+    if (!args.sessionId) {
+      throw new Error('Session ID is required');
+    }
+    
+    let interactions;
+    
+    try {
+      if (this.useHttpClient) {
+        const result = await httpClient.getScreenInteractions(args.sessionId, args.frameIndex, args.type);
+        interactions = result.interactions || [];
+      } else {
+        if (args.frameIndex !== undefined) {
+          // Get interactions for specific frame
+          interactions = await this.chromeController.getFrameInteractions(args.sessionId, args.frameIndex);
+        } else {
+          // Get all interactions for the recording
+          interactions = await this.chromeController.getScreenInteractions(args.sessionId);
+        }
+      }
+    } catch (error) {
+      console.warn('[FrameToolHandler] HTTP client failed, falling back to direct access:', error.message);
+      if (args.frameIndex !== undefined) {
+        interactions = await this.chromeController.getFrameInteractions(args.sessionId, args.frameIndex);
+      } else {
+        interactions = await this.chromeController.getScreenInteractions(args.sessionId);
+      }
+    }
+    
+    // Filter by type if requested
+    if (args.type) {
+      interactions = interactions.filter(i => i.type === args.type);
+    }
+    
+    if (interactions.length === 0) {
+      return {
+        sessionId: args.sessionId,
+        frameIndex: args.frameIndex,
+        type: args.type || null,
+        message: `No interactions found for session ${args.sessionId}${args.frameIndex !== undefined ? ` frame ${args.frameIndex}` : ''}${args.type ? ` of type '${args.type}'` : ''}.`,
+        interactions: []
+      };
+    }
+    
+    return {
+      sessionId: args.sessionId,
+      frameIndex: args.frameIndex,
+      type: args.type || null,
+      totalInteractions: interactions.length,
+      interactions: interactions.map((interaction, index) => ({
+        index: index + 1,
+        ...this.formatInteraction(interaction),
+        timestamp: new Date(interaction.timestamp).toISOString()
+      }))
+    };
+  }
+
+  /**
+   * Format interaction data for consistent output
+   * @param {Object} interaction - Raw interaction data
+   * @returns {Object} Formatted interaction
+   */
+  formatInteraction(interaction) {
+    const formatted = {
+      type: interaction.type.toUpperCase(),
+      frameIndex: interaction.frame_index !== null ? interaction.frame_index : null
+    };
+
+    switch (interaction.type) {
+      case 'click':
+        formatted.target = interaction.selector || `at (${interaction.x}, ${interaction.y})`;
+        if (interaction.text) formatted.text = interaction.text;
+        if (interaction.xpath) formatted.xpath = interaction.xpath;
+        break;
+      case 'input':
+        formatted.selector = interaction.selector;
+        formatted.value = interaction.value;
+        if (interaction.placeholder) formatted.placeholder = interaction.placeholder;
+        break;
+      case 'keypress':
+        formatted.key = interaction.key;
+        break;
+      case 'scroll':
+        formatted.position = {
+          x: interaction.scrollX || interaction.x,
+          y: interaction.scrollY || interaction.y
+        };
+        break;
+      default:
+        // Include any additional properties for unknown types
+        Object.keys(interaction).forEach(key => {
+          if (!['type', 'frame_index', 'timestamp'].includes(key)) {
+            formatted[key] = interaction[key];
+          }
+        });
+    }
+
+    return formatted;
+  }
+
+  /*
+   * SNAPSHOT FEATURE DISABLED (2025-10-01)
+   *
+   * Snapshot handler methods disabled - see SNAPSHOT_FEATURE_DISABLED.md
+   *
+   * WHY DISABLED:
+   * - Snapshots without console logs are just screenshots (users can do this natively)
+   * - Console log capture requires always-on monitoring (privacy concern)
+   * - Core value proposition (screenshot + searchable logs) cannot be achieved cleanly
+   *
+   * TO RE-ENABLE:
+   * 1. Implement privacy-conscious always-on log monitoring
+   * 2. Uncomment these methods
+   * 3. Re-enable MCP tool definitions in tools/index.js
+   * 4. Re-enable case handlers above
+   *
+   * Handle take_snapshot tool - creates a new snapshot
+   * @param {Object} args - Tool arguments
+   * @returns {Object} Snapshot creation result
+   */
+  /*
+  async handleTakeSnapshot(args) {
+    try {
+      // Take screenshot and get current logs
+      const screenshot = await this.chromeController.takeScreenshot(true, true, 30);
+      const logs = await this.chromeController.getLogs();
+
+      // Generate unique session ID for the snapshot
+      const sessionId = `snapshot_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+      // Create frame data structure
+      const frameData = {
+        timestamp: Date.now(),
+        absoluteTimestamp: Date.now(),
+        imageData: screenshot.imageData,
+        logs: logs.logs || [],
+        frameIndex: 0,
+        index: 0
+      };
+
+      // Store snapshot via database
+      const result = await this.chromeController.database.storeSnapshot(sessionId, frameData, args.userNote);
+
+      return {
+        success: true,
+        sessionId: result,
+        timestamp: frameData.timestamp,
+        userNote: args.userNote || null,
+        logCount: frameData.logs.length,
+        message: `Snapshot created successfully with ID: ${result}`
+      };
+    } catch (error) {
+      console.error('Error taking snapshot:', error);
+      throw new Error(`Failed to take snapshot: ${error.message}`);
+    }
+  }
+
+  // Handle list_snapshots tool - lists all snapshots
+  // @param {Object} args - Tool arguments
+  // @returns {Object} List of snapshots
+  async handleListSnapshots(args) {
+    try {
+      const limit = args.limit || 50;
+      const snapshots = await this.chromeController.database.getSnapshots(limit);
+
+      return {
+        success: true,
+        snapshots: snapshots.map(snapshot => ({
+          sessionId: snapshot.id,
+          timestamp: snapshot.timestamp,
+          userNote: snapshot.user_note,
+          frameCount: snapshot.frame_count,
+          createdAt: snapshot.created_at,
+          recordingType: snapshot.recording_type
+        })),
+        total: snapshots.length,
+        limit: limit
+      };
+    } catch (error) {
+      console.error('Error listing snapshots:', error);
+      throw new Error(`Failed to list snapshots: ${error.message}`);
+    }
+  }
+
+  // Handle get_snapshot tool - gets a specific snapshot
+  // @param {Object} args - Tool arguments
+  // @returns {Object} Snapshot data
+  async handleGetSnapshot(args) {
+    try {
+      const { sessionId, includeMetadata = true } = args;
+
+      // Get the snapshot session (reuse existing frame session logic)
+      const snapshot = await this.chromeController.getFrameSession(sessionId);
+
+      if (!snapshot) {
+        throw new Error(`Snapshot not found: ${sessionId}`);
+      }
+
+      const result = {
+        sessionId: sessionId,
+        snapshot: {
+          timestamp: snapshot.timestamp,
+          userNote: snapshot.userNote,
+          frame: snapshot.frames?.[0] || null,
+          logCount: snapshot.frames?.[0]?.logs?.length || 0
+        }
+      };
+
+      if (includeMetadata) {
+        result.metadata = {
+          recordingType: 'snapshot',
+          frameCount: snapshot.frames?.length || 0,
+          createdAt: snapshot.created_at,
+          updatedAt: snapshot.updated_at
+        };
+      }
+
+      return result;
+    } catch (error) {
+      console.error('Error getting snapshot:', error);
+      throw new Error(`Failed to get snapshot: ${error.message}`);
+    }
+  }
+
+  // Handle search_snapshot_logs tool - searches logs within snapshots
+  // @param {Object} args - Tool arguments
+  // @returns {Object} Search results
+  async handleSearchSnapshotLogs(args) {
+    try {
+      const { query, level, limit = 50 } = args;
+
+      // Get all snapshots first
+      const snapshots = await this.chromeController.database.getSnapshots(100);
+
+      const results = [];
+
+      for (const snapshot of snapshots) {
+        try {
+          const sessionData = await this.chromeController.getFrameSession(snapshot.id);
+          if (sessionData?.frames?.[0]?.logs) {
+            const logs = sessionData.frames[0].logs;
+
+            // Filter logs by query and level
+            const matchingLogs = logs.filter(log => {
+              const queryMatch = log.message.toLowerCase().includes(query.toLowerCase());
+              const levelMatch = !level || log.level === level;
+              return queryMatch && levelMatch;
+            });
+
+            if (matchingLogs.length > 0) {
+              results.push({
+                sessionId: snapshot.id,
+                userNote: snapshot.user_note,
+                timestamp: snapshot.timestamp,
+                matchingLogs: matchingLogs.slice(0, limit)
+              });
+            }
+          }
+        } catch (error) {
+          console.warn(`Error processing snapshot ${snapshot.id}:`, error.message);
+        }
+      }
+
+      return {
+        success: true,
+        query: query,
+        level: level || 'all',
+        totalSnapshots: snapshots.length,
+        snapshotsWithMatches: results.length,
+        results: results.slice(0, limit)
+      };
+    } catch (error) {
+      console.error('Error searching snapshot logs:', error);
+      throw new Error(`Failed to search snapshot logs: ${error.message}`);
+    }
+  }
+  */
+}