iflow-mcp_janspoerer-mcp_browser_use 0.1.0__py3-none-any.whl

mcp_browser_use/config/environment.py

@@ -0,0 +1,155 @@
+"""Environment configuration and validation."""
+
+import os
+import hashlib
+from pathlib import Path
+from typing import Optional
+
+import logging
+logger = logging.getLogger(__name__)
+
+
+def get_env_config() -> dict:
+    """
+    Read environment variables and validate required ones.
+
+    Prioritizes Chrome Beta over Chrome Canary over Chrome. This is to free the Chrome instance. Chrome is likely
+    used by the user already. It is easier to separate the executables. If a user already has the Chrome executable open,
+    the MCP will not work properly as the Chrome DevTool Debug mode will not open when Chrome is already open in normal mode.
+    We prioritize Chrome Beta because it is more stable than Canary.
+
+    Required:   Either CHROME_PROFILE_USER_DATA_DIR, BETA_PROFILE_USER_DATA_DIR, or CANARY_PROFILE_USER_DATA_DIR
+    Optional:   CHROME_PROFILE_NAME (default 'Default')
+                CHROME_EXECUTABLE_PATH
+                BETA_EXECUTABLE_PATH (overrides CHROME_EXECUTABLE_PATH)
+                CANARY_EXECUTABLE_PATH (overrides BETA and CHROME)
+                CHROME_REMOTE_DEBUG_PORT
+
+    If BETA_EXECUTABLE_PATH is set, expects:
+                BETA_PROFILE_USER_DATA_DIR
+                BETA_PROFILE_NAME
+    If CANARY_EXECUTABLE_PATH is set, expects:
+                CANARY_PROFILE_USER_DATA_DIR
+                CANARY_PROFILE_NAME
+    """
+    # Base (generic) config
+    user_data_dir = (os.getenv("CHROME_PROFILE_USER_DATA_DIR") or "").strip()
+    if not user_data_dir and not os.getenv("BETA_PROFILE_USER_DATA_DIR") and not os.getenv("CANARY_PROFILE_USER_DATA_DIR"):
+        raise EnvironmentError("CHROME_PROFILE_USER_DATA_DIR is required.")
+
+    profile_name = (os.getenv("CHROME_PROFILE_NAME") or "Default").strip() or "Default"
+    chrome_path = (os.getenv("CHROME_EXECUTABLE_PATH") or "").strip() or None
+
+    # Prefer Beta > Canary > Generic Chrome
+    canary_path = (os.getenv("CANARY_EXECUTABLE_PATH") or "").strip()
+    if canary_path:
+        chrome_path = canary_path
+        user_data_dir = (os.getenv("CANARY_PROFILE_USER_DATA_DIR") or "").strip()
+        profile_name = (os.getenv("CANARY_PROFILE_NAME") or "").strip() or "Default"
+        if not user_data_dir:
+            raise EnvironmentError("CANARY_PROFILE_USER_DATA_DIR is required when CANARY_EXECUTABLE_PATH is set.")
+
+    beta_path = (os.getenv("BETA_EXECUTABLE_PATH") or "").strip()
+    if beta_path:
+        chrome_path = beta_path
+        user_data_dir = (os.getenv("BETA_PROFILE_USER_DATA_DIR") or "").strip()
+        profile_name = (os.getenv("BETA_PROFILE_NAME") or "").strip() or "Default"
+        if not user_data_dir:
+            raise EnvironmentError("BETA_PROFILE_USER_DATA_DIR is required when BETA_EXECUTABLE_PATH is set.")
+
+    fixed_port_env = (os.getenv("CHROME_REMOTE_DEBUG_PORT") or "").strip()
+    fixed_port = int(fixed_port_env) if fixed_port_env.isdigit() else None
+
+    if not user_data_dir:
+            raise EnvironmentError(
+                "No user_data_dir selected. Set CHROME_PROFILE_USER_DATA_DIR, or provide "
+                "BETA_EXECUTABLE_PATH + BETA_PROFILE_USER_DATA_DIR (or CANARY_* equivalents)."
+            )
+
+    return {
+        "user_data_dir": user_data_dir,
+        "profile_name": profile_name,
+        "chrome_path": chrome_path,
+        "fixed_port": fixed_port,
+    }
+
+
+def profile_key(config: Optional[dict] = None) -> str:
+    """
+    Stable key used by cross-process locks, based on absolute user_data_dir + profile_name.
+    - Hard-fails if CHROME_PROFILE_USER_DATA_DIR is missing/blank.
+    - If CHROME_PROFILE_STRICT=1 and the directory doesn't exist, hard-fail.
+      Otherwise we allow Chrome to create it and we normalize the path for stability.
+    """
+    if config is None:
+        config = get_env_config()
+
+    user_data_dir = (config.get("user_data_dir") or "").strip()
+    profile_name = (config.get("profile_name") or "Default").strip() or "Default"
+
+    if not user_data_dir:
+        raise EnvironmentError("CHROME_PROFILE_USER_DATA_DIR is required and cannot be empty.")
+
+    strict = os.getenv("CHROME_PROFILE_STRICT", "0") == "1"
+    p = Path(user_data_dir)
+    if strict and not p.exists():
+        raise FileNotFoundError(f"user_data_dir does not exist: {p}")
+
+    # Normalize to a stable absolute string
+    try:
+        user_data_dir = str(p.resolve())
+    except Exception:
+        user_data_dir = str(p.absolute())
+
+    raw = f"{user_data_dir}|{profile_name}"
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def is_default_user_data_dir(user_data_dir: str) -> bool:
+    """
+    Check if the given user_data_dir matches the platform's default Chrome profile location.
+
+    This is used to determine whether we can safely kill all Chrome processes or if we should
+    be more conservative (to avoid killing the user's main browser).
+
+    Returns True if user_data_dir matches a known default Chrome profile path for the current platform.
+    """
+    import platform
+
+    system = platform.system()
+    user_data_dir_resolved = str(Path(user_data_dir).resolve())
+
+    # Define default profile locations for each platform
+    if system == "Darwin":  # macOS
+        default_paths = [
+            str(Path.home() / "Library" / "Application Support" / "Google" / "Chrome"),
+            str(Path.home() / "Library" / "Application Support" / "Google" / "Chrome Beta"),
+            str(Path.home() / "Library" / "Application Support" / "Google" / "Chrome Canary"),
+        ]
+    elif system == "Windows":
+        default_paths = [
+            str(Path.home() / "AppData" / "Local" / "Google" / "Chrome" / "User Data"),
+            str(Path.home() / "AppData" / "Local" / "Google" / "Chrome Beta" / "User Data"),
+            str(Path.home() / "AppData" / "Local" / "Google" / "Chrome SxS" / "User Data"),  # Canary
+        ]
+    elif system == "Linux":
+        default_paths = [
+            str(Path.home() / ".config" / "google-chrome"),
+            str(Path.home() / ".config" / "google-chrome-beta"),
+            str(Path.home() / ".config" / "google-chrome-unstable"),  # Canary equivalent
+        ]
+    else:
+        # Unknown platform - assume it's not default to be safe
+        return False
+
+    # Resolve all default paths and check for matches
+    for default_path in default_paths:
+        try:
+            default_resolved = str(Path(default_path).resolve())
+            if user_data_dir_resolved == default_resolved:
+                return True
+        except Exception:
+            # If we can't resolve a path, skip it
+            continue
+
+    return False

