decodingtrust-agent-sdk 0.1.0__py3-none-any.whl

dt_arena/mcp_server/browser/main.py

@@ -0,0 +1,1741 @@
+"""
+MCP Server for Browser
+Provides tools for agents to interact with websites
+"""
+
+from fastmcp import FastMCP
+from playwright.async_api import async_playwright, Browser, Page, BrowserContext, TimeoutError as PlaywrightTimeoutError
+from typing import Optional, List, Dict, Any, Union, Annotated
+from mcp.types import ImageContent, TextContent
+from fastmcp.utilities.types import Image
+from collections import OrderedDict
+import asyncio
+import io
+from PIL import Image as PILImage
+import json
+import os
+
+# Initialize FastMCP server
+from contextlib import asynccontextmanager
+
+
+@asynccontextmanager
+async def lifespan(app):
+    """Initialize browser on server startup"""
+    await init_browser()
+    save_current_data()
+    yield
+    # Cleanup on shutdown
+    await cleanup_browser()
+
+
+mcp = FastMCP("decodingtrust-agent-browser", lifespan=lifespan)
+
+# Global browser state
+_playwright = None
+_browser: Optional[Browser] = None
+_context: Optional[BrowserContext] = None
+_pages: List[Page] = []
+_current_page_index: int = 0
+_browsing_history: OrderedDict[str, Dict[str, Any]] = OrderedDict()
+_lock = asyncio.Lock()
+
+# URL mappings
+_url_mappings: List[Dict[str, str]] = []  # List of {original_url, mapped_url}
+# Autofill data storage
+_saved_passwords: List[Dict[str, str]] = []  # List of {url_pattern, username, password}
+_saved_credit_cards: List[Dict[str, str]] = []  # List of {name, number, expiry_month, expiry_year, cvv}
+# Pre-login data
+_pre_logins: List[Dict[str, str]] = []  # List of {url, username, password}
+# Screenshot in snapshot setting
+_include_screenshot_in_snapshot: bool = False
+
+# Load config
+CONFIG_FILE = os.getenv("BROWSER_MCP_CONFIG", "config.json")
+CURRENT_DATA_FILE = CONFIG_FILE + ".current"
+try:
+    with open(CONFIG_FILE, "r") as f:
+        config = json.load(f)
+        _url_mappings = config.get("url_mappings", [])
+        _saved_passwords = config.get("saved_passwords", [])
+        _saved_credit_cards = config.get("saved_credit_cards", [])
+        _pre_logins = config.get("pre-logins", [])
+        _browsing_history = OrderedDict(config.get("browsing_history", {}))
+        _include_screenshot_in_snapshot = config.get("include_screenshot_in_snapshot", False)
+except Exception as e:
+    print(f"Failed to load config: {e}")
+
+
+def save_current_data() -> None:
+    """Persist current _saved_passwords, _saved_credit_cards, and _browsing_history to CURRENT_DATA_FILE"""
+    try:
+        data = {
+            "saved_passwords": _saved_passwords,
+            "saved_credit_cards": _saved_credit_cards,
+            "browsing_history": dict(_browsing_history),
+        }
+        with open(CURRENT_DATA_FILE, "w") as f:
+            json.dump(data, f, indent=2)
+    except Exception as e:
+        print(f"Failed to save current data: {e}")
+
+
+def translate_url_for_browser(agent_url: str) -> str:
+    """
+    Translate URL from agent perspective (original_url) to browser perspective (mapped_url).
+    Used when navigating - agent provides original URL, we navigate to mapped URL.
+    """
+    for mapping in _url_mappings:
+        original = mapping["original_url"]
+        mapped = mapping["mapped_url"]
+
+        # Check if the agent_url starts with or matches the original_url
+        if agent_url.startswith(original):
+            # Replace the original part with mapped part
+            return agent_url.replace(original, mapped, 1)
+        # Also check without trailing slash
+        if agent_url.rstrip("/").startswith(original.rstrip("/")):
+            return agent_url.replace(original.rstrip("/"), mapped.rstrip("/"), 1)
+
+    # No mapping found, return as-is
+    return agent_url
+
+
+def translate_url_for_agent(browser_url: str) -> str:
+    """
+    Translate URL from browser perspective (mapped_url) to agent perspective (original_url).
+    Used when reporting back - browser is at mapped URL, we show original URL to agent.
+    """
+    for mapping in _url_mappings:
+        original = mapping["original_url"]
+        mapped = mapping["mapped_url"]
+
+        # Check if the browser_url starts with or matches the mapped_url
+        if browser_url.startswith(mapped):
+            # Replace the mapped part with original part
+            return browser_url.replace(mapped, original, 1)
+        # Also check without trailing slash
+        if browser_url.rstrip("/").startswith(mapped.rstrip("/")):
+            return browser_url.replace(mapped.rstrip("/"), original.rstrip("/"), 1)
+
+    # No mapping found, return as-is
+    return browser_url
+
+
+def translate_ref_for_browser(ref: str) -> str:
+    """
+    Translate URLs within selectors from agent perspective to browser perspective.
+    Handles attribute selectors like a[href="https://example.com"].
+    """
+    for mapping in _url_mappings:
+        original = mapping["original_url"]
+        mapped = mapping["mapped_url"]
+
+        # Simple string replacement of URLs within the ref
+        ref = ref.replace(original, mapped)
+        # Also handle without trailing slash
+        if original.endswith("/") and not mapped.endswith("/"):
+            ref = ref.replace(original.rstrip("/"), mapped)
+        elif not original.endswith("/") and mapped.endswith("/"):
+            ref = ref.replace(original, mapped.rstrip("/"))
+
+    return ref
+
+
+def translate_urls_in_snapshot(snapshot_text: str) -> str:
+    """
+    Translate all URLs in snapshot text from browser perspective (mapped_url) to agent perspective (original_url).
+    This ensures that URLs appearing in links and other elements within the snapshot show the original URLs.
+    """
+    for mapping in _url_mappings:
+        original = mapping["original_url"]
+        mapped = mapping["mapped_url"]
+
+        # Replace mapped URLs with original URLs in the snapshot text
+        # Handle both with and without trailing slashes
+        snapshot_text = snapshot_text.replace(mapped, original)
+        if mapped.endswith("/") and not original.endswith("/"):
+            snapshot_text = snapshot_text.replace(mapped.rstrip("/"), original)
+        elif not mapped.endswith("/") and original.endswith("/"):
+            snapshot_text = snapshot_text.replace(mapped, original.rstrip("/"))
+
+    return snapshot_text
+
+
+async def process_pre_logins():
+    """Process pre-logins from config to simulate logged-in state"""
+    global _pre_logins, _context, _pages
+
+    if not _pre_logins:
+        return
+
+    print(f"Processing {len(_pre_logins)} pre-login(s)...")
+
+    for login_info in _pre_logins:
+        try:
+            url = login_info.get("url")
+            username = login_info.get("username")
+            password = login_info.get("password")
+
+            if not all([url, username, password]):
+                print(f"Skipping incomplete pre-login entry: {login_info}")
+                continue
+
+            # Create a new page for login
+            login_page = await _context.new_page()
+
+            # Navigate to the login URL (translate to mapped URL)
+            browser_url = translate_url_for_browser(url)
+            # Wait for environment ready before navigating
+            counter = 0
+            while counter < 60:
+                try:
+                    import requests
+
+                    response = requests.get(browser_url, timeout=5)
+                    if response.status_code == 200:
+                        print(f"Successfully connected to {browser_url} for pre-login")
+                        break
+                except Exception:
+                    print(f"Waiting for {browser_url} to be ready for pre-login...")
+                    await asyncio.sleep(2)
+                    counter += 1
+            #
+            await login_page.goto(browser_url, wait_until="networkidle")
+
+            # Try to find and fill login fields
+            # Auto-detect username field
+            username_locator = None
+            username_selectors = [
+                'input[autocomplete="username"]',
+                'input[autocomplete="email"]',
+                'input[id="username"]',
+                'input[id="email"]',
+                'input[name="username"]',
+                'input[name="email"]',
+                'input[type="email"]',
+                'input[type="text"][name*="user"]',
+                'input[type="text"][name*="email"]',
+                'input[type="text"][id*="user"]',
+                'input[type="text"][id*="email"]',
+            ]
+
+            for selector in username_selectors:
+                try:
+                    elements = await login_page.locator(selector).all()
+                    for element in elements:
+                        if await element.is_visible():
+                            username_locator = element
+                            break
+                    if username_locator:
+                        break
+                except:
+                    continue
+
+            # Auto-detect password field
+            password_locator = None
+            password_selectors = [
+                'input[autocomplete="current-password"]',
+                'input[autocomplete="new-password"]',
+                'input[id="password"]',
+                'input[name="password"]',
+                'input[type="password"]',
+            ]
+
+            for selector in password_selectors:
+                try:
+                    elements = await login_page.locator(selector).all()
+                    for element in elements:
+                        if await element.is_visible():
+                            password_locator = element
+                            break
+                    if password_locator:
+                        break
+                except:
+                    continue
+
+            # Fill the login form
+            if username_locator:
+                await username_locator.fill(username)
+            else:
+                print(f"Warning: Could not find username field for {url}")
+
+            if password_locator:
+                await password_locator.fill(password)
+                # Submit the form by pressing Enter on password field
+                await password_locator.press("Enter")
+
+                # Wait for navigation after login
+                try:
+                    await login_page.wait_for_load_state("domcontentloaded", timeout=30000)
+                except:
+                    print("Login navigation timeout, continuing...")
+            else:
+                print(f"Warning: Could not find password field for {url}")
+
+            # Close the login tab - the session cookies are preserved in the context
+            await login_page.close()
+            print(f"Pre-login completed for {username} at {url}")
+
+        except Exception as e:
+            print(f"Error during pre-login for {login_info.get('url', 'unknown')}: {e}")
+            # Try to close the page if it was created
+            try:
+                await login_page.close()
+            except:
+                pass
+            raise RuntimeError(f"Error during pre-login: {e}")
+
+
+async def init_browser():
+    """Initialize browser on startup"""
+    global _playwright, _browser, _context, _pages, _current_page_index
+
+    print("Initializing browser...")
+    _playwright = await async_playwright().start()
+    _browser = await _playwright.chromium.launch(headless=True)
+    _context = await _browser.new_context(viewport={"width": 1280, "height": 960})
+    _context.set_default_timeout(20000)  # 20 seconds (in milliseconds)
+
+    # Process pre-logins before setting up the main page
+    await process_pre_logins()
+
+    page = await _context.new_page()
+    await setup_page_listeners(page)
+    _pages = [page]
+    _current_page_index = 0
+    print("Browser initialized successfully")
+
+
+async def cleanup_browser():
+    """Cleanup browser on server shutdown"""
+    global _browser, _context, _pages, _playwright
+
+    print("Shutting down browser...")
+    if _pages:
+        for page in _pages:
+            await page.close()
+        _pages = []
+
+    if _context:
+        await _context.close()
+
+    if _browser:
+        await _browser.close()
+
+    if _playwright:
+        await _playwright.stop()
+    print("Browser shutdown complete")
+
+
+async def ensure_browser() -> Page:
+    """Ensure browser is launched and ready"""
+    global _pages, _current_page_index
+
+    if not _pages:
+        raise RuntimeError("Browser not initialized")
+
+    if _current_page_index >= len(_pages):
+        raise RuntimeError("No active page")
+    return _pages[_current_page_index]
+
+
+async def add_to_history(url: str, title: str) -> None:
+    """Add a page visit to browsing history"""
+    global _browsing_history
+    from datetime import datetime
+
+    timestamp = datetime.now().isoformat()
+
+    # If URL already exists, update it and move to end (O(1) operation)
+    if url in _browsing_history:
+        _browsing_history[url] = {"url": url, "title": title, "timestamp": timestamp}
+        _browsing_history.move_to_end(url)
+    else:
+        # Add new entry to the end (most recent)
+        _browsing_history[url] = {"url": url, "title": title, "timestamp": timestamp}
+
+    save_current_data()
+
+
+async def setup_page_listeners(page: Page) -> None:
+    """Setup listeners for a page to track navigation events"""
+
+    def on_load():
+        # Track page loads - note: event handlers in Playwright are sync
+        try:
+            # Schedule async work to be done
+            asyncio.create_task(_add_to_history_from_page(page))
+        except Exception as e:
+            # Silently ignore errors in listener
+            pass
+
+    page.on("load", on_load)
+
+
+async def _add_to_history_from_page(page: Page) -> None:
+    """Helper to add current page to history (called from sync event handler)"""
+    try:
+        browser_url = page.url
+        # Translate browser URL (mapped) to agent URL (original) before storing
+        url = translate_url_for_agent(browser_url)
+        title = await page.title()
+        await add_to_history(url, title)
+    except Exception:
+        pass
+
+
+async def mask_password_values_in_snapshot(page: Page, snapshot_text: str) -> str:
+    """Mask password input field values in ARIA snapshot"""
+    try:
+        # Find all password input fields and their values
+        password_inputs = await page.locator('input[type="password"]').all()
+
+        for password_input in password_inputs:
+            try:
+                # Get the value of the password field
+                value = await password_input.input_value()
+
+                if value:
+                    # Mask the password value in the snapshot text
+                    # The ARIA snapshot shows values as children of textbox elements
+                    # We need to replace the actual password value with asterisks
+                    masked_value = "*" * len(value)
+
+                    # Replace all occurrences of the password value in the snapshot
+                    snapshot_text = snapshot_text.replace(value, masked_value)
+            except Exception:
+                # Skip if we can't get the value for this specific input
+                continue
+
+    except Exception:
+        # If we can't find password inputs, return snapshot as-is
+        pass
+
+    return snapshot_text
+
+
+def hardcode_fix_for_ecommerce_review(snapshot_text: str) -> str:
+    """FIXME"""
+    try:
+        import re
+
+        pattern = re.compile(
+            r'(- radio "Rating.{0,50}\d stars?".{0,50}) \[ref=e\d+\](\s+- generic "\d stars?") \[ref=e\d+\]( \[cursor=pointer\]:)',
+            re.S,
+        )
+
+        cleaned = re.sub(pattern, r"\1\2\3", snapshot_text)
+        return cleaned
+    except Exception:
+        pass
+
+    return snapshot_text
+
+
+async def get_page_snapshot() -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Get current page snapshot including URL, title, and ARIA snapshot, and optionally a screenshot"""
+    global _include_screenshot_in_snapshot
+    page = await ensure_browser()
+    browser_url = page.url
+    # Translate browser URL (mapped) to agent URL (original)
+    url = translate_url_for_agent(browser_url)
+    title = await page.title()
+
+    # Get ARIA snapshot in YAML format (matching TypeScript implementation)
+    try:
+        # snapshot_text = await page.locator("body").aria_snapshot()
+        snapshot_text = await page._impl_obj._channel.send("snapshotForAI", None, {"timeout": 20000})
+        if not snapshot_text:
+            snapshot_text = "(empty)"
+        else:
+            # Translate URLs in the snapshot from mapped to original
+            snapshot_text = translate_urls_in_snapshot(snapshot_text)
+            # Mask password values in the snapshot
+            # snapshot_text = await mask_password_values_in_snapshot(page, snapshot_text)
+            # Hardcoded fix for ecommerce review page
+            snapshot_text = hardcode_fix_for_ecommerce_review(snapshot_text)
+    except Exception as e:
+        snapshot_text = f"(unable to capture snapshot: {e})"
+
+    text_result = f"""### Page state
+- Page URL: {url}
+- Page Title: {title}
+- Page Snapshot:
+```yaml
+{snapshot_text}
+```
+To reference an element in the page snapshot, set the `ref` parameter to `aria-ref={{ref_id}}` without brackets. For example, use ref="aria-ref=e2", not ref="[aria-ref=e2]". Traditional CSS selector syntax is also supported, but using `aria-ref` is preferred."""
+
+    # If screenshot should be included, return both text and image
+    if _include_screenshot_in_snapshot:
+        try:
+            # Take a screenshot
+            screenshot_bytes = await page.screenshot(type="png", full_page=False)
+
+            # Convert bytes to PIL Image, then to ImageContent
+            image = PILImage.open(io.BytesIO(screenshot_bytes))
+
+            # Scale image if needed (max 1568x1568, 1.15 megapixels)
+            pixels = image.width * image.height
+            max_pixels = 1.15 * 1024 * 1024
+            max_dimension = 1568
+
+            shrink = min(max_dimension / image.width, max_dimension / image.height, (max_pixels / pixels) ** 0.5)
+            if shrink < 1:
+                new_width = int(image.width * shrink)
+                new_height = int(image.height * shrink)
+                image = image.resize((new_width, new_height), PILImage.Resampling.LANCZOS)
+
+            # Convert to ImageContent
+            buffer = io.BytesIO()
+            image.save(buffer, format="PNG")
+            img_bytes = buffer.getvalue()
+            img_obj = Image(data=img_bytes, format="png")
+            image_content = img_obj.to_image_content()
+
+            # Return both text and image
+            return [TextContent(type="text", text=text_result), image_content]
+        except Exception as e:
+            # If screenshot fails, just return text with error message
+            return text_result + f"\n\n(Failed to capture screenshot: {e})"
+
+    return text_result
+
+
+async def get_tabs_info() -> str:
+    """Get formatted information about all open tabs"""
+    global _pages, _current_page_index
+
+    if len(_pages) <= 1:
+        return ""  # Don't show tabs if only one tab
+
+    tab_info = []
+    for i, page in enumerate(_pages):
+        try:
+            title = await page.title()
+            browser_url = page.url
+            # Translate browser URL (mapped) to agent URL (original)
+            url = translate_url_for_agent(browser_url)
+            current = " (current)" if i == _current_page_index else ""
+            tab_info.append(f"- {i}:{current} [{title}] ({url})")
+        except:
+            tab_info.append(f"- {i}: (unable to get info)")
+
+    return "### Open tabs\n" + "\n".join(tab_info)
+
+
+async def format_response_with_snapshot(
+    result: str, include_snapshot: bool = True, include_tabs: bool = False
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Format response with result, optional tabs, and optional snapshot"""
+    parts = []
+
+    if result:
+        parts.append(f"### Result\n{result}\n")
+
+    # Add tabs info if requested or if multiple tabs exist
+    if include_tabs or (include_snapshot and len(_pages) > 1):
+        try:
+            tabs = await get_tabs_info()
+            if tabs:
+                parts.append(f"\n{tabs}\n")
+        except:
+            pass
+
+    if include_snapshot:
+        try:
+            snapshot = await get_page_snapshot()
+            # If snapshot includes images (it's a list), combine text parts and append image
+            if isinstance(snapshot, list):
+                # snapshot is [TextContent, ImageContent]
+                text_parts = "\n".join(parts)
+                if text_parts:
+                    # Prepend the result/tabs text to the snapshot text
+                    snapshot[0].text = text_parts + "\n" + snapshot[0].text
+                return snapshot
+            else:
+                # snapshot is just a string
+                parts.append(f"\n{snapshot}")
+        except Exception as e:
+            parts.append(f"\n### Page state\n(Unable to capture snapshot: {e})")
+
+    return "\n".join(parts)
+
+
+@mcp.tool()
+async def browser_navigate(
+    url: Annotated[str, "The URL to navigate to"],
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Navigate to a URL"""
+    page = await ensure_browser()
+    # Translate agent's URL (original) to browser URL (mapped)
+    browser_url = translate_url_for_browser(url)
+    await page.goto(browser_url, wait_until="networkidle")
+    title = await page.title()
+    # Show agent the original URL they requested
+    result = f"Navigated to '{title}' at {url}"
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_navigate_back() -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Go back to the previous page"""
+    page = await ensure_browser()
+    await page.go_back(wait_until="networkidle")
+    title = await page.title()
+    result = f"Navigated back to '{title}'"
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_get_history(
+    limit: Annotated[Optional[int], "Optional limit on number of history entries to return (most recent first)"] = 50,
+) -> str:
+    """Get the browsing history"""
+    global _browsing_history
+
+    if not _browsing_history:
+        return "### Browsing History\nNo browsing history yet"
+
+    # Get entries in reverse order (most recent first)
+    history_entries = list(_browsing_history.items())[::-1]
+
+    if limit and limit > 0:
+        history_entries = history_entries[:limit]
+
+    history_lines = ["### Browsing History"]
+    for i, (url, entry) in enumerate(history_entries, 1):
+        timestamp = entry.get("timestamp", "unknown")
+        title = entry.get("title", "untitled")
+        history_lines.append(f"{i}. [{title}]({url}) - {timestamp}")
+
+    return "\n".join(history_lines)
+
+
+@mcp.tool()
+async def browser_open_history(
+    history_id: Annotated[int, "The history item ID (number shown in browser_get_history)"],
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Open a URL from browsing history by its ID"""
+    global _browsing_history
+
+    if not _browsing_history:
+        return "### Result\nNo browsing history available"
+
+    # Get entries in reverse order (most recent first) to match the displayed IDs
+    history_entries = list(_browsing_history.items())[::-1]
+
+    if history_id < 1 or history_id > len(history_entries):
+        return f"### Result\nInvalid history ID. Please use a number between 1 and {len(history_entries)}"
+
+    # Get the URL from the history entry (ID is 1-based)
+    url, entry = history_entries[history_id - 1]
+    title = entry.get("title", "untitled")
+
+    # Navigate to the URL - translate to mapped URL for actual navigation
+    page = await ensure_browser()
+    browser_url = translate_url_for_browser(url)
+    await page.goto(browser_url)
+
+    # Show agent the original URL
+    result = f"Opened history item #{history_id}: '{title}' at {url}"
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_snapshot() -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Capture accessibility snapshot of the current page, this is better than screenshot"""
+    return await get_page_snapshot()
+
+
+@mcp.tool()
+async def browser_click(
+    ref: Annotated[str, "Exact target element reference from the page snapshot"],
+    force: Annotated[bool, "Whether to force the click even if element is not visible"] = False,
+    doubleClick: Annotated[bool, "Whether to perform a double click instead of a single click"] = False,
+    button: Annotated[str, "Button to click, defaults to left"] = "left",
+    modifiers: Annotated[Optional[List[str]], "Modifier keys to press"] = None,
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Perform click on a web page"""
+    async with _lock:
+        page = await ensure_browser()
+        original_ref = ref
+        ref = translate_ref_for_browser(ref)
+        elements = await page.locator(ref).all()
+        locator = None
+        for element in elements:
+            if await element.is_visible():
+                locator = element
+                break
+        if not locator:
+            locator = page.locator(ref).first
+        # Best-effort scroll. Some eBay elements intermittently time out here even
+        # though a direct or forced click still succeeds.
+        try:
+            await locator.scroll_into_view_if_needed(timeout=3000)
+        except PlaywrightTimeoutError:
+            pass
+
+        click_options = {}
+        if force:
+            click_options["force"] = True
+        if button != "left":
+            click_options["button"] = button
+        if modifiers:
+            click_options["modifiers"] = modifiers
+
+        if doubleClick:
+            try:
+                await locator.dblclick(**click_options)
+            except PlaywrightTimeoutError as exc:
+                if force or "intercepts pointer events" not in str(exc).lower():
+                    raise
+                retry_options = dict(click_options)
+                retry_options["force"] = True
+                await locator.dblclick(**retry_options)
+            result = f"Double-clicked element: {original_ref}"
+        else:
+            try:
+                await locator.click(**click_options)
+            except PlaywrightTimeoutError as exc:
+                if force or "intercepts pointer events" not in str(exc).lower():
+                    raise
+                retry_options = dict(click_options)
+                retry_options["force"] = True
+                await locator.click(**retry_options)
+            result = f"Clicked element: {original_ref}"
+
+        # Wait for page to settle after click (network idle or small delay)
+        try:
+            await asyncio.sleep(2.0)
+            await page.wait_for_load_state("networkidle", timeout=2000)
+        except:
+            # If networkidle times out, just wait a bit for DOM updates
+            await asyncio.sleep(0.5)
+
+        return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_type(
+    ref: Annotated[str, "Exact target element reference from the page snapshot"],
+    text: Annotated[str, "Text to type into the element"],
+    submit: Annotated[bool, "Whether to submit entered text (press Enter after)"] = False,
+    slowly: Annotated[bool, "Whether to type one character at a time"] = False,
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Type text into editable element"""
+    async with _lock:
+        page = await ensure_browser()
+        original_ref = ref
+        ref = translate_ref_for_browser(ref)
+        elements = await page.locator(ref).all()
+        locator = None
+        for element in elements:
+            if await element.is_visible():
+                locator = element
+                break
+        if not locator:
+            locator = page.locator(ref).first
+        await locator.scroll_into_view_if_needed()
+
+        if slowly:
+            await locator.press_sequentially(text, delay=100)
+        else:
+            await locator.fill(text)
+
+        if submit:
+            await locator.press("Enter")
+            result = f"Typed text into '{original_ref}' and submitted"
+        else:
+            result = f"Typed text into '{original_ref}'"
+
+        # Wait for page to settle after typing
+        try:
+            await asyncio.sleep(0.5)
+            await page.wait_for_load_state("networkidle", timeout=2000)
+        except:
+            await asyncio.sleep(0.5)
+
+        return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_press_key(
+    key: Annotated[str, "Name of the key to press or a character to generate, such as ArrowLeft or a"],
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Press a key on the keyboard"""
+    page = await ensure_browser()
+    await page.keyboard.press(key)
+    result = f"Pressed key: {key}"
+
+    # Wait for page to settle after key press
+    try:
+        await page.wait_for_load_state("networkidle", timeout=2000)
+    except:
+        await asyncio.sleep(0.5)
+
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_hover(
+    ref: Annotated[str, "Exact target element reference from the page snapshot"],
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Hover over element on page"""
+    page = await ensure_browser()
+    original_ref = ref
+    ref = translate_ref_for_browser(ref)
+    elements = await page.locator(ref).all()
+    locator = None
+    for element in elements:
+        if await element.is_visible():
+            locator = element
+            break
+    if not locator:
+        locator = page.locator(ref).first
+    await locator.scroll_into_view_if_needed()
+    await locator.hover()
+    result = f"Hovered over element: {original_ref}"
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_drag(
+    startRef: Annotated[str, "Exact source element reference from the page snapshot"],
+    endRef: Annotated[str, "Exact target element reference from the page snapshot"],
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Perform drag and drop between two elements"""
+    page = await ensure_browser()
+    original_startRef = startRef
+    original_endRef = endRef
+    startRef = translate_ref_for_browser(startRef)
+    endRef = translate_ref_for_browser(endRef)
+
+    # Get the source and target elements
+    start_elements = await page.locator(startRef).all()
+    source = None
+    for element in start_elements:
+        if await element.is_visible():
+            source = element
+            break
+    if not source:
+        source = page.locator(startRef).first
+
+    end_elements = await page.locator(endRef).all()
+    target = None
+    for element in end_elements:
+        if await element.is_visible():
+            target = element
+            break
+    if not target:
+        target = page.locator(endRef).first
+
+    await source.scroll_into_view_if_needed()
+    await target.scroll_into_view_if_needed()
+
+    # Perform drag and drop
+    await source.drag_to(target)
+
+    result = f"Dragged from {original_startRef} to {original_endRef}"
+
+    # Wait for page to settle after drag
+    try:
+        await asyncio.sleep(0.5)
+        await page.wait_for_load_state("networkidle", timeout=2000)
+    except:
+        await asyncio.sleep(0.5)
+
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_select_option(
+    ref: Annotated[str, "Exact target element reference from the page snapshot"],
+    values: Annotated[List[str], "Array of values to select in the dropdown"],
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Select an option in a dropdown"""
+    page = await ensure_browser()
+    original_ref = ref
+    ref = translate_ref_for_browser(ref)
+    elements = await page.locator(ref).all()
+    locator = None
+    for element in elements:
+        if await element.is_visible():
+            locator = element
+            break
+    if not locator:
+        locator = page.locator(ref).first
+    await locator.scroll_into_view_if_needed()
+    await locator.select_option(values)
+    result = f"Selected options {values} in dropdown: {original_ref}"
+
+    # Wait for page to settle after selection
+    try:
+        await page.wait_for_load_state("networkidle", timeout=2000)
+    except:
+        await asyncio.sleep(0.5)
+
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+# @mcp.tool()
+# async def browser_fill_form(
+#     fields: Annotated[
+#         List[Dict[str, str]], "Array of field objects with 'name', 'type', 'ref', and 'value' properties"
+#     ],
+# ) -> Union[str, List[Union[TextContent, ImageContent]]]:
+#     """Fill multiple form fields"""
+#     page = await ensure_browser()
+
+#     results = []
+#     for field in fields:
+#         field_type = field.get("type", "textbox")
+#         original_ref = field["ref"]
+#         ref = translate_ref_for_browser(field["ref"])
+#         value = field["value"]
+#         name = field.get("name", original_ref)
+
+#         elements = await page.locator(ref).all()
+#         locator = None
+#         for element in elements:
+#             if await element.is_visible():
+#                 locator = element
+#                 break
+#         if not locator:
+#             locator = page.locator(ref).first
+
+#         if field_type in ["textbox", "slider"]:
+#             await locator.fill(value)
+#             results.append(f"Filled {name}")
+#         elif field_type in ["checkbox", "radio"]:
+#             checked = value.lower() == "true"
+#             await locator.set_checked(checked)
+#             results.append(f"Set {name} to {checked}")
+#         elif field_type == "combobox":
+#             await locator.select_option(label=value)
+#             results.append(f"Selected '{value}' in {name}")
+
+#     result = f"Filled form fields: {', '.join(results)}"
+#     return await format_response_with_snapshot(result, include_snapshot=False)
+
+
+@mcp.tool()
+async def browser_wait_for(
+    time: Annotated[Optional[float], "The time to wait in seconds"] = None,
+    text: Annotated[Optional[str], "The text to wait for"] = None,
+    textGone: Annotated[Optional[str], "The text to wait for to disappear"] = None,
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Wait for text to appear or disappear or a specified time to pass"""
+    page = await ensure_browser()
+
+    if not time and not text and not textGone:
+        raise ValueError("Either time, text or textGone must be provided")
+
+    results = []
+
+    if time:
+        await asyncio.sleep(min(30.0, time))
+        results.append(f"waited {time} seconds")
+
+    if textGone:
+        await page.get_by_text(textGone).first.wait_for(state="hidden", timeout=20000)
+        results.append(f"text '{textGone}' disappeared")
+
+    if text:
+        await page.get_by_text(text).first.wait_for(state="visible", timeout=20000)
+        results.append(f"text '{text}' appeared")
+
+    result = f"Wait completed: {', '.join(results)}"
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_take_screenshot(
+    type: Annotated[str, "Image format for the screenshot (png or jpeg)"] = "png",
+    ref: Annotated[
+        Optional[str], "Exact target element reference from the page snapshot (for element screenshot)"
+    ] = None,
+    fullPage: Annotated[bool, "When true, takes a screenshot of the full scrollable page"] = False,
+) -> List[Union[TextContent, ImageContent]]:
+    """Take a screenshot of the current page"""
+    page = await ensure_browser()
+
+    if fullPage and ref:
+        raise ValueError("fullPage cannot be used with element screenshots")
+
+    screenshot_options = {
+        "type": type,
+        "full_page": fullPage,
+    }
+
+    if type == "jpeg":
+        screenshot_options["quality"] = 90
+
+    if ref:
+        # Element screenshot
+        ref = translate_ref_for_browser(ref)
+        element = page.locator(ref)
+        screenshot_bytes = await element.screenshot(**screenshot_options)
+        target_desc = f"element {ref}"
+    else:
+        # Page screenshot
+        screenshot_bytes = await page.screenshot(**screenshot_options)
+        target_desc = "full page" if fullPage else "viewport"
+
+    text_result = f"Screenshot of {target_desc}"
+
+    # Convert bytes to PIL Image, then to ImageContent
+    image = PILImage.open(io.BytesIO(screenshot_bytes))
+
+    # Scale image if needed (max 1568x1568, 1.15 megapixels)
+    pixels = image.width * image.height
+    max_pixels = 1.15 * 1024 * 1024
+    max_dimension = 1568
+
+    shrink = min(max_dimension / image.width, max_dimension / image.height, (max_pixels / pixels) ** 0.5)
+    if shrink < 1:
+        new_width = int(image.width * shrink)
+        new_height = int(image.height * shrink)
+        image = image.resize((new_width, new_height), PILImage.Resampling.LANCZOS)
+
+    # Convert to ImageContent
+    buffer = io.BytesIO()
+    image.save(buffer, format=type.upper())
+    img_bytes = buffer.getvalue()
+    img_obj = Image(data=img_bytes, format=type)
+    image_content = img_obj.to_image_content()
+
+    # Return both text and image
+    return [TextContent(type="text", text=text_result), image_content]
+
+
+@mcp.tool()
+async def browser_resize(
+    width: Annotated[int, "Width of the browser window"], height: Annotated[int, "Height of the browser window"]
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Resize the browser window"""
+    page = await ensure_browser()
+    await page.set_viewport_size({"width": width, "height": height})
+    result = f"Resized browser window to {width}x{height}"
+    return await format_response_with_snapshot(result, include_snapshot=False)
+
+
+@mcp.tool()
+async def browser_close() -> str:
+    """Close the page"""
+    global _browser, _context, _pages, _playwright, _current_page_index
+
+    if _pages:
+        # Close all pages
+        for page in _pages:
+            await page.close()
+        _pages = []
+        _current_page_index = 0
+
+    if _context:
+        await _context.close()
+        _context = None
+
+    if _browser:
+        await _browser.close()
+        _browser = None
+
+    if _playwright:
+        await _playwright.stop()
+        _playwright = None
+
+    return "### Result\nBrowser closed successfully"
+
+
+@mcp.tool()
+async def browser_tabs(
+    action: Annotated[str, "Operation to perform (list, new, close, select)"],
+    index: Annotated[Optional[int], "Tab index, used for close/select"] = None,
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """List, create, close, or select a browser tab"""
+    global _pages, _current_page_index, _context
+
+    if action == "list":
+        tabs_info = await get_tabs_info()
+        if not tabs_info:
+            # Single tab case - translate URL for agent
+            browser_url = _pages[0].url
+            url = translate_url_for_agent(browser_url)
+            return "### Open tabs\n- 0: (current) [" + await _pages[0].title() + "] (" + url + ")"
+        return tabs_info
+
+    elif action == "new":
+        if not _context:
+            raise RuntimeError("Browser context not initialized")
+        new_page = await _context.new_page()
+        await setup_page_listeners(new_page)
+        new_tab_index = len(_pages)
+        _pages.append(new_page)
+        _current_page_index = new_tab_index
+        result = f"Created new tab (index {_current_page_index})"
+        # Always include tabs info when creating new tab
+        return await format_response_with_snapshot(result, include_snapshot=True, include_tabs=True)
+
+    elif action == "close":
+        if index is None:
+            index = _current_page_index
+
+        if index < 0 or index >= len(_pages):
+            raise ValueError(f"Invalid tab index: {index}")
+
+        page_to_close = _pages[index]
+        await page_to_close.close()
+        _pages.pop(index)
+
+        # Adjust current page index
+        if len(_pages) == 0:
+            # Reopen a new tab when closing the last one
+            new_page = await _context.new_page()
+            await setup_page_listeners(new_page)
+            _pages.append(new_page)
+            _current_page_index = 0
+        elif _current_page_index >= len(_pages):
+            _current_page_index = len(_pages) - 1
+
+        result = f"Closed tab {index}"
+        # Include tabs info after closing to show remaining tabs
+        return await format_response_with_snapshot(result, include_snapshot=True, include_tabs=True)
+
+    elif action == "select":
+        if index is None:
+            raise ValueError("Tab index is required for select action")
+
+        if index < 0 or index >= len(_pages):
+            raise ValueError(f"Invalid tab index: {index}")
+
+        _current_page_index = index
+        result = f"Selected tab {index}"
+        # Include tabs info and snapshot when switching tabs
+        return await format_response_with_snapshot(result, include_snapshot=True, include_tabs=True)
+
+    else:
+        raise ValueError(f"Invalid action: {action}")
+
+
+@mcp.tool()
+async def browser_mouse_move_xy(
+    x: Annotated[int, "X coordinate"], y: Annotated[int, "Y coordinate"]
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Move mouse to a given position"""
+    page = await ensure_browser()
+    await page.mouse.move(x, y)
+    result = f"Moved mouse to ({x}, {y})"
+    return await format_response_with_snapshot(result, include_snapshot=False)
+
+
+@mcp.tool()
+async def browser_mouse_click_xy(
+    x: Annotated[int, "X coordinate"], y: Annotated[int, "Y coordinate"]
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Click left mouse button at a given position"""
+    page = await ensure_browser()
+    await page.mouse.move(x, y)
+    await page.mouse.down()
+    await page.mouse.up()
+    result = f"Clicked at ({x}, {y})"
+
+    # Wait for page to settle after click
+    try:
+        await asyncio.sleep(0.5)
+        await page.wait_for_load_state("networkidle", timeout=2000)
+    except:
+        await asyncio.sleep(0.5)
+
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_mouse_drag_xy(
+    startX: Annotated[int, "Start X coordinate"],
+    startY: Annotated[int, "Start Y coordinate"],
+    endX: Annotated[int, "End X coordinate"],
+    endY: Annotated[int, "End Y coordinate"],
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Drag left mouse button to a given position"""
+    page = await ensure_browser()
+    await page.mouse.move(startX, startY)
+    await page.mouse.down()
+    await page.mouse.move(endX, endY)
+    await page.mouse.up()
+    result = f"Dragged from ({startX}, {startY}) to ({endX}, {endY})"
+
+    # Wait for page to settle after drag
+    try:
+        await asyncio.sleep(0.5)
+        await page.wait_for_load_state("networkidle", timeout=2000)
+    except:
+        await asyncio.sleep(0.5)
+
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_save_password(
+    url_pattern: Annotated[str, "URL or URL pattern (e.g., 'example.com' or 'https://example.com/login')"],
+    username: Annotated[str, "Username or email"],
+    password: Annotated[str, "Password"],
+) -> str:
+    """Save login credentials for autofill"""
+    global _saved_passwords
+
+    # Check if credential for this URL pattern already exists
+    for i, cred in enumerate(_saved_passwords):
+        if cred["url_pattern"] == url_pattern and cred["username"] == username:
+            # Update existing credential
+            _saved_passwords[i]["password"] = password
+            save_current_data()
+            return f"### Result\nUpdated saved password for {username} at {url_pattern}"
+
+    # Add new credential
+    _saved_passwords.append({"url_pattern": url_pattern, "username": username, "password": password})
+    save_current_data()
+    return f"### Result\nSaved password for {username} at {url_pattern}"
+
+
+@mcp.tool()
+async def browser_list_saved_passwords() -> str:
+    """List all saved passwords (passwords are masked)"""
+    global _saved_passwords
+
+    if not _saved_passwords:
+        return "### Saved Passwords\nNo saved passwords"
+
+    lines = ["### Saved Passwords"]
+    for i, cred in enumerate(_saved_passwords, 1):
+        masked_password = "*" * len(cred["password"])
+        lines.append(f"{i}. {cred['url_pattern']} - {cred['username']} (password: {masked_password})")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def browser_delete_password(
+    url_pattern: Annotated[str, "URL pattern of the password to delete"],
+    username: Annotated[str, "Username of the password to delete"],
+) -> str:
+    """Delete a saved password"""
+    global _saved_passwords
+
+    for i, cred in enumerate(_saved_passwords):
+        if cred["url_pattern"] == url_pattern and cred["username"] == username:
+            _saved_passwords.pop(i)
+            save_current_data()
+            return f"### Result\nDeleted password for {username} at {url_pattern}"
+
+    return f"### Result\nNo saved password found for {username} at {url_pattern}"
+
+
+@mcp.tool()
+async def browser_save_credit_card(
+    name: Annotated[str, "Cardholder name"],
+    number: Annotated[str, "Credit card number"],
+    expiry_month: Annotated[str, "Expiry month (MM)"],
+    expiry_year: Annotated[str, "Expiry year (YYYY or YY)"],
+    cvv: Annotated[str, "CVV/Security code"],
+) -> str:
+    """Save credit card information for autofill"""
+    global _saved_credit_cards
+
+    if len(expiry_year) == 2:
+        expiry_year = "20" + expiry_year  # Convert YY to YYYY, assuming 2000s
+    # Check if card with same number already exists
+    for i, card in enumerate(_saved_credit_cards):
+        if card["number"] == number:
+            # Update existing card
+            _saved_credit_cards[i] = {
+                "name": name,
+                "number": number,
+                "expiry_month": expiry_month,
+                "expiry_year": expiry_year,
+                "cvv": cvv,
+            }
+            save_current_data()
+            return f"### Result\nUpdated saved credit card ending in {number[-4:]}"
+
+    # Add new card
+    _saved_credit_cards.append(
+        {"name": name, "number": number, "expiry_month": expiry_month, "expiry_year": expiry_year, "cvv": cvv}
+    )
+    save_current_data()
+    return f"### Result\nSaved credit card ending in {number[-4:]}"
+
+
+@mcp.tool()
+async def browser_list_saved_credit_cards() -> str:
+    """List all saved credit cards (numbers are partially masked)"""
+    global _saved_credit_cards
+
+    if not _saved_credit_cards:
+        return "### Saved Credit Cards\nNo saved credit cards"
+
+    lines = ["### Saved Credit Cards"]
+    for i, card in enumerate(_saved_credit_cards, 1):
+        lines.append(f"{i}. {card['name']} - {card['number']} (exp: {card['expiry_month']}/{card['expiry_year']})")
+
+    return "\n".join(lines)
+
+
+@mcp.tool()
+async def browser_delete_credit_card(number: Annotated[str, "Credit card number to delete"]) -> str:
+    """Delete a saved credit card"""
+    global _saved_credit_cards
+
+    for i, card in enumerate(_saved_credit_cards):
+        if card["number"] == number:
+            _saved_credit_cards.pop(i)
+            save_current_data()
+            return f"### Result\nDeleted credit card ending in {number[-4:]}"
+
+    return f"### Result\nNo saved credit card found with that number"
+
+
+@mcp.tool()
+async def browser_autofill_password(
+    username_ref: Annotated[Optional[str], "Selector for username/email field"] = None,
+    password_ref: Annotated[Optional[str], "Selector for password field"] = None,
+    submit: Annotated[bool, "Whether to submit the form after filling"] = False,
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Autofill login form with saved credentials"""
+    global _saved_passwords
+    page = await ensure_browser()
+
+    if not _saved_passwords:
+        return "### Result\nNo saved passwords available"
+
+    # Get current URL and translate to original URL for matching
+    browser_url = page.url
+    current_url = translate_url_for_agent(browser_url)
+
+    # Find matching credential
+    matching_cred = None
+    for cred in _saved_passwords:
+        if cred["url_pattern"] in current_url or current_url in cred["url_pattern"]:
+            matching_cred = cred
+            break
+
+    if not matching_cred:
+        # If no match found, return error with available credentials
+        available = "\n".join([f"  - {cred['username']} ({cred['url_pattern']})" for cred in _saved_passwords])
+        return f"### Result\nNo saved password matches the current URL ({current_url}).\n\nAvailable saved passwords:\n{available}\n\nPlease save a password for this URL pattern or use browser_save_password to add one."
+
+    results = []
+
+    # Auto-detect fields if not provided
+    username_locator = None
+    if username_ref:
+        # Use provided ref - translate and get visible element
+        username_ref = translate_ref_for_browser(username_ref)
+        elements = await page.locator(username_ref).all()
+        for element in elements:
+            if await element.is_visible():
+                username_locator = element
+                break
+        if not username_locator:
+            username_locator = page.locator(username_ref).first
+    else:
+        # Auto-detect username field
+        # Try autocomplete attributes first (standard way)
+        # https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
+        username_selectors = [
+            'input[autocomplete="username"]',
+            'input[autocomplete="email"]',
+            'input[id="username"]',
+            'input[id="email"]',
+            'input[name="username"]',
+            'input[name="email"]',
+            'input[type="email"]',
+            'input[type="text"][name*="user"]',
+            'input[type="text"][name*="email"]',
+            'input[type="text"][id*="user"]',
+            'input[type="text"][id*="email"]',
+        ]
+
+        for selector in username_selectors:
+            try:
+                elements = await page.locator(selector).all()
+                for element in elements:
+                    if await element.is_visible():
+                        username_locator = element
+                        break
+                if username_locator:
+                    break
+            except:
+                continue
+
+    password_locator = None
+    if password_ref:
+        # Use provided ref - translate and get visible element
+        password_ref = translate_ref_for_browser(password_ref)
+        elements = await page.locator(password_ref).all()
+        for element in elements:
+            if await element.is_visible():
+                password_locator = element
+                break
+        if not password_locator:
+            password_locator = page.locator(password_ref).first
+    else:
+        # Auto-detect password field
+        # Try autocomplete attributes first (standard way)
+        password_selectors = [
+            'input[autocomplete="current-password"]',
+            'input[autocomplete="new-password"]',
+            'input[id="password"]',
+            'input[name="password"]',
+            'input[type="password"]',
+        ]
+
+        for selector in password_selectors:
+            try:
+                elements = await page.locator(selector).all()
+                for element in elements:
+                    if await element.is_visible():
+                        password_locator = element
+                        break
+                if password_locator:
+                    break
+            except:
+                continue
+
+    # Fill username field
+    if username_locator:
+        try:
+            await username_locator.fill(matching_cred["username"])
+            results.append(f"filled username field")
+        except Exception as e:
+            results.append(f"failed to fill username: {e}")
+    else:
+        results.append("username field not found")
+
+    # Fill password field
+    if password_locator:
+        try:
+            await password_locator.fill(matching_cred["password"])
+            results.append(f"filled password field")
+        except Exception as e:
+            results.append(f"failed to fill password: {e}")
+    else:
+        results.append("password field not found")
+
+    # Submit if requested
+    if submit and password_locator:
+        try:
+            await password_locator.press("Enter")
+            results.append("submitted form")
+
+            # Wait for page to settle after form submission
+            try:
+                await page.wait_for_load_state("networkidle", timeout=2000)
+            except:
+                await asyncio.sleep(0.5)
+        except Exception as e:
+            results.append(f"failed to submit: {e}")
+
+    result = f"Autofilled credentials for {matching_cred['username']}: {', '.join(results)}"
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+@mcp.tool()
+async def browser_autofill_credit_card(
+    card_index: Annotated[Optional[int], "Index of saved card to use (1-based, defaults to first card)"] = 1,
+    name_ref: Annotated[Optional[str], "Selector for cardholder name field"] = None,
+    number_ref: Annotated[Optional[str], "Selector for card number field"] = None,
+    expiry_ref: Annotated[Optional[str], "Selector for expiry date field"] = None,
+    month_ref: Annotated[Optional[str], "Selector for expiry month field (if separate)"] = None,
+    year_ref: Annotated[Optional[str], "Selector for expiry year field (if separate)"] = None,
+    cvv_ref: Annotated[Optional[str], "Selector for CVV field"] = None,
+) -> Union[str, List[Union[TextContent, ImageContent]]]:
+    """Autofill payment form with saved credit card"""
+    global _saved_credit_cards
+    page = await ensure_browser()
+
+    if not _saved_credit_cards:
+        return "### Result\nNo saved credit cards available"
+
+    # Get the card to use
+    if card_index < 1 or card_index > len(_saved_credit_cards):
+        return f"### Result\nInvalid card index. Please use a number between 1 and {len(_saved_credit_cards)}"
+
+    card = _saved_credit_cards[card_index - 1]
+    results = []
+
+    # Auto-detect fields if not provided
+    # Reference: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
+    name_locator = None
+    if name_ref:
+        # Use provided ref - translate and get visible element
+        name_ref = translate_ref_for_browser(name_ref)
+        elements = await page.locator(name_ref).all()
+        for element in elements:
+            if await element.is_visible():
+                name_locator = element
+                break
+        if not name_locator:
+            name_locator = page.locator(name_ref).first
+    else:
+        # Auto-detect name field
+        name_selectors = [
+            'input[autocomplete="cc-name"]',
+            'input[autocomplete="name"]',
+            'input[name*="name"][name*="card"]',
+            'input[id*="name"][id*="card"]',
+            'input[placeholder*="name"][placeholder*="card"]',
+            'input[name="cardname"]',
+            'input[name="cardholder"]',
+            'input[id="cardname"]',
+            'input[id="cardholder"]',
+        ]
+
+        for selector in name_selectors:
+            try:
+                elements = await page.locator(selector).all()
+                for element in elements:
+                    if await element.is_visible():
+                        name_locator = element
+                        break
+                if name_locator:
+                    break
+            except:
+                continue
+
+    number_locator = None
+    if number_ref:
+        # Use provided ref - translate and get visible element
+        number_ref = translate_ref_for_browser(number_ref)
+        elements = await page.locator(number_ref).all()
+        for element in elements:
+            if await element.is_visible():
+                number_locator = element
+                break
+        if not number_locator:
+            number_locator = page.locator(number_ref).first
+    else:
+        # Auto-detect number field
+        number_selectors = [
+            'input[autocomplete="cc-number"]',
+            'input[name*="card"][name*="number"]',
+            'input[id*="card"][id*="number"]',
+            'input[placeholder*="card"][placeholder*="number"]',
+            'input[name="cardnumber"]',
+            'input[name="card_number"]',
+            'input[id="cardnumber"]',
+            'input[id="card_number"]',
+        ]
+
+        for selector in number_selectors:
+            try:
+                elements = await page.locator(selector).all()
+                for element in elements:
+                    if await element.is_visible():
+                        number_locator = element
+                        break
+                if number_locator:
+                    break
+            except:
+                continue
+
+    cvv_locator = None
+    if cvv_ref:
+        # Use provided ref - translate and get visible element
+        cvv_ref = translate_ref_for_browser(cvv_ref)
+        elements = await page.locator(cvv_ref).all()
+        for element in elements:
+            if await element.is_visible():
+                cvv_locator = element
+                break
+        if not cvv_locator:
+            cvv_locator = page.locator(cvv_ref).first
+    else:
+        # Auto-detect CVV field
+        cvv_selectors = [
+            'input[autocomplete="cc-csc"]',
+            'input[name*="cvv"]',
+            'input[name*="cvc"]',
+            'input[name*="security"]',
+            'input[id*="cvv"]',
+            'input[id*="cvc"]',
+            'input[id*="security"]',
+            'input[placeholder*="cvv"]',
+            'input[placeholder*="cvc"]',
+            'input[placeholder*="security"]',
+        ]
+
+        for selector in cvv_selectors:
+            try:
+                elements = await page.locator(selector).all()
+                for element in elements:
+                    if await element.is_visible():
+                        cvv_locator = element
+                        break
+                if cvv_locator:
+                    break
+            except:
+                continue
+
+    # Fill cardholder name
+    if name_locator:
+        try:
+            await name_locator.fill(card["name"])
+            results.append("filled name")
+        except Exception as e:
+            results.append(f"failed to fill name: {e}")
+
+    # Fill card number
+    if number_locator:
+        try:
+            await number_locator.fill(card["number"])
+            results.append("filled card number")
+        except Exception as e:
+            results.append(f"failed to fill card number: {e}")
+
+    # Fill expiry date - check if combined or separate fields
+    expiry_locator = None
+    if expiry_ref:
+        # Use provided ref for combined expiry field
+        expiry_ref = translate_ref_for_browser(expiry_ref)
+        elements = await page.locator(expiry_ref).all()
+        for element in elements:
+            if await element.is_visible():
+                expiry_locator = element
+                break
+        if not expiry_locator:
+            expiry_locator = page.locator(expiry_ref).first
+
+    if expiry_locator:
+        # Combined expiry field (MM/YY or MM/YYYY)
+        try:
+            expiry_value = f"{card['expiry_month']}/{card['expiry_year'][-2:]}"
+            await expiry_locator.fill(expiry_value)
+            results.append("filled expiry date")
+        except Exception as e:
+            results.append(f"failed to fill expiry: {e}")
+    else:
+        # Separate month/year fields
+        month_locator = None
+        if month_ref:
+            # Use provided ref
+            month_ref = translate_ref_for_browser(month_ref)
+            elements = await page.locator(month_ref).all()
+            for element in elements:
+                if await element.is_visible():
+                    month_locator = element
+                    break
+            if not month_locator:
+                month_locator = page.locator(month_ref).first
+        else:
+            # Auto-detect month field
+            month_selectors = [
+                'input[autocomplete="cc-exp-month"]',
+                'select[autocomplete="cc-exp-month"]',
+                'input[name*="month"]',
+                'input[id*="month"]',
+                'select[name*="month"]',
+                'select[id*="month"]',
+            ]
+
+            for selector in month_selectors:
+                try:
+                    elements = await page.locator(selector).all()
+                    for element in elements:
+                        if await element.is_visible():
+                            month_locator = element
+                            break
+                    if month_locator:
+                        break
+                except:
+                    continue
+
+        year_locator = None
+        if year_ref:
+            # Use provided ref
+            year_ref = translate_ref_for_browser(year_ref)
+            elements = await page.locator(year_ref).all()
+            for element in elements:
+                if await element.is_visible():
+                    year_locator = element
+                    break
+            if not year_locator:
+                year_locator = page.locator(year_ref).first
+        else:
+            # Auto-detect year field
+            year_selectors = [
+                'input[autocomplete="cc-exp-year"]',
+                'select[autocomplete="cc-exp-year"]',
+                'input[name*="year"]',
+                'input[id*="year"]',
+                'select[name*="year"]',
+                'select[id*="year"]',
+            ]
+
+            for selector in year_selectors:
+                try:
+                    elements = await page.locator(selector).all()
+                    for element in elements:
+                        if await element.is_visible():
+                            year_locator = element
+                            break
+                    if year_locator:
+                        break
+                except:
+                    continue
+
+        if month_locator:
+            try:
+                # Check if it's a select or input
+                tag_name = await month_locator.evaluate("el => el.tagName.toLowerCase()")
+                if tag_name == "select":
+                    await month_locator.select_option(value=card["expiry_month"])
+                else:
+                    await month_locator.fill(card["expiry_month"])
+                results.append("filled expiry month")
+            except Exception as e:
+                results.append(f"failed to fill month: {e}")
+
+        if year_locator:
+            try:
+                tag_name = await year_locator.evaluate("el => el.tagName.toLowerCase()")
+                if tag_name == "select":
+                    # Try both 2-digit and 4-digit year
+                    try:
+                        await year_locator.select_option(value=card["expiry_year"])
+                    except:
+                        await year_locator.select_option(value=card["expiry_year"][-2:])
+                else:
+                    await year_locator.fill(card["expiry_year"][-2:])
+                results.append("filled expiry year")
+            except Exception as e:
+                results.append(f"failed to fill year: {e}")
+
+    # Fill CVV
+    if cvv_locator:
+        try:
+            await cvv_locator.fill(card["cvv"])
+            results.append("filled CVV")
+        except Exception as e:
+            results.append(f"failed to fill CVV: {e}")
+
+    result = f"Autofilled credit card ending in {card['number'][-4:]}: {', '.join(results)}"
+    return await format_response_with_snapshot(result, include_snapshot=True)
+
+
+def main():
+    import sys
+
+    print("Starting Browser MCP server...", file=sys.stderr)
+    sys.stderr.flush()
+
+    env_port = os.getenv("PORT", "").strip()
+    if env_port.isdigit():
+        port = int(env_port)
+    else:
+        port = 8850
+    mcp.run(transport="streamable-http", port=port)
+
+
+if __name__ == "__main__":
+    main()