@extension.dev/mcp 5.5.1 → 5.5.2

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "extension-mcp",
       "source": "./",
       "description": "MCP tools for browser extension development: scaffold from 60+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox.",
-      "version": "5.5.1",
+      "version": "5.5.2",
       "category": "development",
       "author": {
         "name": "Cezar Augusto"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "extension-mcp",
   "description": "MCP tools for browser extension development: scaffold from 60+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox. Ships /extension, /extension-add, /extension-debug, and /extension-publish commands.",
-  "version": "5.5.1",
+  "version": "5.5.2",
   "author": {
     "name": "Cezar Augusto",
     "email": "hello@extension.dev",

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 5.5.2
+
+Honest browser support wording ahead of the Safari lane landing.
+
+### Changed
+
+- The package description and README now say Safari is coming next
+  instead of listing it alongside the browsers that are store-ready
+  today. Chrome, Edge, Firefox, and every Chromium- or Gecko-based
+  browser remain fully supported; nothing changes functionally.
+
 ## 5.5.1
 
 The store journey stops being write-only after submit, and the token

package/README.md

@@ -26,7 +26,7 @@ Extensions fail silently: content scripts that never inject, panels that never o
 These tools give agents eyes on the live browser, so they debug from evidence instead of guessing:
 
 - **Scaffold** from the 60+ template catalog behind [templates.extension.dev](https://templates.extension.dev), or add a popup, sidebar, or content script to an existing project
-- **Run** the dev server with HMR in Chrome, Edge, Firefox, Safari, Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf, or any Chromium- or Gecko-based binary, no build config
+- **Run** the dev server with HMR in Chrome, Edge, Firefox, Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf, or any Chromium- or Gecko-based binary (Safari coming next), no build config
 - **See** the live DOM, unified logs from every extension context, `chrome.storage` contents, and the loaded-extension list
 - **Act**: evaluate code in any context, trigger the action button and commands, reload the extension, replay events
 - **Ship**: validate the manifest cross-browser, build for production, publish a shareable preview, and promote builds to release channels headlessly

package/dist/module.js

@@ -219,7 +219,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.5.1","El":{"OP":"^4.0.13"}}');
+var package_namespaceObject = JSON.parse('{"rE":"5.5.2","El":{"OP":"^4.0.13"}}');
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -3012,9 +3012,178 @@ function isCdpEndpoint(port) {
         });
     });
 }