mcp_browser_use/config/paths.py

@@ -0,0 +1,97 @@
+"""Path utilities and management for browser configuration."""
+
+import os
+import tempfile
+from pathlib import Path
+
+from .environment import profile_key
+
+
+_DEFAULT_LOCK_DIR = None
+
+
+def get_lock_dir() -> str:
+    """
+    Get the lock directory path.
+
+    Uses MCP_BROWSER_LOCK_DIR env var if set, otherwise uses:
+        <repo_root>/tmp/mcp_locks
+
+    The directory is created if it doesn't exist.
+
+    Returns:
+        Absolute path to lock directory
+    """
+    global _DEFAULT_LOCK_DIR
+
+    if _DEFAULT_LOCK_DIR is None:
+        # Calculate default: <repo_root>/tmp/mcp_locks
+        repo_root = Path(__file__).parent.parent.parent.parent
+        _DEFAULT_LOCK_DIR = str(repo_root / "tmp" / "mcp_locks")
+
+    lock_dir = os.getenv("MCP_BROWSER_LOCK_DIR") or _DEFAULT_LOCK_DIR
+
+    # Ensure directory exists
+    Path(lock_dir).mkdir(parents=True, exist_ok=True)
+
+    return lock_dir
+
+
+def rendezvous_path(config: dict) -> str:
+    """Get the path to the rendezvous file for inter-process communication."""
+    return os.path.join(tempfile.gettempdir(), f"mcp_chrome_rendezvous_{profile_key(config)}.json")
+
+
+def start_lock_dir(config: dict) -> str:
+    """Get the directory path for the startup lock."""
+    return os.path.join(tempfile.gettempdir(), f"mcp_chrome_start_lock_{profile_key(config)}")
+
+
+def chromedriver_log_path(config: dict) -> str:
+    """Get the path to the ChromeDriver log file."""
+    return os.path.join(tempfile.gettempdir(), f"chromedriver_shared_{profile_key(config)}_{os.getpid()}.log")
+
+
+def _lock_paths():
+    """
+    Return paths for the action lock files (softlock JSON, mutex, and startup mutex).
+    These paths are based on the profile key and LOCK_DIR environment variable.
+    """
+    from ..config.environment import get_env_config
+
+    # Get LOCK_DIR from global state
+    _DEFAULT_LOCK_DIR = str(Path(__file__).parent.parent.parent.parent / "tmp" / "mcp_locks")
+    LOCK_DIR = os.getenv("MCP_BROWSER_LOCK_DIR") or _DEFAULT_LOCK_DIR
+    Path(LOCK_DIR).mkdir(parents=True, exist_ok=True)
+
+    key = profile_key(get_env_config())  # stable across processes; independent of port
+    base = Path(LOCK_DIR)
+    base.mkdir(parents=True, exist_ok=True)
+    softlock_json = base / f"{key}.softlock.json"
+    softlock_mutex = base / f"{key}.softlock.mutex"
+    startup_mutex = base / f"{key}.startup.mutex"
+    return str(softlock_json), str(softlock_mutex), str(startup_mutex)
+
+
+def _window_registry_path() -> str:
+    """
+    Return the path to the window registry file for tracking window ownership.
+    """
+    from ..config.environment import get_env_config
+
+    # Get LOCK_DIR from global state
+    _DEFAULT_LOCK_DIR = str(Path(__file__).parent.parent.parent.parent / "tmp" / "mcp_locks")
+    LOCK_DIR = os.getenv("MCP_BROWSER_LOCK_DIR") or _DEFAULT_LOCK_DIR
+
+    key = profile_key(get_env_config())
+    return os.path.join(LOCK_DIR, f"{key}.window_registry.json")
+
+
+def _same_dir(a: str, b: str) -> bool:
+    """Compare two directory paths for equality, normalizing for platform differences."""
+    if not a or not b:
+        return False
+    try:
+        return os.path.normcase(os.path.realpath(a)) == os.path.normcase(os.path.realpath(b))
+    except Exception:
+        return a == b

