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

package/dist.moz/index.js

@@ -39,8 +39,19 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
+import { createHash } from "crypto";
+import { homedir } from "os";
+import { join } from "path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
+function defaultProfileDir(firefoxPath) {
+  const base = join(homedir(), ".firefox-devtools-mcp");
+  if (!firefoxPath) {
+    return join(base, "profile");
+  }
+  const hash2 = createHash("sha1").update(firefoxPath).digest("hex").slice(0, 8);
+  return join(base, `profile-${hash2}`);
+}
 function parsePrefs(prefs) {
   const result = {};
   if (!prefs || prefs.length === 0) {
@@ -122,6 +133,11 @@ var init_cli = __esm({
         type: "string",
         description: "Path to Firefox profile directory (optional, for persistent profile)"
       },
+      autoProfile: {
+        type: "boolean",
+        description: "Automatically use a persistent profile stored in ~/.firefox-devtools-mcp/. When --firefox-path is set, the profile is scoped to that binary so different Firefox builds stay isolated.",
+        default: (process.env.AUTO_PROFILE ?? "false") === "true"
+      },
       firefoxArg: {
         type: "array",
         description: "Additional arguments for Firefox. Only applies when Firefox is launched by firefox-devtools-mcp."
@@ -28076,8 +28092,8 @@ var SERVER_NAME, SERVER_VERSION;
 var init_constants = __esm({
   "src/config/constants.ts"() {
     "use strict";
-    SERVER_NAME = "firefox-devtools";
-    SERVER_VERSION = "0.7.1";
+    SERVER_NAME = true ? "@mozilla/firefox-devtools-mcp" : "firefox-devtools";
+    SERVER_VERSION = true ? "0.9.12" : "dev";
   }
 });
 
@@ -28157,12 +28173,12 @@ var init_logger = __esm({
 
 // src/firefox/profile.ts
 import { existsSync, mkdirSync, copyFileSync } from "fs";
-import { join } from "path";
+import { join as join2 } from "path";
 function isFirefoxProfile(dir) {
-  return FIREFOX_PROFILE_INDICATORS.some((file2) => existsSync(join(dir, file2)));
+  return FIREFOX_PROFILE_INDICATORS.some((file2) => existsSync(join2(dir, file2)));
 }
 function resolveProfilePath(parentPath) {
-  const mcpProfilePath = join(parentPath, MCP_PROFILE_DIR_NAME);
+  const mcpProfilePath = join2(parentPath, MCP_PROFILE_DIR_NAME);
   let warning = null;
   if (isFirefoxProfile(parentPath)) {
     warning = `Warning: The path "${parentPath}" looks like an existing Firefox profile.
@@ -28177,9 +28193,9 @@ function resolveProfilePath(parentPath) {
   if (isNew) {
     mkdirSync(mcpProfilePath, { recursive: true });
     log(`Created MCP profile directory: ${mcpProfilePath}`);
-    const parentPrefs = join(parentPath, "prefs.js");
+    const parentPrefs = join2(parentPath, "prefs.js");
     if (existsSync(parentPrefs)) {
-      copyFileSync(parentPrefs, join(mcpProfilePath, "prefs.js"));
+      copyFileSync(parentPrefs, join2(mcpProfilePath, "prefs.js"));
       log(`   Copied prefs.js from parent profile for initial preferences.`);
     }
   }
@@ -28199,14 +28215,14 @@ var init_profile = __esm({
 import { Builder, Browser, Capabilities } from "selenium-webdriver";
 import firefox from "selenium-webdriver/firefox.js";
 import { mkdirSync as mkdirSync2, openSync, closeSync, existsSync as existsSync2, readdirSync, statSync } from "fs";
-import { homedir } from "os";
-import { join as join2, delimiter } from "path";
+import { homedir as homedir2 } from "os";
+import { join as join3, delimiter } from "path";
 function findGeckodriverInPath(binaryName) {
   for (const dir of (process.env.PATH ?? "").split(delimiter)) {
     if (!dir) {
       continue;
     }
-    const candidate = join2(dir, binaryName);
+    const candidate = join3(dir, binaryName);
     if (existsSync2(candidate)) {
       return candidate;
     }
@@ -28214,18 +28230,18 @@ function findGeckodriverInPath(binaryName) {
   return null;
 }
 function findGeckodriverInSeleniumCache(binaryName) {
-  const cacheBase = join2(homedir(), ".cache/selenium/geckodriver");
+  const cacheBase = join3(homedir2(), ".cache/selenium/geckodriver");
   try {
     if (!existsSync2(cacheBase)) {
       return null;
     }
     for (const platformDir of readdirSync(cacheBase)) {
-      const platformPath = join2(cacheBase, platformDir);
+      const platformPath = join3(cacheBase, platformDir);
       if (!statSync(platformPath).isDirectory()) {
         continue;
       }
       for (const versionDir of readdirSync(platformPath).sort().reverse()) {
-        const candidate = join2(platformPath, versionDir, binaryName);
+        const candidate = join3(platformPath, versionDir, binaryName);
         if (existsSync2(candidate)) {
           return candidate;
         }
@@ -28315,10 +28331,10 @@ var init_core3 = __esm({
           if (this.options.logFile) {
             this.logFilePath = this.options.logFile;
           } else if (this.options.env && Object.keys(this.options.env).length > 0) {
-            const outputDir = join2(homedir(), ".firefox-devtools-mcp", "output");
+            const outputDir = join3(homedir2(), ".firefox-devtools-mcp", "output");
             mkdirSync2(outputDir, { recursive: true });
             const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-            this.logFilePath = join2(outputDir, `firefox-${timestamp}.log`);
+            this.logFilePath = join3(outputDir, `firefox-${timestamp}.log`);
           }
           if (this.options.env) {
             for (const [key, value] of Object.entries(this.options.env)) {
@@ -33419,7 +33435,7 @@ async function getFirefox() {
     options = {
       firefoxPath: args.firefoxPath ?? void 0,
       headless: args.headless,
-      profilePath: args.profilePath ?? void 0,
+      profilePath: args.profilePath ?? (args.autoProfile ? defaultProfileDir(args.firefoxPath) : void 0),
       viewport: args.viewport ?? void 0,
       args: args.firefoxArg ?? void 0,
       startUrl: args.startUrl ?? void 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mozilla/firefox-devtools-mcp-moz",
-  "version": "0.9.9",
+  "version": "0.9.12",
   "description": "Model Context Protocol (MCP) server for Firefox DevTools automation (moz build with privileged context support)",
   "author": "Mozilla",
   "license": "MIT OR Apache-2.0",
@@ -38,6 +38,7 @@
     "yargs": "17.7.2"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "2.1.2",
     "@types/jsdom": "28.0.0",
     "@types/node": "24.1.0",
     "@types/selenium-webdriver": "4.35.1",

package/plugins/firefox-devtools-mcp/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "firefox-devtools-mcp",
+  "description": "Control Firefox for browsing, web testing, and debugging. Fill forms, capture network and console activity, take screenshots, run scripts, and profile performance. Supports Android devices.",
+  "author": {
+    "name": "Mozilla",
+    "url": "https://github.com/mozilla/firefox-devtools-mcp"
+  },
+  "repository": "https://github.com/mozilla/firefox-devtools-mcp",
+  "homepage": "https://github.com/mozilla/firefox-devtools-mcp",
+  "license": "MIT OR Apache-2.0",
+  "mcpServers": {
+    "firefox-devtools": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mozilla/firefox-devtools-mcp@latest",
+        "--auto-profile",
+        "--enable-script",
+        "--pref",
+        "remote.prefs.recommended=false"
+      ]
+    }
+  }
+}

package/plugins/firefox-devtools-mcp/agents/e2e-tester.md

@@ -0,0 +1,42 @@
+---
+name: e2e-tester
+description: Agent for running E2E tests on web applications. Navigates pages, fills forms, clicks buttons, and verifies results.
+model: sonnet
+---
+
+You are an E2E testing agent specializing in automated browser testing using Firefox DevTools MCP.
+
+## Your Task
+
+When given a test scenario, execute it step-by-step using Firefox automation tools, verify the results, and report pass/fail status.
+
+## Process
+
+1. **Navigate to the target**: Use `navigate_page` to open the URL
+2. **Take snapshot**: Always call `take_snapshot` before interacting
+3. **Execute test steps**: Use `fill_by_uid`, `click_by_uid`, etc.
+4. **Re-snapshot after changes**: DOM updates require fresh snapshots
+5. **Verify results**: Check for expected elements, text, or states
+6. **Report outcome**: Clear pass/fail with evidence (screenshots if needed)
+
+## Available Tools
+
+- `navigate_page` - Go to URL
+- `navigate_history` - Go back or forward
+- `take_snapshot` - Get DOM with UIDs
+- `fill_by_uid` / `fill_form_by_uid` - Enter text into fields
+- `click_by_uid` - Click elements
+- `hover_by_uid` - Hover over elements
+- `drag_by_uid_to_uid` - Drag and drop
+- `accept_dialog` / `dismiss_dialog` - Handle browser dialogs
+- `screenshot_page` - Capture evidence
+- `list_console_messages` - Check for JS errors
+- `list_network_requests` - Verify API calls
+
+## Guidelines
+
+- Always snapshot before AND after interactions
+- Take screenshots at key checkpoints using `screenshot_page` — display the returned image inline as evidence
+- Report console errors as test failures
+- Be specific about what passed or failed
+- Handle dialogs explicitly — unexpected dialogs block interactions

package/plugins/firefox-devtools-mcp/agents/web-extractor.md

@@ -0,0 +1,36 @@
+---
+name: web-extractor
+description: Agent for browsing and extracting structured content from web pages. Navigates pages, handles pagination, and returns structured data.
+model: sonnet
+---
+
+You are a web extraction agent specializing in retrieving structured content from web pages using Firefox DevTools MCP.
+
+## Your Task
+
+When given an extraction task, navigate to pages, locate the target content, handle pagination if needed, and return structured results.
+
+## Process
+
+1. **Navigate to source**: Use `navigate_page` to open the URL
+2. **Take snapshot**: Call `take_snapshot` to see page structure
+3. **Identify target elements**: Find UIDs for elements containing target data
+4. **Extract content**: The snapshot contains text content of elements
+5. **Handle pagination**: Click "next" buttons, re-snapshot, repeat
+6. **Structure output**: Return data in requested format (JSON, table, etc.)
+
+## Available Tools
+
+- `navigate_page` - Go to URL
+- `navigate_history` - Go back or forward
+- `take_snapshot` - Get DOM with content and UIDs
+- `click_by_uid` - Navigate pagination or interact with elements
+- `list_network_requests` - Monitor API calls (often cleaner than DOM extraction)
+- `screenshot_page` - Capture page state (returns base64 image, display it inline)
+
+## Guidelines
+
+- Snapshots contain element text — no need for separate "get text" calls
+- Check network requests for API endpoints (often cleaner than parsing the DOM)
+- Handle "load more" buttons and infinite scroll patterns
+- Return structured data, not raw HTML

package/plugins/firefox-devtools-mcp/skills/browser-automation/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: browser-automation
+description: This skill should be used when the user asks about browser automation, testing web pages, extracting content, filling forms, taking screenshots, or monitoring console/network activity. Activates for E2E testing, form automation, browsing tasks, or debugging web applications.
+---
+
+When the user asks about browser automation, use Firefox DevTools MCP to control a real Firefox browser.
+
+## Before Starting
+
+Always call `list_pages` first. This checks whether Firefox is already running and which pages are open. Do not assume Firefox needs to be restarted or that you need to navigate from scratch — reuse the existing session whenever possible.
+
+## When to Use This Skill
+
+Activate this skill when the user:
+
+- Wants to automate browser interactions ("Fill out this form", "Click the login button")
+- Needs E2E testing ("Test the checkout flow", "Verify the login works")
+- Wants to browse or extract content ("Get all links on this page", "Extract prices")
+- Needs screenshots ("Screenshot this page", "Capture the error state")
+- Wants to debug ("Check for JS errors", "Show failed network requests")
+- Needs to profile performance ("Profile this page load")
+
+## Core Workflow
+
+### Step 1: Navigate and Snapshot
+
+```
+navigate_page url="https://example.com"
+take_snapshot
+```
+
+The snapshot returns a DOM representation with UIDs (e.g., `e42`) for each interactive element.
+
+### Step 2: Interact with Elements
+
+Use UIDs from the snapshot:
+
+```
+fill_by_uid uid="e5" text="user@example.com"
+click_by_uid uid="e8"
+```
+
+### Step 3: Re-snapshot After Changes
+
+DOM changes invalidate UIDs. Always re-snapshot after:
+- Page navigation
+- Form submissions
+- Dynamic content loads
+
+```
+take_snapshot  # Get fresh UIDs
+```
+
+## Quick Reference
+
+| Task | Tools |
+|------|-------|
+| Navigate | `navigate_page`, `navigate_history` |
+| See DOM | `take_snapshot` |
+| Click | `click_by_uid` |
+| Hover | `hover_by_uid` |
+| Type | `fill_by_uid`, `fill_form_by_uid` |
+| Drag | `drag_by_uid_to_uid` |
+| Dialogs | `accept_dialog`, `dismiss_dialog` |
+| Screenshot | `screenshot_page`, `screenshot_by_uid` |
+| Debug | `list_console_messages`, `list_network_requests` |
+| Profile | `profiler_start`, `profiler_stop` |
+
+## Guidelines
+
+- **Check existing session first**: Call `list_pages` before navigating — reuse the running Firefox session rather than starting fresh
+- **Always snapshot first**: UIDs only exist after `take_snapshot`
+- **Re-snapshot after DOM changes**: UIDs become stale after interactions
+- **Screenshots**: in Cowork (system prompt has an outputs folder host path), call `screenshot_page saveTo="<host-outputs-path>/screenshot.png"` then call `present_files` with that path. Otherwise call `screenshot_page` without `saveTo` and include the returned image directly in your reply — the user cannot see tool call outputs.
+- **Check for errors**: Use `list_console_messages level="error"` to catch JS issues
+- **Firefox only**: This MCP controls Firefox, not Chrome or Safari
+- **Reconfiguring Firefox**: to use a specific binary, profile, or headless mode, call `restart_firefox` with the relevant options (`firefoxPath`, `profilePath`, `headless`)

package/plugins/firefox-devtools-mcp/skills/debug/SKILL.md

@@ -0,0 +1,32 @@
+---
+description: Show console errors and failed network requests
+argument-hint: [console|network|all]
+---
+
+# /firefox-devtools-mcp:debug
+
+Displays debugging information from the current page.
+
+## Usage
+
+```
+/firefox-devtools-mcp:debug              # Show all (console errors + failed requests)
+/firefox-devtools-mcp:debug console      # Console messages only
+/firefox-devtools-mcp:debug network      # Network requests only
+```
+
+## Examples
+
+```
+/firefox-devtools-mcp:debug
+/firefox-devtools-mcp:debug console
+/firefox-devtools-mcp:debug network
+```
+
+## What Happens
+
+- `console`: Calls `list_console_messages` with `level="error"`
+- `network`: Calls `list_network_requests` with `statusMin=400`
+- `all` (default): Shows both console errors and failed network requests
+
+Requires Firefox to already be running and on the page you want to debug. If Firefox is not running or is on about:blank, call `navigate_page` first.

package/plugins/firefox-devtools-mcp/skills/navigate/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: navigate
+description: Navigate Firefox to a URL and take a DOM snapshot for interaction
+argument-hint: <url>
+---
+
+# /firefox-devtools-mcp:navigate
+
+Opens a URL in Firefox and takes a DOM snapshot for interaction.
+
+## Usage
+
+```
+/firefox-devtools-mcp:navigate <url>
+```
+
+## Examples
+
+```
+/firefox-devtools-mcp:navigate https://example.com
+/firefox-devtools-mcp:navigate https://github.com/login
+/firefox-devtools-mcp:navigate file:///path/to/local.html
+```
+
+## What Happens
+
+1. Calls `navigate_page` with the URL
+2. Waits for page load
+3. Calls `take_snapshot` to create UID mappings
+4. Returns the DOM snapshot with interactive elements marked
+
+After navigating, you can interact with elements using their UIDs (e.g., `e42`).

package/plugins/firefox-devtools-mcp/skills/screenshot/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: screenshot
+description: Take a screenshot of a URL or the current page. Use when the user asks to capture, screenshot, or photograph a web page or URL.
+argument-hint: [url or uid]
+---
+
+# /firefox-devtools-mcp:screenshot
+
+Captures a screenshot of a URL or the current page and shows it to the user.
+
+## Usage
+
+```
+/firefox-devtools-mcp:screenshot https://example.com   # Navigate then screenshot
+/firefox-devtools-mcp:screenshot                       # Screenshot current page
+/firefox-devtools-mcp:screenshot <uid>                 # Screenshot specific element
+```
+
+## Steps
+
+1. Navigate if a URL was given: call `navigate_page`.
+2. Take the screenshot using the method that matches your environment:
+
+**In Cowork** (system prompt contains an outputs folder host path under "Shell access"):
+- Call `screenshot_page saveTo="<host-outputs-path>/screenshot.png"` using the host path from the system prompt, not the container path.
+- Load and call `present_files` with that same path so the user receives a clickable file card.
+
+**In Claude.ai chat or Claude Desktop** (no outputs folder in system prompt):
+- Call `screenshot_page` without `saveTo`.
+- Your final response must include the actual image returned — not a description of it. The user cannot see tool call outputs, only what you include in your reply.

package/plugins/firefox-devtools-troubleshoot/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "firefox-devtools-troubleshoot",
+  "description": "Diagnose and fix Firefox DevTools MCP setup issues. Use this if the firefox-devtools-mcp plugin is not working.",
+  "author": {
+    "name": "Mozilla",
+    "url": "https://github.com/mozilla/firefox-devtools-mcp"
+  },
+  "repository": "https://github.com/mozilla/firefox-devtools-mcp",
+  "homepage": "https://github.com/mozilla/firefox-devtools-mcp",
+  "license": "MIT OR Apache-2.0"
+}

package/plugins/firefox-devtools-troubleshoot/skills/diagnose/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: firefox-devtools-diagnose
+description: Diagnose Firefox DevTools MCP setup issues. Activate when the firefox-devtools-mcp plugin fails to connect, its tools are not available, or the user reports Firefox DevTools not working in Cowork.
+---
+
+When Firefox DevTools MCP tools are unavailable or the user reports issues with the firefox-devtools-mcp plugin, run this diagnostic sequence automatically. Do not ask the user to do these checks manually.
+
+## Diagnostic Steps
+
+### 1. Check Node.js
+
+Run `node --version` using the Bash tool.
+
+- If the command fails with "command not found": tell the user Node.js is not installed and direct them to download Node.js 20.19.0 or higher from https://nodejs.org.
+- If the version is below 20.19.0: tell the user their Node.js version is too old and they need to upgrade to 20.19.0 or higher from https://nodejs.org.
+- If the version is 20.19.0 or higher: Node.js is not the issue, continue to the next check.
+
+### 2. Check Your Own Tool List
+
+Check whether any `firefox-devtools-mcp:*` tools are present in your current tool list.
+
+- If present: the plugin is installed and connected in this conversation. The reported issue is not a setup problem — investigate the specific tool failure directly (bad arguments, target page state, etc.) rather than continuing this checklist.
+- If absent: this is ambiguous by itself. An empty tool list looks identical whether the plugin isn't installed, the user is in the Chat tab instead of Cowork, or the plugin is installed in Cowork but failing for some other reason. Do not guess which; continue to the next step.
+
+### 3. Check Installation and Tab Together
+
+Since an absent tool list can't be attributed to a single cause from your side, ask the user to confirm both of the following in one pass:
+
+- Open **Customize > Plugins** in Claude Cowork and confirm `firefox-devtools-mcp` appears in the list.
+- Confirm they are currently in the **Cowork** tab, not the **Chat** tab — plugins only work in Cowork.
+
+- If the plugin is missing: direct them to the installation steps at https://github.com/mozilla/firefox-devtools-mcp.
+- If the plugin is present but they were in Chat: ask them to switch to Cowork and retry.
+- If the plugin is present and they are already in Cowork: continue to the next step.
+
+### 4. Escalate
+
+If all checks pass and the plugin still does not work, tell the user to report the issue:
+
+- File a bug on [Bugzilla](https://bugzilla.mozilla.org/enter_bug.cgi?format=__default__&blocked=2026717&product=Developer%20Infrastructure&component=Firefox%20MCP)
+- Or ask in the [#firefox-devtools-mcp Matrix room](https://chat.mozilla.org/#/room/#firefox-devtools-mcp:mozilla.org)

package/scripts/build-mcpb.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * Builds the firefox-devtools-mcp .mcpb bundle (Claude Desktop extension).
+ * Assembles a staging directory with dist/, production node_modules and
+ * manifest.json, then runs `mcpb pack` on it.
+ */
+
+import { readFileSync, writeFileSync, existsSync, cpSync, mkdtempSync, rmSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+const manifest = JSON.parse(readFileSync(resolve(root, 'manifest.json'), 'utf8'));
+
+console.log('Building server...');
+execSync('npm run build', { cwd: root, stdio: 'inherit' });
+
+const stagingDir = mkdtempSync(resolve(tmpdir(), 'firefox-devtools-mcpb-'));
+
+try {
+  cpSync(resolve(root, 'dist'), resolve(stagingDir, 'dist'), { recursive: true });
+  for (const file of ['README.md', 'LICENSE-MIT', 'LICENSE-APACHE', 'package.json', 'package-lock.json']) {
+    cpSync(resolve(root, file), resolve(stagingDir, file));
+  }
+
+  console.log('Installing production dependencies...');
+  execSync('npm ci --omit=dev', { cwd: stagingDir, stdio: 'inherit' });
+
+  writeFileSync(
+    resolve(stagingDir, 'manifest.json'),
+    JSON.stringify({ ...manifest, version: pkg.version }, null, 2) + '\n'
+  );
+
+  const outDir = resolve(root, 'dist-mcpb');
+  if (!existsSync(outDir)) {
+    execSync(`mkdir -p ${outDir}`);
+  }
+  const outFile = resolve(outDir, `firefox-devtools-mcp-${pkg.version}.mcpb`);
+
+  console.log('Packing .mcpb bundle...');
+  execSync(`npx mcpb pack "${stagingDir}" "${outFile}"`, {
+    cwd: root,
+    stdio: 'inherit',
+  });
+
+  console.log(`Written ${outFile}`);
+} finally {
+  rmSync(stagingDir, { recursive: true, force: true });
+}