get_browser_history

Instructions

Args:
    time_period_in_days: Number of days of history to retrieve (default: 7)
    browser_type: Browser type ('firefox', 'chrome', 'safari', or None for auto-detect)
    all_browsers: If True, get history from all available browsers (default: True)

Returns:
    Either a list of history entries or a dictionary with partial results and browser status

Implementation Reference

• server/main.py:40-52 (registration)

  Registers the 'get_browser_history' tool using @mcp.tool() decorator. Defines input schema via type hints and comprehensive docstring describing parameters and return types.

  @mcp.tool()
  async def get_browser_history(time_period_in_days: int = 7, browser_type: Optional[str] = None, all_browsers: bool = True) -> Union[List[HistoryEntryDict], Dict[str, Any]]:
      """Step 2: Get raw browser history data without analysis. This is the fastest way to retrieve browser history and should be used before any analysis.
      
      Args:
          time_period_in_days: Number of days of history to retrieve (default: 7)
          browser_type: Browser type ('firefox', 'chrome', 'safari', or None for auto-detect)
          all_browsers: If True, get history from all available browsers (default: True)
      
      Returns:
          Either a list of history entries or a dictionary with partial results and browser status
      """
      return await tool_get_browser_history(time_period_in_days, CACHED_HISTORY, browser_type, all_browsers)

