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

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 4.8.0
+
+Dev-session ergonomics hardened from a 30-persona agent walk of the toolchain.
+
+- **`allowEval` now implies `allowControl`.** Enabling eval on `extension_dev`
+  also opens the control channel, so a single `allowEval: true` unlocks
+  `extension_storage`/`reload`/`open`/`dom_inspect` too. `extension_dev` now
+  returns a `capabilities` block naming exactly which verbs the session unlocked,
+  ending the stop-and-restart loop that hit agents who passed one flag and not
+  the other.
+- **Session-aware browser default.** `extension_stop` (and the other
+  browser-scoped tools) resolve the browser from the one live session for the
+  project instead of assuming `chrome`. `extension_stop` also reaps the launched
+  browser's process tree and refuses to report `stopped: true` while a process
+  survives, fixing orphaned browsers (notably Firefox) after a stop.
+- **Forgiving argument names.** Common synonyms are accepted and normalized:
+  `path`/`dir` for `projectPath`, `name` for `projectName`, `template` for
+  `slug`, `code` for `expression`, and more, so a reasonable first guess no
+  longer 400s.
+- **`extension_manifest_validate`** accepts `projectPath` (it finds the
+  manifest) and probes path-valued fields (popup, service worker, icons, content
+  scripts) against disk, warning on dangling references instead of a false
+  all-clear.
+- **`extension_doctor`** inlines the dev session's own recorded errors so a build
+  or load failure no longer reads as healthy.
+- **`extension_inspect`** lists declared entrypoints (so a small content script
+  is not buried under assets) and warns when a store-listing promo image is
+  shipped inside the package.
+- **`extension_source_inspect`** on a Gecko session now names the working
+  alternatives (`extension_logs`, `extension_eval`) instead of pointing back at
+  the tool that just refused.
+
 ## 4.7.0
 
 `extension_deploy` now submits **through** extension.dev instead of driving a

package/dist/module.js

@@ -7,11 +7,11 @@ import node_path, { join } from "node:path";
 import { extensionCreate } from "extension-create";
 import node_os from "node:os";
 import cross_spawn from "cross-spawn";
+import { execFile, execFileSync } from "node:child_process";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
 import ws from "ws";
 import node_http from "node:http";
 import { extensionInstall, extensionUninstall, getManagedBrowsersCacheRoot } from "extension-install";
-import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 var add_feature_namespaceObject = {};
 __webpack_require__.r(add_feature_namespaceObject);
