@mozilla/firefox-devtools-mcp-moz 0.9.12 → 0.9.15

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.
-- **Avoid enabling extra flags unless needed.** `--enable-script` and `--enable-privileged-context` significantly expand what the agent can do.
+- **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.
 
 See [SECURITY.md](SECURITY.md) for a full breakdown of risks and how to report vulnerabilities.
 
@@ -90,6 +90,7 @@ Then call tools like:
 - `list_pages`, `select_page`, `navigate_page`
 - `take_snapshot` then `click_by_uid` / `fill_by_uid`
 - `list_network_requests` (always‑on capture), `get_network_request`
+- `list_downloads` (always‑on capture), `set_download_behavior`
 - `screenshot_page`, `list_console_messages`
 
 ## CLI options
@@ -106,13 +107,44 @@ You can pass flags or environment variables (names on the right):
 - `--connect-existing` — attach to an already-running Firefox instead of launching a new one (`CONNECT_EXISTING=true`)
 - `--marionette-port` — Marionette port for connect-existing mode, default 2828 (`MARIONETTE_PORT`)
 - `--pref name=value` — set Firefox preference at startup via `moz:firefoxOptions` (repeatable)
-- `--enable-script` — enable the `evaluate_script` tool (executes arbitrary JavaScript in the page context) and debugging tools (list scripts, inspect source, set logpoints). Debugging tools require Firefox 153+. (`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`)
+- `--tool-preset` — select which tool modules to enable: `slim`, `basic` (default), `developer`, `mozilla`, or `all`. See [Tool modules and presets](#tool-modules-and-presets). (`TOOL_PRESET`)
+- `--tools` — explicit list of tool modules to enable, overriding `--tool-preset` entirely (e.g. `--tools pages network script`). See [Tool modules and presets](#tool-modules-and-presets).
+- `--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-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`)
 - `--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`
 
 
+### Tool modules and presets
+
+Tools are grouped into modules. You choose which modules to expose either with a named preset
+(`--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`.
+
+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`
+- `mozilla` — `developer` plus `prefs`, `privileged`
+- `all` — every module
+
+```bash
+# Use the developer preset (adds script and debugging tools)
+npx @mozilla/firefox-devtools-mcp --tool-preset developer
+
+# Enable only the modules you need
+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.
+
 ### Useful preferences (`--pref`)
 
 - remote.prefs.recommended=false. 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. Set remote.prefs.recommended to false to skip those and have a configuration closer to a regular Firefox instance.
@@ -141,19 +173,17 @@ Port forwarding between the host and device is handled automatically by geckodri
 
 ### Connect to existing Firefox
 
-Use `--connect-existing` to automate your real browsing session — with cookies, logins, and open tabs intact:
+Use `--connect-existing` to automate your real browsing session, with cookies, logins, and open tabs intact:
 
 ```bash
-# Start Firefox with Marionette enabled
-firefox --marionette
+# Start Firefox with Marionette and the Remote Agent (BiDi)
+firefox --marionette --remote-debugging-port
 
 # Run the MCP server
 npx @mozilla/firefox-devtools-mcp --connect-existing --marionette-port 2828
 ```
 
-Or set `marionette.enabled` to `true` in `about:config` (or `user.js`) to enable Marionette on every launch.
-
-BiDi-dependent features (console events, network events) are not available in connect-existing mode; all other features work normally.
+Both flags are required because the MCP uses both WebDriver Classic (`--marionette`) and WebDriver BiDi (`--remote-debugging-port`). If Firefox is only started with `--marionette`, the MCP server fails to connect and asks you to restart Firefox with both flags.
 
 > **Warning:** Do not leave Marionette enabled during normal browsing. It sets
 > `navigator.webdriver = true` and changes other browser fingerprint signals,
@@ -164,29 +194,58 @@ BiDi-dependent features (console events, network events) are not available in co
 ## Tool overview
 
 - Pages: list/new/navigate/select/close
-- Snapshot/UID: take/resolve/clear
+- 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)
 - Screenshot: page/by uid (with optional `saveTo` for CLI environments)
-- Script: evaluate_script
+- Script: evaluate_script (with 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
 - 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
 
-### Screenshot optimization for Claude Code
+### Saving bulky output to disk
+
+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
+`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:
 
-When using screenshots in Claude Code CLI, the base64 image data can consume significant context.
-Use the `saveTo` parameter to save screenshots to disk instead:
+- a file path (relative to the current working directory, or absolute within `~/.firefox-devtools-mcp`; parent directories are created)
+- an existing directory (a timestamped file is generated inside it)
+- `true` (a timestamped file is generated under `~/.firefox-devtools-mcp/output/`)
+
+The response returns the path and byte size. The saved file always holds the full,
+untruncated data: the inline size safeguards (console message caps, network header
+truncation, snapshot line caps) never apply to it.
+
+The text-producing tools (everything except the screenshots) also accept `preview`, a number
+of characters of the saved output to echo back inline as a short excerpt. Screenshots have no
+preview.
 
 ```
-screenshot_page({ saveTo: "/tmp/page.png" })
-screenshot_by_uid({ uid: "abc123", saveTo: "/tmp/element.png" })
+screenshot_page({ saveTo: "page.png" })
+take_snapshot({ saveTo: true })
+list_network_requests({ urlContains: "api", saveTo: "network.json" })
+evaluate_script({ function: "() => performance.getEntries()", saveTo: true, preview: 2000 })
 ```
 
-The file can then be viewed with Claude Code's `Read` tool without impacting context size.
+By default, save paths are restricted: relative paths resolve against the current working
+directory, and absolute paths are only allowed within `~/.firefox-devtools-mcp`. Paths that
+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.
 
 ## Local development