@extension.dev/mcp 5.4.0 → 5.5.0

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.4.0",
+      "version": "5.5.0",
       "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.4.0",
+  "version": "5.5.0",
   "author": {
     "name": "Cezar Augusto",
     "email": "boss@cezaraugusto.net",

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 5.5.0
+
+The debug surfaces learn to point at things: tabs are targetable by
+URL, extensions in lists have names, and eval works on the default
+template by default.
+
+### Added
+
+- `extension_dom_inspect` targets tabs by `tabUrl` (case-insensitive
+  URL substring, title as fallback). Exactly one match inspects it and
+  the result names the resolved target; zero or multiple matches return
+  the candidate targets instead of guessing. `listTargets: true` lists
+  the browser's live CDP page targets (targetId, url, title, type) with
+  the standing warning that a CDP targetId is NOT a chrome.tabs id.
+- `extension_list_extensions` names its entries. The dev session's own
+  extension resolves to `name`, `version`, and `ownExtension: true`
+  (identified by recomputing Chrome's unpacked-extension id from the
+  ready contract's distPath) and sorts first; entries that cannot be
+  resolved carry a note saying why instead of a silent bare id. Other
+  extensions' contexts are never attached to or evaluated in.
+
+### Fixed
+
+- `extension_eval` works on the default template by default. On
+  Chromium with an MV3 manifest the default context is now `page` (the
+  MV3 service worker CSP blocks background eval), disclosed in the
+  result as `defaultedContext` with the reason; explicit
+  `context: "background"` is unchanged and keeps its CSP explanation.
+  Firefox and MV2 defaults are untouched. A defaulted eval that lands
+  on an unreachable active tab returns a hint to navigate or pass
+  `url`/`tab`.
+- Error remedies speak tool arguments, never CLI flags: the engine's
+  `--context page --tab <id>` prose is rewritten into `context:`/
+  `tab:`/`url:` vocabulary, with guards so ordinary prose is never
+  garbled by the rewriting.
+- The debugging documentation's headline example now runs on the
+  default template (page-context eval); the background variant is
+  labeled MV2/Firefox, and the cross-browser matrix states per-context
+  eval support honestly with the MV3 CSP footnote.
+
 ## 5.4.0
 
 The DevX swarm's non-blocker friction clusters, cleared: waiting is

package/dist/module.js

@@ -68,6 +68,7 @@ var eval_namespaceObject = {};
 __webpack_require__.r(eval_namespaceObject);
 __webpack_require__.d(eval_namespaceObject, {
     handler: ()=>eval_handler,
+    resolveDefaultEvalContext: ()=>resolveDefaultEvalContext,
     schema: ()=>eval_schema
 });
 var get_template_source_namespaceObject = {};
@@ -210,7 +211,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.4.0","El":{"OP":"^4.0.13"}}');
+var package_namespaceObject = JSON.parse('{"rE":"5.5.0","El":{"OP":"^4.0.13"}}');
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -3179,7 +3180,7 @@ async function source_inspect_handler(args) {
 }
 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). Identity is read read-only via the Extensions domain, other extensions' contexts are never attached to or evaluated in. 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.",
+    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.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3197,6 +3198,47 @@ const list_extensions_schema = {
         ]
     }
 };