mcp_browser_use/constants.py

@@ -0,0 +1,68 @@
+"""
+Global constants and configuration defaults.
+No dependencies - safe to import from anywhere.
+
+This module extracts constants from helpers.py to break circular dependencies.
+"""
+
+import os
+
+# ============================================================================
+# Lock Configuration
+# ============================================================================
+
+ACTION_LOCK_TTL_SECS = int(os.getenv("MCP_ACTION_LOCK_TTL", "30"))
+"""Time-to-live for action locks in seconds."""
+
+ACTION_LOCK_WAIT_SECS = int(os.getenv("MCP_ACTION_LOCK_WAIT", "60"))
+"""Maximum time to wait for action lock acquisition in seconds."""
+
+FILE_MUTEX_STALE_SECS = int(os.getenv("MCP_FILE_MUTEX_STALE_SECS", "60"))
+"""Consider file mutex stale after this many seconds."""
+
+
+# ============================================================================
+# Window Registry Configuration
+# ============================================================================
+
+WINDOW_REGISTRY_STALE_THRESHOLD = int(os.getenv("MCP_WINDOW_REGISTRY_STALE_SECS", "300"))
+"""Consider window registry entry stale after this many seconds."""
+
+
+# ============================================================================
+# Rendering Configuration
+# ============================================================================
+
+MAX_SNAPSHOT_CHARS = int(os.getenv("MCP_MAX_SNAPSHOT_CHARS", "10000"))
+"""Maximum characters in HTML snapshots."""
+
+
+# ============================================================================
+# Chrome Startup Configuration
+# ============================================================================
+
+START_LOCK_WAIT_SEC = 8.0
+"""How long to wait to acquire the startup lock."""
+
+RENDEZVOUS_TTL_SEC = 24 * 3600
+"""How long a rendezvous file is considered valid (24 hours)."""
+
+
+# ============================================================================
+# Feature Flags
+# ============================================================================
+
+ALLOW_ATTACH_ANY = os.getenv("MCP_ATTACH_ANY_PROFILE", "0") == "1"
+"""Allow attaching to any Chrome profile, not just the configured one."""
+
+
+__all__ = [
+    "ACTION_LOCK_TTL_SECS",
+    "ACTION_LOCK_WAIT_SECS",
+    "FILE_MUTEX_STALE_SECS",
+    "WINDOW_REGISTRY_STALE_THRESHOLD",
+    "MAX_SNAPSHOT_CHARS",
+    "START_LOCK_WAIT_SEC",
+    "RENDEZVOUS_TTL_SEC",
+    "ALLOW_ATTACH_ANY",
+]