• server/browser_utils.py:493-636 (handler)

  Core implementation of browser history retrieval. Detects available browsers (Firefox, Chrome, Safari), queries their SQLite databases for recent history, handles locked databases and errors, supports multi-browser aggregation and single-browser modes, returns structured results or errors with user guidance.

  async def tool_get_browser_history(time_period_in_days: int, CACHED_HISTORY: CachedHistory, browser_type: Optional[str] = None, all_browsers: bool = True) -> Union[List[HistoryEntryDict], BrowserHistoryResult]:
  
      start_time = time.time()
      print(f"🚀 Starting browser history retrieval for {time_period_in_days} days...")
  
      if time_period_in_days <= 0:
          raise ValueError("time_period_in_days must be a positive integer")
      
      # Map browser types to their handler functions
      browser_handlers = {
          "firefox": get_firefox_history,
          "chrome": get_chrome_history,
          "safari": get_safari_history
      }
      
      if all_browsers:
          # Step 1: Detect available browsers
          step_start = time.time()
          print("📊 Step 1: Detecting available browsers...")
          browser_status = tool_detect_available_browsers()
          detect_time = time.time() - step_start
          print(f"📊 Browser detection completed in {detect_time:.3f}s")
          
          if browser_status.get("status") == "error":
              print(f"❌ {browser_status['error_message']}")
              raise RuntimeError(browser_status['error_message'])
          elif browser_status.get("status") == "browser_locked":
              print(f"❌ {browser_status['error_message']}")
              raise RuntimeError(browser_status['error_message'])
          
          available_browsers = browser_status.get('available_browsers', [])
          if not available_browsers:
              print("❌ No available browsers found")
              raise RuntimeError("No browser history databases found. Please ensure Firefox, Chrome, or Safari is installed and try again.")
          
          print(f"📊 Available browsers: {available_browsers}")
          
          # Step 2: Get history from each browser
          all_entries = []
          successful_browsers = []
          failed_browsers = []
          failure_reasons = {}
          
          for browser in available_browsers:
              browser_start = time.time()
              print(f"📊 Step 2.{len(successful_browsers) + len(failed_browsers) + 1}: Getting {browser} history...")
              
              try:
                  entries = browser_handlers[browser](time_period_in_days)
                  browser_time = time.time() - browser_start
                  print(f"📊 {browser} history retrieved in {browser_time:.3f}s: {len(entries)} entries")
                  
                  logger.warning(f"Retrieved {len(entries)} {browser} history entries from last {time_period_in_days} days")
                  all_entries.extend([entry.to_dict() for entry in entries])
                  successful_browsers.append(browser)
              except Exception as e:
                  browser_time = time.time() - browser_start
                  error_msg = str(e)
                  print(f"❌ {browser} history failed in {browser_time:.3f}s: {error_msg}")
                  
                  logger.warning(f"Failed to get {browser} history: {error_msg}. If the database is locked, please try closing the browser and running the tool again.")
                  failed_browsers.append(browser)
                  failure_reasons[browser] = error_msg
                  continue
          
          total_time = time.time() - start_time
          print(f"📊 Total browser history retrieval time: {total_time:.3f}s")
          
          # If we have any successful browsers, return partial results
          if successful_browsers:
              recommendation = ""
              if failed_browsers:
                  locked_browsers = [browser for browser in failed_browsers if "database is locked" in failure_reasons.get(browser, "").lower()]
                  if locked_browsers:
                      recommendation = f"🔒 BROWSER LOCKED: {', '.join([b.title() for b in locked_browsers])} {'is' if len(locked_browsers) == 1 else 'are'} currently running. Please close {'this browser' if len(locked_browsers) == 1 else 'these browsers'} completely to get complete history analysis. You can restore tabs with Ctrl+Shift+T (Cmd+Shift+T on Mac). "
                  recommendation += f"Successfully retrieved {len(all_entries)} entries from {', '.join([b.title() for b in successful_browsers])}."
              else:
                  recommendation = f"✅ Successfully retrieved {len(all_entries)} entries from all browsers: {', '.join([b.title() for b in successful_browsers])}."
              
              logger.warning(f"Retrieved total of {len(all_entries)} history entries from {len(successful_browsers)} browsers")
              
              return {
                  "history_entries": all_entries,
                  "successful_browsers": successful_browsers,
                  "failed_browsers": failed_browsers,
                  "failure_reasons": failure_reasons,
                  "total_entries": len(all_entries),
                  "status": "partial_success" if failed_browsers else "success",
                  "user_action_required": bool(failed_browsers),
                  "recommendation": recommendation
              }
          
          # If no browsers succeeded, raise error with detailed information
          locked_browsers = [browser for browser in failed_browsers if "database is locked" in failure_reasons.get(browser, "").lower()]
          if locked_browsers:
              error_message = f"🔒 BROWSER LOCKED: All browsers ({', '.join([b.title() for b in locked_browsers])}) are currently running and their databases are locked. Please close ALL browsers completely to analyze history. You can restore tabs with Ctrl+Shift+T (Cmd+Shift+T on Mac)."
          else:
              error_details = "; ".join([f"{browser}: {reason}" for browser, reason in failure_reasons.items()])
              error_message = f"❌ ERROR: Failed to retrieve history from any browser: {error_details}"
          
          raise RuntimeError(error_message)
      
      else:
          # Single browser mode (original behavior)
          if browser_type is None:
              browser_status = tool_detect_available_browsers()
              if browser_status.get("status") == "error":
                  raise RuntimeError(browser_status['error_message'])
              elif browser_status.get("status") == "browser_locked":
                  raise RuntimeError(browser_status['error_message'])
              
              # Get the first available browser from the available_browsers list
              available_browsers = browser_status.get('available_browsers', [])
              browser_type = available_browsers[0] if available_browsers else None
                  
              if browser_type is None:
                  raise RuntimeError("No browser history databases found. Please ensure Firefox, Chrome, or Safari is installed and try again.")
                  
              logger.warning(f"Auto-detected active browser: {browser_type}")
          
          if browser_type not in browser_handlers:
              raise ValueError(f"Unsupported browser type: {browser_type}. Supported types: {list(browser_handlers.keys())}")
          
          try:
              entries = browser_handlers[browser_type](time_period_in_days)
              logger.warning(f"Retrieved {len(entries)} {browser_type} history entries from last {time_period_in_days} days")
  
              # Ensure we are always working with dictionaries
              entries_dict = [ensure_history_entry_dict(e) for e in entries]
  
              # Cache the history for later use
              CACHED_HISTORY.add_history(entries_dict, time_period_in_days, browser_type)
  
              return entries_dict
          except sqlite3.Error as e:
              logger.error(f"Error querying {browser_type} history: {e}")
              if "database is locked" in str(e).lower():
                  raise RuntimeError(f"🔒 BROWSER LOCKED: {browser_type.title()} is currently running and its database is locked. Please close {browser_type.title()} completely to analyze its history. You can restore tabs with Ctrl+Shift+T (Cmd+Shift+T on Mac).")
              else:
                  raise RuntimeError(f"❌ ERROR: Failed to query {browser_type.title()} history: {e}")
          except Exception as e:
              logger.error(f"Unexpected error querying {browser_type} history: {e}")
              raise RuntimeError(f"❌ ERROR: Failed to query {browser_type.title()} history: {e}")