+function toMcpSpeak(text) {
+    return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/Use --context page --tab <id>/g, 'Use context: "page" (targets the active tab; pass url or tab to pick another)').replace(/--context[= ](background|popup|options|sidebar|devtools|newtab|history|bookmarks|content|page)\b/g, 'context: "$1"').replace(/--tab[= ](\d+|<[\w-]+>)/g, "tab: $1").replace(/--url[= ]"([^"]+)"/g, 'url: "$1"').replace(/--url[= ](<[\w-]+>|\S*(?:\/\/|\*)\S*)/g, 'url: "$1"').replace(/--browser[= ]([\w]+-based|chrome|chromium|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|safari)\b/g, 'browser: "$1"').replace(/--timeout[= ](\d+)/g, "timeout: $1").replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev").replace(/--tab\b/g, "`tab`").replace(/--url\b/g, "`url`").replace(/--context\b/g, "`context`").replace(/--browser\b/g, "`browser`").replace(/--timeout\b/g, "`timeout`");
+}
+function withSessionContext(message, projectPath) {
+    const isControlError = /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
+    if (!isControlError) return message;
+    const dead = deadReadySession(projectPath);
+    if (dead) return `${message}\nLikely cause: the dev server has exited, ${dead.browser} ready.json still says ready but its pid ${dead.pid} is dead. Restart with extension_dev (this is not an allowControl problem); extension_doctor confirms.`;
+    const running = knownSessionBrowsers(projectPath);
+    if (0 === running.length) return message;
+    return `${message} Active session browser(s) for this project: ${running.join(", ")}, pass that as \`browser\`, or restart it via extension_dev with allowControl: true if the control channel is off.`;
+}
+function translateFrame(frame, projectPath) {
+    if (!frame || false !== frame.ok) return frame;
+    if (frame.error && "string" == typeof frame.error.message) frame.error.message = withSessionContext(toMcpSpeak(frame.error.message), projectPath);
+    if ("string" == typeof frame.error?.hint) frame.error.hint = toMcpSpeak(frame.error.hint);
+    if ("string" == typeof frame.hint) frame.hint = toMcpSpeak(frame.hint);
+    return frame;
+}
+async function runActVerb(args, projectPath, timeoutMs) {
+    const { code, stdout, stderr } = await runExtensionCli([
+        ...args,
+        "--output",
+        "json"
+    ], {
+        cwd: projectPath,
+        timeoutMs
+    });
+    const out = stdout.trim();
+    if (out) try {
+        const frame = JSON.parse(out);
+        if (frame && false === frame.ok) return JSON.stringify(translateFrame(frame, projectPath));
+        return out;
+    } catch  {}
+    const message = stderr.trim() || `extension exited with code ${code}`;
+    return JSON.stringify({
+        ok: false,
+        error: {
+            name: "CliError",
+            message: withSessionContext(toMcpSpeak(message), projectPath)
+        }
+    });
+}
+function commonFlags(args) {
+    const flags = [];
+    if (args.context) flags.push("--context", args.context);
+    if (args.url) flags.push("--url", args.url);
+    if (null != args.tab) flags.push("--tab", String(args.tab));
+    if (args.browser) flags.push("--browser", args.browser);
+    if (null != args.timeout) flags.push("--timeout", String(args.timeout));
+    return flags;
+}
+async function listBridgeTabs(projectPath, browser, timeout) {
+    const raw = await runActVerb([
+        "inspect",
+        projectPath,
+        "--list-tabs",
+        "--browser",
+        browser,
+        ...null != timeout ? [
+            "--timeout",
+            String(timeout)
+        ] : []
+    ], projectPath, timeout);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return {
+            error: raw
+        };
+    }
+    if (parsed?.ok === false) return {
+        error: raw
+    };
+    const list = Array.isArray(parsed?.tabs) ? parsed.tabs : Array.isArray(parsed?.value) ? parsed.value : Array.isArray(parsed?.value?.tabs) ? parsed.value.tabs : null;
+    if (!list) return {
+        error: raw
+    };
+    return {
+        tabs: list.map((t)=>({
+                tabId: "number" == typeof t?.tabId ? t.tabId : "number" == typeof t?.id ? t.id : null,
+                url: String(t?.url ?? ""),
+                title: String(t?.title ?? "")
+            }))
+    };
+}
+function matchTabsByUrl(tabs, needle) {
+    const wanted = needle.toLowerCase();
+    const byUrl = tabs.filter((t)=>t.url.toLowerCase().includes(wanted));
+    if (byUrl.length > 0) return byUrl;
+    return tabs.filter((t)=>t.title.toLowerCase().includes(wanted));
+}
+async function pollForBridgeTab(projectPath, browser, url, budgetMs) {
+    const deadline = Date.now() + budgetMs;
+    const wanted = url.replace(/#.*$/, "");
+    for(;;){
+        const listed = await listBridgeTabs(projectPath, browser);
+        if ("tabs" in listed) {
+            for (const t of listed.tabs)if (t.url === wanted || t.url.startsWith(wanted)) return t;
+        }
+        if (Date.now() >= deadline) return null;
+        await new Promise((r)=>setTimeout(r, 250));
+    }
+}
+async function navigateToUrlViaBridge(projectPath, browser, url, timeout) {
+    const expression = `(async () => { const api = typeof browser !== "undefined" ? browser : chrome; const tabs = await api.tabs.query({ active: true, currentWindow: true }); const active = tabs && tabs[0]; const tab = active && active.id != null ? await api.tabs.update(active.id, { url: ${JSON.stringify(url)} }) : await api.tabs.create({ url: ${JSON.stringify(url)} }); return { tabId: tab && tab.id != null ? tab.id : null }; })()`;
+    const raw = await runActVerb([
+        "eval",
+        expression,
+        projectPath,
+        "--context",
+        "background",
+        "--browser",
+        browser,
+        ...null != timeout ? [
+            "--timeout",
+            String(timeout)
+        ] : []
+    ], projectPath, timeout);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.ok === false) {
+            if (!parsed.hint) parsed.hint = "On this browser family URL navigation rides the agent bridge (a background eval of tabs.update), so the dev session must be started with allowEval: true (extension_dev).";
+            return JSON.stringify(parsed);
+        }
+    } catch  {
+        return raw;
+    }
+    const settled = await pollForBridgeTab(projectPath, browser, url, null != timeout ? Math.min(timeout, 6000) : 6000);
+    if (!settled) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NavigateFailed",
+            message: `Navigation to ${url} did not produce a tab reporting that URL. The URL may not exist, or the browser refused the navigation (Firefox rejects privileged about:/chrome: URLs and other extensions' moz-extension: pages).`
+        },
+        hint: "Confirm the URL, or discover open tabs with extension_dom_inspect listTabs: true. For an extension page, the path must match the BUILT manifest."
+    });
+    return JSON.stringify({
+        ok: true,
+        navigated: url,
+        tab: {
+            tabId: settled.tabId,
+            url: settled.url,
+            title: settled.title
+        },
+        hint: "Inspect it with extension_dom_inspect or extension_eval using url or this numeric tab id (context: 'page'/'content')."
+    });
+}
+async function resolveBridgeBaseUrl(projectPath, browser, timeout) {
+    const raw = await runActVerb([
+        "eval",
+        '(typeof browser !== "undefined" ? browser : chrome).runtime.getURL("")',
+        projectPath,
+        "--context",
+        "background",
+        "--browser",
+        browser,
+        ...null != timeout ? [
+            "--timeout",
+            String(timeout)
+        ] : []
+    ], projectPath, timeout);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.ok && "string" == typeof parsed.value && parsed.value) return parsed.value.endsWith("/") ? parsed.value : `${parsed.value}/`;
+    } catch  {}
+    return null;
+}
 const source_inspect_schema = {
     name: "extension_source_inspect",
-    description: "Inspect a running extension's live state via Chrome DevTools Protocol: full HTML (with shadow DOM), DOM structure, content script injection, console messages, and CSS selector queries. Requires an active dev or start session.",
+    description: "Inspect a running extension's live state: full HTML (with shadow DOM), DOM structure, content script injection, console messages, and CSS selector queries. Chromium sessions ride Chrome DevTools Protocol; Firefox sessions ride the agent bridge (needs allowEval: true) and cover summary/meta/html/probes, while dom_snapshot, extension_roots, console, and deepDom stay CDP-only. Requires an active dev or start session.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3081,10 +3250,7 @@ async function source_inspect_handler(args) {
         "console"
     ]);
     const maxBytes = args.maxBytes ?? 262144;
