@mozilla/firefox-devtools-mcp 0.9.15 → 0.10.1

package/README.md

@@ -19,7 +19,7 @@ Browser MCP servers carry inherent risks. A few key practices:
 
 - **Use a dedicated Firefox profile.** Never run the server against your regular profile — the agent has access to whatever the browser can reach, including cookies and saved sessions.
 - **Be cautious about which sites you visit.** Pages can return content designed to manipulate the agent (prompt injection). Stick to sites you control or trust.
-- **Enable only the tool modules you need.** Higher presets such as `--tool-preset developer` (script, debugging) and `--tool-preset mozilla` (privileged context) significantly expand what the agent can do.
+- **Enable only the tool modules you need.** The default `basic` preset already includes `evaluate_script`; `--tool-preset slim` drops it. Higher presets such as `--tool-preset developer` (debugging, network, console, profiler) and `--tool-preset mozilla` (privileged context) expand what the agent can do further.
 
 See [SECURITY.md](SECURITY.md) for a full breakdown of risks and how to report vulnerabilities.
 
@@ -28,19 +28,17 @@ See [SECURITY.md](SECURITY.md) for a full breakdown of risks and how to report v
 - Node.js ≥ 20.19.0
 - Firefox 100+ installed (auto‑detected, or pass `--firefox-path`)
 
-## Install and use with Claude Code (npx)
+## Install and use with Claude Code or Codex (npx)
 
-Recommended: use npx so you always run the latest published version from npm.
+Recommended: use `npx` so you run the latest published version from npm.
 
-Option A — Claude Code CLI
+### Option A — CLI
+
+#### Claude Code
 
 ```bash
 claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest
-```
-
-Pass options either as args or env vars. Examples:
 
-```bash
 # Headless + viewport via args
 claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720
 
@@ -50,13 +48,27 @@ claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest \
   --env FIREFOX_HEADLESS=true
 ```
 
-Option B — Edit Claude Code settings JSON
+#### Codex
+
+```bash
+codex mcp add firefox-devtools -- npx @mozilla/firefox-devtools-mcp@latest
+
+# Headless + viewport via args
+codex mcp add firefox-devtools -- \
+  npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720
+
+# Or via environment variables
+codex mcp add firefox-devtools \
+  --env START_URL=https://example.com \
+  --env FIREFOX_HEADLESS=true \
+  -- npx @mozilla/firefox-devtools-mcp@latest
+```
+
+### Option B — Edit the configuration file
 
-Add to your Claude Code config file:
+#### Claude Code
 
-- macOS: `~/Library/Application Support/Claude/Code/mcp_settings.json`
-- Linux: `~/.config/claude/code/mcp_settings.json`
-- Windows: `%APPDATA%\Claude\Code\mcp_settings.json`
+Add to Claude Code’s mcp_settings.json:
 
 ```json
 {
@@ -72,7 +84,20 @@ Add to your Claude Code config file:
 }
 ```
 
-Option C — Helper script (local dev build)
+#### Codex
+
+Add to ~/.codex/config.toml:
+
+```toml
+[mcp_servers.firefox-devtools]
+command = "npx"
+args = ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"]
+
+[mcp_servers.firefox-devtools.env]
+START_URL = "about:blank"
+```
+
+### Option C — Helper script (local dev build)
 
 ```bash
 npm run setup
@@ -112,7 +137,9 @@ You can pass flags or environment variables (names on the right):
 - `--enable-script` — _deprecated, use `--tool-preset developer` or `--tools ... script debugging`._ Selects the `developer` tool preset. (`ENABLE_SCRIPT=true`)
 - `--enable-privileged-context` — _deprecated, use `--tool-preset mozilla` or `--tools ... privileged prefs`._  Selects the `mozilla` tool preset. 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-wipe-app-data` — confirm that Android mode wipes all data of the target app. Required together with `--android-device`. (`ANDROID_WIPE_APP_DATA=true`)
 - `--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`)