+function unpackedExtensionId(distPath) {
+    const digest = node_crypto.createHash("sha256").update(distPath).digest();
+    let id = "";
+    for(let i = 0; i < 16; i++){
+        id += String.fromCharCode(97 + (digest[i] >> 4));
+        id += String.fromCharCode(97 + (0x0f & digest[i]));
+    }
+    return id;
+}
+function readOwnIdentity(projectPath, browser) {
+    let contract;
+    try {
+        const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+        contract = JSON.parse(node_fs.readFileSync(file, "utf8"));
+    } catch  {
+        return null;
+    }
+    const distPath = "string" == typeof contract?.distPath ? contract.distPath : null;
+    const ids = [];
+    if (distPath) {
+        ids.push(unpackedExtensionId(distPath));
+        try {
+            const real = node_fs.realpathSync(distPath);
+            if (real !== distPath) ids.push(unpackedExtensionId(real));
+        } catch  {}
+    }
+    let name = "string" == typeof contract?.extensionName ? contract.extensionName : void 0;
+    let version = "string" == typeof contract?.extensionVersion ? contract.extensionVersion : void 0;
+    if ((!name || !version) && distPath) try {
+        const manifest = JSON.parse(node_fs.readFileSync(node_path.join(distPath, "manifest.json"), "utf8"));
+        if (!name && "string" == typeof manifest?.name && !manifest.name.startsWith("__MSG_")) name = manifest.name;
+        if (!version && "string" == typeof manifest?.version) version = manifest.version;
+    } catch  {}
+    if (0 === ids.length && !name) return null;
+    return {
+        ids,
+        name,
+        version
+    };
+}
+const UNRESOLVED_NOTE = "Identity unresolved: the browser's Extensions CDP domain returned nothing for this id, and other extensions' contexts are never attached to or evaluated in to read a manifest.";
 async function list_extensions_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     if (!isChromiumFamily(browser)) return JSON.stringify({
@@ -3237,6 +3279,7 @@ async function list_extensions_handler(args) {
             });
             byId.set(id, list);
         }
+        const own = readOwnIdentity(args.projectPath, browser);
         const extensions = [];
         for (const [id, ctxTargets] of byId){
             const entry = {
@@ -3257,15 +3300,33 @@ async function list_extensions_handler(args) {
                     entry.source = "extensions-domain";
                 }
             } catch  {}
+            if (own?.ids.includes(id)) {
+                entry.ownExtension = true;
+                if (void 0 === entry.name && void 0 !== own.name) {
+                    entry.name = own.name;
+                    if (void 0 !== own.version) entry.version = own.version;
+                    entry.source = "session-contract";
+                }
+            }
             extensions.push(entry);
         }
-        extensions.sort((a, b)=>(a.name ?? a.id).localeCompare(b.name ?? b.id));
+        if (own?.name && !extensions.some((e)=>e.ownExtension)) {
+            const byName = extensions.filter((e)=>e.name === own.name);
+            if (1 === byName.length) byName[0].ownExtension = true;
+        }
+        for (const entry of extensions)if (void 0 === entry.name) entry.note = UNRESOLVED_NOTE;
+        extensions.sort((a, b)=>{
+            if ((a.ownExtension ?? false) !== (b.ownExtension ?? false)) return a.ownExtension ? -1 : 1;
+            return (a.name ?? a.id).localeCompare(b.name ?? b.id);
+        });
+        const ownEntry = extensions.find((e)=>e.ownExtension);
         return JSON.stringify({
             cdpPort,
             browser,
             count: extensions.length,
+            ownExtensionId: ownEntry?.id ?? null,
             extensions,
-            note: "Lists extensions that currently have at least one live context (service worker or open page). An MV3 service worker that has gone dormant with no open page may be absent until it wakes. Identity is read read-only via the Extensions domain; other extensions' contexts are never attached to or evaluated in."
+            note: "Lists extensions that currently have at least one live context (service worker or open page). An MV3 service worker that has gone dormant with no open page may be absent until it wakes. ownExtension marks the extension this dev session serves, identified from the session's ready contract. Other identity is read read-only via the Extensions domain; other extensions' contexts are never attached to or evaluated in."
         });
     } catch (error) {
         return JSON.stringify({
@@ -3597,7 +3658,7 @@ async function logs_handler(args) {
     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(/--context[= ]([\w-]+)/g, 'context: "$1"').replace(/--tab[= ](\d+)/g, "tab: $1").replace(/--url[= ](\S+)/g, 'url: "$1"').replace(/--browser[= ]([\w-]+)/g, 'browser: "$1"').replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev");
+    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);
@@ -3650,7 +3711,7 @@ function commonFlags(args) {
 }
 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). 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). Chromium caveat: eval in the MV3 background/service_worker is blocked by CSP (use an MV2/Firefox build for that context). Use extension_dom_inspect with listTabs: true to enumerate {tabId,url,title}. Wraps `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`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3676,8 +3737,7 @@ const eval_schema = {
                     "content",
                     "page"
                 ],
-                default: "background",
-                description: "Which extension surface to evaluate in"
+                description: "Which extension surface to evaluate in. Default: `background`, EXCEPT on Chromium sessions whose manifest is MV3, where the default is `page` (the active tab) because the MV3 service worker CSP blocks eval; pass `context: \"background\"` explicitly to target the worker anyway."
             },
             url: {
                 type: "string",
@@ -3702,14 +3762,38 @@ const eval_schema = {
         ]
     }
 };