-    if (!isChromiumFamily(browser)) return JSON.stringify({
-        error: `Source inspection reads the live DOM over Chrome DevTools Protocol, which ${browser} (Gecko) does not expose. This is a capability limit, not a missing session.`,
-        hint: `For the ${browser} session, read runtime state with extension_logs, or extension_eval / extension_dom_inspect (content/page, an open surface like popup/options/sidebar, or an override page like newtab) which work against Firefox over the control channel. To get CDP DOM inspection, run a Chromium-family dev session (extension_dev with browser: "chrome") in parallel.`
-    });
+    if (!isChromiumFamily(browser)) return inspectViaBridge(args, browser, include, maxBytes);
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return JSON.stringify({
         error: "No active dev session found. Cannot connect to Chrome DevTools Protocol.",
@@ -3186,6 +3352,117 @@ async function source_inspect_handler(args) {
         cdp.disconnect();
     }
 }
+function buildBridgeInspectExpression(opts) {
+    const parts = [
+        "const out = {};"
+    ];
+    if (opts.meta) parts.push("try { out.meta = { url: location.href, title: document.title, readyState: document.readyState }; } catch (e) {}");
+    if (opts.summary) parts.push(`try {
+        const roots = document.querySelectorAll('#extension-root,[data-extension-root]:not([data-extension-root="extension-js-devtools"])');
+        out.summary = {
+          htmlLength: document.documentElement.outerHTML.length,
+          scriptCount: document.querySelectorAll('script').length,
+          styleCount: document.querySelectorAll('style').length,
+          linkCount: document.querySelectorAll('link').length,
+          extensionRootCount: roots.length,
+          bodyChildCount: document.body ? document.body.children.length : 0
+        };
+      } catch (e) { out.summary = {}; }`);
+    if (opts.html) parts.push(`try {
+        const html = document.documentElement.outerHTML;
+        const cap = ${JSON.stringify(opts.maxBytes)};
+        out.htmlTruncated = cap > 0 && html.length > cap;
+        out.html = out.htmlTruncated ? html.slice(0, cap) : html;
+      } catch (e) {}`);
+    if (opts.probes.length) parts.push(`out.probes = {};
+      for (const sel of ${JSON.stringify(opts.probes)}) {
+        try {
+          const nodes = document.querySelectorAll(sel);
+          const first = nodes[0];
+          out.probes[sel] = { count: nodes.length, sample: first ? String(first.outerHTML || "").slice(0, 200) : null };
+        } catch (e) { out.probes[sel] = { error: String((e && e.message) || e) }; }
+      }`);
+    parts.push("return out;");
+    return `(() => { ${parts.join("\n")} })()`;
+}
+async function inspectViaBridge(args, browser, include, maxBytes) {
+    const notes = [];
+    const cdpOnly = [
+        "dom_snapshot",
+        "extension_roots"
+    ].filter((k)=>include.has(k));
+    if (cdpOnly.length) notes.push(`${cdpOnly.join(" and ")} require CDP and are Chromium-only; on ${browser}, extension_dom_inspect's summary reports extension roots and open shadow roots.`);
+    if (args.deepDom) notes.push("deepDom (closed shadow roots) requires CDP and is Chromium-only.");
+    if (include.has("console")) notes.push(`Console capture rides CDP; on ${browser} read extension_logs, where the engine streams console output.`);
+    if (args.url) {
+        const listed = await listBridgeTabs(args.projectPath, browser, args.timeout);
+        if ("error" in listed) return listed.error;
+        const already = listed.tabs.some((t)=>t.url.includes(args.url));
+        if (!already) {
+            const nav = await navigateToUrlViaBridge(args.projectPath, browser, args.url, args.timeout);
+            try {
+                if (JSON.parse(nav)?.ok !== true) return nav;
+            } catch  {
+                return nav;
+            }
+        }
+    }
+    const expression = buildBridgeInspectExpression({
+        summary: include.has("summary"),
+        meta: true,
+        html: include.has("html"),
+        probes: args.probe ?? [],
+        maxBytes
+    });
+    const raw = await runActVerb([
+        "eval",
+        expression,
+        args.projectPath,
+        "--context",
+        "page",
+        ...args.url ? [
+            "--url",
+            args.url
+        ] : [],
+        "--browser",
+        browser,
+        ...null != args.timeout ? [
+            "--timeout",
+            String(args.timeout)
+        ] : []
+    ], args.projectPath, args.timeout);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return raw;
+    }
+    if (parsed?.ok !== true) return raw;
+    const value = parsed.value ?? {};
+    const result = {
+        browser,
+        transport: "bridge"
+    };
+    if (value.meta) {
+        result.target = {
+            url: value.meta.url,
+            title: value.meta.title
+        };
+        if (include.has("meta")) result.meta = value.meta;
+    }
+    if (include.has("summary") && value.summary) result.summary = value.summary;
+    if (include.has("html") && "string" == typeof value.html) {
+        result.html = value.html;
+        if (value.htmlTruncated) result.htmlTruncated = true;
+    }
+    if (value.probes) {
+        result.probes = value.probes;
+        const jsLooking = (args.probe ?? []).filter((p)=>/^typeof\s|^(chrome|browser|window|document)\.|\(\)|=>|===/.test(p));
+        if (jsLooking.length) result.probeWarning = `Probes are CSS selectors run through querySelectorAll against the live page, NOT JavaScript expressions. ${jsLooking.map((s)=>`"${s}"`).join(", ")} parsed as selectors and will match nothing. To evaluate JS, use extension_eval.`;
+    }
+    if (notes.length) result.notes = notes;
+    return JSON.stringify(result);
+}
 const list_extensions_schema = {
     name: "extension_list_extensions",
     description: "List the extensions with a live context in the running dev browser via Chrome DevTools Protocol. Returns each extension's id, name, version, and live contexts (service worker, page). The entry for THIS dev session's extension (the project being served) is flagged ownExtension: true, with name and version resolved from the session's ready contract even when the browser exposes no identity. Other extensions resolve via the read-only Extensions domain when available; their contexts are never attached to or evaluated in, so an id that the domain does not describe stays id-only with a note saying why. A dormant MV3 service worker with no open page may be absent until it wakes. Chromium only (Firefox uses RDP, not yet supported). Requires an active dev or start session.",
@@ -3665,58 +3942,6 @@ async function logs_handler(args) {
     if (args.follow) return readFromStream(args, browser, limit);
     return readFromFile(args, browser, limit);
 }
-function toMcpSpeak(text) {
-    return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/Use --context page --tab <id>/g, 'Use context: "page" (targets the active tab; pass url or tab to pick another)').replace(/--context[= ](background|popup|options|sidebar|devtools|newtab|history|bookmarks|content|page)\b/g, 'context: "$1"').replace(/--tab[= ](\d+|<[\w-]+>)/g, "tab: $1").replace(/--url[= ]"([^"]+)"/g, 'url: "$1"').replace(/--url[= ](<[\w-]+>|\S*(?:\/\/|\*)\S*)/g, 'url: "$1"').replace(/--browser[= ]([\w]+-based|chrome|chromium|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|safari)\b/g, 'browser: "$1"').replace(/--timeout[= ](\d+)/g, "timeout: $1").replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev").replace(/--tab\b/g, "`tab`").replace(/--url\b/g, "`url`").replace(/--context\b/g, "`context`").replace(/--browser\b/g, "`browser`").replace(/--timeout\b/g, "`timeout`");
-}
-function withSessionContext(message, projectPath) {
-    const isControlError = /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
-    if (!isControlError) return message;
-    const dead = deadReadySession(projectPath);
-    if (dead) return `${message}\nLikely cause: the dev server has exited, ${dead.browser} ready.json still says ready but its pid ${dead.pid} is dead. Restart with extension_dev (this is not an allowControl problem); extension_doctor confirms.`;
-    const running = knownSessionBrowsers(projectPath);
-    if (0 === running.length) return message;
-    return `${message} Active session browser(s) for this project: ${running.join(", ")}, pass that as \`browser\`, or restart it via extension_dev with allowControl: true if the control channel is off.`;
-}
-function translateFrame(frame, projectPath) {
-    if (!frame || false !== frame.ok) return frame;
-    if (frame.error && "string" == typeof frame.error.message) frame.error.message = withSessionContext(toMcpSpeak(frame.error.message), projectPath);
-    if ("string" == typeof frame.error?.hint) frame.error.hint = toMcpSpeak(frame.error.hint);
-    if ("string" == typeof frame.hint) frame.hint = toMcpSpeak(frame.hint);
-    return frame;
-}
-async function runActVerb(args, projectPath, timeoutMs) {
-    const { code, stdout, stderr } = await runExtensionCli([
-        ...args,
-        "--output",
-        "json"
-    ], {
-        cwd: projectPath,
-        timeoutMs
-    });
-    const out = stdout.trim();
-    if (out) try {
-        const frame = JSON.parse(out);
-        if (frame && false === frame.ok) return JSON.stringify(translateFrame(frame, projectPath));
-        return out;
-    } catch  {}
-    const message = stderr.trim() || `extension exited with code ${code}`;
-    return JSON.stringify({
-        ok: false,
-        error: {
-            name: "CliError",
-            message: withSessionContext(toMcpSpeak(message), projectPath)
-        }
-    });
-}
-function commonFlags(args) {
-    const flags = [];
-    if (args.context) flags.push("--context", args.context);
-    if (args.url) flags.push("--url", args.url);
-    if (null != args.tab) flags.push("--tab", String(args.tab));
-    if (args.browser) flags.push("--browser", args.browser);
-    if (null != args.timeout) flags.push("--timeout", String(args.timeout));
-    return flags;
-}
 const eval_schema = {
     name: "extension_eval",
     description: "Evaluate an expression in a running extension context. Requires the dev session to be started with allowEval: true (extension_dev; writes a 0600 session token the CLI reads). Context default: on a Chromium session whose manifest is MV3 (the default template) the default is `page` (the active tab), because the MV3 background is a service worker whose CSP blocks eval, so a background default would fail on the most common path; on Firefox/MV2 sessions the default stays `background`. Pass `context: \"background\"` explicitly to target the worker anyway (on Chromium MV3 that returns the CSP explanation). Targeting for context content/page: pass `url` to pick the matching tab, or omit both `url` and `tab` to use the ACTIVE tab; a numeric `tab` id is only needed to disambiguate. Extension surfaces (popup/options/sidebar/devtools) and override pages (newtab/history/bookmarks) evaluate over the in-bundle relay and need NO tab id; the surface must be OPEN (extension_open first; a closed surface returns an explicit error). Use extension_dom_inspect with listTabs: true to enumerate {tabId,url,title}. Wraps `extension eval`.",
@@ -3984,14 +4209,8 @@ async function pollForTarget(port, url, budgetMs) {
         await new Promise((r)=>setTimeout(r, 250));
     }
 }
