Search History MCP Server

Instructions

Implementation Reference

• mcp_server.py:737-865 (handler)

  The @mcp.tool decorator registers the tool, and the function implements the logic to retrieve the most frequently visited sites from the browser's history database. It handles different browsers (Brave, Safari, Chrome, Firefox, Edge, Arc, Opera, DuckDuckGo) with specific SQL queries, decryption for DuckDuckGo on macOS, timestamp conversions, and formats the output.

  @mcp.tool
  def get_most_visited(limit: int = 20, browser: Literal["brave", "safari", "chrome", "firefox", "edge", "arc", "opera", "duckduckgo"] = "brave") -> str:
      """
      Get the most frequently visited sites from browser history.
  
      Args:
          limit: Maximum number of results to return (default: 20, max: 100)
          browser: Which browser to query ("brave", "safari", "chrome", "firefox", "edge", "arc", "opera", or "duckduckgo")
  
      Returns:
          Formatted list of most visited sites with visit counts
      """
      if limit > 100:
          limit = 100
  
      if browser == "duckduckgo":
          if is_duckduckgo_encrypted():
              # DuckDuckGo macOS - encrypted database schema
              query = """
                  SELECT
                      ZURLENCRYPTED,
                      ZTITLEENCRYPTED,
                      ZNUMBEROFTOTALVISITS,
                      ZNUMBEROFTRACKERSBLOCKED,
                      ZLASTVISIT
                  FROM ZHISTORYENTRYMANAGEDOBJECT
                  WHERE ZURLENCRYPTED IS NOT NULL AND ZNUMBEROFTOTALVISITS > 1
                  ORDER BY ZNUMBEROFTOTALVISITS DESC
                  LIMIT ?
              """
              results = query_duckduckgo_db(query, (limit,))
          else:
              # DuckDuckGo Windows - Chromium-based
              query = """
              SELECT url, title, visit_count, last_visit_time
              FROM urls
              WHERE visit_count > 1
              AND url NOT LIKE 'https://static.ddg.local/%'
              ORDER BY visit_count DESC
              LIMIT ?
              """
              results = query_history_db(query, (limit,), browser)
  
      elif browser == "safari":
          # Safari database schema
          query = """
          SELECT
              history_items.url as url,
              history_visits.title as title,
              COUNT(history_visits.id) as visit_count,
              MAX(history_visits.visit_time) as last_visit_time
          FROM history_items
          JOIN history_visits ON history_items.id = history_visits.history_item
          GROUP BY history_items.url
          HAVING visit_count > 1
          ORDER BY visit_count DESC
          LIMIT ?
          """
      elif browser == "firefox":
          # Firefox database schema (places.sqlite)
          query = """
          SELECT
              url, title, visit_count,
              last_visit_date as last_visit_time
          FROM moz_places
          WHERE hidden = 0 AND visit_count > 1
          ORDER BY visit_count DESC
          LIMIT ?
          """
      else:
          # Chromium-based browsers (Brave/Chrome/Edge) database schema
          query = """
          SELECT url, title, visit_count, last_visit_time
          FROM urls
          WHERE visit_count > 1
          ORDER BY visit_count DESC
          LIMIT ?
          """
  
      # Query databases (DuckDuckGo already queried above)
      if browser != "duckduckgo":
          results = query_history_db(query, (limit,), browser)
  
      if not results:
          return f"No frequently visited sites found in {browser.capitalize()}"
  
      output = [f"Top {len(results)} most visited {browser.capitalize()} sites:\n"]
  
      for i, entry in enumerate(results, 1):
          title = entry['title'] or "No title"
          url = entry['url']
          visit_count = entry['visit_count']
  
          if browser == "duckduckgo":
              if is_duckduckgo_encrypted():
                  # macOS encrypted version has trackers blocked
                  last_visit = cocoa_timestamp_to_datetime(entry['last_visit_time'])
                  trackers_blocked = entry.get('trackers_blocked', 0)
                  output.append(f"{i}. {title}")
                  output.append(f"   URL: {url}")
                  output.append(f"   Visits: {visit_count} | Trackers blocked: {trackers_blocked} | Last visited: {last_visit}")
                  output.append("")
              else:
                  # Windows Chromium version
                  last_visit = chrome_timestamp_to_datetime(entry['last_visit_time'])
                  output.append(f"{i}. {title}")
                  output.append(f"   URL: {url}")
                  output.append(f"   Visits: {visit_count} | Last visited: {last_visit}")
                  output.append("")
          elif browser == "safari":
              last_visit = safari_timestamp_to_datetime(entry['last_visit_time'])
              output.append(f"{i}. {title}")
              output.append(f"   URL: {url}")
              output.append(f"   Visits: {visit_count} | Last visited: {last_visit}")
              output.append("")
          elif browser == "firefox":
              last_visit = firefox_timestamp_to_datetime(entry['last_visit_time'])
              output.append(f"{i}. {title}")
              output.append(f"   URL: {url}")
              output.append(f"   Visits: {visit_count} | Last visited: {last_visit}")
              output.append("")
          else:
              last_visit = chrome_timestamp_to_datetime(entry['last_visit_time'])
              output.append(f"{i}. {title}")
              output.append(f"   URL: {url}")
              output.append(f"   Visits: {visit_count} | Last visited: {last_visit}")
              output.append("")
  
      return "\n".join(output)