mcp_browser_use/context.py

@@ -0,0 +1,150 @@
+"""
+Centralized browser state management.
+
+This module replaces module-level globals with a context object,
+providing a single source of truth for browser session state.
+
+Thread Safety:
+    The BrowserContext itself is NOT thread-safe. Access should be
+    coordinated using the locking decorators (exclusive_browser_access).
+
+Usage:
+    from mcp_browser_use.context import get_context
+
+    ctx = get_context()
+    if ctx.driver is None:
+        # Initialize driver
+        ctx.driver = create_driver()
+"""
+
+from typing import Optional
+from selenium import webdriver
+from dataclasses import dataclass, field
+import asyncio
+
+
+@dataclass
+class BrowserContext:
+    """
+    Encapsulates all browser session state.
+
+    This replaces the module-level globals:
+        DRIVER, DEBUGGER_HOST, DEBUGGER_PORT, TARGET_ID,
+        WINDOW_ID, MY_TAG, LOCK_DIR, etc.
+
+    Attributes:
+        driver: Selenium WebDriver instance
+        debugger_host: Chrome DevTools debugger hostname
+        debugger_port: Chrome DevTools debugger port
+        target_id: Chrome DevTools Protocol target ID for this window
+        window_id: Chrome window ID (from Browser.getWindowForTarget)
+        process_tag: Unique identifier for this process/session
+        config: Environment configuration dictionary
+        lock_dir: Directory for lock files
+        intra_process_lock: Asyncio lock for serializing operations within this process
+    """
+
+    # Driver state
+    driver: Optional[webdriver.Chrome] = None
+    debugger_host: Optional[str] = None
+    debugger_port: Optional[int] = None
+
+    # Window state
+    target_id: Optional[str] = None
+    window_id: Optional[int] = None
+
+    # Process identity
+    process_tag: Optional[str] = None
+
+    # Configuration (should be immutable after initialization)
+    config: dict = field(default_factory=dict)
+
+    # Lock directory
+    lock_dir: str = ""
+
+    # Intra-process lock
+    intra_process_lock: Optional[asyncio.Lock] = None
+
+    def is_driver_initialized(self) -> bool:
+        """Check if driver is initialized."""
+        return self.driver is not None
+
+    def is_window_ready(self) -> bool:
+        """Check if browser window is ready."""
+        return (
+            self.driver is not None
+            and self.target_id is not None
+        )
+
+    def get_debugger_address(self) -> Optional[str]:
+        """Get debugger address as host:port string."""
+        if self.debugger_host and self.debugger_port:
+            return f"{self.debugger_host}:{self.debugger_port}"
+        return None
+
+    def reset_window_state(self) -> None:
+        """Reset window state (useful after window close)."""
+        self.target_id = None
+        self.window_id = None
+
+    def get_intra_process_lock(self) -> asyncio.Lock:
+        """Get or create the intra-process asyncio lock."""
+        if self.intra_process_lock is None:
+            self.intra_process_lock = asyncio.Lock()
+        return self.intra_process_lock
+
+
+# ============================================================================
+# Global Context Management
+# ============================================================================
+
+_global_context: Optional[BrowserContext] = None
+
+
+def get_context() -> BrowserContext:
+    """
+    Get or create the global browser context.
+
+    This is a singleton pattern - all calls return the same context instance.
+    Use reset_context() to clear the singleton (mainly for testing).
+
+    Returns:
+        The global BrowserContext instance
+    """
+    global _global_context
+
+    if _global_context is None:
+        # Lazy initialization - import here to avoid circular dependencies
+        try:
+            from .config.environment import get_env_config
+            from .config.paths import get_lock_dir
+
+            _global_context = BrowserContext(
+                config=get_env_config(),
+                lock_dir=get_lock_dir(),
+            )
+        except Exception:
+            # If config not available yet, create minimal context
+            _global_context = BrowserContext()
+
+    return _global_context
+
+
+def reset_context() -> None:
+    """
+    Reset the global context.
+
+    ⚠️  WARNING: This is primarily for testing. In production code,
+    use close_browser() instead of directly resetting context.
+
+    This will clear all state including driver, window IDs, etc.
+    """
+    global _global_context
+    _global_context = None
+
+
+__all__ = [
+    "BrowserContext",
+    "get_context",
+    "reset_context",
+]

