From ce41b8e1f0fe73625876997b12e8f941cee93985 Mon Sep 17 00:00:00 2001 From: Ksenia Berezina Date: Sun, 15 Nov 2026 20:14:09 -0500 Subject: [PATCH 1/2] Add Android browsers support for autowebcompat --- .../autowebcompat_tools/android_browser.py | 279 ++++++++++++++++++ 1 file changed, 279 insertions(+) create mode 100644 libs/autowebcompat-tools/autowebcompat_tools/android_browser.py diff --git a/libs/autowebcompat-tools/autowebcompat_tools/android_browser.py b/libs/autowebcompat-tools/autowebcompat_tools/android_browser.py new file mode 100644 index 0000000000..069cf71133 --- /dev/null +++ b/libs/autowebcompat-tools/autowebcompat_tools/android_browser.py @@ -0,0 +1,279 @@ +import json +import logging +import socket +import tempfile +import time +from abc import ABC, abstractmethod +from contextlib import contextmanager +from dataclasses import dataclass +from pathlib import Path +from urllib.request import urlopen + +import mozdownload + +from . import android_emulator + +logger = logging.getLogger(__name__) +FIREFOX_MARIONETTE_PORT = 2829 +FIREFOX_BIDI_PORT = 9223 +CHROME_DEVTOOLS_PORT = 9222 +CHROME_PACKAGE = "com.android.chrome" +CHROME_SOCKET = "chrome_devtools_remote" +FENIX_PACKAGES = {"nightly": "org.mozilla.fenix", "stable": "org.mozilla.firefox"} + + +def prepare_chrome() -> None: + """Configure the mobile Chrome preinstalled in the system image.""" + # Select Chrome as the debug app so it reads our startup flags, + # which skip welcome screens and configure its remote debugging socket + android_emulator.adb("shell", "am", "set-debug-app", "--persistent", CHROME_PACKAGE) + android_emulator.adb( + "shell", + "echo 'chrome --disable-fre --no-first-run --no-default-browser-check " + f"--remote-debugging-socket-name={CHROME_SOCKET}' " + "> /data/local/tmp/chrome-command-line", + ) + android_emulator.adb("shell", "chmod", "644", "/data/local/tmp/chrome-command-line") + + +def wait_for_firefox(timeout: int = 120) -> None: + """Wait for the Marionette greeting, without creating a session.""" + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + # adb forward accepts the connection even when nothing listens on the + # device, then closes it, so only a greeting proves Firefox is ready. + try: + with socket.create_connection( + ("127.0.0.1", FIREFOX_MARIONETTE_PORT), timeout=2 + ) as connection: + greeting = b"" + while b'"applicationType":"gecko"' not in greeting: + chunk = connection.recv(256) + if not chunk or len(greeting) > 4096: + break + greeting += chunk + else: + logger.info("Firefox Marionette is ready for MCP attachment") + return + except OSError: + pass + time.sleep(1) + raise android_emulator.AndroidError( + f"Firefox Marionette did not become ready within {timeout}s" + ) + + +def chrome_ready(port: int = CHROME_DEVTOOLS_PORT) -> bool: + try: + with urlopen(f"http://127.0.0.1:{port}/json/version", timeout=2) as response: + version = json.load(response) + except OSError, ValueError: + return False + if not version.get("webSocketDebuggerUrl"): + return False + logger.info("%s DevTools ready on port %s", version.get("Browser"), port) + return True + + +def forward_chrome_devtools(port: int = CHROME_DEVTOOLS_PORT) -> None: + """Expose Chrome's on-device DevTools socket on a host port.""" + android_emulator.adb("forward", f"tcp:{port}", f"localabstract:{CHROME_SOCKET}") + deadline = time.monotonic() + 60 + while time.monotonic() < deadline: + if chrome_ready(port): + return + time.sleep(1) + raise android_emulator.AndroidError( + f"Chrome DevTools on port {port} did not become ready" + ) + + +def install_fenix(channel: str) -> None: + package = FENIX_PACKAGES[channel] + if android_emulator.adb("shell", "pm", "path", package, check=False).strip(): + return + with tempfile.TemporaryDirectory(prefix="fenix-") as tmp: + options = ( + {"branch": "mozilla-central"} + if channel == "nightly" + else {"version": "latest"} + ) + scraper = mozdownload.FactoryScraper( + "daily" if channel == "nightly" else "release", + application="fenix", + platform="android-x86_64", + destination=tmp, + **options, + ) + android_emulator.install_apk(Path(scraper.download())) + + +class AndroidBrowser(ABC): + name: str + ports: tuple[int, ...] + + @property + @abstractmethod + def package(self) -> str: ... + + @property + @abstractmethod + def endpoint(self) -> str: ... + + @abstractmethod + def start(self, *, fresh: bool = False) -> None: ... + + @abstractmethod + def is_ready(self) -> bool: ... + + def __str__(self) -> str: + return f"android:{self.name}" + + @staticmethod + def parse(value: str) -> AndroidBrowser: + _, name, *channel = value.split(":") + return AndroidChrome() if name == "chrome" else AndroidFirefox(*channel) + + def is_alive(self) -> bool: + return bool( + android_emulator.adb("shell", "pidof", self.package, check=False).strip() + ) + + def activate(self) -> None: + """Bring a browser forward, restoring automation if it stopped working.""" + if not self.is_ready(): + # The other browser may have replaced Android's global debug-app + # selection. Restore it before relaunching so automation flags load. + self.start() + return + android_emulator.start_app(self.package) + + def stop(self) -> None: + android_emulator.adb("shell", "am", "force-stop", self.package) + for port in self.ports: + android_emulator.adb("forward", "--remove", f"tcp:{port}", check=False) + + +@dataclass(frozen=True) +class AndroidFirefox(AndroidBrowser): + channel: str = "stable" + name = "firefox" + ports = (FIREFOX_MARIONETTE_PORT, FIREFOX_BIDI_PORT) + + def __str__(self) -> str: + return f"{super().__str__()}:{self.channel}" + + @property + def package(self) -> str: + return FENIX_PACKAGES[self.channel] + + @property + def endpoint(self) -> str: + return f"ws://127.0.0.1:{FIREFOX_BIDI_PORT}/session" + + def is_ready(self) -> bool: + return self.is_alive() + + def start(self, *, fresh: bool = False) -> None: + """Launch a browser with automation enabled. + + ``fresh`` wipes Firefox's app data first, giving it a clean profile. + Relaunches within a task keep the profile. + """ + install_fenix(self.channel) + # Nightly and release use the same device ports. Stopping only the + # requested package lets a previous channel answer the new connection. + channels = [AndroidFirefox(channel) for channel in FENIX_PACKAGES] + for firefox in channels: + firefox.stop() + # force-stop can return before the process exits; a survivor would + # answer on the shared ports and the run would test the wrong channel. + deadline = time.monotonic() + 10 + while running := [ + firefox.package for firefox in channels if firefox.is_alive() + ]: + if time.monotonic() > deadline: + raise android_emulator.AndroidError( + f"Firefox packages did not stop: {running}" + ) + time.sleep(0.2) + if fresh: + output = android_emulator.adb("shell", "pm", "clear", self.package) + if "Success" not in output: + raise android_emulator.AndroidError( + f"pm clear {self.package} failed: {output.strip()}" + ) + logger.info("Starting Firefox %s: package=%s", self.channel, self.package) + config = { + "env": {"MOZ_REMOTE_ALLOW_SYSTEM_ACCESS": "1"}, + "args": [ + "--marionette", + "--remote-debugging-port", + str(FIREFOX_BIDI_PORT), + "--remote-allow-hosts", + "localhost,127.0.0.1", + ], + "prefs": {"marionette.port": FIREFOX_MARIONETTE_PORT}, + } + + destination = f"/data/local/tmp/{self.package}-geckoview-config.yaml" + android_emulator.adb("shell", f"echo '{json.dumps(config)}' > {destination}") + android_emulator.adb("shell", "chmod", "644", destination) + android_emulator.adb( + "shell", "am", "set-debug-app", "--persistent", self.package + ) + for port in self.ports: + android_emulator.adb("forward", f"tcp:{port}", f"tcp:{port}") + android_emulator.am_start( + "-n", + f"{self.package}/org.mozilla.fenix.IntentReceiverActivity", + "-a", + "android.intent.action.VIEW", + "-d", + "about:blank", + "--ez", + "automationtest", + "true", + "--ez", + "performancetest", + "true", + ) + wait_for_firefox() + + +@dataclass(frozen=True) +class AndroidChrome(AndroidBrowser): + name = "chrome" + ports = (CHROME_DEVTOOLS_PORT,) + + @property + def package(self) -> str: + return CHROME_PACKAGE + + @property + def endpoint(self) -> str: + return f"http://127.0.0.1:{CHROME_DEVTOOLS_PORT}" + + def is_ready(self) -> bool: + return chrome_ready() + + def start(self, *, fresh: bool = False) -> None: + prepare_chrome() + self.stop() + android_emulator.start_app(self.package, "about:blank") + forward_chrome_devtools() + + +class AndroidFirefoxBrowsers: + nightly = AndroidFirefox("nightly") + stable = AndroidFirefox("stable") + + +class AndroidChromeBrowsers: + stable = AndroidChrome() + + +@contextmanager +def AndroidEnvironment(logcat: Path | None = None): + with android_emulator.emulator(logcat): + yield AndroidFirefoxBrowsers(), AndroidChromeBrowsers() From 456c3e2e22cca0c1f248c1b6dc9301d74a38295b Mon Sep 17 00:00:00 2001 From: Ksenia Berezina Date: Thu, 5 Nov 2026 01:23:17 -0500 Subject: [PATCH 2/2] Connect Android browsers to DevTools MCP servers --- .../autowebcompat_tools/android_mcp_proxy.py | 124 ++++++++++++++++++ .../autowebcompat_tools/mcp_servers.py | 61 +++++++++ libs/autowebcompat-tools/pyproject.toml | 1 + uv.lock | 2 + 4 files changed, 188 insertions(+) create mode 100644 libs/autowebcompat-tools/autowebcompat_tools/android_mcp_proxy.py diff --git a/libs/autowebcompat-tools/autowebcompat_tools/android_mcp_proxy.py b/libs/autowebcompat-tools/autowebcompat_tools/android_mcp_proxy.py new file mode 100644 index 0000000000..5df3e97116 --- /dev/null +++ b/libs/autowebcompat-tools/autowebcompat_tools/android_mcp_proxy.py @@ -0,0 +1,124 @@ +"""Prepare Android browsers before forwarding calls to their DevTools MCP servers. + +The existing MCP servers connect to the browsers' debugging endpoints, but do +not handle our Android app setup or foreground switching. This proxy starts or +activates the appropriate browser before each tool call, installs any extensions +requested by the task, and forwards the call to the existing server. It also +restarts Firefox after a reset so a Puppeteer script can take over its session. + +Keeping this preparation here lets the agent use the existing browser tools +without having to issue separate Android setup commands between tool calls. +Callers launch this module with a browser identifier, extension slugs, and the +upstream MCP server command. +""" + +import asyncio +import base64 +import contextlib +import json +import logging +import sys +import tempfile +from datetime import timedelta +from pathlib import Path + +from mcp import ClientSession, StdioServerParameters +from mcp.client.stdio import stdio_client +from mcp.server import Server +from mcp.server.stdio import stdio_server + +from autowebcompat_tools.amo import download, extract_extension_id, resolve_xpi_url +from autowebcompat_tools.android_browser import AndroidBrowser + +logger = logging.getLogger(__name__) + + +async def install_extension(session, slug): + """Install a signed AMO addon using the upstream MCP connection.""" + + def fetch(): + with tempfile.TemporaryDirectory(prefix="android-addon-") as tmp: + url, version = resolve_xpi_url(slug) + path = Path(tmp) / "addon.xpi" + download(url, path) + return ( + version, + extract_extension_id(path), + base64.b64encode(path.read_bytes()).decode("ascii"), + ) + + version, extension_id, encoded = await asyncio.to_thread(fetch) + logger.info("Installing Android extension %s %s through Firefox MCP", slug, version) + result = await session.call_tool( + "install_extension", + { + "type": "base64", + "value": encoded, + "permanent": True, + }, + ) + text = "\n".join(block.text for block in result.content if block.type == "text") + if result.isError or f"ID: {extension_id}" not in text: + raise RuntimeError(f"Android extension installation failed: {text}") + + +class AndroidTools: + def __init__(self, browser, session, extensions=()): + self.browser = browser + self.session = session + self.extensions = extensions + self.started = False + self.installed = False + self.lock = asyncio.Lock() + + async def call(self, name, arguments): + async with self.lock: + with contextlib.redirect_stdout(sys.stderr): + if self.started: + await asyncio.to_thread(self.browser.activate) + else: + await asyncio.to_thread(self.browser.start, fresh=True) + self.started = True + if not self.installed: + for slug in self.extensions: + await install_extension(self.session, slug) + self.installed = True + result = await self.session.call_tool(name, arguments) + if name == "restart_firefox": + self.started = False + with contextlib.redirect_stdout(sys.stderr): + await asyncio.to_thread(self.browser.start) + self.started = True + return result + + +async def serve(browser, command, extensions=()): + parameters = StdioServerParameters(command=command[0], args=command[1:]) + async with ( + stdio_client(parameters) as (reader, writer), + ClientSession( + reader, writer, read_timeout_seconds=timedelta(seconds=180) + ) as session, + ): + await session.initialize() + tools = AndroidTools(browser, session, extensions) + server = Server("android-devtools") + + @server.list_tools() + async def list_tools(): + return (await session.list_tools()).tools + + @server.call_tool() + async def call_tool(name, arguments): + return await tools.call(name, arguments) + + async with stdio_server() as (incoming, outgoing): + await server.run(incoming, outgoing, server.create_initialization_options()) + + +if __name__ == "__main__": + logging.basicConfig(level=logging.INFO, stream=sys.stderr) + marker, encoded_extensions, *command = sys.argv[1:] + asyncio.run( + serve(AndroidBrowser.parse(marker), command, json.loads(encoded_extensions)) + ) diff --git a/libs/autowebcompat-tools/autowebcompat_tools/mcp_servers.py b/libs/autowebcompat-tools/autowebcompat_tools/mcp_servers.py index 0527d3b6e4..2eda2b7cbc 100644 --- a/libs/autowebcompat-tools/autowebcompat_tools/mcp_servers.py +++ b/libs/autowebcompat-tools/autowebcompat_tools/mcp_servers.py @@ -4,10 +4,19 @@ each agent image with ``npm ci`` (see the agents' Dockerfiles). """ +import json +import sys +from collections.abc import Sequence from pathlib import Path from claude_agent_sdk.types import McpStdioServerConfig +from autowebcompat_tools.android_browser import ( + CHROME_DEVTOOLS_PORT, + FIREFOX_MARIONETTE_PORT, + AndroidBrowser, +) + NODE_MODULES = Path("/app/node_modules") @@ -103,3 +112,55 @@ def build_chrome_devtools_server( args += ["--chromeArg=--no-sandbox", "--chromeArg=--disable-setuid-sandbox"] return McpStdioServerConfig(command=resolve_bin("chrome-devtools-mcp"), args=args) + + +def _build_android_server( + browser: AndroidBrowser, + extensions: Sequence[str], + bin_name: str, + args: list[str], +) -> McpStdioServerConfig: + return McpStdioServerConfig( + command=sys.executable, + args=[ + "-m", + "autowebcompat_tools.android_mcp_proxy", + str(browser), + json.dumps(list(extensions)), + resolve_bin(bin_name), + *args, + ], + ) + + +def build_android_firefox_devtools_server( + browser: AndroidBrowser, + *, + enable_privileged_context: bool = False, + extensions: Sequence[str] = (), +) -> McpStdioServerConfig: + args = [ + "--connect-existing", + "--marionette-port", + str(FIREFOX_MARIONETTE_PORT), + "--enable-script", + ] + if enable_privileged_context: + args.append("--enable-privileged-context") + return _build_android_server(browser, extensions, "firefox-devtools-mcp-moz", args) + + +def build_android_chrome_devtools_server( + browser: AndroidBrowser, +) -> McpStdioServerConfig: + return _build_android_server( + browser, + (), + "chrome-devtools-mcp", + [ + "--browserUrl", + f"http://127.0.0.1:{CHROME_DEVTOOLS_PORT}", + "--usageStatistics=false", + "--performanceCrux=false", + ], + ) diff --git a/libs/autowebcompat-tools/pyproject.toml b/libs/autowebcompat-tools/pyproject.toml index 36d138662d..b90fb73835 100644 --- a/libs/autowebcompat-tools/pyproject.toml +++ b/libs/autowebcompat-tools/pyproject.toml @@ -6,6 +6,7 @@ requires-python = ">=3.14" dependencies = [ "claude-agent-sdk>=0.2.165", "hackbot-runtime[claude-sdk]", + "mcp>=1.0.0", "mozdownload", "mozinstall", "pydantic>=2.0.0", diff --git a/uv.lock b/uv.lock index fb678a261c..fb2beeef02 100644 --- a/uv.lock +++ b/uv.lock @@ -508,6 +508,7 @@ source = { editable = "libs/autowebcompat-tools" } dependencies = [ { name = "claude-agent-sdk" }, { name = "hackbot-runtime", extra = ["claude-sdk"] }, + { name = "mcp" }, { name = "mozdownload" }, { name = "mozinstall" }, { name = "pydantic" }, @@ -524,6 +525,7 @@ dev = [ requires-dist = [ { name = "claude-agent-sdk", specifier = ">=0.2.165" }, { name = "hackbot-runtime", extras = ["claude-sdk"], editable = "libs/hackbot-runtime" }, + { name = "mcp", specifier = ">=1.0.0" }, { name = "mozdownload" }, { name = "mozinstall" }, { name = "pydantic", specifier = ">=2.0.0" },