Browser History Analysis MCP

Instructions

Implementation Reference

• server/main.py:16-38 (handler)

  Handler and registration for the check_browser_status tool. Calls the helper function and adds Claude-specific instructions.
  @mcp.tool() def check_browser_status() -> Dict[str, Any]: """Step 1: Check which browsers are available and which are locked. This is the first step in the workflow - run this to see if you need to close any browsers. Returns a dictionary with: - status: "ready", "browser_locked", or "error" - error_message: Clear error message if there's an issue - user_action_required: True if user needs to close browsers - recommended_action: Specific instructions for the user - available_browsers: List of detected browsers - active_browsers: List of browsers that are currently running IMPORTANT: If status is "browser_locked", you MUST tell the user to close the specified browser(s). """ result = tool_detect_available_browsers() # If there's a user action required, make it very clear if result.get("user_action_required", False): result["claude_instruction"] = "IMPORTANT: Tell the user they need to close their browser(s) as specified in the recommended_action field." return result
• server/browser_utils.py:409-488 (helper)

  Supporting utility function that implements the browser status check logic by testing database connections for Firefox, Chrome, and Safari to detect availability and locks.
  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)}" }