-async function navigateToUrl(projectPath, browser, url) {
-    if (!isChromiumFamily(browser)) return JSON.stringify({
-        ok: false,
-        error: {
-            name: "Unsupported",
-            message: `URL navigation drives a tab over Chrome DevTools Protocol, which ${browser} (Gecko) does not expose. On Firefox, drive the page via extension_eval (context: "page"/"content") or read extension_logs.`
-        }
-    });
+async function navigateToUrl(projectPath, browser, url, timeout) {
+    if (!isChromiumFamily(browser)) return navigateToUrlViaBridge(projectPath, browser, url, timeout);
     const resolved = await resolveCdpPort(projectPath, browser);
     if (!resolved) return JSON.stringify({
         ok: false,
@@ -4234,16 +4453,32 @@ async function applyPopupBounds(projectPath, browser, targetId) {
 async function openSurfaceAsTab(projectPath, browser, surface) {
     const doc = surfaceDocument(projectPath, browser, surface);
     if (!doc) return missingSurfaceError(projectPath, browser, surface, "so there is no page to render as a tab");
-    const id = await resolveExtensionId(projectPath, browser);
-    if (!id) return JSON.stringify({
-        ok: false,
-        error: {
-            name: "NoExtensionId",
-            message: "Could not resolve the extension id from the live session's CDP targets."
-        },
-        hint: `Confirm the session is ready (extension_wait). ${CDP_PORT_MISSING_HINT}`
-    });
-    const url = `chrome-extension://${id}/${doc}`;
+    let url;
+    let extensionId = null;
+    if (isChromiumFamily(browser)) {
+        extensionId = await resolveExtensionId(projectPath, browser);
+        if (!extensionId) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoExtensionId",
+                message: "Could not resolve the extension id from the live session's CDP targets."
+            },
+            hint: `Confirm the session is ready (extension_wait). ${CDP_PORT_MISSING_HINT}`
+        });
+        url = `chrome-extension://${extensionId}/${doc}`;
+    } else {
+        const base = await resolveBridgeBaseUrl(projectPath, browser);
+        if (!base) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoExtensionId",
+                message: "Could not resolve the extension's moz-extension:// base URL from the live session (a background eval of runtime.getURL)."
+            },
+            hint: "Confirm the session is ready (extension_wait) and was started with allowEval: true (extension_dev)."
+        });
+        url = `${base}${doc}`;
+        extensionId = base.replace(/^.*:\/\//, "").replace(/\/$/, "");
+    }
     const raw = await navigateToUrl(projectPath, browser, url);
     try {
         const parsed = JSON.parse(raw);
@@ -4251,14 +4486,14 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
             parsed.renderedAsTab = {
                 surface,
                 document: doc,
-                extensionId: id
+                extensionId
             };
             let popupBounds = null;
             if (("popup" === surface || "action" === surface) && "string" == typeof parsed.target?.targetId) {
                 popupBounds = await applyPopupBounds(projectPath, browser, parsed.target.targetId);
                 if (popupBounds) parsed.renderedAsTab.popupBounds = popupBounds;
             }
-            parsed.hint = `Rendered the ${surface} document in a real tab, which is how you inspect a surface headlessly. ` + (popupBounds ? `The window was resized to the popup's content size (${popupBounds.width}x${popupBounds.height}${popupBounds.clamped ? ", clamped to Chrome's 25x25-800x600 popup bounds" : ""}), approximating real popup rendering. This resizes the WHOLE browser window for the session. It is the same page with the same extension APIs, but window.close() closes the tab. ` : "It is the same page with the same extension APIs, but it is NOT hosted in a popup window: no popup sizing, and window.close() closes the tab. ") + `Inspect it with extension_dom_inspect context: '${surface}' (include: ['html']), or extension_source_inspect with this url. ` + "Do NOT pass this chrome-extension:// url to extension_dom_inspect or extension_eval as a tab target: script injection cannot reach extension pages, only the surface context or CDP can.";
+            parsed.hint = `Rendered the ${surface} document in a real tab, which is how you inspect a surface headlessly. ` + (popupBounds ? `The window was resized to the popup's content size (${popupBounds.width}x${popupBounds.height}${popupBounds.clamped ? ", clamped to Chrome's 25x25-800x600 popup bounds" : ""}), approximating real popup rendering. This resizes the WHOLE browser window for the session. It is the same page with the same extension APIs, but window.close() closes the tab. ` : "It is the same page with the same extension APIs, but it is NOT hosted in a popup window: no popup sizing, and window.close() closes the tab. ") + `Inspect it with extension_dom_inspect context: '${surface}' (include: ['html']), or extension_source_inspect with this url. ` + "Do NOT pass this extension-page url to extension_dom_inspect or extension_eval as a tab target: script injection cannot reach extension pages, only the surface context or CDP can.";
             return JSON.stringify(parsed);
         }
     } catch  {}
