@extension.dev/mcp 4.8.0 → 4.9.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": "4.8.0",
+      "version": "4.9.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": "4.8.0",
+  "version": "4.9.0",
   "author": {
     "name": "Cezar Augusto",
     "email": "boss@cezaraugusto.net",

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 4.9.0
+
+A second pass from the persona swarm, closing the gaps 4.8.0 left and the top
+new blockers it surfaced.
+
+- **Honest `extension_manifest_validate`.** It now scans the project source for
+  permission-gated `chrome.*`/`browser.*` calls and flags any the manifest does
+  not declare — an API used without its permission is `undefined` at runtime and
+  crashes the context, the exact case where validate used to report `valid:true`.
+  The headline is now honest (`valid:false` + `buildBlocking:true` on any error),
+  and it accepts singular `browser` as an alias for `browsers`.
+- **`extension_open` can navigate a tab.** Pass a `url` (Chromium, via CDP) to
+  drive a content-script test page, a `webNavigation` target, or the popup as a
+  page (`chrome-extension://<id>/popup.html`) — the loop the surface-only open
+  could not do. `target` is accepted as an alias for `surface`.
+- **`extension_stop` actually reaps the session.** It now terminates the dev CLI
+  and both browser families (gecko profile + chromium `--load-extension`, under
+  the project's dist) and refuses to report `stopped:true` while any survive.
+- **`extension_wait` won't lie about a dead session.** A `ready.json` whose pid
+  is dead now returns `status:"stale"` instead of `ready`, so you don't walk into
+  a reload/eval that fails with a misleading control-channel error.
+- **Dropped-channel errors name the real cause.** A `1006` / "no control channel"
+  now detects an exited dev server (stale ready.json + dead pid) and says so,
+  instead of asking "is the session started with allowControl?" when it was.
+- **`extension_doctor`** surfaces recent error-level logs as a `runtime-errors`
+  check (so a background throwing on every event isn't `healthy:true`), keeps the
+  project-local engine version in project mode, and flags when that engine
+  differs from a pinned `EXTENSION_MCP_CLI_VERSION`.
+- **`extension_build`** lists declared entrypoints in its success output, so a
+  content script no longer reads as "didn't build".
+- **`extension_create`** forces non-interactive git (`GIT_TERMINAL_PROMPT=0`) so a
+  credential prompt can't hang the template download, retries once on a transient
+  network/timeout failure (cleaning the partial dir first), reports a download
+  failure as such instead of "choose a valid template name", and warns when the
+  scaffold's `extension@latest` pin will win over your pinned CLI.
+- Eval/inspect error guidance now speaks MCP JSON args (`context`, `tab`, `url`)
+  instead of CLI flags.
+
 ## 4.8.0
 
 Dev-session ergonomics hardened from a 30-persona agent walk of the toolchain.

package/dist/module.js

@@ -199,7 +199,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"4.7.0","El":{"OP":"^4.0.11"}}');
+var package_namespaceObject = JSON.parse('{"rE":"4.8.0","El":{"OP":"^4.0.11"}}');
 function detectPackageManager(projectPath) {
     const byLockfile = [
         [
@@ -259,14 +259,27 @@ const create_schema = {
 async function create_handler(args) {
     const start = Date.now();
     const projectInput = args.parentDir ? node_path.resolve(args.parentDir, args.projectName) : args.projectName;
+    process.env.GIT_TERMINAL_PROMPT = "0";
+    if (void 0 === process.env.GIT_ASKPASS) process.env.GIT_ASKPASS = "";
     const logLines = [];
     const capture = (stream)=>(...parts)=>{
             const line = parts.map((p)=>"string" == typeof p ? p : String(p)).join(" ").trim();
             if (line) logLines.push("error" === stream ? `[error] ${line}` : line);
         };
     const logTail = (max = 20)=>logLines.slice(-max);
-    try {
-        const result = await extensionCreate(projectInput, {
+    const looksTransient = ()=>{
+        const blob = logLines.join("\n").toLowerCase();
+        return /timed out|timeout|etimedout|econnreset|rate limit|\b429\b|network|could not resolve host|terminal prompts disabled|authentication failed|early eof|rpc failed|remote end hung up/.test(blob);
+    };
+    const cleanPartial = ()=>{
+        try {
+            if (args.parentDir && node_fs.existsSync(projectInput)) node_fs.rmSync(projectInput, {
+                recursive: true,
+                force: true
+            });
+        } catch  {}
+    };
+    const attempt = ()=>extensionCreate(projectInput, {
             template: args.template ?? "typescript",
             install: args.install ?? true,
             logger: {
@@ -274,34 +287,53 @@ async function create_handler(args) {
                 error: capture("error")
             }
         });
-        const packageManager = result.depsInstalled ? detectPackageManager(result.projectPath) : "npm";
-        const runDev = `${packageManager} run dev`;
-        return JSON.stringify({
-            projectPath: result.projectPath,
-            projectName: result.projectName,
-            template: result.template,
-            depsInstalled: result.depsInstalled,
-            packageManager: result.depsInstalled ? packageManager : null,
-            duration: Date.now() - start,
-            nextSteps: result.depsInstalled ? [
-                `cd ${result.projectPath}`,
-                runDev
-            ] : [
-                `cd ${result.projectPath}`,
-                "npm install",
-                "npm run dev"
-            ],
-            ...result.depsInstalled ? {} : {
-                warnings: logTail()
-            }
-        });
-    } catch (err) {
-        return JSON.stringify({
-            error: err instanceof Error ? err.message : String(err),
+    const failure = (err, transient)=>JSON.stringify({
+            error: transient ? "Template download failed (network/timeout/rate-limit) — this is not a bad template name. Retry, or check connectivity/GitHub rate limits." : err instanceof Error ? err.message : String(err),
+            ...transient ? {
+                cause: err instanceof Error ? err.message : String(err)
+            } : {},
             duration: Date.now() - start,
             log: logTail()
         });
+    let result;
+    try {
+        result = await attempt();
+    } catch (err1) {
+        if (!looksTransient()) return failure(err1, false);
+        logLines.push("[retry] transient template-download failure; retrying once");
+        cleanPartial();
+        try {
+            result = await attempt();
+        } catch (err2) {
+            return failure(err2, looksTransient());
+        }
     }
+    const packageManager = result.depsInstalled ? detectPackageManager(result.projectPath) : "npm";
+    const runDev = `${packageManager} run dev`;
+    const pin = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
+    const engineWarning = pin && "latest" !== pin ? `The scaffold pins "extension": "latest"; the project-local engine wins over EXTENSION_MCP_CLI_VERSION=${pin}. Run \`(cd ${result.projectPath} && npm i -D extension@${pin})\` to match the pinned engine.` : void 0;
+    return JSON.stringify({
+        projectPath: result.projectPath,
+        projectName: result.projectName,
+        template: result.template,
+        depsInstalled: result.depsInstalled,
+        packageManager: result.depsInstalled ? packageManager : null,
+        duration: Date.now() - start,
+        nextSteps: result.depsInstalled ? [
+            `cd ${result.projectPath}`,
+            runDev
+        ] : [
+            `cd ${result.projectPath}`,
+            "npm install",
+            "npm run dev"
+        ],
+        ...engineWarning ? {
+            engineWarning
+        } : {},
+        ...result.depsInstalled ? {} : {
+            warnings: logTail()
+        }
+    });
 }
 const CACHE_DIR = node_path.join(node_os.homedir(), ".cache", "extension-js");
 const CACHE_FILE = node_path.join(CACHE_DIR, "templates-meta.json");
@@ -535,6 +567,34 @@ function spawnExtensionCli(args, options) {
     child.unref();
     return child;
 }
+function builtEntrypoints(distDir) {
+    let manifest;
+    try {
+        manifest = JSON.parse(node_fs.readFileSync(node_path.join(distDir, "manifest.json"), "utf8"));
+    } catch  {
+        return [];
+    }
+    const out = [];
+    const add = (role, ref)=>{
+        if ("string" != typeof ref) return;
+        out.push({
+            role,
+            path: ref,
+            present: node_fs.existsSync(node_path.join(distDir, ref.replace(/^\.?\//, "")))
+        });
+    };
+    const bg = manifest.background;
+    if (bg?.service_worker) add("background.service_worker", bg.service_worker);
+    if (Array.isArray(bg?.scripts)) bg.scripts.forEach((s)=>add("background.scripts", s));
+    const action = manifest.action || manifest.browser_action;
+    if (action?.default_popup) add("action.default_popup", action.default_popup);
+    const cs = manifest.content_scripts;
+    if (Array.isArray(cs)) cs.forEach((c, i)=>{
+        if (Array.isArray(c.js)) c.js.forEach((j)=>add(`content_scripts[${i}].js`, j));
+        if (Array.isArray(c.css)) c.css.forEach((s)=>add(`content_scripts[${i}].css`, s));
+    });
+    return out;
+}
 const build_schema = {
     name: "extension_build",
     description: "Build a browser extension for production. Outputs to dist/<browser>/. Optionally creates .zip for store submission.",
@@ -632,6 +692,7 @@ async function build_handler(args) {
     if (0 === code) {
         const size = out.match(/Size:\s*([\d.]+\s*[kKmMgG]?B)/)?.[1];
         const status = out.match(/Build Status:\s*(\w+)/)?.[1];
+        const entrypoints = builtEntrypoints(node_path.resolve(args.projectPath, "dist", browser));
         return JSON.stringify({
             success: true,
             browser,
@@ -641,6 +702,9 @@ async function build_handler(args) {
             ...status ? {
                 status
             } : {},
+            ...entrypoints.length ? {
+                entrypoints
+            } : {},
             zip: args.zip ?? false,
             duration,
             output: lastLines(out, 12)
@@ -1050,6 +1114,13 @@ function knownSessionBrowsers(projectPath) {
     for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
     return Array.from(new Set(browsers));
 }
+function deadReadySession(projectPath) {
+    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && !pidAlive(sighting.pid)) return {
+        browser: sighting.browser,
+        pid: sighting.pid
+    };
+    return null;
+}
 function resolveSessionBrowser(projectPath, explicit, fallback = "chromium") {
     if (explicit) return {
         browser: explicit,
@@ -1094,12 +1165,11 @@ const stop_schema = {
         required: []
     }
 };
-function profileProcessPids(projectPath, browser) {
-    const marker = node_path.resolve(projectPath, "dist", `extension-profile-${browser}`);
+function pgrepPids(pattern) {
     try {
         const out = execFileSync("pgrep", [
             "-f",
-            marker
+            pattern
         ], {
             encoding: "utf8"
         });
@@ -1108,8 +1178,19 @@ function profileProcessPids(projectPath, browser) {
         return [];
     }
 }
-function reapProfileProcesses(projectPath, browser) {
-    const pids = profileProcessPids(projectPath, browser);
+function sessionProcessPids(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const pids = new Set();
+    for (const marker of [
+        `extension dev ${resolved}`,
+        node_path.join(resolved, "dist")
+    ])for (const pid of pgrepPids(marker))pids.add(pid);
+    return [
+        ...pids
+    ];
+}
+function reapSessionProcesses(projectPath) {
+    const pids = sessionProcessPids(projectPath);
     for (const pid of pids)try {
         process.kill(pid, "SIGKILL");
     } catch  {}
@@ -1152,7 +1233,7 @@ async function stopOne(projectPath, browser) {
     const session = getSession(projectPath, browser);
     const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
     if (null == pid) {
-        const reaped = reapProfileProcesses(projectPath, browser);
+        const reaped = reapSessionProcesses(projectPath);
         return {
             projectPath,
             browser,
@@ -1172,14 +1253,14 @@ async function stopOne(projectPath, browser) {
         }
         detail = isAlive(pid) ? "Sent SIGTERM and SIGKILL but the process still reports alive; it may be exiting." : "Terminated.";
     } else detail = "Process was already gone; cleaned up session records.";
-    const reaped = reapProfileProcesses(projectPath, browser);
+    const reaped = reapSessionProcesses(projectPath);
     removeSession(projectPath, browser);
     try {
         node_fs.rmSync(readyJsonPath(projectPath, browser), {
             force: true
         });
     } catch  {}
-    const survivors = profileProcessPids(projectPath, browser);
+    const survivors = sessionProcessPids(projectPath);
     const stopped = !isAlive(pid) && 0 === survivors.length;
     if (survivors.length) detail += ` Warning: ${survivors.length} browser process(es) still alive after reap (pids ${survivors.join(", ")}).`;
     else if (reaped.length) detail += ` Reaped ${reaped.length} browser process(es).`;
@@ -1413,6 +1494,10 @@ const manifest_validate_schema = {
                     "firefox"
                 ],
                 description: "Browsers to validate against"
+            },
+            browser: {
+                type: "string",
+                description: "Single browser to validate against; alias for browsers:[browser] to match the other tools."
             }
         },
         required: []
@@ -1473,7 +1558,90 @@ function findManifest(projectPath) {
     }
     return null;
 }
+const API_PERMISSION = {
+    storage: "storage",
+    webNavigation: "webNavigation",
+    history: "history",
+    cookies: "cookies",
+    bookmarks: "bookmarks",
+    alarms: "alarms",
+    contextMenus: "contextMenus",
+    notifications: "notifications",
+    downloads: "downloads",
+    webRequest: "webRequest",
+    tabGroups: "tabGroups",
+    topSites: "topSites",
+    idle: "idle",
+    management: "management",
+    scripting: "scripting",
+    declarativeNetRequest: "declarativeNetRequest",
+    sessions: "sessions",
+    proxy: "proxy",
+    tts: "tts",
+    pageCapture: "pageCapture",
+    desktopCapture: "desktopCapture",
+    debugger: "debugger",
+    geolocation: "geolocation"
+};
+const HARD_APIS = new Set([
+    "history",
+    "cookies",
+    "bookmarks",
+    "webNavigation",
+    "downloads",
+    "webRequest",
+    "topSites",
+    "management",
+    "tabGroups",
+    "sessions",
+    "proxy",
+    "debugger",
+    "pageCapture",
+    "desktopCapture"
+]);
+function scanApiUsage(roots) {
+    const used = new Set();
+    let filesRead = 0;
+    const walk = (dir, depth)=>{
+        if (depth > 6 || filesRead > 300) return;
+        let entries;
+        try {
+            entries = node_fs.readdirSync(dir, {
+                withFileTypes: true
+            });
+        } catch  {
+            return;
+        }
+        for (const e of entries){
+            if ("node_modules" === e.name || "dist" === e.name || e.name.startsWith(".")) continue;
+            const full = node_path.join(dir, e.name);
+            if (e.isDirectory()) {
+                walk(full, depth + 1);
+                continue;
+            }
+            if (!/\.(js|mjs|cjs|ts|tsx|jsx|svelte|vue)$/.test(e.name)) continue;
+            if (filesRead++ > 300) return;
+            let src;
+            try {
+                src = node_fs.readFileSync(full, "utf8");
+            } catch  {
+                continue;
+            }
+            const re = /\b(?:chrome|browser)\.(\w+)/g;
+            let m;
+            while(m = re.exec(src))if (API_PERMISSION[m[1]]) used.add(m[1]);
+        }
+    };
+    for (const root of new Set(roots))walk(root, 0);
+    return used;
+}
 async function manifest_validate_handler(args) {
+    if (!args.browsers && "string" == typeof args.browser) args = {
+        ...args,
+        browsers: [
+            args.browser
+        ]
+    };
     const browsers = args.browsers ?? [
         "chrome",
         "firefox"
@@ -1522,6 +1690,17 @@ async function manifest_validate_handler(args) {
         ] : []
     ];
     for (const ref of new Set(collectPathRefs(chromiumManifest)))if (!fileResolvesSomewhere(ref, roots)) result.warnings.push(`Referenced file "${ref}" was not found near the manifest — this is the kind of dangling reference extension_build fails on. Verify with extension_build.`);
+    const declaredPermSet = new Set([
+        ...chromiumManifest.permissions ?? [],
+        ...chromiumManifest.optional_permissions ?? []
+    ].filter((p)=>"string" == typeof p));
+    for (const api of scanApiUsage(roots)){
+        const perm = API_PERMISSION[api];
+        if (declaredPermSet.has(perm)) continue;
+        const base = `Code calls chrome.${api} but "${perm}" is not in permissions`;
+        if (HARD_APIS.has(api)) result.errors.push(`${base} — chrome.${api} is undefined without it and will crash the context at runtime.`);
+        else result.warnings.push(`${base}; it may be undefined at runtime — add "${perm}" if you use it.`);
+    }
     if (!chromiumManifest.manifest_version) result.errors.push('Missing manifest_version. Use "chromium:manifest_version": 3 and "firefox:manifest_version": 2 for cross-browser support.');
     const declaredPerms = [
         ...chromiumManifest.permissions ?? [],
@@ -1580,8 +1759,11 @@ async function manifest_validate_handler(args) {
                 surfaces: t.surfaces
             }));
     } catch  {}
-    if (0 === result.errors.length) result.valid = Object.values(result.browserSupport).every((b)=>b.supported);
-    return JSON.stringify(result);
+    result.valid = 0 === result.errors.length && Object.values(result.browserSupport).every((b)=>b.supported);
+    return JSON.stringify({
+        ...result,
+        buildBlocking: result.errors.length > 0
+    });
 }
 const inspect_schema = {
     name: "extension_inspect",
@@ -2787,10 +2969,13 @@ 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(/--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(/--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");
 }
 function withSessionContext(message, projectPath) {
-    if (!/no active control channel/i.test(message)) return message;
+    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.`;
@@ -3031,6 +3216,64 @@ async function reload_handler(args) {
         })
     ], args.projectPath, args.timeout);
 }
+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.`
+        }
+    });
+    const resolved = await resolveCdpPort(projectPath, browser);
+    if (!resolved) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NoSession",
+            message: `No active dev session / CDP port for ${browser}. Start extension_dev and extension_wait for ready. ${CDP_PORT_MISSING_HINT}`
+        }
+    });
+    const cdp = new CDPClient();
+    try {
+        const targets = await CDPClient.discoverTargets(resolved.port);
+        const pageTargets = targets.filter((t)=>"page" === t.type && !String(t.url || "").startsWith("devtools://"));
+        if (0 === pageTargets.length) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoTab",
+                message: "The dev browser has no open page tab to navigate. Trigger one (e.g. extension_open surface, or open the extension) first."
+            }
+        });
+        const target = pageTargets[0];
+        const browserWsUrl = await CDPClient.discoverBrowserWsUrl(resolved.port);
+        await cdp.connect(browserWsUrl);
+        const sessionId = await cdp.attachToTarget(String(target.id));
+        await cdp.navigate(sessionId, url);
+        await new Promise((r)=>setTimeout(r, 1200));
+        const meta = await cdp.getPageMeta(sessionId).catch(()=>({}));
+        return JSON.stringify({
+            ok: true,
+            navigated: url,
+            tab: {
+                id: target.id,
+                title: meta.title,
+                url: meta.url || url
+            },
+            hint: "Inspect it with extension_dom_inspect or extension_source_inspect (context: 'page')."
+        });
+    } catch (e) {
+        return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NavigateError",
+                message: e instanceof Error ? e.message : String(e)
+            }
+        });
+    } finally{
+        try {
+            cdp.disconnect();
+        } catch  {}
+    }
+}
 const open_schema = {
     name: "extension_open",
     description: "Open an extension surface or replay an event in a running session. 'popup'/'options'/'sidebar' open UI surfaces. 'action' triggers the toolbar action: opens the action's popup, or (no popup) replays chrome.action.onClicked. 'command' replays a chrome.commands.onCommand keyboard shortcut (pass `name`). NOTE: action/command replay invokes your listener WITHOUT a user gesture, so the gesture-derived activeTab grant does not apply (the result includes gesture:false and a warning when activeTab is declared). Requires the dev session to be started with allowControl: true (extension_dev). Wraps `extension open`.",
@@ -3056,6 +3299,10 @@ const open_schema = {
                 type: "string",
                 description: "For surface 'command': the chrome.commands name to trigger."
             },
+            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`."
+            },
             browser: {
                 type: "string",
                 description: "Browser session to target. Defaults to the active dev session's browser for this project."
@@ -3066,13 +3313,20 @@ const open_schema = {
             }
         },
         required: [
-            "projectPath",
-            "surface"
+            "projectPath"
         ]
     }
 };
 async function open_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    if (args.url) return navigateToUrl(args.projectPath, browser, args.url);
+    if (!args.surface) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "BadRequest",
+            message: "Pass `surface` (popup/options/sidebar/action/command) to open a surface, or `url` to navigate a tab."
+        }
+    });
     const cli = [
         "open",
         args.surface,
@@ -3679,6 +3933,14 @@ async function deploy_handler(args) {
     });
 }
 const SAFE_CEILING_MS = 50000;
+function wait_isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
 const wait_schema = {
     name: "extension_wait",
     description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status. A single call is bounded to ~50s to stay under the MCP client request timeout; if it returns status:'timeout', call it again to keep waiting (polling resumes on the same contract).",
@@ -3716,18 +3978,27 @@ async function wait_handler(args) {
         try {
             const raw = node_fs.readFileSync(readyPath, "utf8");
             const contract = JSON.parse(raw);
-            if ("ready" === contract.status) return JSON.stringify({
-                status: "ready",
-                command: contract.command,
-                browser: contract.browser,
-                port: contract.port,
-                pid: contract.pid,
-                distPath: contract.distPath,
-                manifestPath: contract.manifestPath,
-                compiledAt: contract.compiledAt,
-                startedAt: contract.startedAt,
-                waitDuration: Date.now() - start
-            });
+            if ("ready" === contract.status) {
+                if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return JSON.stringify({
+                    status: "stale",
+                    message: `ready.json reports ready but its dev-server pid ${contract.pid} is dead — the session exited. Restart with extension_dev; extension_doctor will confirm.`,
+                    browser: contract.browser,
+                    pid: contract.pid,
+                    waitDuration: Date.now() - start
+                });
+                return JSON.stringify({
+                    status: "ready",
+                    command: contract.command,
+                    browser: contract.browser,
+                    port: contract.port,
+                    pid: contract.pid,
+                    distPath: contract.distPath,
+                    manifestPath: contract.manifestPath,
+                    compiledAt: contract.compiledAt,
+                    startedAt: contract.startedAt,
+                    waitDuration: Date.now() - start
+                });
+            }
             if ("error" === contract.status) return JSON.stringify({
                 status: "error",
                 message: contract.message,
@@ -4925,6 +5196,37 @@ async function environmentPreflight() {
         hint: "Pass projectPath to diagnose a live dev session end-to-end."
     });
 }
+function recentErrorLogs(projectPath, browser, max = 5) {
+    const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "logs.ndjson");
+    let lines;
+    try {
+        lines = node_fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    } catch  {
+        return [];
+    }
+    const errs = [];
+    for (const line of lines){
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        } catch  {
+            continue;
+        }
+        if (ev && "error" === ev.level) {
+            const msg = Array.isArray(ev.args) ? ev.args.join(" ") : ev.message || ev.text || "";
+            if (msg) errs.push(String(msg).slice(0, 300));
+        }
+    }
+    return errs.slice(-max);
+}
+function projectEngineVersion(projectPath) {
+    try {
+        const p = node_path.resolve(projectPath, "node_modules", "extension", "package.json");
+        return JSON.parse(node_fs.readFileSync(p, "utf8")).version || null;
+    } catch  {
+        return null;
+    }
+}
 async function doctor_handler(args) {
     if (!args.projectPath) return environmentPreflight();
     const projectPath = args.projectPath;
@@ -4958,9 +5260,36 @@ async function doctor_handler(args) {
                 detail: toMcpSpeak(detail),
                 remediation: "The build or extension load failed. Fix the reported error, let the dev server recompile, then re-run doctor."
             });
+        } else {
+            const errs = recentErrorLogs(projectPath, browser);
+            if (errs.length) {
+                healthy = false;
+                checks.push({
+                    check: "runtime-errors",
+                    status: "fail",
+                    detail: `Recent error-level logs: ${errs.join(" | ")}`,
+                    remediation: "The extension is throwing at runtime. Inspect with extension_logs; a missing permission for a called chrome.* API is a common cause (extension_manifest_validate now checks this)."
+                });
+            }
+        }
+        const engineVersion = projectEngineVersion(projectPath);
+        if (engineVersion) {
+            const pin = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
+            const mismatch = "" !== pin && "latest" !== pin && !engineVersion.includes(pin);
+            checks.push({
+                check: "project-engine",
+                status: mismatch ? "warn" : "pass",
+                detail: `project-local extension@${engineVersion}${mismatch ? ` — but EXTENSION_MCP_CLI_VERSION=${pin}; the dev loop uses the project bin, not the pin` : ""}`,
+                ...mismatch ? {
+                    remediation: `Run \`(cd ${projectPath} && npm i -D extension@${pin})\` to match the pinned engine.`
+                } : {}
+            });
         }
         return JSON.stringify({
             browser,
+            ...engineVersion ? {
+                engineVersion
+            } : {},
             healthy,
             checks
         });
@@ -5035,7 +5364,8 @@ const ARG_ALIASES = {
         "manifest"
     ],
     surface: [
-        "view"
+        "view",
+        "target"
     ]
 };
 function normalizeArgAliases(inputSchema, args) {

package/dist/src/lib/session-browser.d.ts

@@ -3,4 +3,8 @@ export interface ResolvedBrowser {
     source: "explicit" | "session" | "contract" | "fallback";
 }
 export declare function knownSessionBrowsers(projectPath: string): string[];
+export declare function deadReadySession(projectPath: string): {
+    browser: string;
+    pid: number;
+} | null;
 export declare function resolveSessionBrowser(projectPath: string, explicit: string | undefined, fallback?: string): ResolvedBrowser;

package/dist/src/tools/manifest-validate.d.ts

@@ -20,6 +20,10 @@ export declare const schema: {
                 default: string[];
                 description: string;
             };
+            browser: {
+                type: string;
+                description: string;
+            };
         };
         required: never[];
     };
@@ -27,5 +31,6 @@ export declare const schema: {
 export declare function handler(args: {
     manifestPath?: string;
     projectPath?: string;
+    browser?: string;
     browsers?: string[];
 }): Promise<string>;

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

@@ -18,6 +18,10 @@ export declare const schema: {
                 type: string;
                 description: string;
             };
+            url: {
+                type: string;
+                description: string;
+            };
             browser: {
                 type: string;
                 description: string;
@@ -31,6 +35,7 @@ export declare const schema: {
     };
 };
 export declare function handler(args: ActArgs & {
-    surface: string;
+    surface?: string;
     name?: string;
+    url?: string;
 }): Promise<string>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "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.",
   "mcpName": "io.github.extensiondev/mcp",
   "license": "MIT",

package/server.json

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