+function resolveDefaultEvalContext(projectPath, browser) {
+    if (!isChromiumFamily(browser)) return "background";
+    const candidates = [
+        node_path.join(projectPath, "dist", browser, "manifest.json"),
+        node_path.join(projectPath, "dist", "manifest.json"),
+        node_path.join(projectPath, "src", "manifest.json"),
+        node_path.join(projectPath, "manifest.json")
+    ];
+    for (const file of candidates){
+        let manifest;
+        try {
+            manifest = JSON.parse(node_fs.readFileSync(file, "utf8"));
+        } catch  {
+            continue;
+        }
+        const version = manifest["chromium:manifest_version"] ?? manifest.manifest_version;
+        if (3 === version) return "page";
+        if (2 === version) break;
+    }
+    return "background";
+}
 async function eval_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    const defaulted = !args.context && "page" === resolveDefaultEvalContext(args.projectPath, browser);
+    const context = defaulted ? "page" : args.context;
     const raw = await runActVerb([
         "eval",
         args.expression,
         args.projectPath,
         ...commonFlags({
             ...args,
+            context,
             browser
         })
     ], args.projectPath, args.timeout);
@@ -3720,6 +3804,15 @@ async function eval_handler(args) {
             return JSON.stringify(parsed);
         }
     } catch  {}
+    if (defaulted) try {
+        const parsed = JSON.parse(raw);
+        if (parsed && "object" == typeof parsed) {
+            parsed.defaultedContext = "page";
+            parsed.contextNote = 'No context given: defaulted to "page" (the active tab) because this Chromium session\'s MV3 background is a service worker whose CSP blocks eval. Pass context: "background" explicitly to target the worker (works on Firefox/MV2 builds).';
+            if (false === parsed.ok && /cannot access|chrome-extension:\/\/|chrome:\/\//i.test(JSON.stringify(parsed.error ?? ""))) parsed.hint = "The active tab is a browser or extension page that eval cannot reach. Navigate the dev browser to a regular web page, or pass url (match pattern) or tab to pick one; extension_dom_inspect with listTabs: true lists open tabs.";
+            return JSON.stringify(parsed);
+        }
+    } catch  {}
     return raw;
 }
 const storage_schema = {
@@ -3948,7 +4041,7 @@ async function navigateToUrl(projectPath, browser, url) {
         } catch  {}
     }
 }