mcp_browser_use/context_pack.py

@@ -0,0 +1,85 @@
+# mcp_browser_use/context_pack.py
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Optional, Any
+
+
+class ReturnMode:
+    HTML = "html"
+    TEXT = "text"
+    OUTLINE = "outline"
+    DOMPATHS = "dompaths"
+    MIXED = "mixed"
+
+class CleaningLevel:
+    RAW_VISIBLE = 0
+    LIGHT = 1
+    DEFAULT = 2
+    AGGRESSIVE = 3
+
+@dataclass
+class IframeInfo:
+    index: int
+    name: Optional[str]
+    id: Optional[str]
+    src: Optional[str]
+    same_origin: Optional[bool]
+    css_path: Optional[str]
+    visible: Optional[bool]
+    summary_title: Optional[str] = None
+    subtree_id: Optional[str] = None
+
+@dataclass
+class OutlineItem:
+    level: int
+    text: str
+    word_count: int
+    css_path: Optional[str]
+    subtree_id: Optional[str]
+
+@dataclass
+class CatalogInteractive:
+    role: Optional[str]
+    text_excerpt: str
+    css_path: Optional[str]
+    xpath: Optional[str]
+    nth_path: Optional[str]
+    clickable: Optional[bool]
+    enabled: Optional[bool]
+
+@dataclass
+class ContextPack:
+    # meta
+    window_tag: Optional[str]
+    url: Optional[str]
+    title: Optional[str]
+    page_fingerprint: Optional[str] = None
+    lock_owner: Optional[str] = None
+    lock_expires_at: Optional[str] = None
+
+    # stats
+    cleaning_level_applied: int = CleaningLevel.DEFAULT
+    approx_tokens: int = 0
+    pruned_counts: Dict[str, int] = field(default_factory=dict)
+    tokens_budget: Optional[int] = None
+    nodes_kept: Optional[int] = None
+    nodes_pruned: Optional[int] = None
+    hard_capped: bool = False
+
+    # presence flags
+    snapshot_mode: str = ReturnMode.OUTLINE
+    outline_present: bool = False
+    diff_present: bool = False
+    iframe_index_present: bool = False
+
+    # payloads
+    outline: List[OutlineItem] = field(default_factory=list)
+    html: Optional[str] = None
+    text: Optional[str] = None
+    dompaths: Optional[List[Dict[str, Any]]] = None
+    mixed: Optional[Dict[str, Any]] = None
+    catalogs: Optional[Dict[str, Any]] = None
+    forms: Optional[Dict[str, Any]] = None
+    iframe_index: Optional[List[IframeInfo]] = None
+
+    errors: List[Dict[str, Any]] = field(default_factory=list)