@@ -4294,7 +4529,7 @@ const open_schema = {
             },
             url: {
                 type: "string",
-                description: "Navigate a real tab to this URL (Chromium only, via CDP) instead of opening a surface. Use for content-script/webNavigation test pages, or the popup as a page: chrome-extension://<id>/popup.html. Alternative to `surface`."
+                description: "Navigate a real tab to this URL instead of opening a surface (Chromium via CDP; Firefox via the agent bridge, which needs allowEval: true). Use for content-script/webNavigation test pages, or the popup as a page: chrome-extension://<id>/popup.html. Alternative to `surface`."
             },
             asTab: {
                 type: "boolean",
@@ -4317,7 +4552,7 @@ const open_schema = {
 };
 async function open_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
-    if (args.url) return navigateToUrl(args.projectPath, browser, args.url);
+    if (args.url) return navigateToUrl(args.projectPath, browser, args.url, args.timeout);
     const AS_TAB_SURFACES = [
         "popup",
         "options",
@@ -4368,7 +4603,7 @@ async function open_handler(args) {
         const parsed = JSON.parse(raw);
         const msg = String(parsed?.error?.message ?? "");
         if (parsed?.ok === false && /active browser window|no active|headless|user gesture/i.test(msg)) {
-            if (AS_TAB_SURFACES.includes(args.surface) && isChromiumFamily(browser)) {
+            if (AS_TAB_SURFACES.includes(args.surface)) {
                 const fallback = await openSurfaceAsTab(args.projectPath, browser, args.surface);
                 try {
                     const parsedFallback = JSON.parse(fallback);
@@ -4422,7 +4657,7 @@ const dom_inspect_schema = {
             },
             tabUrl: {
                 type: "string",
-                description: "Target the tab whose URL contains this substring (case-insensitive; titles are checked only when no url matches). Resolved against the live browser's CDP page targets BEFORE inspecting: exactly one match proceeds; zero or several matches return the candidate targets (targetId/url/title) so you can narrow, never a guess. Chromium sessions only; on Firefox use `url`/`tab`. Alternative to `url`."
+                description: "Target the tab whose URL contains this substring (case-insensitive; titles are checked only when no url matches). Resolved against the live browser BEFORE inspecting (Chromium: CDP page targets; Firefox: the agent bridge tab list): exactly one match proceeds; zero or several matches return the candidates so you can narrow, never a guess. Alternative to `url`."
             },
             listTargets: {
                 type: "boolean",
@@ -4550,6 +4785,7 @@ async function dom_inspect_handler(args) {
         ] : []
     ], args.projectPath, args.timeout);
     let targetUrl = args.url;
+    let targetTab = args.tab;
     let resolvedTarget = null;
     if (args.tabUrl) {
         if (null != args.tab || args.url) return JSON.stringify({
@@ -4560,48 +4796,79 @@ async function dom_inspect_handler(args) {
             }
         });
         const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
-        const cdp = await cdpPortOrError(args.projectPath, browser, "tabUrl");
-        if ("error" in cdp) return cdp.error;
-        let targets;
-        try {
-            targets = await listPageTargets(cdp.port);
-        } catch (e) {
-            return JSON.stringify({
+        if (isChromiumFamily(browser)) {
+            const cdp = await cdpPortOrError(args.projectPath, browser, "tabUrl");
+            if ("error" in cdp) return cdp.error;
+            let targets;
+            try {
+                targets = await listPageTargets(cdp.port);
+            } catch (e) {
+                return JSON.stringify({
+                    ok: false,
+                    error: {
+                        name: "CdpError",
+                        message: `Could not list page targets to resolve tabUrl: ${e instanceof Error ? e.message : String(e)}`
+                    },
+                    hint: "Confirm the session is ready (extension_wait), then retry, or target with `url`/`tab` instead."
+                });
+            }
+            const matches = matchTargetsByUrl(targets, args.tabUrl);
+            if (0 === matches.length) return JSON.stringify({
                 ok: false,
                 error: {
-                    name: "CdpError",
-                    message: `Could not list page targets to resolve tabUrl: ${e instanceof Error ? e.message : String(e)}`
+                    name: "NoMatchingTarget",
+                    message: `No open page target's url (or title) contains "${args.tabUrl}" (case-insensitive).`
                 },
-                hint: "Confirm the session is ready (extension_wait), then retry, or target with `url`/`tab` instead."
+                availableTargets: targets,
+                hint: `Pick one from availableTargets and retry with a \`tabUrl\` substring of its url, or open the page first (extension_open with \`url\`). ${TARGET_ID_NOTE}`
             });
+            if (matches.length > 1) return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "AmbiguousTabUrl",
+                    message: `${matches.length} page targets match "${args.tabUrl}"; refusing to guess which tab you mean.`
+                },
+                matchingTargets: matches,
+                hint: `Narrow \`tabUrl\` to a longer substring that matches exactly one url in matchingTargets. ${TARGET_ID_NOTE}`
+            });
+            resolvedTarget = {
+                ...matches[0]
+            };
+            targetUrl = matches[0].url;
+        } else {
+            const listed = await listBridgeTabs(args.projectPath, browser, args.timeout);
+            if ("error" in listed) return listed.error;
+            const matches = matchTabsByUrl(listed.tabs, args.tabUrl);
+            if (0 === matches.length) return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "NoMatchingTarget",
+                    message: `No open tab's url (or title) contains "${args.tabUrl}" (case-insensitive).`
+                },
+                availableTabs: listed.tabs,
+                hint: "Pick one from availableTabs and retry with a `tabUrl` substring of its url, or open the page first (extension_open with `url`)."
+            });
+            if (matches.length > 1) return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "AmbiguousTabUrl",
+                    message: `${matches.length} tabs match "${args.tabUrl}"; refusing to guess which tab you mean.`
+                },
+                matchingTabs: matches,
+                hint: "Narrow `tabUrl` to a longer substring that matches exactly one url in matchingTabs, or pass its numeric tabId as `tab`."
+            });
+            resolvedTarget = {
+                ...matches[0]
+            };
+            if (null != matches[0].tabId) targetTab = matches[0].tabId;
+            else targetUrl = matches[0].url;
         }
-        const matches = matchTargetsByUrl(targets, args.tabUrl);
-        if (0 === matches.length) return JSON.stringify({
-            ok: false,
-            error: {
-                name: "NoMatchingTarget",
-                message: `No open page target's url (or title) contains "${args.tabUrl}" (case-insensitive).`
-            },
-            availableTargets: targets,
-            hint: `Pick one from availableTargets and retry with a \`tabUrl\` substring of its url, or open the page first (extension_open with \`url\`). ${TARGET_ID_NOTE}`
-        });
-        if (matches.length > 1) return JSON.stringify({
-            ok: false,
-            error: {
-                name: "AmbiguousTabUrl",
-                message: `${matches.length} page targets match "${args.tabUrl}"; refusing to guess which tab you mean.`
-            },
-            matchingTargets: matches,
-            hint: `Narrow \`tabUrl\` to a longer substring that matches exactly one url in matchingTargets. ${TARGET_ID_NOTE}`
-        });
-        resolvedTarget = matches[0];
-        targetUrl = resolvedTarget.url;
     }
     const cli = [
         "inspect",
         args.projectPath
     ];
