@mozilla/firefox-devtools-mcp 0.9.3 → 0.9.4

package/README.md

@@ -108,9 +108,31 @@ You can pass flags or environment variables (names on the right):
 - `--pref name=value` — set Firefox preference at startup via `moz:firefoxOptions` (repeatable)
 - `--enable-script` — enable the `evaluate_script` tool, which executes arbitrary JavaScript in the page context (`ENABLE_SCRIPT=true`)
 - `--enable-privileged-context` — enable privileged context tools: list/select privileged contexts, evaluate privileged scripts, get/set Firefox prefs, and list extensions. Requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1` (`ENABLE_PRIVILEGED_CONTEXT=true`)
+- `--android-device` — enable Firefox for Android mode; value is the ADB device serial (e.g. `emulator-5554`). Run `adb devices` to list connected devices. Omit the value or use `auto` to select the single connected device automatically.
+- `--android-package` — Android app package name, default `org.mozilla.firefox`. Other packages: `org.mozilla.firefox_beta` for Firefox Beta, `org.mozilla.fenix` for Firefox Nightly, `org.mozilla.fenix.debug` for Firefox Nightly Debug, `org.mozilla.geckoview_example` for geckoview (`ANDROID_PACKAGE`)
 
 > **Note on `--pref`:** When Firefox runs in automation, it applies [RecommendedPreferences](https://searchfox.org/firefox-main/source/remote/shared/RecommendedPreferences.sys.mjs) that modify browser behavior for testing. The `--pref` option allows overriding these defaults when needed.
 
+### Firefox for Android
+
+Use `--android-device` to automate Firefox running on an Android device. Requires `adb` on your PATH and geckodriver, which is managed automatically.
+
+```bash
+# List connected devices
+adb devices
+
+# Launch Firefox for Android on the single connected device
+npx firefox-devtools-mcp --android-device auto
+
+# Target a specific device
+npx firefox-devtools-mcp --android-device <serial>
+
+# Use Firefox Nightly instead
+npx firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix
+```
+
+Port forwarding between the host and device is handled automatically by geckodriver.
+
 ### Connect to existing Firefox
 
 Use `--connect-existing` to automate your real browsing session — with cookies, logins, and open tabs intact:

package/dist/index.js

@@ -155,6 +155,15 @@ var init_cli = __esm({
         description: "Set Firefox preference at startup via moz:firefoxOptions (format: name=value). Can be specified multiple times.",
         alias: "p"
       },
+      androidDevice: {
+        type: "string",
+        description: "Android device serial for launching Firefox for Android via ADB. Omit to auto-select the single connected device. Requires adb on PATH."
+      },
+      androidPackage: {
+        type: "string",
+        description: "Android app package name (default: org.mozilla.firefox). Use org.mozilla.fenix for Nightly.",
+        default: process.env.ANDROID_PACKAGE ?? "org.mozilla.firefox"
+      },
       enableScript: {
         type: "boolean",
         description: "Enable the evaluate_script tool, which allows executing arbitrary JavaScript in the page context.",
@@ -5172,8 +5181,8 @@ var init_regexes = __esm({
     _emoji = `^(\\p{Extended_Pictographic}|\\p{Emoji_Component})+$`;
     ipv4 = /^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$/;
     ipv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$/;
-    mac = (delimiter) => {
-      const escapedDelim = escapeRegex(delimiter ?? ":");
+    mac = (delimiter2) => {
+      const escapedDelim = escapeRegex(delimiter2 ?? ":");
       return new RegExp(`^(?:[0-9A-F]{2}${escapedDelim}){5}[0-9A-F]{2}$|^(?:[0-9a-f]{2}${escapedDelim}){5}[0-9a-f]{2}$`);
     };
     cidrv4 = /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/;
@@ -28049,50 +28058,61 @@ var init_profile = __esm({
 // src/firefox/core.ts
 import { Builder, Browser, Capabilities } from "selenium-webdriver";
 import firefox from "selenium-webdriver/firefox.js";
-import { mkdirSync as mkdirSync2, openSync, closeSync } from "fs";
+import { mkdirSync as mkdirSync2, openSync, closeSync, existsSync as existsSync2, readdirSync, statSync } from "fs";
 import { homedir } from "os";
-import { join as join2 } from "path";
-async function findGeckodriver() {
-  const path = await import("path");
-  const { execFileSync } = await import("child_process");
+import { join as join2, delimiter } from "path";
+function findGeckodriverInPath(binaryName) {
+  for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+    if (!dir) {
+      continue;
+    }
+    const candidate = join2(dir, binaryName);
+    if (existsSync2(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function findGeckodriverInSeleniumCache(binaryName) {
+  const cacheBase = join2(homedir(), ".cache/selenium/geckodriver");
   try {
-    const { createRequire } = await import("module");
-    const require2 = createRequire(import.meta.url);
-    const swPkg = require2.resolve("selenium-webdriver/package.json");
-    const swDir = path.dirname(swPkg);
-    const platform = process.platform === "win32" ? "windows" : process.platform === "darwin" ? "macos" : "linux";
-    const ext = process.platform === "win32" ? ".exe" : "";
-    const smBin = path.join(swDir, "bin", platform, `selenium-manager${ext}`);
-    const result = JSON.parse(
-      execFileSync(smBin, ["--driver", "geckodriver", "--output", "json"], { encoding: "utf-8" })
-    );
-    return result.result.driver_path;
-  } catch {
-    const os = await import("os");
-    const fs = await import("fs");
-    const cacheBase = path.join(os.homedir(), ".cache/selenium/geckodriver");
-    const ext = process.platform === "win32" ? ".exe" : "";
-    const binaryName = `geckodriver${ext}`;
-    try {
-      if (fs.existsSync(cacheBase)) {
-        for (const platformDir of fs.readdirSync(cacheBase)) {
-          const platformPath = path.join(cacheBase, platformDir);
-          if (!fs.statSync(platformPath).isDirectory()) {
-            continue;
-          }
-          for (const versionDir of fs.readdirSync(platformPath).sort().reverse()) {
-            const candidate = path.join(platformPath, versionDir, binaryName);
-            if (fs.existsSync(candidate)) {
-              return candidate;
-            }
-          }
+    if (!existsSync2(cacheBase)) {
+      return null;
+    }
+    for (const platformDir of readdirSync(cacheBase)) {
+      const platformPath = join2(cacheBase, platformDir);
+      if (!statSync(platformPath).isDirectory()) {
+        continue;
+      }
+      for (const versionDir of readdirSync(platformPath).sort().reverse()) {
+        const candidate = join2(platformPath, versionDir, binaryName);
+        if (existsSync2(candidate)) {
+          return candidate;
         }
       }
-    } catch {
     }
-    throw new Error("Cannot find geckodriver binary. Ensure selenium-webdriver is installed.");
+  } catch {
+  }
+  return null;
+}
+async function findGeckodriverInNpmPackage() {
+  try {
+    const { download } = await import("geckodriver");
+    log("geckodriver not found in PATH or selenium cache, downloading via npm package...");
+    return await download();
+  } catch {
+    return null;
   }
 }
+async function findGeckodriver() {
+  const ext = process.platform === "win32" ? ".exe" : "";
+  const binaryName = `geckodriver${ext}`;
+  const found = findGeckodriverInPath(binaryName) ?? findGeckodriverInSeleniumCache(binaryName) ?? await findGeckodriverInNpmPackage();
+  if (!found) {
+    throw new Error("Cannot find geckodriver binary. Ensure geckodriver is in PATH.");
+  }
+  return found;
+}
 var FirefoxCore;
 var init_core3 = __esm({
   "src/firefox/core.ts"() {
@@ -28113,12 +28133,35 @@ var init_core3 = __esm({
        * Launch Firefox (or connect to an existing instance) and establish BiDi connection
        */
       async connect() {
-        if (this.options.connectExisting) {
+        const isAndroid = this.options.androidDevice !== void 0;
+        if (isAndroid) {
+          log("Launching Firefox for Android via ADB...");
+        } else if (this.options.connectExisting) {
           log("Connecting to existing Firefox via Marionette...");
         } else {
           log("Launching Firefox via Selenium WebDriver BiDi...");
         }
-        if (this.options.connectExisting) {
+        if (isAndroid) {
+          const geckodriverPath = await findGeckodriver();
+          logDebug(`Using geckodriver: ${geckodriverPath}`);
+          const pkg = this.options.androidPackage ?? "org.mozilla.firefox";
+          const mozOptions = { androidPackage: pkg };
+          const deviceSerial = this.options.androidDevice;
+          if (deviceSerial && deviceSerial !== "auto") {
+            mozOptions.androidDeviceSerial = deviceSerial;
+          }
+          if (this.options.prefs) {
+            mozOptions.prefs = this.options.prefs;
+          }
+          const caps = new Capabilities();
+          caps.set("webSocketUrl", true);
+          caps.set("moz:firefoxOptions", mozOptions);
+          if (this.options.acceptInsecureCerts) {
+            caps.set("acceptInsecureCerts", true);
+          }
+          const serviceBuilder = new firefox.ServiceBuilder(geckodriverPath);
+          this.driver = firefox.Driver.createSession(caps, serviceBuilder.build());
+        } else if (this.options.connectExisting) {
           const port = this.options.marionettePort ?? 2828;
           const geckodriverPath = await findGeckodriver();
           logDebug(`Using geckodriver: ${geckodriverPath}`);
@@ -28177,7 +28220,14 @@ var init_core3 = __esm({
               firefoxOptions.setPreference(name, value);
             }
           }
-          const serviceBuilder = new firefox.ServiceBuilder();
+          let serviceBuilder;
+          if (process.platform === "win32") {
+            const geckodriverPath = await findGeckodriver();
+            logDebug(`Using geckodriver: ${geckodriverPath}`);
+            serviceBuilder = new firefox.ServiceBuilder(geckodriverPath);
+          } else {
+            serviceBuilder = new firefox.ServiceBuilder();
+          }
           if (this.logFilePath) {
             this.logFileFd = openSync(this.logFilePath, "a");
             serviceBuilder.setStdio(["ignore", this.logFileFd, this.logFileFd]);
@@ -29051,22 +29101,41 @@ var init_dom = __esm({
 });
 
 // src/firefox/pages.ts
-var PageManagement;
+function isCommonScheme(url2) {
+  try {
+    return COMMON_URL_SCHEMES.includes(new URL(url2).protocol);
+  } catch {
+    return false;
+  }
+}
+var COMMON_URL_SCHEMES, PageManagement;
 var init_pages = __esm({
   "src/firefox/pages.ts"() {
     "use strict";
     init_logger();
+    COMMON_URL_SCHEMES = ["http:", "https:", "data:", "blob:", "file:"];
     PageManagement = class {
-      constructor(driver, getCurrentContextId, setCurrentContextId) {
+      constructor(driver, getCurrentContextId, setCurrentContextId, sendBiDiCommand) {
         this.driver = driver;
         this.getCurrentContextId = getCurrentContextId;
         this.setCurrentContextId = setCurrentContextId;
+        this.sendBiDiCommand = sendBiDiCommand;
       }
       /**
-       * Navigate to URL
+       * Navigate to URL using BiDi
        */
       async navigate(url2) {
-        await this.driver.get(url2);
+        const contextId = this.getCurrentContextId();
+        if (!contextId) {
+          throw new Error(`Cannot navigate: no browsing context ID`);
+        }
+        const wait = isCommonScheme(url2) ? "interactive" : "none";
+        await this.sendBiDiCommand("browsingContext.navigate", {
+          context: contextId,
+          url: url2,
+          wait
+        });
+        logDebug(`BiDi navigate (wait:${wait}) to: ${url2}`);
         log(`Navigated to: ${url2}`);
       }
       /**
@@ -29188,7 +29257,7 @@ var init_pages = __esm({
         const newIdx = handles.length - 1;
         this.setCurrentContextId(handles[newIdx]);
         this.cachedSelectedIdx = newIdx;
-        await this.driver.get(url2);
+        await this.navigate(url2);
         return newIdx;
       }
       /**
@@ -29673,7 +29742,8 @@ var init_firefox = __esm({
         this.pages = new PageManagement(
           driver,
           () => this.core.getCurrentContextId(),
-          (id) => this.core.setCurrentContextId(id)
+          (id) => this.core.setCurrentContextId(id),
+          (method, params) => this.core.sendBiDiCommand(method, params)
         );
         if (this.consoleEvents) {
           try {
@@ -31586,7 +31656,7 @@ var init_utilities = __esm({
 });
 
 // src/tools/firefox-management.ts
-import { readFileSync as readFileSync2, existsSync as existsSync2, statSync } from "fs";
+import { readFileSync as readFileSync2, existsSync as existsSync3, statSync as statSync2 } from "fs";
 async function handleGetFirefoxLogs(input) {
   try {
     const {
@@ -31601,11 +31671,11 @@ async function handleGetFirefoxLogs(input) {
         "No output capture configured. Use --env to set environment variables or --output-file to enable output capture."
       );
     }
-    if (!existsSync2(logFilePath)) {
+    if (!existsSync3(logFilePath)) {
       return successResponse(`Output file not found: ${logFilePath}`);
     }
     if (since !== void 0) {
-      const stats = statSync(logFilePath);
+      const stats = statSync2(logFilePath);
       const ageSeconds = (Date.now() - stats.mtimeMs) / 1e3;
       if (ageSeconds > since) {
         return successResponse(
@@ -31674,8 +31744,8 @@ async function handleGetFirefoxInfo(_input) {
     if (logFilePath) {
       info.push("");
       info.push(`Output File: ${logFilePath}`);
-      if (existsSync2(logFilePath)) {
-        const stats = statSync(logFilePath);
+      if (existsSync3(logFilePath)) {
+        const stats = statSync2(logFilePath);
         const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
         info.push(`  Size: ${sizeMB} MB`);
         info.push(`  Last Modified: ${stats.mtime.toISOString()}`);
@@ -32577,7 +32647,9 @@ async function getFirefox() {
       marionettePort: args.marionettePort,
       env: envVars,
       logFile: args.outputFile ?? void 0,
-      prefs
+      prefs,
+      androidDevice: args.androidDevice ?? void 0,
+      androidPackage: args.androidPackage ?? void 0
     };
   }
   firefox2 = new FirefoxClient(options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mozilla/firefox-devtools-mcp",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Model Context Protocol (MCP) server for Firefox DevTools automation",
   "author": "Mozilla",
   "license": "MIT OR Apache-2.0",