-function unpackedExtensionId(distPath) {
+function open_unpackedExtensionId(distPath) {
     const digest = node_crypto.createHash("sha256").update(distPath).digest();
     let id = "";
     for(let i = 0; i < 16; i++){
@@ -3959,7 +4052,7 @@ function unpackedExtensionId(distPath) {
 }
 async function resolveExtensionId(projectPath, browser) {
     const distPath = readDistPath(projectPath, browser);
-    const computed = distPath ? unpackedExtensionId(distPath) : null;
+    const computed = distPath ? open_unpackedExtensionId(distPath) : null;
     const resolved = await resolveCdpPort(projectPath, browser);
     if (!resolved) return computed;
     const ids = new Set();
@@ -4283,9 +4376,27 @@ async function open_handler(args) {
     } catch  {}
     return raw;
 }
+const TARGET_ID_NOTE = "targetId is a CDP target id, NOT a chrome.tabs id: do not pass it as `tab`. Target a tab with `tabUrl` (URL substring) or `url`; if you need a numeric tab id, call extension_dom_inspect with listTabs: true.";
+function filterPageTargets(raw) {
+    return raw.filter((t)=>"page" === t.type && !String(t.url ?? "").startsWith("devtools://")).map((t)=>({
+            targetId: String(t.id),
+            type: String(t.type),
+            url: String(t.url ?? ""),
+            title: String(t.title ?? "")
+        }));
+}
+async function listPageTargets(port) {
+    return filterPageTargets(await CDPClient.discoverTargets(port));
+}
+function matchTargetsByUrl(targets, needle) {
+    const wanted = needle.toLowerCase();
+    const byUrl = targets.filter((t)=>t.url.toLowerCase().includes(wanted));
+    if (byUrl.length > 0) return byUrl;
+    return targets.filter((t)=>t.title.toLowerCase().includes(wanted));
+}
 const dom_inspect_schema = {
     name: "extension_dom_inspect",
-    description: "Inspect a page/content-script DOM via the agent bridge (CDP-free, localhost). Returns a structured snapshot (counts, extension roots, open shadow roots, optional capped HTML). Requires the dev session to be started with allowControl: true (extension_dev). For closed shadow roots or deep CDP inspection use extension_source_inspect. Wraps `extension inspect`.",
+    description: "Inspect a page/content-script DOM via the agent bridge (CDP-free, localhost). Returns a structured snapshot (counts, extension roots, open shadow roots, optional capped HTML). Target a tab by `tabUrl` (case-insensitive URL substring resolved against the browser's live page targets; zero or several matches return the candidates instead of guessing), by `url`, or by numeric `tab`. Discover what is open with listTargets: true (CDP targetIds) or listTabs: true (numeric chrome.tabs ids). Requires the dev session to be started with allowControl: true (extension_dev). For closed shadow roots or deep CDP inspection use extension_source_inspect. Wraps `extension inspect`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -4301,6 +4412,15 @@ const dom_inspect_schema = {
                 type: "string",
                 description: "For content/page: selects the target tab by url (match pattern, then substring fallback). Preferred over `tab`."
             },
+            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`."
+            },
+            listTargets: {
+                type: "boolean",
+                default: false,
+                description: "Enumerate the browser's CDP page targets as {targetId,url,title,type} and return, ignoring the other args. The discovery path for `tabUrl`. targetId is a CDP target id, NOT a numeric chrome.tabs id (for those use listTabs)."
+            },
             listTabs: {
                 type: "boolean",
                 default: false,
@@ -4361,8 +4481,55 @@ const dom_inspect_schema = {
         ]
     }
 };
+async function cdpPortOrError(projectPath, browser, feature) {
+    if (!isChromiumFamily(browser)) return {
+        error: JSON.stringify({
+            ok: false,
+            error: {
+                name: "Unsupported",
+                message: `${feature} reads the browser's CDP page targets, which ${browser} (Gecko) does not expose. Target the tab with \`url\` or \`tab\` instead, and discover tabs with listTabs: true (agent bridge, works on every browser).`
+            }
+        })
+    };
+    const resolved = await resolveCdpPort(projectPath, browser);
+    if (!resolved) return {
+        error: JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoSession",
+                message: `No active dev session / CDP port for ${browser}, so ${feature} has no browser to ask. Start extension_dev and extension_wait for ready. ${CDP_PORT_MISSING_HINT}`
+            }
+        })
+    };
+    return {
+        port: resolved.port
+    };
+}
 async function dom_inspect_handler(args) {
     const withConsole = true === args.withConsole ? 50 : false === args.withConsole ? void 0 : args.withConsole;
+    if (args.listTargets) {
+        const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+        const cdp = await cdpPortOrError(args.projectPath, browser, "listTargets");
+        if ("error" in cdp) return cdp.error;
+        try {
+            const targets = await listPageTargets(cdp.port);
+            return JSON.stringify({
+                ok: true,
+                browser,
+                targets,
+                note: TARGET_ID_NOTE
+            });
+        } catch (e) {
+            return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "CdpError",
+                    message: `Could not list page targets: ${e instanceof Error ? e.message : String(e)}`
+                },
+                hint: "Confirm the session is ready (extension_wait), then retry. listTabs: true is the CDP-free alternative."
+            });
+        }
+    }
     if (args.listTabs) return runActVerb([
         "inspect",
         args.projectPath,
@@ -4374,19 +4541,78 @@ async function dom_inspect_handler(args) {
             String(args.timeout)
         ] : []
     ], args.projectPath, args.timeout);