+- `--unrestricted-save-paths` — let the `saveTo` parameter write anywhere on disk instead of the default roots. See [Saving bulky output to disk](#saving-bulky-output-to-disk) and the security note in [SECURITY.md](SECURITY.md). (`UNRESTRICTED_SAVE_PATHS=true`)
 - `--log-file` — write MCP server logs to a file instead of stderr. Useful for debugging sessions with MCP clients that hide server output. Set `DEBUG=*` to also include verbose debug logs. Example: `--log-file /tmp/firefox-mcp.log`
 
 
@@ -122,20 +149,24 @@ Tools are grouped into modules. You choose which modules to expose either with a
 (`--tool-preset`) or with an explicit list (`--tools`). When both are given, `--tools` wins and
 the preset is ignored.
 
-Modules: `pages`, `snapshot`, `input`, `network`, `console`, `screenshot`, `utilities`,
-`management`, `webextension`, `profiler`, `screencast`, `script`, `debugging`, `prefs`,
-`privileged`.
+Modules: `pages`, `snapshot`, `input`, `network`, `console`, `screenshot`, `downloads`,
+`utilities`, `management`, `webextension`, `profiler`, `screencast`, `script`, `debugging`,
+`prefs`, `privileged`.
 
 Presets (each is a superset of the previous):
 
-- `slim` — `pages`, `snapshot`, `input`, `network`, `console`
-- `basic` (default) — `slim` plus `screenshot`, `utilities`, `management`, `webextension`, `profiler`, `screencast`
-- `developer` — `basic` plus `script`, `debugging`
+- `slim` — `pages`, `snapshot`, `input`, `screenshot`
+- `basic` (default) — `slim` plus `downloads`, `script`, `utilities`, `management`, `webextension`, `screencast`
+- `developer` — `basic` plus `debugging`, `network`, `console`, `profiler`
 - `mozilla` — `developer` plus `prefs`, `privileged`
 - `all` — every module
 
+Note that `basic`, the default, includes `script` and therefore the `evaluate_script` tool.
+See [SECURITY.md](SECURITY.md#tool-modules-and-presets) for what that means for the attack
+surface, and use `--tool-preset slim` or an explicit `--tools` list to drop it.
+
 ```bash
-# Use the developer preset (adds script and debugging tools)
+# Use the developer preset (adds network, console, debugging and profiler tools)
 npx @mozilla/firefox-devtools-mcp --tool-preset developer
 
 # Enable only the modules you need
@@ -143,7 +174,8 @@ npx @mozilla/firefox-devtools-mcp --tools pages network console
 ```
 
 The `prefs` and `privileged` modules require `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1` and are only
-available in the Mozilla-internal build; the public package silently skips them even if requested.
+available in the Mozilla-internal build. The public package skips them even if requested and
+logs a warning naming the modules it dropped.
 
 ### Useful preferences (`--pref`)
 
@@ -155,18 +187,27 @@ available in the Mozilla-internal build; the public package silently skips them
 
 Use `--android-device` to automate Firefox running on an Android device. Requires `adb` on your PATH and geckodriver, which is managed automatically.
 
+> **Warning:** Android mode wipes all data of the target app before every session.
+> Tabs, history, bookmarks, passwords, cookies and settings are all lost. geckodriver runs
+> `adb shell pm clear <package>` when creating the session and offers no way to skip it,
+> then runs the session on its own temporary profile which is deleted afterwards.
+> Because of this, `--android-device` requires `--android-wipe-app-data`, and you should
+> install a build dedicated to automation rather than automating the browser you use.
+> [Bug 2064088](https://bugzilla.mozilla.org/show_bug.cgi?id=2064088) tracks adding an
+> option to geckodriver to keep the existing app data.
+
 ```bash
 # List connected devices
 adb devices
 
 # Launch Firefox for Android on the single connected device
-npx @mozilla/firefox-devtools-mcp --android-device auto
+npx @mozilla/firefox-devtools-mcp --android-device auto --android-wipe-app-data
 
 # Target a specific device
-npx @mozilla/firefox-devtools-mcp --android-device <serial>
+npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-wipe-app-data
 
 # Use Firefox Nightly instead
-npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix
+npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix --android-wipe-app-data
 ```
 
 Port forwarding between the host and device is handled automatically by geckodriver.
@@ -193,22 +234,18 @@ Both flags are required because the MCP uses both WebDriver Classic (`--marionet
 
 ## Tool overview
 
-- Pages: list/new/navigate/select/close
+- Pages: list/new/navigate/select/close/get_page_text (get_page_text supports optional `saveTo`)
 - Snapshot/UID: take/resolve/clear (take supports optional `saveTo`)
 - Input: click/hover/fill/drag/upload/form fill
-<<<<<<< HEAD
 - Network: list/get (ID‑first, filters, always‑on capture; both support optional `saveTo`)
-- Console: list/clear (list supports optional `saveTo`)
-=======
-- Network: list/get (ID‑first, filters, always‑on capture)
 - Downloads: list_downloads/clear_downloads (always‑on capture), set_download_behavior (allow/deny/default)
-- Console: list/clear
->>>>>>> 6873767 (Bug 2055949 - [firefox-devtools-mcp] expose download events to firefox devtools mcp)
+- Console: list/clear (list supports optional `saveTo`)
 - Screenshot: page/by uid (with optional `saveTo` for CLI environments)
-- Script: evaluate_script (with optional `saveTo` for bulky results)
+- Script: evaluate_script (optional `sandbox` for an isolated realm; optional `saveTo` for bulky results)
 - Privileged Context: list/select privileged ("chrome") contexts, evaluate_privileged_script (requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
 - WebExtension: install_extension, uninstall_extension, list_extensions (list requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
-- Firefox Management: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs
+- Firefox Management: get_firefox_info, get_firefox_output, restart_firefox
+- Firefox Preferences: get_firefox_prefs, set_firefox_prefs (requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
 - Profiler: profiler_is_active, profiler_start (preset or explicit config), profiler_stop (saves profile to downloads directory)
 - Screencast: screencast_start (records the page viewport to a video file in the downloads directory), screencast_stop (requires Firefox 154+)
 - Utilities: accept/dismiss dialog, history back/forward, set viewport
@@ -217,7 +254,8 @@ Both flags are required because the MCP uses both WebDriver Classic (`--marionet
 
 Large tool output can consume significant context in CLI clients like Claude Code. The
 `screenshot_page`, `screenshot_by_uid`, `take_snapshot`, `list_console_messages`,
-`list_network_requests`, `get_network_request`, `evaluate_script`, and
+`list_network_requests`, `get_network_request`, `get_page_text`,
+`evaluate_script`, and
 `evaluate_privileged_script` tools accept an optional `saveTo` parameter that writes the
 result to a file instead of returning it inline. `saveTo` takes one of three forms:
 
@@ -245,7 +283,7 @@ directory, and absolute paths are only allowed within `~/.firefox-devtools-mcp`.
 escape these locations are rejected. Start the server with `--unrestricted-save-paths` to
 write to arbitrary locations, including absolute paths outside that directory.
 
-Saved files can then be viewed with Claude Code's `Read` tool without impacting context size.
+Saved files can then be viewed for instance with Claude Code's `Read` tool without impacting context size.
 
 ## Local development
 
@@ -266,7 +304,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on local development, te
 
 - Firefox not found: pass `--firefox-path "/Applications/Firefox.app/Contents/MacOS/firefox"` (macOS) or the correct path on your OS.
 - First run is slow: Selenium sets up the BiDi session; subsequent runs are faster.
-- Stale UIDs after navigation: take a fresh snapshot (`take_snapshot`) before using UID tools.
+- Stale UIDs: a UID stays valid until its element is removed or the page navigates; take a fresh snapshot (`take_snapshot`) when a UID tool reports one is gone.
 - Windows 10: Error during discovery for MCP server 'firefox-devtools': MCP error -32000: Connection closed
   - **Solution 1** Wrap with `cmd /c` ([details](https://github.com/modelcontextprotocol/servers/issues/1082#issuecomment-2791786310)):