mcp_browser_use/decorators/__init__.py

@@ -0,0 +1,13 @@
+# mcp_browser_use/decorators/__init__.py
+#
+# Re-exports decorators from their respective modules.
+
+from .ensure import ensure_driver_ready
+from .locking import exclusive_browser_access
+from .envelope import tool_envelope
+
+__all__ = [
+    "ensure_driver_ready",
+    "exclusive_browser_access",
+    "tool_envelope",
+]

mcp_browser_use/decorators/ensure.py

@@ -0,0 +1,84 @@
+# mcp_browser_use/decorators/ensure.py
+import json
+import inspect
+import functools
+
+def ensure_driver_ready(_func=None, *, include_snapshot=False, include_diagnostics=False):
+    def decorator(fn):
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def wrapper(*args, **kwargs):
+                import mcp_browser_use.helpers as helpers  # module import, not from-import
+                from mcp_browser_use.config.environment import get_env_config
+                from mcp_browser_use.utils.diagnostics import collect_diagnostics
+
+                # Check if driver is already initialized, but don't auto-initialize
+                if helpers.get_context().driver is None:
+                    payload = {
+                        "ok": False, 
+                        "error": "browser_not_started",
+                        "message": "Browser session not started. Please call 'start_browser' first before using browser actions."
+                    }
+                    if include_snapshot:
+                        payload["snapshot"] = {"url": None, "title": None, "html": "", "truncated": False}
+                    if include_diagnostics:
+                        try:
+                            payload["diagnostics"] = collect_diagnostics(None, None, get_env_config())
+                        except Exception:
+                            pass
+                    return json.dumps(payload)
+
+                # Ensure we have a valid window for this driver
+                try:
+                    helpers._ensure_singleton_window(helpers.get_context().driver)
+                except Exception:
+                    payload = {
+                        "ok": False,
+                        "error": "browser_window_lost", 
+                        "message": "Browser window was lost. Please call 'start_browser' to create a new session."
+                    }
+                    if include_snapshot:
+                        payload["snapshot"] = {"url": None, "title": None, "html": "", "truncated": False}
+                    return json.dumps(payload)
+                
+                return await fn(*args, **kwargs)
+            return wrapper
+        else:
+            @functools.wraps(fn)
+            def wrapper(*args, **kwargs):
+                import mcp_browser_use.helpers as helpers  # module import, not from-import
+                from mcp_browser_use.config.environment import get_env_config
+                from mcp_browser_use.utils.diagnostics import collect_diagnostics
+
+                # Check if driver is already initialized, but don't auto-initialize
+                if helpers.get_context().driver is None:
+                    payload = {
+                        "ok": False, 
+                        "error": "browser_not_started",
+                        "message": "Browser session not started. Please call 'start_browser' first before using browser actions."
+                    }
+                    if include_snapshot:
+                        payload["snapshot"] = {"url": None, "title": None, "html": "", "truncated": False}
+                    if include_diagnostics:
+                        try:
+                            payload["diagnostics"] = collect_diagnostics(None, None, get_env_config())
+                        except Exception:
+                            pass
+                    return json.dumps(payload)
+
+                # Ensure we have a valid window for this driver
+                try:
+                    helpers._ensure_singleton_window(helpers.get_context().driver)
+                except Exception:
+                    payload = {
+                        "ok": False,
+                        "error": "browser_window_lost", 
+                        "message": "Browser window was lost. Please call 'start_browser' to create a new session."
+                    }
+                    if include_snapshot:
+                        payload["snapshot"] = {"url": None, "title": None, "html": "", "truncated": False}
+                    return json.dumps(payload)
+                
+                return fn(*args, **kwargs)
+            return wrapper
+    return decorator if _func is None else decorator(_func)