+    let targetUrl = args.url;
+    let resolvedTarget = null;
+    if (args.tabUrl) {
+        if (null != args.tab || args.url) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "BadRequest",
+                message: "Pass ONE tab selector: `tabUrl` (URL substring, resolved against live targets), `url` (engine-side match), or `tab` (numeric chrome.tabs id), not several."
+            }
+        });
+        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({
+                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: "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 (args.url) cli.push("--url", args.url);
+    if (targetUrl) cli.push("--url", targetUrl);
     if (args.context) cli.push("--context", args.context);
     if (args.include?.length) cli.push("--include", args.include.join(","));
     if (null != args.maxBytes) cli.push("--max-bytes", String(args.maxBytes));
     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));
-    return runActVerb(cli, args.projectPath, args.timeout);
+    const raw = await runActVerb(cli, args.projectPath, args.timeout);
+    if (!resolvedTarget) return raw;
+    try {
+        const parsed = JSON.parse(raw);
+        parsed.resolvedTarget = {
+            ...resolvedTarget,
+            matchedBy: "tabUrl"
+        };
+        return JSON.stringify(parsed);
+    } catch  {
+        return raw;
+    }
 }
 function credentialsPath() {
     if ("win32" === process.platform) {

package/dist/src/lib/cdp-targets.d.ts

@@ -0,0 +1,15 @@
+export interface PageTarget {
+    targetId: string;
+    type: string;
+    url: string;
+    title: string;
+}
+export declare const TARGET_ID_NOTE: string;
+export declare function filterPageTargets(raw: Array<{
+    id: string;
+    type: string;
+    url: string;
+    title: string;
+}>): PageTarget[];
+export declare function listPageTargets(port: number): Promise<PageTarget[]>;
+export declare function matchTargetsByUrl(targets: PageTarget[], needle: string): PageTarget[];

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

@@ -17,6 +17,15 @@ export declare const schema: {
                 type: string;
                 description: string;
             };
+            tabUrl: {
+                type: string;
+                description: string;
+            };
+            listTargets: {
+                type: string;
+                default: boolean;
+                description: string;
+            };
             listTabs: {
                 type: string;
                 default: boolean;
@@ -60,6 +69,8 @@ export declare const schema: {
 export declare function handler(args: ActArgs & {
     tab?: number;
     url?: string;
+    tabUrl?: string;
+    listTargets?: boolean;
     listTabs?: boolean;
     include?: string[];
     maxBytes?: number;

package/dist/src/tools/eval.d.ts

@@ -16,7 +16,6 @@ export declare const schema: {
             context: {
                 type: string;
                 enum: string[];
-                default: string;
                 description: string;
             };
             url: {
@@ -39,6 +38,7 @@ export declare const schema: {
         required: string[];
     };
 };
+export declare function resolveDefaultEvalContext(projectPath: string, browser: string): "background" | "page";
 export declare function handler(args: ActArgs & {
     expression: string;
 }): Promise<string>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "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": "MIT",

package/server.json

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