@@ -199,7 +199,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"4.6.0","El":{"OP":"^4.0.11"}}');
+var package_namespaceObject = JSON.parse('{"rE":"4.7.0","El":{"OP":"^4.0.11"}}');
 function detectPackageManager(projectPath) {
     const byLockfile = [
         [
@@ -769,7 +769,7 @@ const dev_schema = {
             allowEval: {
                 type: "boolean",
                 default: false,
-                description: "Additionally enable extension_eval (runs code in a context; writes a 0600 session token)"
+                description: "Enable extension_eval (runs code in a context; writes a 0600 session token). Implies allowControl, so a single allowEval: true also unlocks storage/reload/open/dom_inspect — you do not need to pass both."
             }
         },
         required: [
@@ -779,6 +779,7 @@ const dev_schema = {
 };
 async function dev_handler(args) {
     const browser = args.browser ?? "chrome";
+    const allowControl = Boolean(args.allowControl || args.allowEval);
     const cliArgs = [
         "dev",
         args.projectPath,
@@ -789,7 +790,7 @@ async function dev_handler(args) {
     if (args.noBrowser) cliArgs.push("--no-browser");
     if (false === args.polyfill) cliArgs.push("--polyfill", "false");
     cliArgs.push(...launchFlagArgs(args));
-    if (args.allowControl) cliArgs.push("--allow-control");
+    if (allowControl) cliArgs.push("--allow-control");
     if (args.allowEval) cliArgs.push("--allow-eval");
     const child = spawnExtensionCli(cliArgs, {
         projectDir: args.projectPath
@@ -812,13 +813,20 @@ async function dev_handler(args) {
     await new Promise((resolve)=>setTimeout(resolve, 3000));
     child.stdout?.off("data", collector);
     child.stderr?.off("data", collector);
+    const controlVerbs = "storage, reload, open, dom_inspect";
+    const capabilities = {
+        allowControl,
+        allowEval: Boolean(args.allowEval),
+        unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, source_inspect, wait, doctor)"
+    };
     return JSON.stringify({
         pid,
         browser,
         port: args.port ?? 8080,
         projectPath: args.projectPath,
         status: "started",
-        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. When you are done, call extension_stop to shut down the dev server and browser.",
+        capabilities,
+        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_inspect need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). Restart extension_dev with the flag you need.") + " When you are done, call extension_stop to shut down the dev server and browser.",
         earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500)
     });
 }
@@ -1003,6 +1011,66 @@ async function preview_handler(args) {
         hint: "Call extension_stop when you are done to close the preview browser."
     });
 }
+function contractSightings(projectPath) {
+    const root = node_path.resolve(projectPath, "dist", "extension-js");
+    let dirs;
+    try {
+        dirs = node_fs.readdirSync(root);
+    } catch  {
+        return [];
+    }
+    const sightings = [];
+    for (const dir of dirs){
+        const readyPath = node_path.join(root, dir, "ready.json");
+        try {
+            const stat = node_fs.statSync(readyPath);
+            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+            if (contract?.status !== "ready") continue;
+            sightings.push({
+                browser: dir,
+                mtimeMs: stat.mtimeMs,
+                pid: "number" == typeof contract.pid ? contract.pid : void 0
+            });
+        } catch  {}
+    }
+    return sightings;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function knownSessionBrowsers(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const browsers = [];
+    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
+    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 resolveSessionBrowser(projectPath, explicit, fallback = "chromium") {
+    if (explicit) return {
+        browser: explicit,
+        source: "explicit"
+    };
+    const resolved = node_path.resolve(projectPath);
+    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
+    if (mine.length > 0) return {
+        browser: mine[mine.length - 1].browser,
+        source: "session"
+    };
+    const sightings = contractSightings(projectPath).filter((s)=>void 0 === s.pid || pidAlive(s.pid)).sort((a, b)=>b.mtimeMs - a.mtimeMs);
+    if (sightings.length > 0) return {
+        browser: sightings[0].browser,
+        source: "contract"
+    };
+    return {
+        browser: fallback,
+        source: "fallback"
+    };
+}
 const stop_schema = {
     name: "extension_stop",
     description: "Stop a running dev, start, or preview session: terminates the dev server and the browser it launched. Counterpart to extension_dev/extension_start. Call it when you are done verifying so sessions do not accumulate.",
@@ -1015,8 +1083,7 @@ const stop_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome",
-                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start)"
+                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start). Defaults to the one live session for this project when omitted, instead of assuming chrome."
             },
             all: {
                 type: "boolean",
@@ -1027,6 +1094,27 @@ const stop_schema = {
         required: []
     }
 };
+function profileProcessPids(projectPath, browser) {
+    const marker = node_path.resolve(projectPath, "dist", `extension-profile-${browser}`);
+    try {
+        const out = execFileSync("pgrep", [
+            "-f",
+            marker
+        ], {
+            encoding: "utf8"
+        });
+        return out.split("\n").map((s)=>parseInt(s.trim(), 10)).filter((n)=>Number.isInteger(n) && n > 0 && n !== process.pid);
+    } catch  {
+        return [];
+    }
+}
+function reapProfileProcesses(projectPath, browser) {
+    const pids = profileProcessPids(projectPath, browser);
+    for (const pid of pids)try {
+        process.kill(pid, "SIGKILL");
+    } catch  {}
+    return pids;
+}
 function isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -1063,13 +1151,17 @@ function pidFromReadyContract(projectPath, browser) {
 async function stopOne(projectPath, browser) {
     const session = getSession(projectPath, browser);
     const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
-    if (null == pid) return {
-        projectPath,
-        browser,
-        pid: null,
-        stopped: false,
-        detail: "No known session for this project/browser (nothing registered in this server and no ready.json contract found)."
-    };
+    if (null == pid) {
+        const reaped = reapProfileProcesses(projectPath, browser);
+        return {
+            projectPath,
+            browser,
+            pid: null,
+            stopped: 0 !== reaped.length,
+            reaped,
+            detail: 0 === reaped.length ? "No known session for this project/browser (nothing registered in this server and no ready.json contract found)." : `No dev pid on record, but reaped ${reaped.length} orphaned browser process(es) from the profile dir.`
+        };
+    }
     let detail;
     if (isAlive(pid)) {
         signal(pid, "SIGTERM");
@@ -1080,17 +1172,23 @@ 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);
     removeSession(projectPath, browser);
     try {
         node_fs.rmSync(readyJsonPath(projectPath, browser), {
             force: true
         });
     } catch  {}
+    const survivors = profileProcessPids(projectPath, browser);
+    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).`;
     return {
         projectPath,
         browser,
         pid,
-        stopped: !isAlive(pid),
+        stopped,
+        reaped,
         detail
     };
 }
@@ -1110,7 +1208,8 @@ async function stop_handler(args) {
     if (!args.projectPath) return JSON.stringify({
         error: "projectPath is required unless all=true. Pass the same projectPath used with extension_dev/extension_start."
     });
-    const outcome = await stopOne(args.projectPath, args.browser ?? "chrome");
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    const outcome = await stopOne(args.projectPath, browser);
     return JSON.stringify(outcome);
 }
 const RAW_BASE = "https://raw.githubusercontent.com/extension-js/examples/main/examples";
@@ -1298,7 +1397,11 @@ const manifest_validate_schema = {
         properties: {
             manifestPath: {
                 type: "string",
-                description: "Path to manifest.json"
+                description: "Path to manifest.json. Or pass projectPath and the manifest is located for you."
+            },
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root; manifest.json is resolved from it (root or src/). Accepted in place of manifestPath."
             },
             browsers: {
                 type: "array",
@@ -1312,11 +1415,64 @@ const manifest_validate_schema = {
                 description: "Browsers to validate against"
             }
         },
-        required: [
-            "manifestPath"
-        ]
+        required: []
     }
 };
+function collectPathRefs(m) {
+    const refs = [];
+    const push = (v)=>{
+        if ("string" == typeof v) refs.push(v);
+    };
+    const action = m.action || m.browser_action;
+    if (action) {
+        push(action.default_popup);
+        if ("string" == typeof action.default_icon) push(action.default_icon);
+        else if (action.default_icon) Object.values(action.default_icon).forEach(push);
+    }
+    const bg = m.background;
+    if (bg) {
+        push(bg.service_worker);
+        push(bg.page);
+        if (Array.isArray(bg.scripts)) bg.scripts.forEach(push);
+    }
+    if (m.icons) Object.values(m.icons).forEach(push);
+    const cs = m.content_scripts;
+    if (Array.isArray(cs)) for (const c of cs){
+        if (Array.isArray(c.js)) c.js.forEach(push);
+        if (Array.isArray(c.css)) c.css.forEach(push);
+    }
+    push(m.options_page);
+    const oui = m.options_ui;
+    if (oui) push(oui.page);
+    const sp = m.side_panel;
+    if (sp) push(sp.default_path);
+    const sa = m.sidebar_action;
+    if (sa) push(sa.default_panel);
+    const cuo = m.chrome_url_overrides;
+    if (cuo) Object.values(cuo).forEach(push);
+    return refs;
+}
+function fileResolvesSomewhere(ref, roots) {
+    if (!ref || ref.includes("*") || /^(https?:|data:)/i.test(ref)) return true;
+    const clean = ref.replace(/^\.?\//, "");
+    return roots.some((root)=>{
+        try {
+            return node_fs.existsSync(node_path.resolve(root, clean));
+        } catch  {
+            return false;
+        }
+    });
+}
+function findManifest(projectPath) {
+    for (const rel of [
+        "manifest.json",
+        node_path.join("src", "manifest.json")
+    ]){
+        const candidate = node_path.resolve(projectPath, rel);
+        if (node_fs.existsSync(candidate)) return candidate;
+    }
+    return null;
+}
 async function manifest_validate_handler(args) {
     const browsers = args.browsers ?? [
         "chrome",
@@ -1329,9 +1485,20 @@ async function manifest_validate_handler(args) {
         browserSupport: {},
         similarTemplates: []
     };
+    const manifestPath = args.manifestPath ?? (args.projectPath ? findManifest(args.projectPath) : null);
+    if (!manifestPath) return JSON.stringify({
+        valid: false,
+        errors: [
+            args.projectPath ? `No manifest.json found under ${args.projectPath} (looked in the root and src/).` : "Pass manifestPath (path to manifest.json) or projectPath (project root)."
+        ],
+        warnings: [],
+        browserSupport: {},
+        similarTemplates: []
+    });
+    const manifestDir = node_path.dirname(node_path.resolve(manifestPath));
     let manifest;
     try {
-        const raw = node_fs.readFileSync(node_path.resolve(args.manifestPath), "utf8");
+        const raw = node_fs.readFileSync(node_path.resolve(manifestPath), "utf8");
         manifest = JSON.parse(raw);
     } catch (err) {
         return JSON.stringify({
@@ -1347,6 +1514,14 @@ async function manifest_validate_handler(args) {
     if (!manifest.name) result.errors.push("Missing required field: name");
     if (!manifest.version) result.warnings.push("Missing field: version (required for store submission)");
     const chromiumManifest = filterKeysForThisBrowser(manifest, "chrome");
+    const roots = [
+        manifestDir,
+        node_path.join(manifestDir, "src"),
+        ..."src" === node_path.basename(manifestDir) ? [
+            node_path.dirname(manifestDir)
+        ] : []
+    ];
+    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.`);
     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 ?? [],
@@ -1525,9 +1700,46 @@ async function inspect_handler(args) {
     const sourcemapSize = byType.sourcemap?.size ?? 0;
     const buildType = sourcemapSize > 0 ? "development" : "production";
     const shippableSize = totalSize - sourcemapSize;
+    const sizeByPath = new Map(files.map((f)=>[
+            f.path,
+            f.size
+        ]));
+    const entrypoints = [];
+    const addEntry = (role, ref)=>{
+        if ("string" != typeof ref) return;
+        const size = sizeByPath.get(ref.replace(/^\.?\//, ""));
+        entrypoints.push({
+            role,
+            path: ref,
+            present: void 0 !== size,
+            ...void 0 !== size ? {
+                sizeFormatted: formatBytes(size)
+            } : {}
+        });
+    };
+    const bg = manifest.background;
+    if (bg?.service_worker) addEntry("background.service_worker", bg.service_worker);
+    if (Array.isArray(bg?.scripts)) bg.scripts.forEach((s)=>addEntry("background.scripts", s));
+    const actionField = manifest.action || manifest.browser_action;
+    if (actionField?.default_popup) addEntry("action.default_popup", actionField.default_popup);
+    const contentScripts = manifest.content_scripts;
+    if (Array.isArray(contentScripts)) contentScripts.forEach((c, i)=>{
+        if (Array.isArray(c.js)) c.js.forEach((j)=>addEntry(`content_scripts[${i}].js`, j));
+        if (Array.isArray(c.css)) c.css.forEach((s)=>addEntry(`content_scripts[${i}].css`, s));
+    });
+    const PROMO_RE = /(screenshot|promo|marquee|tile|banner|preview)[-_.]?\d*\.(png|jpe?g|webp|gif)$/i;
+    const sizeWarnings = [];
+    for (const f of files)if ("sourcemap" !== f.type) {
+        if (PROMO_RE.test(f.path)) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) looks like a store-listing promo image shipped inside the extension package — move it out of the bundled sources so it does not inflate the store zip.`);
+        else if ("image" === f.type && !f.path.includes("icon") && f.size > 51200 && shippableSize > 0 && f.size / shippableSize > 0.25) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) is ${Math.round(f.size / shippableSize * 100)}% of the shipped bundle — unusually large for a shipped asset.`);
+    }
     const result = {
         browser,
         distPath,
+        entrypoints,
+        ...sizeWarnings.length ? {
+            sizeWarnings
+        } : {},
         buildType,
         totalSize,
         totalSizeFormatted: formatBytes(totalSize),
@@ -1567,6 +1779,7 @@ async function inspect_handler(args) {
             hasManifest: node_fs.existsSync(manifestPath),
             hasIcons: files.some((f)=>"image" === f.type && f.path.includes("icon")),
             noSourceMaps: !files.some((f)=>"sourcemap" === f.type),
+            noPromoAssets: !files.some((f)=>PROMO_RE.test(f.path)),
             under10MB: totalSize < 10485760
         }
     };
@@ -2027,66 +2240,6 @@ function isCdpEndpoint(port) {
         });
     });
 }
-function contractSightings(projectPath) {
-    const root = node_path.resolve(projectPath, "dist", "extension-js");
-    let dirs;
-    try {
-        dirs = node_fs.readdirSync(root);
-    } catch  {
-        return [];
-    }
-    const sightings = [];
-    for (const dir of dirs){
-        const readyPath = node_path.join(root, dir, "ready.json");
-        try {
-            const stat = node_fs.statSync(readyPath);
-            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-            if (contract?.status !== "ready") continue;
-            sightings.push({
-                browser: dir,
-                mtimeMs: stat.mtimeMs,
-                pid: "number" == typeof contract.pid ? contract.pid : void 0
-            });
-        } catch  {}
-    }
-    return sightings;
-}
-function pidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    } catch  {
-        return false;
-    }
-}
-function knownSessionBrowsers(projectPath) {
-    const resolved = node_path.resolve(projectPath);
-    const browsers = [];
-    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
-    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 resolveSessionBrowser(projectPath, explicit, fallback = "chromium") {
-    if (explicit) return {
-        browser: explicit,
-        source: "explicit"
-    };
-    const resolved = node_path.resolve(projectPath);
-    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
-    if (mine.length > 0) return {
-        browser: mine[mine.length - 1].browser,
-        source: "session"
-    };
-    const sightings = contractSightings(projectPath).filter((s)=>void 0 === s.pid || pidAlive(s.pid)).sort((a, b)=>b.mtimeMs - a.mtimeMs);
-    if (sightings.length > 0) return {
-        browser: sightings[0].browser,
-        source: "contract"
-    };
-    return {
-        browser: fallback,
-        source: "fallback"
-    };
-}
 const source_inspect_schema = {
     name: "extension_source_inspect",
     description: "Inspect a running extension's live state via Chrome DevTools Protocol: full HTML (with shadow DOM), DOM structure, content script injection, console messages, and CSS selector queries. Requires an active dev or start session.",
@@ -2157,8 +2310,8 @@ async function source_inspect_handler(args) {
     ]);
     const maxBytes = args.maxBytes ?? 262144;
     if (!isChromiumFamily(browser)) return JSON.stringify({
-        error: `Source inspection for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
-        hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
+        error: `Source inspection reads the live DOM over Chrome DevTools Protocol, which ${browser} (Gecko) does not expose. This is a capability limit, not a missing session.`,
+        hint: `For the ${browser} session, read runtime state with extension_logs, or extension_eval (context: "content"/"page") which works against Firefox over the control channel. To get CDP DOM inspection, run a Chromium-family dev session (extension_dev with browser: "chrome") in parallel.`
     });
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return JSON.stringify({
@@ -4711,6 +4864,14 @@ async function detect_browsers_handler(args) {
         hint: missing.length ? `Missing browser(s): ${missing.map((d)=>d.browser).join(", ")}.${missing.some((d)=>MANAGED_INSTALLABLE.has(d.browser)) ? ` Use extension_install_browser to install ${missing.filter((d)=>MANAGED_INSTALLABLE.has(d.browser)).map((d)=>d.browser).join(", ")}.` : ""}` : "All requested browsers are available."
     });
 }
+function doctor_readReadyContract(projectPath, browser) {
+    try {
+        const raw = node_fs.readFileSync(node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json"), "utf8");
+        return JSON.parse(raw);
+    } catch  {
+        return null;
+    }
+}
 const doctor_schema = {
     name: "extension_doctor",
     description: "Diagnose a dev session end-to-end: ready contract, dev-server process, control-port agreement, control channel, eval token, executor, and browser liveness. Returns one {check, status, detail, remediation?} entry per leg in dependency order — a 'skip' names the check that blocked it and is NOT a pass. Run this first when any act tool (storage/reload/eval/open) errors unexpectedly. Wraps `extension doctor`. Call with no projectPath for a pre-flight environment check (node, extension CLI, template cache) before any project exists.",
@@ -4786,9 +4947,21 @@ async function doctor_handler(args) {
             if ("string" == typeof check.detail) check.detail = toMcpSpeak(check.detail);
             if ("string" == typeof check.remediation) check.remediation = toMcpSpeak(check.remediation);
         }
+        let healthy = 0 === code;
+        const contract = doctor_readReadyContract(projectPath, browser);
+        if (contract?.status === "error") {
+            healthy = false;
+            const detail = contract.errors && contract.errors.length ? contract.errors.join("; ") : contract.message || "The dev session recorded status: error in ready.json.";
+            checks.push({
+                check: "runtime-errors",
+                status: "fail",
+                detail: toMcpSpeak(detail),
+                remediation: "The build or extension load failed. Fix the reported error, let the dev server recompile, then re-run doctor."
+            });
+        }
         return JSON.stringify({
             browser,
-            healthy: 0 === code,
+            healthy,
             checks
         });
     } catch  {
@@ -4835,6 +5008,55 @@ function checkPrimitive(path, value, schema, issues) {
         });
     }
 }
+const ARG_ALIASES = {
+    projectPath: [
+        "path",
+        "dir",
+        "projectDir",
+        "cwd"
+    ],
+    projectName: [
+        "name"
+    ],
+    parentDir: [
+        "parent",
+        "into"
+    ],
+    slug: [
+        "template",
+        "templateSlug"
+    ],
+    expression: [
+        "code",
+        "js",
+        "script"
+    ],
+    manifestPath: [
+        "manifest"
+    ],
+    surface: [
+        "view"
+    ]
+};
+function normalizeArgAliases(inputSchema, args) {
+    const schema = inputSchema;
+    const props = schema.properties ?? {};
+    const out = {
+        ...args
+    };
+    for (const [canonical, aliases] of Object.entries(ARG_ALIASES))if (canonical in props) {
+        if (void 0 === out[canonical]) {
+            for (const alias of aliases)if (!(alias in props)) {
+                if (void 0 !== out[alias]) {
+                    out[canonical] = out[alias];
+                    delete out[alias];
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
 function validateToolInput(inputSchema, args) {
     const schema = inputSchema;
     const issues = [];
@@ -4933,7 +5155,8 @@ async function startServer() {
             ],
             isError: true
         };
-        const issues = validateToolInput(tool.schema.inputSchema, args ?? {});
+        const normalizedArgs = normalizeArgAliases(tool.schema.inputSchema, args ?? {});
+        const issues = validateToolInput(tool.schema.inputSchema, normalizedArgs);
         if (issues.length) return {
             content: [
                 {
@@ -4944,7 +5167,7 @@ async function startServer() {
             isError: true
         };
         try {
-            const result = await tool.handler(args ?? {});
+            const result = await tool.handler(normalizedArgs);
             return {
                 content: [
                     {

package/dist/src/lib/validate-input.d.ts

@@ -2,5 +2,6 @@ export interface InputIssue {
     path: string;
     message: string;
 }
+export declare function normalizeArgAliases(inputSchema: Record<string, unknown>, args: Record<string, unknown>): Record<string, unknown>;
 export declare function validateToolInput(inputSchema: Record<string, unknown>, args: Record<string, unknown>): InputIssue[];
 export declare function inputValidationError(toolName: string, issues: InputIssue[]): string;

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

@@ -8,6 +8,10 @@ export declare const schema: {
                 type: string;
                 description: string;
             };
+            projectPath: {
+                type: string;
+                description: string;
+            };
             browsers: {
                 type: string;
                 items: {
@@ -17,10 +21,11 @@ export declare const schema: {
                 description: string;
             };
         };
-        required: string[];
+        required: never[];
     };
 };
 export declare function handler(args: {
-    manifestPath: string;
+    manifestPath?: string;
+    projectPath?: string;
     browsers?: string[];
 }): Promise<string>;

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

@@ -10,7 +10,6 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
                 description: string;
             };
             all: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "4.7.0",
+  "version": "4.8.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.7.0",
+  "version": "4.8.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@extension.dev/mcp",
-      "version": "4.7.0",
+      "version": "4.8.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"