@extension.dev/mcp 10.10.6 → 10.10.8

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "extension-mcp",
       "source": "./",
       "description": "MCP tools for browser extension development: scaffold from 50+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox.",
-      "version": "10.10.6",
+      "version": "10.10.8",
       "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 50+ 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": "10.10.6",
+  "version": "10.10.8",
   "author": {
     "name": "Cezar Augusto",
     "email": "hello@extension.dev",

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 10.10.8
+
+- On Firefox, `extension_eval` now reads an extension whose content
+  security policy forbids eval, which is every MV3 extension page
+  (BUGS_TO_FIX_MCP.md entry 20). Extension.js 4.1.31 evaluates such a
+  document over the debugger protocol, but the wrapper this server put
+  around a popup, options, sidebar or override-page expression called
+  eval itself, so those contexts still answered "blocked by CSP" on an
+  engine that could read them. A refused surface is now asked again with
+  the bare expression, which the engine takes over the protocol and
+  awaits there. A project pinned below 4.1.31 keeps the refusal, and its
+  hint now names that floor.
+- `extension_eval` with `context: "page"` and a `moz-extension://` url
+  reaches a page the manifest declares as no surface (`pages/*`), through
+  the console actor of the tab showing it. It used to answer
+  `E_NO_SURFACE_DOCUMENT`. Open the page with `extension_open` first; a
+  page no tab shows answers `E_NO_MATCHING_TARGET`.
+- `extension_dom_snapshot` on a `moz-extension://` url reads the page the
+  same way when Firefox refuses the injection with "Missing host
+  permission for the tab", and returns the engine's own snapshot fields.
+- `extension_eval` with `context: "page"` on a site whose policy forbids
+  eval now works on an MV3 Firefox build, over the debugger protocol,
+  when `url` names the tab. An MV2 build keeps its `tabs.executeScript`
+  route, which had gone dead on Extension.js 4.1.31 because that engine
+  renamed the refusal to `E_CSP_BLOCKS_EVAL`; both spellings are read now.
+- The protocol takes one expression. A statement list sent to a
+  policy-locked Firefox document answers `E_BAD_REQUEST` with the way to
+  wrap it, where the background used to answer a control-channel error
+  carrying "SyntaxError: expected expression".
+- Still refused, by name: a string evaluated in the content-script world
+  of an extension whose policy forbids eval. Use `context: "page"` or
+  `extension_dom_snapshot` there.
+
+- `extension_submit` and `extension_store_status` link to the console's
+  Submissions tab at `/<workspace>/<project>/submissions`, where the page
+  moved; the old `/stores` address still redirects. `@extension.dev/urls`
+  moves to `^0.8.2`, which carries the new paths.
+
+## 10.10.7
+
+- A share revoke now waits for a person by default, like a real store
+  submission and a promotion to stable: the first `extension_shares`
+  revoke answers `approval-required` with a link, and the same call with
+  the returned `approvalId` runs it once. A revoke cannot be undone, so
+  it is the one outward call that should never run on an agent's word
+  alone. `EXTENSION_DEV_APPROVAL_GATE=0` still turns the gate off.
+- New tool `extension_docs_search`: keyword search over the Extension.js
+  and extension.dev docs, returning up to 8 pages with a title, URL and
+  an excerpt of at most 400 characters. It calls
+  `/api/docs/search` on extension.dev, which ranks with no model call, so
+  it is free, needs no login and is in the `local` group. Its
+  description is kept short on purpose so it costs little context.
+
 ## 10.10.6
 
 - Tools that read a page or an extension (`extension_logs`,

package/README.md

@@ -7,7 +7,7 @@
 
 # @extension.dev/mcp [![Version][npm-version-image]][npm-version-url] [![Downloads][npm-downloads-image]][npm-downloads-url] [![Discord][discord-image]][discord-url]
 
-> Give your AI agent hands for browser extension development. 31 MCP tools that scaffold, run, inspect, debug, and publish cross-browser extensions.
+> Give your AI agent hands for browser extension development. 32 MCP tools that scaffold, run, inspect, debug, and publish cross-browser extensions.
 
 <img alt="Logo" align="right" src="https://media.extension.land/brand/extension-dev/logo-dock.png" width="20.7%" />
 
@@ -151,7 +151,7 @@ Two flags (or environment variables) narrow the server before an agent sees it:
 
 A refused call answers `E_TOOL_DISABLED` with the flag to change.
 
-A real store submission and a promotion to stable also wait for a person by default: the first call answers `approval-required` with a link on extension.dev, a workspace member approves exactly that action, and the same call with the returned `approvalId` runs it once. `EXTENSION_DEV_APPROVAL_GATE=1` extends this to every promotion and share revoke; `EXTENSION_DEV_APPROVAL_GATE=0` turns it off.
+A real store submission, a promotion to stable and a share revoke also wait for a person by default: the first call answers `approval-required` with a link on extension.dev, a workspace member approves exactly that action, and the same call with the returned `approvalId` runs it once. `EXTENSION_DEV_APPROVAL_GATE=1` extends this to every promotion; `EXTENSION_DEV_APPROVAL_GATE=0` turns it off.
 
 Every tool also carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so clients can auto-approve reads and ask before the rest.
 
@@ -196,6 +196,7 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | ---- | ---- | ----------- |
 | build | `extension_create` | Scaffold from a template |
 | build | `extension_templates` | Browse 50+ templates (`list`) and read one's source (`source`) |
+| build | `extension_docs_search` | Search the Extension.js and extension.dev docs by keyword |
 | build | `extension_add_feature` | Add sidebar/popup/content script |
 | build | `extension_build` | Build for production |
 | run | `extension_dev` | Dev server with HMR |

package/dist/module.js

@@ -9,7 +9,7 @@ import node_os from "node:os";
 import cross_spawn from "cross-spawn";
 import { PROD_ORIGINS, resolveOrigins } from "@extension.dev/urls/origins";
 import node_crypto, { createHash, randomUUID } from "node:crypto";
-import { consoleProjectPath, wwwNewPath } from "@extension.dev/urls/paths";
+import { ConsoleProjectPage, consoleProjectPath, wwwNewPath } from "@extension.dev/urls/paths";
 import { UserlandProjectPage, userlandUrl } from "@extension.dev/urls/userland";
 import { CLOSE_BAD_HELLO, CLOSE_BAD_INSTANCE, CLOSE_CONTROL_UNAVAILABLE, CLOSE_SLOW_CONSUMER, CONTROL_ENVELOPE_VERSION, CONTROL_WS_PATH, actionsPath, browserArtifactsDir, buildSummaryPath, eventsPath, logsPath, matchesLogQuery, readLogEvents, readReadyContract, readyContractPath as bridge_readyContractPath, sessionArtifactsRootDir, sessionStateDir as bridge_sessionStateDir } from "extension-develop/bridge";
 import { fileURLToPath } from "node:url";
@@ -75,6 +75,12 @@ __webpack_require__.d(dev_namespaceObject, {
     handler: ()=>dev_handler,
     schema: ()=>dev_schema
 });
+var docs_search_namespaceObject = {};
+__webpack_require__.r(docs_search_namespaceObject);
+__webpack_require__.d(docs_search_namespaceObject, {
+    handler: ()=>docs_search_handler,
+    schema: ()=>docs_search_schema
+});
 var doctor_namespaceObject = {};
 __webpack_require__.r(doctor_namespaceObject);
 __webpack_require__.d(doctor_namespaceObject, {
@@ -86,6 +92,7 @@ var dom_snapshot_namespaceObject = {};
 __webpack_require__.r(dom_snapshot_namespaceObject);
 __webpack_require__.d(dom_snapshot_namespaceObject, {
     handler: ()=>dom_snapshot_handler,
+    protocolSnapshotExpression: ()=>protocolSnapshotExpression,
     schema: ()=>dom_snapshot_schema
 });
 var eval_namespaceObject = {};
@@ -236,7 +243,7 @@ __webpack_require__.d(workspace_create_namespaceObject, {
     handler: ()=>workspace_create_handler,
     schema: ()=>workspace_create_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"10.10.6","El":{"OP":"4.1.31"}}');
+var package_namespaceObject = JSON.parse('{"rE":"10.10.8","El":{"OP":"4.1.31"}}');
 const ENVELOPE_SCHEMA = 1;
 const collectWarnings = (warnings)=>{
     if (!warnings) return [];
@@ -9930,7 +9937,10 @@ async function revokeShare(args) {
         api: args.api
     };
     if (token) {
-        const gate = await evaluateApproval(gateInput);
+        const gate = await evaluateApproval({
+            ...gateInput,
+            enabled: approvalGateEnabled(true)
+        });
         if (gate.blocked) return gate.envelope;
     }
     const result = await revokeArtifact({
@@ -13600,6 +13610,223 @@ async function rdpCollectConsoleMessages(port, options) {
         return messages;
     });
 }
+const RDP_EVAL_SLOT = "__extensionDevRdpEval";
+const RDP_FRAME_WAIT_MS = 5000;
+const RDP_FRAME_POLL_MS = 50;
+const RDP_RESULT_POLL_MS = 100;
+function rdpStartExpression(expression, token) {
+    const key = JSON.stringify(token);
+    return `(function () {
+  var store = globalThis.${RDP_EVAL_SLOT} = globalThis.${RDP_EVAL_SLOT} || {};
+  store[${key}] = { state: "pending" };
+  function settle(next) { store[${key}] = next; }
+  function encode(value) {
+    if (value === undefined) return { state: "value" };
+    var json;
+    try { json = JSON.stringify(value); } catch (error) { json = undefined; }
+    return { state: "value", json: json === undefined ? JSON.stringify(String(value)) : json };
+  }
+  function thrown(error) {
+    return { state: "throw", name: (error && error.name) || "EvalError", message: (error && error.message) || String(error) };
+  }
+  try {
+    Promise.resolve((${expression}
+)).then(function (value) { settle(encode(value)); }, function (error) { settle(thrown(error)); });
+  } catch (error) {
+    settle(thrown(error));
+  }
+  return "started";
+})()`;
+}
+function rdpPollExpression(token) {
+    const key = JSON.stringify(token);
+    return `(function () {
+  var store = globalThis.${RDP_EVAL_SLOT};
+  var entry = (store && store[${key}]) || null;
+  if (entry && entry.state !== "pending") {
+    delete store[${key}];
+    if (Object.keys(store).length === 0) { try { delete globalThis.${RDP_EVAL_SLOT}; } catch (error) {} }
+  }
+  var encoded = JSON.stringify(entry);
+  return encoded;
+})()`;
+}
+function readRdpEvalSlot(raw) {
+    if ("string" != typeof raw) return "lost";
+    let slot;
+    try {
+        slot = JSON.parse(raw);
+    } catch  {
+        return "lost";
+    }
+    if (!slot || "object" != typeof slot) return "lost";
+    if ("pending" === slot.state) return "pending";
+    if ("throw" === slot.state) return {
+        ok: false,
+        name: "string" == typeof slot.name && slot.name ? slot.name : "EvalError",
+        message: "string" == typeof slot.message && slot.message ? slot.message : "the expression threw inside the document"
+    };
+    if ("value" !== slot.state) return "lost";
+    if ("string" != typeof slot.json) return {
+        ok: true,
+        value: null
+    };
+    try {
+        return {
+            ok: true,
+            value: JSON.parse(slot.json)
+        };
+    } catch  {
+        return {
+            ok: true,
+            value: slot.json
+        };
+    }
+}
+function exceptionText(packet) {
+    const message = packet.exceptionMessage;
+    if ("string" == typeof message) return message;
+    const initial = message?.initial;
+    if ("string" == typeof initial) return initial;
+    return true === packet.hasException || void 0 !== packet.exception && null !== packet.exception ? "the expression threw inside the document" : "";
+}
+async function readStringResult(session, result, timeoutMs) {
+    if (!result || "object" != typeof result) return result;
+    const grip = result;
+    if ("longString" !== grip.type || "string" != typeof grip.actor) return result;
+    const length = "number" == typeof grip.length ? grip.length : 0;
+    const reply = await session.request(grip.actor, {
+        type: "substring",
+        start: 0,
+        end: length
+    }, timeoutMs);
+    return "string" == typeof reply.substring ? reply.substring : grip.initial;
+}
+async function consoleEvaluate(session, consoleActor, text, timeoutMs) {
+    const results = [];
+    let wake = null;
+    const untap = session.tap((packet)=>{
+        if (packet.from !== consoleActor || "evaluationResult" !== packet.type) return;
+        results.push(packet);
+        wake?.();
+    });
+    try {
+        const reply = await session.request(consoleActor, {
+            type: "evaluateJSAsync",
+            text
+        }, timeoutMs);
+        const resultId = String(reply.resultID ?? "");
+        const deadline = Date.now() + timeoutMs;
+        for(;;){
+            const hit = results.find((p)=>String(p.resultID ?? "") === resultId);
+            if (hit) return {
+                result: await readStringResult(session, hit.result, timeoutMs),
+                threw: exceptionText(hit)
+            };
+            const left = deadline - Date.now();
+            if (left <= 0) throw new Error(`Firefox sent no evaluation result within ${timeoutMs}ms`);
+            await new Promise((resolve)=>{
+                const timer = setTimeout(resolve, Math.min(left, 250));
+                wake = ()=>{
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+            wake = null;
+        }
+    } finally{
+        untap();
+    }
+}
+function topFrameConsoleActor(frames) {
+    const usable = frames.filter((frame)=>"string" == typeof frame.consoleActor);
+    const top = usable.find((frame)=>true === frame.isTopLevelTarget) ?? usable[0];
+    return top ? String(top.consoleActor) : void 0;
+}
+async function rdpEvaluateInTab(port, options) {
+    const timeoutMs = options.timeoutMs ?? 10000;
+    return withSession(port, timeoutMs, async (session)=>{
+        const listed = await session.request("root", {
+            type: "listTabs"
+        }, timeoutMs);
+        const tab = options.select(listed.tabs ?? []);
+        if (!tab?.actor) return {
+            ok: false,
+            name: "TargetNotFound",
+            message: "no open tab matches"
+        };
+        const watcher = await session.request(String(tab.actor), {
+            type: "getWatcher",
+            isServerTargetSwitchingEnabled: true
+        }, timeoutMs);
+        const watcherActor = String(watcher.actor ?? "");
+        if (!watcherActor) return {
+            ok: false,
+            name: "Unsupported",
+            message: "this Firefox build exposes no watcher actor for a tab, so the tab cannot be evaluated over the debugger protocol"
+        };
+        const frames = [];
+        const untap = session.tap((packet)=>{
+            if ("target-available-form" !== packet.type) return;
+            const target = packet.target;
+            if (target && "object" == typeof target) frames.push(target);
+        });
+        try {
+            await session.request(watcherActor, {
+                type: "watchTargets",
+                targetType: "frame"
+            }, timeoutMs);
+            const frameDeadline = Date.now() + Math.min(timeoutMs, RDP_FRAME_WAIT_MS);
+            let consoleActor = topFrameConsoleActor(frames);
+            while(!consoleActor && Date.now() < frameDeadline){
+                await new Promise((resolve)=>setTimeout(resolve, RDP_FRAME_POLL_MS));
+                consoleActor = topFrameConsoleActor(frames);
+            }
+            if (!consoleActor) return {
+                ok: false,
+                name: "TargetNotFound",
+                message: "the tab announced no document to evaluate in (it may still be loading)"
+            };
+            const token = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+            const started = await consoleEvaluate(session, consoleActor, rdpStartExpression(options.expression, token), timeoutMs);
+            if (started.threw) return {
+                ok: false,
+                name: "EvalError",
+                message: started.threw
+            };
+            const resultDeadline = Date.now() + timeoutMs;
+            for(;;){
+                const polled = await consoleEvaluate(session, consoleActor, rdpPollExpression(token), timeoutMs);
+                const settled = readRdpEvalSlot(polled.result);
+                if ("lost" === settled) return {
+                    ok: false,
+                    name: "EvalLost",
+                    message: "the document reloaded or navigated before the expression settled, so its result is gone"
+                };
+                if ("pending" !== settled) return settled.ok ? {
+                    ok: true,
+                    value: settled.value,
+                    tab: {
+                        url: String(tab.url ?? ""),
+                        title: String(tab.title ?? "")
+                    }
+                } : settled;
+                if (Date.now() >= resultDeadline) return {
+                    ok: false,
+                    name: "Timeout",
+                    message: `the expression did not settle within ${timeoutMs}ms`
+                };
+                await new Promise((resolve)=>setTimeout(resolve, RDP_RESULT_POLL_MS));
+            }
+        } finally{
+            untap();
+            session.request(watcherActor, {
+                type: "unwatchTargets",
+                targetType: "frame"
+            }, 1000).catch(()=>{});
+        }
+    });
+}
 const inspect_schema_schema = {
     name: "extension_inspect",
     description: "Inspect a running extension deeply over the browser's debugger protocol: full HTML including shadow DOM, DOM structure, content-script injection, console messages, and CSS selector queries through `probe`. This is the ONLY tool that pierces closed shadow roots (deepDom), runs selector probes, and navigates a tab to `url` before reading it. It reads a web or override page and picks the first inspectable target, or the first whose url contains `url`; it cannot address an extension surface by name and takes no chrome.tabs id. Use extension_dom_snapshot to choose which tab or which open surface (popup, options, sidebar, devtools) to read, or to enumerate what is open. Use extension_analyze for a built extension's files and sizes on disk. Chromium rides the Chrome DevTools Protocol and needs the session's debug port, not allowControl. Firefox is fully paired: summary, meta, html, dom_snapshot, extension_roots and probes ride the agent bridge and need allowEval:true, console rides the RDP watcher replay on engine 4.0.15 and later, and deepDom needs an MV2 session with host permissions for the target url, because the Firefox MV3 background CSP blocks bridge evals. This requires an active dev or start session.",
@@ -14434,7 +14661,7 @@ function readRelayFrame(value) {
 }
 const eval_schema = {
     name: "extension_eval",
-    description: "Evaluate an expression in a running extension context. Start the session with allowEval:true (extension_dev), which writes a 0600 session token. Context defaults to 'background', except on a Chromium MV3 session (the default template) where it defaults to 'page', the active tab, because the MV3 service worker CSP blocks eval; pass context:'background' to target the worker anyway and get that explanation back. For content and page, pass `url` to pick the tab, or omit both `url` and `tab` for the active tab; a numeric `tab` only disambiguates. Extension surfaces (popup, options, sidebar, devtools) and override pages (newtab, history, bookmarks) need no tab id but must already be open: open one with extension_open first, because a closed one returns an explicit error. On a Chromium MV3 session those pages, and context:'page' with a chrome-extension:// url, evaluate over CDP, the inspector path the extension page CSP does not govern; elsewhere they evaluate over the in-bundle relay. Call extension_dom_snapshot with listTabs:true to enumerate {tabId, url, title}.",
+    description: "Evaluate an expression in a running extension context. Start the session with allowEval:true (extension_dev), which writes a 0600 session token. Context defaults to 'background', except on a Chromium MV3 session (the default template) where it defaults to 'page', the active tab, because the MV3 service worker CSP blocks eval; pass context:'background' to target the worker anyway and get that explanation back. For content and page, pass `url` to pick the tab, or omit both `url` and `tab` for the active tab; a numeric `tab` only disambiguates. Extension surfaces (popup, options, sidebar, devtools) and override pages (newtab, history, bookmarks) need no tab id but must already be open: open one with extension_open first, because a closed one returns an explicit error. On a Chromium MV3 session those pages, and context:'page' with a chrome-extension:// url, evaluate over CDP, the inspector path the extension page CSP does not govern; elsewhere they evaluate over the in-bundle relay. On Firefox a document whose content security policy forbids eval (the extension's own pages, or a site's) is evaluated over the debugger protocol instead, which takes one expression; a page inside the extension that is no declared surface (pages/*) is reached the same way by context:'page' and its moz-extension:// url once a tab shows it. Call extension_dom_snapshot with listTabs:true to enumerate {tabId, url, title}.",
     inputSchema: {
         type: "object",
         properties: {
@@ -14755,6 +14982,7 @@ async function evaluateThroughRelay(args, browser, context) {
         ], args.projectPath, args.timeout, eval_schema.name);
     let raw = await run(relaySafeExpression(args.expression, token));
     let parsed = tryParseFrame(raw);
+    if (isGeckoFamily(browser) && cspRefusedFrame(parsed)) return evaluatePastSurfaceCsp(args, context, run);
     if (!parsed || true !== parsed.ok) return raw;
     let frame = readRelayFrame(parsed.value);
     if (!frame) return raw;
@@ -14801,21 +15029,28 @@ async function evaluateThroughRelay(args, browser, context) {
     return actFrameJson(parsed);
 }
 const CSP_EVAL_REFUSAL = /blocked by CSP|call to eval|unsafe-eval|Content Security Policy/i;
+function cspRefusedFrame(parsed) {
+    if (!parsed || false !== parsed.ok) return false;
+    const code = "string" == typeof parsed.error?.code ? parsed.error.code : "";
+    if ("E_CSP_BLOCKS_EVAL" === code) return true;
+    return "E_EVAL" === code && CSP_EVAL_REFUSAL.test(String(parsed.error?.message ?? ""));
+}
+function cspRefusalHint(context) {
+    if ("page" === context) return "This page's own Content-Security-Policy forbids eval, so the in-page executor cannot run any expression in it; this is the site's policy, not a fault in the expression. Pass url so the tab is evaluated through the browser's debugger, which the policy does not govern (CDP on Chromium, the debugger protocol on Firefox), or read the page with extension_dom_snapshot or extension_inspect.";
+    if ("content" === context) return "The extension's content_security_policy forbids eval in its content-script world on this engine, so no string runs there; this is the extension's policy, not a fault in the expression. Evaluate the page itself with context: \"page\" and a url, or read the DOM the content script sees with extension_dom_snapshot or extension_inspect.";
+    return `The extension's content_security_policy (or the MV3 default) forbids eval in its own ${context ?? "background"} context, so the in-page executor cannot run any expression there; this is the extension's policy, not a fault in the expression. Read the page instead with extension_dom_snapshot or extension_inspect, evaluate a web page with context: \"page\" and a url, or read the extension's console with extension_logs. On a Chromium MV3 session the extension's own pages evaluate over CDP, which the page policy does not govern. On Firefox, Extension.js 4.1.31 and later evaluate them over the debugger protocol instead: if this session runs an older engine, upgrade the project's extension dependency and restart it.`;
+}
 function explainCspRefusal(raw, context) {
     const parsed = tryParseFrame(raw);
-    if (!parsed || false !== parsed.ok) return null;
-    const code = "string" == typeof parsed.error?.code ? parsed.error.code : "";
-    const message = String(parsed.error?.message ?? "");
-    if ("E_EVAL" !== code || !CSP_EVAL_REFUSAL.test(message)) return null;
+    if (!parsed || !cspRefusedFrame(parsed)) return null;
     parsed.error.name = "CspBlocksEval";
-    parsed.hint = `The extension's content_security_policy (or the MV3 default) forbids eval in its own ${context ?? "background"} context, so the in-page executor cannot run any expression there; this is the extension's policy, not a fault in the expression. Read the page instead with extension_dom_snapshot or extension_inspect, evaluate a web page with context: \"page\" and a url, or read the extension's console with extension_logs. On a Chromium MV3 session the extension's own pages evaluate over CDP, which the page policy does not govern.`;
+    parsed.hint = cspRefusalHint(context);
     if ("string" == typeof parsed.error.hint) delete parsed.error.hint;
     return actFrameJson(parsed);
 }
 const NO_SCRIPTING_API = /scripting is not available/i;
 function pageEvalRefusedByCsp(parsed) {
-    const code = "string" == typeof parsed.error?.code ? parsed.error.code : "";
-    return "E_EVAL" === code && CSP_EVAL_REFUSAL.test(String(parsed.error?.message ?? ""));
+    return cspRefusedFrame(parsed);
 }
 function isSingleExpression(source) {
     try {
@@ -14825,6 +15060,110 @@ function isSingleExpression(source) {
         return false;
     }
 }
+function notOneExpression() {
+    return envelope_envelope({
+        ok: false,
+        command: eval_schema.name,
+        status: "bad-request",
+        error: {
+            code: "E_BAD_REQUEST",
+            name: "NotOneExpression",
+            message: "This document's content security policy forbids eval, so Firefox evaluates it over the debugger protocol, which takes one expression, and this input is a statement list."
+        },
+        hint: "Pass one expression. Wrap statements in a function that returns the value, for example (() => { const a = 20; return a + 1; })()."
+    });
+}
+async function evaluatePastSurfaceCsp(args, context, run) {
+    if (!isSingleExpression(args.expression)) return notOneExpression();
+    const direct = await run(args.expression);
+    const frame = tryParseFrame(direct);
+    if (!frame) return direct;
+    if (cspRefusedFrame(frame)) return explainCspRefusal(direct, context) ?? direct;
+    if (true === frame.ok && void 0 === frame.value) {
+        frame.value = null;
+        return actFrameJson(frame);
+    }
+    return direct;
+}
+const sameDocumentUrl = (a, b)=>String(a ?? "").replace(/[?#].*$/, "") === b.replace(/[?#].*$/, "");
+function tabByUrl(tabs, url) {
+    const exact = tabs.filter((tab)=>sameDocumentUrl(tab.url, url));
+    const covered = exact.length ? exact : tabs.filter((tab)=>matchPatternCovers(url, String(tab.url ?? "")));
+    const candidates = covered.length ? covered : tabs.filter((tab)=>String(tab.url ?? "").includes(url));
+    return candidates.find((tab)=>true === tab.selected) ?? candidates[0];
+}
+async function evaluateInGeckoTab(args, browser, select, missing) {
+    const resolved = await resolveRdpPort(args.projectPath, browser, {
+        waitMs: 3000,
+        graceMs: 1000
+    });
+    if (!resolved) return null;
+    let outcome;
+    try {
+        outcome = await rdpEvaluateInTab(resolved.port, {
+            select,
+            expression: args.expression,
+            timeoutMs: args.timeout ?? 10000
+        });
+    } catch  {
+        return null;
+    }
+    if (outcome.ok) return envelope_envelope({
+        ok: true,
+        command: eval_schema.name,
+        status: "ok",
+        value: void 0 === outcome.value ? null : outcome.value
+    });
+    if ("TargetNotFound" === outcome.name) return envelope_envelope({
+        ok: false,
+        command: eval_schema.name,
+        status: "no-matching-target",
+        error: {
+            code: "E_NO_MATCHING_TARGET",
+            name: "NoMatchingTarget",
+            message: missing
+        },
+        hint: "Open the page first with extension_open and its url, then retry; extension_dom_snapshot with listTabs: true lists what is open."
+    });
+    if ("Timeout" === outcome.name) return envelope_envelope({
+        ok: false,
+        command: eval_schema.name,
+        status: "eval-pending",
+        error: {
+            code: "E_WAIT_TIMEOUT",
+            name: "EvalPending",
+            message: outcome.message
+        },
+        hint: "The expression returned a promise that is still pending; pass a larger timeout to wait for it."
+    });
+    return envelope_envelope({
+        ok: false,
+        command: eval_schema.name,
+        status: "eval-failed",
+        error: {
+            code: "E_EVAL",
+            name: outcome.name,
+            message: outcome.message
+        },
+        hint: "The expression threw inside the document. It ran over the debugger protocol, which the document's content security policy does not govern, so this is the expression's own error."
+    });
+}
+function backgroundRouteRefusedStatements(args, browser, context, raw) {
+    if (!isGeckoFamily(browser) || (context ?? "background") !== "background") return false;
+    const failed = tryParseFrame(raw);
+    if (!failed || false !== failed.ok) return false;
+    if (failed.error?.name !== "Unavailable") return false;
+    if (!/SyntaxError/.test(String(failed.error?.message ?? ""))) return false;
+    return !isSingleExpression(args.expression);
+}
+async function evaluatePagePastSiteCsp(args, browser, context, raw) {
+    if ("page" !== context || !isGeckoFamily(browser)) return null;
+    if (!cspRefusedFrame(tryParseFrame(raw))) return null;
+    if (!args.url && null != args.tab) return null;
+    if (!isSingleExpression(args.expression)) return notOneExpression();
+    const url = args.url;
+    return evaluateInGeckoTab(args, browser, url ? (tabs)=>tabByUrl(tabs, url) : (tabs)=>tabs.find((tab)=>true === tab.selected), url ? `No open tab matches url: ${url}` : "No tab is selected in the dev browser.");
+}
 async function evaluateThroughExecuteScript(args, browser, context, raw) {
     if ("page" !== context && "content" !== context) return null;
     if (isChromiumFamily(browser)) return null;
@@ -14919,6 +15258,12 @@ async function eval_handler(args) {
             }
             return raw;
         }
+        if (isGeckoFamily(browser)) {
+            if (!isSingleExpression(args.expression)) return notOneExpression();
+            const url = args.url;
+            const overProtocol = await evaluateInGeckoTab(args, browser, (tabs)=>tabs.find((tab)=>sameDocumentUrl(tab.url, url)), `No open tab shows ${url}.`);
+            if (null !== overProtocol) return overProtocol;
+        }
         const declared = declaredSurfaces(args.projectPath, browser) ?? [];
         return envelope_envelope({
             ok: false,
@@ -14946,6 +15291,9 @@ async function eval_handler(args) {
     ], args.projectPath, args.timeout, eval_schema.name);
     const mv2Fallback = await evaluateThroughExecuteScript(args, browser, context, raw);
     if (null !== mv2Fallback) return mv2Fallback;
+    const pastSiteCsp = await evaluatePagePastSiteCsp(args, browser, context, raw);
+    if (null !== pastSiteCsp) return pastSiteCsp;
+    if (backgroundRouteRefusedStatements(args, browser, context, raw)) return notOneExpression();
     const cspRefusal = explainCspRefusal(raw, context);
     if (null !== cspRefusal) return cspRefusal;
     const trustedTypes = tryParseFrame(raw);
@@ -15182,6 +15530,72 @@ const dom_snapshot_schema = {
         ]
     }
 };
+const GECKO_EXTENSION_URL = /^moz-extension:\/\//;
+const dom_snapshot_sameDocumentUrl = (a, b)=>String(a ?? "").replace(/[?#].*$/, "") === b.replace(/[?#].*$/, "");
+function protocolSnapshotExpression(wantHtml, maxBytes) {
+    return `(function () {
+  var doc = document;
+  function countShadow(root) {
+    var n = 0, els = root.querySelectorAll("*");
+    for (var i = 0; i < els.length; i++) { if (els[i].shadowRoot) { n++; n += countShadow(els[i].shadowRoot); } }
+    return n;
+  }
+  var html = doc.documentElement.outerHTML;
+  var snap = {
+    context: "page",
+    url: String(location.href),
+    title: doc.title,
+    summary: {
+      htmlLength: html.length,
+      scriptCount: doc.querySelectorAll("script").length,
+      styleCount: doc.querySelectorAll("style,link[rel=stylesheet]").length,
+      extensionRootCount: doc.querySelectorAll("#extension-root,[data-extension-root]").length,
+      openShadowRoots: countShadow(doc),
+      bodyChildCount: doc.body ? doc.body.children.length : 0
+    }
+  };
+  if (${wantHtml ? "true" : "false"}) {
+    var cap = ${Math.max(0, Math.floor(maxBytes))};
+    if (cap > 0 && html.length > cap) { snap.html = html.slice(0, cap); snap.htmlTruncated = true; }
+    else { snap.html = html; }
+  }
+  return snap;
+})()`;
+}
+async function snapshotExtensionPageOverProtocol(args, browser, url, raw, consoleAsked) {
+    if (!url || !isGeckoFamily(browser) || !GECKO_EXTENSION_URL.test(url)) return null;
+    try {
+        const refused = JSON.parse(raw);
+        if (!refused || false !== refused.ok) return null;
+    } catch  {
+        return null;
+    }
+    const resolved = await resolveRdpPort(args.projectPath, browser, {
+        waitMs: 3000,
+        graceMs: 1000
+    });
+    if (!resolved) return null;
+    const wantHtml = args.include?.includes("html") === true;
+    try {
+        const outcome = await rdpEvaluateInTab(resolved.port, {
+            select: (tabs)=>tabs.find((tab)=>dom_snapshot_sameDocumentUrl(tab.url, url)),
+            expression: protocolSnapshotExpression(wantHtml, args.maxBytes ?? 262144),
+            timeoutMs: args.timeout ?? 10000
+        });
+        if (!outcome.ok) return null;
+        return envelope_envelope({
+            ok: true,
+            command: dom_snapshot_schema.name,
+            status: "ok",
+            value: outcome.value,
+            warnings: [
+                `${url} is a page inside the extension, which Firefox lets no script be injected into, so this snapshot was read over the debugger protocol from the tab showing it.` + (consoleAsked ? " Console lines are not collected on this path; read them with extension_logs." : "")
+            ]
+        });
+    } catch  {
+        return null;
+    }
+}
 async function cdpPortOrError(projectPath, browser, feature) {
     if (!isChromiumFamily(browser)) return {
         error: envelope_envelope({
@@ -15424,7 +15838,10 @@ async function dom_snapshot_handler(args) {
     if (null != withConsole) cli.push("--with-console", String(withConsole));
     cli.push("--browser", resolveSessionBrowser(args.projectPath, args.browser).browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
-    const raw = await runActVerb(cli, args.projectPath, args.timeout, dom_snapshot_schema.name);
+    const sessionBrowser = resolveSessionBrowser(args.projectPath, args.browser).browser;
+    const asked = await runActVerb(cli, args.projectPath, args.timeout, dom_snapshot_schema.name);
+    const overProtocol = await snapshotExtensionPageOverProtocol(args, sessionBrowser, targetUrl ?? ("string" == typeof resolvedTarget?.url ? resolvedTarget.url : void 0), asked, null != withConsole);
+    const raw = overProtocol ?? asked;
     if (!resolvedTarget) return raw;
     try {
         const parsed = JSON.parse(raw);
@@ -15996,7 +16413,7 @@ async function readStores(args) {
     const healthUrl = registryFileUrl(ref, "stores/health.json");
     const statusUrl = registryFileUrl(ref, "stores/status.json");
     const submissionsUrl = registryFileUrl(ref, "stores/submissions.json");
-    const consoleStoresUrl = consoleProjectUrl(ref, "stores", args.api);
+    const consoleStoresUrl = consoleProjectUrl(ref, ConsoleProjectPage.submissions, args.api);
     const [healthRes, statusRes, submissionsRes] = await Promise.all([
         fetchRegistryJson(healthUrl, fetch, {
             ref,
@@ -16026,7 +16443,7 @@ async function readStores(args) {
             project: ref.project
         }
     });
-    if (!healthRes.ok && !statusRes.ok && !submissionsRes.ok) return store_status_fail("StoreStatusNotFound", `No store data on the registry for ${ref.workspace}/${ref.project} (${healthRes.message}). The project may have no stores configured yet, be private (private registry data needs a share token), or the workspace/project slugs may be wrong. Configure stores at ${consoleStoresUrl}/new; the console Stores page is the authoritative view: ${consoleStoresUrl}`, "unavailable", "E_PLATFORM", {
+    if (!healthRes.ok && !statusRes.ok && !submissionsRes.ok) return store_status_fail("StoreStatusNotFound", `No store data on the registry for ${ref.workspace}/${ref.project} (${healthRes.message}). The project may have no stores configured yet, be private (private registry data needs a share token), or the workspace/project slugs may be wrong. Configure stores at ${consoleStoresUrl}/new; the console Submissions page is the authoritative view: ${consoleStoresUrl}`, "unavailable", "E_PLATFORM", {
         workspace: ref.workspace,
         project: ref.project,
         registryUrls: {
@@ -16438,7 +16855,7 @@ async function submit_handler(args) {
     let statusNote = null;
     if (dryRun) {
         const ref = resolveProjectRef();
-        const consoleStoresUrl = consoleProjectUrl(ref, "stores", args.api);
+        const consoleStoresUrl = consoleProjectUrl(ref, ConsoleProjectPage.submissions, args.api);
         const storeModeNote = `Store publish mode (draft / skip-publish / live) is not readable with the CLI token, so it cannot be verified from here; check per-store settings at ${consoleStoresUrl}.`;
         let health = null;
         let healthUnreadable = null;
@@ -17939,6 +18356,95 @@ async function browsers_handler(args) {
     });
     return detectBrowsers(args.browsers);
 }
+const docs_search_COMMAND = "extension_docs_search";
+const docs_search_schema = {
+    name: docs_search_COMMAND,
+    description: "Find pages in the Extension.js and extension.dev docs by keyword, each with a short excerpt. Use it before answering from memory on anything version-specific: a CLI flag, a manifest field across browsers, a store submission rule. Free and needs no login.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "What to look up, in a few words."
+            },
+            limit: {
+                type: "number",
+                minimum: 1,
+                maximum: 8,
+                default: 5,
+                description: "How many pages to return, 1 to 8."
+            },
+            api: API_BASE
+        },
+        required: [
+            "query"
+        ]
+    }
+};
+async function docs_search_handler(args) {
+    const query = String(args.query || "").trim();
+    if (!query) return envelope_envelope({
+        ok: false,
+        command: docs_search_COMMAND,
+        status: "bad-request",
+        error: {
+            code: "E_BAD_REQUEST",
+            message: "query is required."
+        }
+    });
+    const base = mcpOrigins(args.api).www.replace(/\/+$/, "");
+    const limit = Math.min(8, Math.max(1, Math.floor(Number(args.limit) || 5)));
+    const url = `${base}/api/docs/search?q=${encodeURIComponent(query)}&limit=${limit}`;
+    let res;
+    try {
+        res = await fetch(url, {
+            headers: {
+                accept: "application/json"
+            }
+        });
+    } catch (err) {
+        return envelope_envelope({
+            ok: false,
+            command: docs_search_COMMAND,
+            status: "network-failed",
+            error: {
+                code: "E_NETWORK",
+                message: `Could not reach ${base}: ${err instanceof Error ? err.message : String(err)}`
+            }
+        });
+    }
+    let body = {};
+    try {
+        body = await res.json();
+    } catch  {
+        body = {};
+    }
+    if (!res.ok) return envelope_envelope({
+        ok: false,
+        command: docs_search_COMMAND,
+        status: 429 === res.status ? "rate-limited" : "search-failed",
+        error: {
+            code: "E_PLATFORM",
+            message: body.message || `Docs search answered ${res.status}.`
+        },
+        ...429 === res.status ? {
+            hint: `Wait ${body.retryAfterSeconds ?? 60} seconds, or read the docs at https://extension.js.org/docs.`
+        } : {}
+    });
+    const results = Array.isArray(body.results) ? body.results : [];
+    return envelope_envelope({
+        ok: true,
+        command: docs_search_COMMAND,
+        status: results.length ? "found" : "no-match",
+        value: {
+            query,
+            results
+        },
+        ...results.length ? {} : {
+            hint: "No page matched. Try fewer or different words, or browse https://extension.js.org/docs."
+        }
+    });
+}
 function typeOf(value) {
     if (Array.isArray(value)) return "array";
     if (null === value) return "null";
@@ -18195,6 +18701,10 @@ const TOOL_POLICY = {
         group: "local",
         annotations: reads(true)
     },
+    extension_docs_search: {
+        group: "local",
+        annotations: reads(true)
+    },
     extension_add_feature: {
         group: "local",
         annotations: reads()
@@ -18535,7 +19045,8 @@ const tools = [
     project_create_namespaceObject,
     workspace_create_namespaceObject,
     browsers_namespaceObject,
-    doctor_namespaceObject
+    doctor_namespaceObject,
+    docs_search_namespaceObject
 ];
 function toolResultFrame(result, untrusted = false) {
     let refused;

package/dist/src/lib/rdp.d.ts

@@ -47,4 +47,32 @@ export declare function rdpCollectConsoleMessages(port: number, options?: {
     timeoutMs?: number;
     settleMs?: number;
 }): Promise<ConsoleMessage[]>;
+export type RdpEvalOutcome = {
+    ok: true;
+    value: unknown;
+    tab: {
+        url: string;
+        title: string;
+    };
+} | {
+    ok: false;
+    name: string;
+    message: string;
+};
+export declare function rdpStartExpression(expression: string, token: string): string;
+export declare function rdpPollExpression(token: string): string;
+type RdpSettled = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    name: string;
+    message: string;
+};
+export declare function readRdpEvalSlot(raw: unknown): RdpSettled | "pending" | "lost";
+export declare function rdpEvaluateInTab(port: number, options: {
+    select: (tabs: RdpTab[]) => RdpTab | null | undefined;
+    expression: string;
+    timeoutMs?: number;
+}): Promise<RdpEvalOutcome>;
 export {};

package/dist/src/tools/docs-search.d.ts

@@ -0,0 +1,30 @@
+export declare const schema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+                description: string;
+            };
+            api: {
+                readonly type: "string";
+                readonly description: "Platform base URL (default EXTENSION_DEV_API_URL, else https://www.extension.dev)";
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handler(args: {
+    query: string;
+    limit?: number;
+    api?: string;
+}): Promise<string>;

package/dist/src/tools/dom-snapshot.d.ts

@@ -66,6 +66,7 @@ export declare const schema: {
         required: string[];
     };
 };
+export declare function protocolSnapshotExpression(wantHtml: boolean, maxBytes: number): string;
 export declare function handler(args: ActArgs & {
     tab?: number;
     url?: string;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "10.10.6",
-  "description": "MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex) build, run, inspect, and publish browser extensions. 31 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": "10.10.8",
+  "description": "MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex) build, run, inspect, and publish browser extensions. 32 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.",
   "mcpName": "io.github.extensiondev/mcp",
   "license": "Apache-2.0",
   "author": {
@@ -92,7 +92,7 @@
     "extension.js"
   ],
   "dependencies": {
-    "@extension.dev/urls": "^0.8.1",
+    "@extension.dev/urls": "^0.8.2",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "browser-extension-manifest-fields": "^2.2.9",
     "cross-spawn": "^7.0.6",

package/server.json

@@ -1,19 +1,19 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
   "name": "io.github.extensiondev/mcp",
-  "description": "Build, run, inspect, and publish browser extensions from any MCP client. 31 tools, 11 browsers.",
+  "description": "Build, run, inspect, and publish browser extensions from any MCP client. 32 tools, 11 browsers.",
   "repository": {
     "url": "https://github.com/extensiondev/mcp",
     "source": "github"
   },
   "websiteUrl": "https://extension.dev",
-  "version": "10.10.6",
+  "version": "10.10.8",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@extension.dev/mcp",
-      "version": "10.10.6",
+      "version": "10.10.8",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"