@mozilla/firefox-devtools-mcp 0.9.4 → 0.9.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +23 -16
  2. package/dist/index.js +980 -175
  3. package/package.json +6 -5
  4. package/scripts/test-closed-window.js +216 -0
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Firefox DevTools MCP
2
2
 
3
- [![npm version](https://badge.fury.io/js/firefox-devtools-mcp.svg)](https://www.npmjs.com/package/firefox-devtools-mcp)
3
+ [![npm version](https://badge.fury.io/js/@mozilla%2Ffirefox-devtools-mcp.svg)](https://www.npmjs.com/package/mozilla/firefox-devtools-mcp)
4
4
  [![CI](https://github.com/mozilla/firefox-devtools-mcp/workflows/CI/badge.svg)](https://github.com/mozilla/firefox-devtools-mcp/actions/workflows/ci.yml)
5
5
  [![codecov](https://codecov.io/gh/mozilla/firefox-devtools-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/mozilla/firefox-devtools-mcp)
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE-MIT) [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE-APACHE)
@@ -11,7 +11,7 @@ Model Context Protocol server for automating Firefox via WebDriver BiDi (through
11
11
 
12
12
  Repository: https://github.com/mozilla/firefox-devtools-mcp
13
13
 
14
- > **Note**: This MCP server requires a local Firefox browser installation and cannot run on cloud hosting services like glama.ai. Use `npx firefox-devtools-mcp@latest` to run locally, or use Docker with the provided Dockerfile.
14
+ > **Note**: This MCP server requires a local Firefox browser installation and cannot run on cloud hosting services like glama.ai. Use `npx @mozilla/firefox-devtools-mcp@latest` to run locally, or use Docker with the provided Dockerfile.
15
15
 
16
16
  ## Security
17
17
 
@@ -35,17 +35,17 @@ Recommended: use npx so you always run the latest published version from npm.
35
35
  Option A — Claude Code CLI
36
36
 
37
37
  ```bash
38
- claude mcp add firefox-devtools npx firefox-devtools-mcp@latest
38
+ claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest
39
39
  ```
40
40
 
41
41
  Pass options either as args or env vars. Examples:
42
42
 
43
43
  ```bash
44
44
  # Headless + viewport via args
45
- claude mcp add firefox-devtools npx firefox-devtools-mcp@latest -- --headless --viewport 1280x720
45
+ claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest -- --headless --viewport 1280x720
46
46
 
47
47
  # Or via environment variables
48
- claude mcp add firefox-devtools npx firefox-devtools-mcp@latest \
48
+ claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest \
49
49
  --env START_URL=https://example.com \
50
50
  --env FIREFOX_HEADLESS=true
51
51
  ```
@@ -63,9 +63,9 @@ Add to your Claude Code config file:
63
63
  "mcpServers": {
64
64
  "firefox-devtools": {
65
65
  "command": "npx",
66
- "args": ["-y", "firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
66
+ "args": ["-y", "@mozilla/firefox-devtools-mcp@latest", "--headless", "--viewport", "1280x720"],
67
67
  "env": {
68
- "START_URL": "about:home"
68
+ "START_URL": "about:blank"
69
69
  }
70
70
  }
71
71
  }
@@ -82,7 +82,7 @@ npm run setup
82
82
  ## Try it with MCP Inspector
83
83
 
84
84
  ```bash
85
- npx @modelcontextprotocol/inspector npx firefox-devtools-mcp@latest --start-url https://example.com --headless
85
+ npx @modelcontextprotocol/inspector npx @mozilla/firefox-devtools-mcp@latest --start-url https://example.com --headless
86
86
  ```
87
87
 
88
88
  Then call tools like:
@@ -106,12 +106,18 @@ You can pass flags or environment variables (names on the right):
106
106
  - `--connect-existing` — attach to an already-running Firefox instead of launching a new one (`CONNECT_EXISTING=true`)
107
107
  - `--marionette-port` — Marionette port for connect-existing mode, default 2828 (`MARIONETTE_PORT`)
108
108
  - `--pref name=value` — set Firefox preference at startup via `moz:firefoxOptions` (repeatable)
109
- - `--enable-script` — enable the `evaluate_script` tool, which executes arbitrary JavaScript in the page context (`ENABLE_SCRIPT=true`)
109
+ - `--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`)
110
110
  - `--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`)
111
111
  - `--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.
112
112
  - `--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`)
113
+ - `--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`
113
114
 
114
- > **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.
115
+
116
+ ### Useful preferences (`--pref`)
117
+
118
+ - 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.
119
+ - remote.log.level=Trace. Enable verbose WebDriver protocol logs in Firefox. The MCP server will automatically pass the matching log level to geckodriver so both sides log at the same verbosity.
120
+ - app.update.disabledForTesting=false. Allow Firefox to automatically download and apply updates. Note that updates may interrupt your session. Requires also setting remote.prefs.recommended=false.
115
121
 
116
122
  ### Firefox for Android
117
123
 
@@ -122,13 +128,13 @@ Use `--android-device` to automate Firefox running on an Android device. Require
122
128
  adb devices
123
129
 
124
130
  # Launch Firefox for Android on the single connected device
125
- npx firefox-devtools-mcp --android-device auto
131
+ npx @mozilla/firefox-devtools-mcp --android-device auto
126
132
 
127
133
  # Target a specific device
128
- npx firefox-devtools-mcp --android-device <serial>
134
+ npx @mozilla/firefox-devtools-mcp --android-device <serial>
129
135
 
130
136
  # Use Firefox Nightly instead
131
- npx firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix
137
+ npx @mozilla/firefox-devtools-mcp --android-device <serial> --android-package org.mozilla.fenix
132
138
  ```
133
139
 
134
140
  Port forwarding between the host and device is handled automatically by geckodriver.
@@ -142,7 +148,7 @@ Use `--connect-existing` to automate your real browsing session — with cookies
142
148
  firefox --marionette
143
149
 
144
150
  # Run the MCP server
145
- npx firefox-devtools-mcp --connect-existing --marionette-port 2828
151
+ npx @mozilla/firefox-devtools-mcp --connect-existing --marionette-port 2828
146
152
  ```
147
153
 
148
154
  Or set `marionette.enabled` to `true` in `about:config` (or `user.js`) to enable Marionette on every launch.
@@ -167,6 +173,7 @@ BiDi-dependent features (console events, network events) are not available in co
167
173
  - Privileged Context: list/select privileged ("chrome") contexts, evaluate_privileged_script (requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
168
174
  - WebExtension: install_extension, uninstall_extension, list_extensions (list requires `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`)
169
175
  - Firefox Management: get_firefox_info, get_firefox_output, restart_firefox, set_firefox_prefs, get_firefox_prefs
176
+ - Profiler: profiler_is_active, profiler_start (preset or explicit config), profiler_stop (saves profile to downloads directory)
170
177
  - Utilities: accept/dismiss dialog, history back/forward, set viewport
171
178
 
172
179
  ### Screenshot optimization for Claude Code
@@ -208,7 +215,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on local development, te
208
215
  "mcpServers": {
209
216
  "firefox-devtools": {
210
217
  "command": "cmd",
211
- "args": ["/c", "npx", "-y", "firefox-devtools-mcp@latest"]
218
+ "args": ["/c", "npx", "-y", "@mozilla/firefox-devtools-mcp@latest"]
212
219
  }
213
220
  }
214
221
  ```
@@ -219,7 +226,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on local development, te
219
226
  "mcpServers": {
220
227
  "firefox-devtools": {
221
228
  "command": "C:\\nvm4w\\nodejs\\npx.ps1",
222
- "args": ["-y", "firefox-devtools-mcp@latest"]
229
+ "args": ["-y", "@mozilla/firefox-devtools-mcp@latest"]
223
230
  }
224
231
  }
225
232
  ```