-    if (null != args.tab) cli.push("--tab", String(args.tab));
+    if (null != targetTab) cli.push("--tab", String(targetTab));
     if (targetUrl) cli.push("--url", targetUrl);
     if (args.context) cli.push("--context", args.context);
     if (args.include?.length) cli.push("--include", args.include.join(","));

package/dist/src/lib/bridge-tabs.d.ts

@@ -0,0 +1,14 @@
+export interface BridgeTab {
+    tabId: number | null;
+    url: string;
+    title: string;
+}
+export declare function listBridgeTabs(projectPath: string, browser: string, timeout?: number): Promise<{
+    tabs: BridgeTab[];
+} | {
+    error: string;
+}>;
+export declare function matchTabsByUrl(tabs: BridgeTab[], needle: string): BridgeTab[];
+export declare function pollForBridgeTab(projectPath: string, browser: string, url: string, budgetMs: number): Promise<BridgeTab | null>;
+export declare function navigateToUrlViaBridge(projectPath: string, browser: string, url: string, timeout?: number): Promise<string>;
+export declare function resolveBridgeBaseUrl(projectPath: string, browser: string, timeout?: number): Promise<string | null>;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "5.5.1",
-  "description": "MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex) build, run, inspect, and publish browser extensions. 33 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, Firefox, Safari, and every Chromium- or Gecko-based browser (Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf). Powered by extension.dev and Extension.js.",
+  "version": "5.5.2",
+  "description": "MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex) build, run, inspect, and publish browser extensions. 33 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, Firefox, and every Chromium- or Gecko-based browser (Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf), with Safari coming next. Powered by extension.dev and Extension.js.",
   "mcpName": "io.github.extensiondev/mcp",
   "license": "MIT",
   "author": {

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://extension.dev",
-  "version": "5.5.1",
+  "version": "5.5.2",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@extension.dev/mcp",
-      "version": "5.5.1",
+      "version": "5.5.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"