• server/browser_utils.py:409-487 (helper)

  Helper utility to detect available browsers and their history database accessibility. Critical for the main handler to determine which browsers to query and detect locked/running browsers.

  def tool_detect_available_browsers() -> Dict[str, Any]:
      browsers_to_check = []
      
      # Check Firefox
      if PATH_TO_FIREFOX_HISTORY:
          browsers_to_check.append(('firefox', PATH_TO_FIREFOX_HISTORY))
      
      # Check Chrome
      if PATH_TO_CHROME_HISTORY:
          browsers_to_check.append(('chrome', PATH_TO_CHROME_HISTORY))
      
      # Check Safari
      if PATH_TO_SAFARI_HISTORY:
          browsers_to_check.append(('safari', PATH_TO_SAFARI_HISTORY))
      
      if not browsers_to_check:
          logger.warning("No browser history databases found")
          return {
              "available_browsers": [],
              "active_browsers": [],
              "status": "error",
              "error_message": "No browser history databases found. Please ensure Firefox, Chrome, or Safari is installed.",
              "user_action_required": False,
              "recommended_action": "Install Firefox, Chrome, or Safari to use this tool"
          }
      
      browsers_in_use = []
      for browser_name, db_path in browsers_to_check:
          logger.warning(f"Checking {browser_name} database at {db_path}")
          try:
              # Try to connect with read-only mode
              conn = sqlite3.connect(f"file:{db_path}?mode=ro", uri=True)
              
              # Test if we can actually query the database
              cursor = conn.cursor()
              cursor.execute("SELECT COUNT(*) FROM sqlite_master WHERE type='table';")
              table_count = cursor.fetchone()[0]
              conn.close()
              
              logger.warning(f"Successfully connected to {browser_name} database and queried {table_count} tables. Browser may still be running, encourage the user to close this browser to make history available.")
          except sqlite3.OperationalError as e:
              if "database is locked" in str(e).lower():
                  logger.warning(f"Database locked for {browser_name} - browser is likely open and active - prompt the user to close it to get complete history.")
                  # Short-circuit: return immediately if any browser is locked
                  return {
                      "available_browsers": [browser[0] for browser in browsers_to_check],
                      "active_browsers": [browser_name],
                      "status": "browser_locked",
                      "error_message": f"🔒 BROWSER LOCKED: {browser_name.title()} is currently running and its database is locked.",
                      "user_action_required": True,
                      "recommended_action": f"❗ IMPORTANT: Please close all browsers, especially {browser_name.title()} completely to analyze its history. You can restore your tabs later with Ctrl+Shift+T (Cmd+Shift+T on Mac).",
                      "technical_details": f"Database error: {str(e)}"
                  }
              else:
                  logger.warning(f"Error connecting to {browser_name} database: {e} - please inform the user that this browser is not available for analysis.")
          except Exception as e:
              logger.warning(f"Unexpected error connecting to {browser_name} database: {e}")
              # Short-circuit: return immediately if any browser has an error
              return {
                  "available_browsers": [browser[0] for browser in browsers_to_check],
                  "active_browsers": [browser_name],
                  "status": "error",
                  "error_message": f"❌ ERROR: Cannot access {browser_name.title()} database.",
                  "user_action_required": True,
                  "recommended_action": f"Please close all browsers, especially {browser_name.title()} completely and try again. You can restore your tabs later with Ctrl+Shift+T (Cmd+Shift+T on Mac).",
                  "technical_details": f"Technical error: {str(e)}"
              }
      
      # If we get here, no browsers are locked
      available_browsers = [browser[0] for browser in browsers_to_check]
      logger.warning(f"No active browser detected, available browsers: {available_browsers}")
      return {
          "available_browsers": available_browsers,
          "active_browsers": [],
          "status": "ready",
          "error_message": None,
          "user_action_required": False,
          "recommended_action": f"✅ All browsers are available for analysis. Found: {', '.join(available_browsers)}"
      }

• server/browser_utils.py:58-111 (helper)

  Firefox-specific history extractor: connects to places.sqlite, queries moz_places table, converts timestamps, filters irrelevant entries.

  def get_firefox_history(days: int) -> List[HistoryEntry]:
      """Get Firefox history from the last N days"""
      firefox_start = time.time()
      print(f"📊 Firefox: Starting history retrieval for {days} days...")
      
      # Check if database exists
      if not os.path.exists(PATH_TO_FIREFOX_HISTORY):
          raise RuntimeError(f"Firefox history not found at {PATH_TO_FIREFOX_HISTORY}")
      
      # Connect to the database
      print(f"📊 Firefox: Connecting to database...")
      conn = sqlite3.connect(f"file:{PATH_TO_FIREFOX_HISTORY}?mode=ro", uri=True)
      try:
          cursor = conn.cursor()
          
          # Firefox stores timestamps as microseconds since Unix epoch
          cutoff_time = (datetime.now() - timedelta(days=days)).timestamp() * 1_000_000
          
          query = """
          SELECT DISTINCT h.url, h.title, h.visit_count, h.last_visit_date
          FROM moz_places h
          WHERE h.last_visit_date > ? 
          AND h.hidden = 0
          AND h.url NOT LIKE 'moz-extension://%'
          ORDER BY h.last_visit_date DESC
          """
          
          cursor.execute(query, (cutoff_time,))
          results = cursor.fetchall()
          
          entries = []
          for url, title, visit_count, last_visit_date in results:
              # Convert Firefox timestamp (microseconds) to datetime
              visit_time = datetime.fromtimestamp(last_visit_date / 1_000_000)
              
              entries.append(HistoryEntry(
                  url=url or "",
                  title=title,
                  visit_count=visit_count or 0,
                  last_visit_time=visit_time
              ))
          
          firefox_time = time.time() - firefox_start
          print(f"📊 Firefox: History retrieval completed in {firefox_time:.3f}s: {len(entries)} entries")
          return entries
      except Exception as e:
          firefox_time = time.time() - firefox_start
          print(f"❌ Firefox: History retrieval failed in {firefox_time:.3f}s: {e}")
          logger.error(f"Error querying Firefox history: {e}")
          raise RuntimeError(f"Failed to query Firefox history: {e}")
      finally:
          if conn:
              conn.close()