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

mcp_browser_use/decorators/envelope.py

@@ -0,0 +1,83 @@
+# mcp_browser_use/decorators/envelope.py
+
+import os
+import json
+import asyncio
+import inspect
+import datetime
+import functools
+import traceback
+from typing import Any, Callable
+
+
+__all__ = [
+    "tool_envelope",
+]
+
+
+def tool_envelope(func: Callable):
+    """
+    Minimal decorator for MCP tool functions:
+      - Works with both async and sync callables.
+      - On success: ensures the return value is a string (json.dumps for non-strings).
+      - On error: returns a uniform JSON string with a summary and optional traceback.
+    Environment:
+      - Set MBU_TOOL_ERRORS_TRACEBACK=0 to suppress traceback in error payloads.
+    """
+    include_tb = os.getenv("MBU_TOOL_ERRORS_TRACEBACK", "1") not in ("0", "false", "False")
+
+    def _normalize(value: Any) -> str:
+        if value is None:
+            return ""
+        if isinstance(value, str):
+            return value
+        if isinstance(value, bytes):
+            try:
+                return value.decode("utf-8")
+            except Exception:
+                return value.decode("utf-8", "replace")
+        try:
+            return json.dumps(value, ensure_ascii=False, default=lambda o: getattr(o, "__dict__", repr(o)))
+        except Exception:
+            # Fallback to a best-effort string
+            try:
+                return str(value)
+            except Exception:
+                return ""
+
+    def _error_payload(err: Exception) -> str:
+        tb = traceback.format_exc() if include_tb else None
+        payload = {
+            "ok": False,
+            "summary": f"{err.__class__.__name__}: {err}",
+            "error": {
+                "type": err.__class__.__name__,
+                "message": str(err),
+            },
+            "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        }
+        if tb:
+            payload["error"]["traceback"] = tb
+        return json.dumps(payload, ensure_ascii=False)
+
+    if inspect.iscoroutinefunction(func):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            try:
+                result = await func(*args, **kwargs)
+            except asyncio.CancelledError:
+                # Preserve cooperative cancellation semantics
+                raise
+            except Exception as e:
+                return _error_payload(e)
+            return _normalize(result)
+        return wrapper
+    else:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            try:
+                result = func(*args, **kwargs)
+            except Exception as e:
+                return _error_payload(e)
+            return _normalize(result)
+        return wrapper

mcp_browser_use/decorators/locking.py

@@ -0,0 +1,172 @@
+# mcp_browser_use/decorators/locking.py
+#
+# Known Limitation: Iframe Context
+# Multi-step iframe interactions require specifying iframe_selector for each action.
+# This is intentional design to prevent context state bugs.
+
+
+"""
+If multiple agents are working at the same time, there will be some natural
+concurrency because the agents anyway need to produce tokens (think) before
+calling the next action. This makes issues arising from sequential locking a
+bit less pronounced.
+
+
+"""
+
+import os
+import json
+import asyncio
+import inspect
+import warnings
+import functools
+import contextlib
+import threading
+import time as _time
+from typing import Callable
+
+
+__all__ = [
+    "exclusive_browser_access",
+]
+
+
+def _validate_config_or_error():
+    """
+    Validate browser configuration early to provide clear error messages.
+
+    Returns None if valid, or JSON error string if invalid.
+    """
+    try:
+        from mcp_browser_use.config.environment import get_env_config
+        get_env_config()  # Just validate - don't store since config never changes
+        return None  # Valid config
+    except Exception as e:
+        error_payload = {
+            "ok": False,
+            "error": "invalid_configuration",
+            "message": f"Browser configuration error: {str(e)}. Please check your environment variables.",
+            "details": {
+                "required": ["CHROME_PROFILE_USER_DATA_DIR or BETA_PROFILE_USER_DATA_DIR or CANARY_PROFILE_USER_DATA_DIR"],
+                "optional": ["CHROME_EXECUTABLE_PATH", "CHROME_REMOTE_DEBUG_PORT"]
+            }
+        }
+        return json.dumps(error_payload)
+
+
+def exclusive_browser_access(_func=None):
+    """
+    Acquire the action lock, keep it alive with a heartbeat while the function runs,
+    and renew once on exit. Also serializes calls within this process.
+    Use on tools that mutate or depend on exclusive browser access.
+    """
+
+    def decorator(func):
+        if inspect.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def wrapper(*args, **kwargs):
+                # Early config validation to prevent race condition
+                config_error = _validate_config_or_error()
+                if config_error:
+                    return config_error
+
+                # Import lazily to avoid cycles at module import time
+                from mcp_browser_use.constants import ACTION_LOCK_TTL_SECS
+                from mcp_browser_use.locking.action_lock import (
+                    get_intra_process_lock,
+                    _acquire_action_lock_or_error,
+                    _renew_action_lock,
+                )
+                from mcp_browser_use.browser.process import ensure_process_tag
+
+                # Ensure process tag exists
+                owner = ensure_process_tag()
+
+                # In-process serialization across tools
+                lock = get_intra_process_lock()
+                async with lock:
+                    # Acquire cross-process action lock (waits up to ACTION_LOCK_WAIT_SECS)
+                    err = _acquire_action_lock_or_error(owner)
+                    if err:
+                        # err is already a JSON string; let your tool_envelope pass it through
+                        return err
+
+                    stop = asyncio.Event()
+
+                    async def _beater():
+                        try:
+                            while not stop.is_set():
+                                try:
+                                    await asyncio.wait_for(stop.wait(), timeout=1.0)
+                                    break
+                                except asyncio.TimeoutError:
+                                    pass
+                                try:
+                                    _renew_action_lock(owner, ttl=ACTION_LOCK_TTL_SECS)
+                                except Exception:
+                                    pass
+                        except asyncio.CancelledError:
+                            pass
+
+                    task = asyncio.create_task(_beater())
+                    try:
+                        return await func(*args, **kwargs)
+                    finally:
+                        stop.set()
+                        task.cancel()
+                        with contextlib.suppress(asyncio.CancelledError, Exception):
+                            await task
+                        with contextlib.suppress(Exception):
+                            _renew_action_lock(owner, ttl=ACTION_LOCK_TTL_SECS)
+            return wrapper
+
+        # Optional sync path (rare in your code); no asyncio.Lock here.
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Early config validation to prevent race condition
+            config_error = _validate_config_or_error()
+            if config_error:
+                return config_error
+
+            from mcp_browser_use.constants import ACTION_LOCK_TTL_SECS
+            from mcp_browser_use.locking.action_lock import (
+                _acquire_action_lock_or_error,
+                _renew_action_lock,
+            )
+            from mcp_browser_use.browser.process import ensure_process_tag
+
+            # Ensure process tag exists
+            owner = ensure_process_tag()
+
+
+
+            err = _acquire_action_lock_or_error(owner)
+            if err:
+                return err
+
+            stop = False
+            def _beater():
+                nonlocal stop
+                while not stop:
+                    _time.sleep(1.0)
+                    try:
+                        _renew_action_lock(owner, ttl=ACTION_LOCK_TTL_SECS)
+                    except Exception:
+                        pass
+
+            t = threading.Thread(target=_beater, daemon=True)
+            t.start()
+            try:
+                return func(*args, **kwargs)
+            finally:
+                stop = True
+                with contextlib.suppress(Exception):
+                    t.join(timeout=0.5)
+                with contextlib.suppress(Exception):
+                    _renew_action_lock(owner, ttl=ACTION_LOCK_TTL_SECS)
+
+        return wrapper
+
+    return decorator if _func is None else decorator(_func)
+
+

mcp_browser_use/helpers.py

@@ -0,0 +1,173 @@
+"""
+Helpers module - Compatibility layer.
+
+This module now serves as a compatibility layer that re-exports functions
+from the refactored modules. All actual implementations have been moved to:
+- locking/ (file_mutex, action_lock, window_registry)
+- browser/ (process, devtools, chrome, driver)
+- actions/ (navigation, elements, screenshots, keyboard)
+- utils/ (html_utils, retry, diagnostics)
+
+The functions are re-exported here to maintain backward compatibility with
+existing code that imports from helpers.
+"""
+
+#region Imports
+import os
+import sys
+import json
+import time
+import psutil
+import socket
+import shutil
+import asyncio
+import hashlib
+import tempfile
+import platform
+import traceback
+import subprocess
+import contextlib
+import urllib.request
+from pathlib import Path
+from bs4 import BeautifulSoup
+from typing import Callable, Optional, Tuple, Dict, Any
+import io
+import base64
+
+import logging
+logger = logging.getLogger(__name__)
+#endregion Imports
+
+#region Browser
+import selenium
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+from selenium.common.exceptions import (
+    TimeoutException,
+    NoSuchWindowException,
+    StaleElementReferenceException,
+    WebDriverException,
+    ElementClickInterceptedException,
+)
+
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+#endregion
+
+#region Imports Dotenv
+from dotenv import load_dotenv, find_dotenv
+load_dotenv(find_dotenv(filename=".env", usecwd=True), override=True)
+#endregion
+
+#region Context Integration (Phase 2)
+# Import new modules
+from .context import get_context, reset_context, BrowserContext
+from .constants import (
+    ACTION_LOCK_TTL_SECS as _ACTION_LOCK_TTL_SECS,
+    ACTION_LOCK_WAIT_SECS as _ACTION_LOCK_WAIT_SECS,
+    FILE_MUTEX_STALE_SECS as _FILE_MUTEX_STALE_SECS,
+    WINDOW_REGISTRY_STALE_THRESHOLD as _WINDOW_REGISTRY_STALE_THRESHOLD,
+    MAX_SNAPSHOT_CHARS as _MAX_SNAPSHOT_CHARS,
+    START_LOCK_WAIT_SEC as _START_LOCK_WAIT_SEC,
+    RENDEZVOUS_TTL_SEC as _RENDEZVOUS_TTL_SEC,
+    ALLOW_ATTACH_ANY as _ALLOW_ATTACH_ANY,
+)
+from .config.environment import get_env_config as _get_env_config, profile_key as _profile_key
+from .config.paths import get_lock_dir as _get_lock_dir
+#endregion
+
+#region Constants / policy parameters (Backwards Compatible - delegates to constants.py)
+# These now delegate to constants.py but maintain the old API
+ACTION_LOCK_TTL_SECS = _ACTION_LOCK_TTL_SECS
+ACTION_LOCK_WAIT_SECS = _ACTION_LOCK_WAIT_SECS
+FILE_MUTEX_STALE_SECS = _FILE_MUTEX_STALE_SECS
+WINDOW_REGISTRY_STALE_THRESHOLD = _WINDOW_REGISTRY_STALE_THRESHOLD
+MAX_SNAPSHOT_CHARS = _MAX_SNAPSHOT_CHARS
+START_LOCK_WAIT_SEC = _START_LOCK_WAIT_SEC
+RENDEZVOUS_TTL_SEC = _RENDEZVOUS_TTL_SEC
+ALLOW_ATTACH_ANY = _ALLOW_ATTACH_ANY
+#endregion
+
+
+
+#region Re-exports
+
+# Core functions needed by decorators (internal but exported)
+from .locking.action_lock import (
+    get_intra_process_lock,         # Used by decorators
+    _acquire_action_lock_or_error,  # Used by decorators
+    _renew_action_lock,              # Used by decorators
+    _release_action_lock,            # Used by tools
+)
+
+from .browser.process import (
+    ensure_process_tag,              # Used by decorators/tools
+    make_process_tag,                # Used internally
+)
+
+from .browser.driver import (
+    _ensure_driver_and_window,       # Used by tools
+    _ensure_singleton_window,        # Used by decorators
+    close_singleton_window,          # Used by tools
+    _cleanup_own_blank_tabs,         # Used by tools
+    _close_extra_blank_windows_safe, # Used by tools
+)
+
+from .actions.navigation import (
+    _wait_document_ready,            # Used by tools
+)
+
+from .actions.screenshots import (
+    _make_page_snapshot,             # Used by tools
+)
+
+# DO NOT re-export everything else - force migration
+# If someone needs it, they import directly from the module
+#endregion
+
+# Export list - Only essentials
+__all__ = [
+    # ===== Public API =====
+    # Context
+    'get_context',
+    'reset_context',
+    'BrowserContext',
+
+    # Constants
+    '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',
+
+    # ===== Core Functions (Internal but needed by decorators/tools) =====
+    # Locking
+    'get_intra_process_lock',
+    '_acquire_action_lock_or_error',
+    '_renew_action_lock',
+    '_release_action_lock',
+
+    # Process
+    'ensure_process_tag',
+    'make_process_tag',
+
+    # Driver
+    '_ensure_driver_and_window',
+    '_ensure_singleton_window',
+    'close_singleton_window',
+    '_cleanup_own_blank_tabs',
+    '_close_extra_blank_windows_safe',
+
+    # Actions
+    '_wait_document_ready',
+    '_make_page_snapshot',
+]
+
+# NOTE: For all other functions, import directly from the source module:
+#   from mcp_browser_use.actions.navigation import navigate_to_url
+#   from mcp_browser_use.actions.elements import click_element
+#   from mcp_browser_use.browser.chrome import start_or_attach_chrome_from_env
+#   etc.

mcp_browser_use/helpers_context.py

@@ -0,0 +1,261 @@
+# mcp_browser_use/helpers_context.py
+import os
+import time
+import json as _json
+from typing import Optional
+from selenium.webdriver.support.ui import WebDriverWait
+from .context_pack import ContextPack, ReturnMode
+from .cleaners import basic_prune, approx_token_count, extract_outline
+
+
+def _wait_for_dom_ready(driver, timeout=15):
+    WebDriverWait(driver=driver, timeout=timeout).until(
+        lambda d: d.execute_script("return document.readyState") == "complete"
+    )
+
+def _apply_snapshot_settle():
+    settle_ms = int(os.getenv("SNAPSHOT_SETTLE_MS", "200"))  # 0 disables
+    if settle_ms > 0:
+        time.sleep(settle_ms / 1000.0)
+
+def get_outer_html(driver) -> str:
+    _wait_for_dom_ready(driver=driver)
+    _apply_snapshot_settle()
+    # If you currently use driver.page_source, keep that; both are fine.
+    return driver.execute_script("return document.documentElement.outerHTML")
+
+def take_screenshot(driver, path: str):
+    _wait_for_dom_ready(driver=driver)
+    _apply_snapshot_settle()
+    driver.save_screenshot(path)
+
+def pack_snapshot(
+    *,
+    window_tag: Optional[str],
+    url: Optional[str],
+    title: Optional[str],
+    raw_html: Optional[str],
+    return_mode: str,
+    cleaning_level: int,
+    token_budget: Optional[int],
+    text_offset: Optional[int] = None,
+    html_offset: Optional[int] = None,
+) -> ContextPack:
+    cp = ContextPack(
+        window_tag=window_tag,
+        url=url,
+        title=title,
+        cleaning_level_applied=cleaning_level,
+        snapshot_mode=return_mode,
+        tokens_budget=token_budget,
+    )
+
+    html = raw_html or ""
+    cleaned_html, pruned_counts = basic_prune(html=html, level=cleaning_level)
+    cp.pruned_counts = pruned_counts
+
+    if return_mode == ReturnMode.OUTLINE:
+        outline = extract_outline(html=cleaned_html)
+        cp.outline_present = True
+        cp.outline = [
+            # convert dict -> dataclass-ish dict; leaving as dict is fine for now
+            o for o in outline
+        ]
+        cp.approx_tokens = approx_token_count(text=" ".join([o["text"] for o in outline]))
+        return cp
+
+    if return_mode == ReturnMode.HTML:
+        # Apply html_offset if specified (for pagination through large HTML content)
+        if html_offset and html_offset > 0:
+            cleaned_html = cleaned_html[html_offset:]
+
+        # Respect token budget by truncating cleaned_html conservatively
+        if token_budget:
+            # Convert tokens -> chars budget ~4 chars/token
+            char_budget = token_budget * 4
+            if len(cleaned_html) > char_budget:
+                cleaned_html = cleaned_html[:char_budget]
+                cp.hard_capped = True
+        cp.html = cleaned_html
+        cp.approx_tokens = approx_token_count(text=cleaned_html)
+        return cp
+
+    if return_mode == ReturnMode.TEXT:
+        # Very naive visible text extraction through soup.get_text()
+        try:
+            from bs4 import BeautifulSoup
+            txt = BeautifulSoup(cleaned_html, "html.parser").get_text("\n", strip=True)
+        except Exception:
+            txt = ""
+
+        # Apply text_offset if specified (for pagination through large content)
+        if text_offset and text_offset > 0:
+            txt = txt[text_offset:]
+
+        if token_budget:
+            char_budget = token_budget * 4
+            if len(txt) > char_budget:
+                txt = txt[:char_budget]
+                cp.hard_capped = True
+        cp.text = txt
+        cp.approx_tokens = approx_token_count(text=txt)
+        return cp
+
+    # Fallback to outline
+    outline = extract_outline(html=cleaned_html)
+    cp.outline_present = True
+    cp.outline = [o for o in outline]
+    cp.approx_tokens = approx_token_count(text=" ".join([o["text"] for o in outline]))
+    return cp
+
+
+
+def pack_from_snapshot_dict(
+    snapshot: dict,
+    window_tag: Optional[str],
+    return_mode: str,
+    cleaning_level: int,
+    token_budget: Optional[int],
+    text_offset: Optional[int] = None,
+    html_offset: Optional[int] = None,
+):
+    """
+    Build a ContextPack object from a raw snapshot dict and packing controls.
+
+    Applies structural/content pruning and optional truncation to fit the `token_budget`,
+    derives the selected representation (outline/text/html/dompaths/mixed), and attaches
+    metadata including `window_tag`.
+
+    Args:
+        snapshot: Raw snapshot dict (e.g., {"url", "title", "html", ...}).
+        window_tag: Optional identifier for the active window/tab.
+        return_mode: Target representation to materialize in the ContextPack.
+            {"outline", "text", "html", "dompaths", "mixed"}
+        cleaning_level: Structural/content cleaning intensity (0–3).
+        token_budget: Optional approximate token cap for the returned snapshot.
+        text_offset: Optional character offset to skip at the start of text (for pagination).
+            Only used when return_mode="text".
+        html_offset: Optional character offset to skip at the start of HTML (for pagination).
+            Only used when return_mode="html".
+
+    Returns:
+        ContextPack: The structured envelope ready for JSON serialization.
+
+    Notes:
+        - **Processing order**:
+          1. Clean HTML (remove noise based on cleaning_level)
+          2. Apply offset (skip first N chars)
+          3. Apply token_budget (truncate to fit)
+
+        - **Offset behavior**:
+          - Applied to cleaned content, not raw HTML
+          - Character-based, not token-based
+          - If offset exceeds content length, returns empty string
+          - Use consistent cleaning_level across paginated calls
+
+        - Consider computing a `page_fingerprint` (e.g., sha256 of cleaned html) to assist
+          agents in cheap change detection between steps.
+    """
+    return pack_snapshot(
+        window_tag=window_tag,
+        url=snapshot.get("url"),
+        title=snapshot.get("title"),
+        raw_html=snapshot.get("html"),
+        return_mode=return_mode,
+        cleaning_level=cleaning_level,
+        token_budget=token_budget,
+        text_offset=text_offset,
+        html_offset=html_offset,
+    )
+
+
+async def to_context_pack(result_json: str, return_mode: str, cleaning_level: int, token_budget=1000, text_offset: Optional[int] = None, html_offset: Optional[int] = None) -> str:
+    """
+    Convert a helper's raw JSON result into a JSON-serialized ContextPack envelope.
+
+    Parses a helper response (typically including a "snapshot" dict and auxiliary fields),
+    normalizes `return_mode`, fetches current page metadata, and produces a size-controlled,
+    structured ContextPack. Any non-snapshot fields from the helper are surfaced under
+    the ContextPack's auxiliary section (e.g., `mixed`). Helper-reported errors (e.g.,
+    ok=false) are surfaced in `errors`.
+    
+    Args:
+        result_json: JSON string returned by a helper call (must parse to a dict).
+        return_mode: Desired snapshot representation {"outline","text","html","dompaths","mixed"}.
+        cleaning_level: Structural/content cleaning intensity (0–3).
+        token_budget: Approximate token cap for the returned snapshot. Should usually be 5_000 or lower.
+        text_offset: Optional character offset for text mode pagination.
+        html_offset: Optional character offset for html mode pagination.
+
+    Returns:
+        str: JSON-serialized ContextPack.
+
+    Raises:
+        TypeError: If `result_json` is not valid JSON or is not a dict after parsing.
+        ValueError: If `return_mode` is invalid (normalized internally to a default).
+    """
+    # Import here to avoid circular dependency at module load time
+    import mcp_browser_use.helpers as helpers
+
+    try:
+        obj = _json.loads(result_json)
+    except Exception:
+        raise TypeError(f"helper returned non-JSON: {type(result_json)}")
+
+    # Normalize/validate return_mode
+    mode = (return_mode or "outline").lower()
+    if mode not in {"html", "text", "outline", "dompaths", "mixed"}:
+        mode = "outline"
+
+    try:
+        meta = await helpers.get_current_page_meta()
+    except Exception:
+        meta = {"url": None, "title": None, "window_tag": None}
+
+    snap = obj.get("snapshot")
+    if not isinstance(snap, dict):
+        snap = {"url": meta.get("url"), "title": meta.get("title"), "html": ""}
+
+    cp = pack_from_snapshot_dict(
+        snapshot=snap,
+        window_tag=meta.get("window_tag"),
+        return_mode=mode,
+        cleaning_level=cleaning_level,
+        token_budget=token_budget,
+        text_offset=text_offset,
+        html_offset=html_offset,
+    )
+
+    # Add warning if token budget is too high
+    if token_budget and token_budget > 10_000:
+        cp.errors.append({
+            "type": "warning",
+            "summary": "High token budget detected",
+            "details": {
+                "requested_token_budget": token_budget,
+                "message": (
+                    f"You requested a token budget of {token_budget} tokens, which may clog your context. "
+                    "Consider using the extract_elements tool with structured extraction (MODE 2) "
+                    "to extract only the specific data you need. This can reduce token usage by 90%+ "
+                    "while getting more precise results. "
+                    "Example: extract_elements(container_selector='div.product', fields=[...], max_items=50)"
+                ),
+                "recommendation": "Use extract_elements tool for targeted data extraction instead of large snapshots"
+            }
+        })
+
+    # Surface errors in a first-class place
+    if obj.get("ok") is False:
+        try:
+            cp.errors.append({
+                "type": obj.get("error") or "error",
+                "summary": obj.get("summary"),
+                "details": {k: v for k, v in obj.items() if k != "snapshot"},
+            })
+        except Exception:
+            pass
+
+    leftovers = {k: v for k, v in obj.items() if k != "snapshot"}
+    cp.mixed = leftovers
+
+    return _json.dumps(cp, default=lambda o: getattr(o, "__dict__", repr(o)), ensure_ascii=False)

mcp_browser_use/locking/__init__.py

@@ -0,0 +1 @@
+"""Multi-agent coordination and locking."""