@extension.dev/mcp 4.2.1 → 4.3.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "extensiondev-mcp",
+  "owner": {
+    "name": "Cezar Augusto",
+    "email": "boss@cezaraugusto.net",
+    "url": "https://extension.dev"
+  },
+  "plugins": [
+    {
+      "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.3.0",
+      "category": "development",
+      "author": {
+        "name": "Cezar Augusto"
+      },
+      "homepage": "https://github.com/extensiondev/mcp",
+      "strict": false
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "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.3.0",
+  "author": {
+    "name": "Cezar Augusto",
+    "email": "boss@cezaraugusto.net",
+    "url": "https://cezaraugusto.com"
+  },
+  "homepage": "https://github.com/extensiondev/mcp",
+  "repository": "https://github.com/extensiondev/mcp",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "browser-extension",
+    "chrome-extension",
+    "firefox-addon",
+    "edge-extension",
+    "manifest-v3",
+    "webextension",
+    "cross-browser"
+  ],
+  "commands": "./claude/commands",
+  "mcpServers": {
+    "extension-dev": {
+      "command": "npx",
+      "args": ["-y", "@extension.dev/mcp"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 4.3.0
+
+Diagnosis + version-skew release: a 29th tool that turns "an act tool
+errored, now what" into one call, and a CI that tests the engine
+versions users actually run.
+
+- New tool `extension_doctor`. Wraps `extension doctor --output json`:
+  walks the dev session's control-channel legs (ready contract,
+  dev-server process, control-port agreement, control channel, eval
+  token, executor, browser liveness) and returns one
+  `{check, status, detail, remediation?}` entry per leg in dependency
+  order. Detail and remediation prose are rewritten to MCP-speak like
+  every other act-verb error. Engines that predate the `doctor` verb get
+  a clean CliError with a hint instead of a crash.
+- Browser-family classification now has ONE copy
+  (`src/lib/browser-family.ts`). Fixes real drift: `browsers:
+  ["chromium"]` ran ZERO family checks in `extension_manifest_validate`
+  (an MV2 manifest validated "fine"), and `chromium` was still missing
+  from the `extension_build` / `extension_dev` / `extension_preview` /
+  `extension_start` schema enums.
+- CI version-skew matrix: every push builds and tests against the
+  engine canary, the latest stable, and the vendored floor (deduped),
+  plus a nightly run that exercises the real `npx extension@<pin>` path
+  end-to-end (`RUN_CLI_SMOKE=1`). A red canary cell now surfaces engine
+  regressions the day they publish instead of on the next unrelated PR.
+- Legacy ready-contract compatibility suite: fixtures pin the contract
+  shapes older engines wrote (no `cdpPort`, no `pid`), so a 4.0.6-era
+  session stays visible to browser defaulting and `resolveCdpPort`
+  refuses to adopt an unrelated developer Chrome instead of probing a
+  bogus port.
+
+## 4.2.2
+
+Agent-ergonomics release from the 4.2.1 fresh-eyes walk: the two changes
+that removed nearly all friction a real MCP client hit.
+
+- Session-aware browser default. Tools that target a running session
+  (`extension_logs`, `extension_reload`, `extension_eval`,
+  `extension_storage`, `extension_open`, `extension_dom_inspect`,
+  `extension_list_extensions`, `extension_source_inspect`,
+  `extension_wait`) no longer hard-default `browser` to a constant that
+  could disagree with the session `extension_dev` actually started.
+  Omitting `browser` now resolves to the active session's browser:
+  in-memory registry first, then the freshest live `ready.json` contract
+  on disk (dead pids ignored), then the old constant. Starting a session
+  with `browser: "chrome"` and calling `extension_logs` with no args now
+  just works instead of erroring about a missing chromium channel.
+- Error hints speak the MCP tool surface, not the CLI. Act-verb error
+  prose is rewritten before returning: `` `extension dev
+  --browser=chromium --allow-control` `` becomes `extension_dev with
+  { browser: "chromium", allowControl: true }`, and stray
+  `--allow-control` / `--allow-eval` / `--browser=<x>` mentions become
+  their tool-argument names. Result data is never touched — only
+  error/hint prose. Tool descriptions now name `allowControl` /
+  `allowEval` directly, so agents no longer discover the gates by
+  fuzzing the schema.
+- The no-channel error now names the session that IS running ("Active
+  session browser(s) for this project: chrome — pass that as `browser`"),
+  so an agent retargets instead of spawning a second, conflicting
+  session. Same for the `extension_logs` follow miss.
+- `extension_list_extensions` / `extension_source_inspect` accept
+  `browser: "chromium"` (the default dev target) instead of rejecting it
+  as non-Chromium.
+- Tests: session-browser resolution + hint-translation suite (137 total).
+
+## 4.2.1
+
+`extension_build` failures no longer kill the MCP server process
+(fatal-error path returned a rejected promise the server didn't catch).
+CDP-dependent tools resolve the debug port from the session's ready
+contract instead of assuming 9222 (plus a test-only engine pin
+override, `EXTENSION_MCP_CLI_VERSION`).
+
 ## 4.2.0
 
 Session lifecycle + determinism release. Tool count 27 -> 28.

package/README.md

@@ -7,7 +7,7 @@
 
 # @extension.dev/mcp [![Version][npm-version-image]][npm-version-url] [![Downloads][npm-downloads-image]][npm-downloads-url] [![Discord][discord-image]][discord-url]
 
-> Give your AI agent hands for browser extension development. 28 MCP tools that scaffold, run, inspect, debug, and publish cross-browser extensions.
+> Give your AI agent hands for browser extension development. 29 MCP tools that scaffold, run, inspect, debug, and publish cross-browser extensions.
 
 <img alt="Logo" align="right" src="https://avatars.githubusercontent.com/u/106714027" width="20%" />
 
@@ -41,6 +41,17 @@ Built on [Extension.js](https://extension.js.org), the open-source cross-browser
 claude mcp add extension-dev npx @extension.dev/mcp
 ```
 
+Or install it as a plugin — the MCP server plus the `/extension`, `/extension-add`, `/extension-debug`, and `/extension-publish` commands in one step:
+
+```
+/plugin marketplace add extensiondev/mcp
+/plugin install extension-mcp@extensiondev-mcp
+```
+
+### Cursor
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=extension-dev&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAZXh0ZW5zaW9uLmRldi9tY3AiXX0%3D)
+
 ### Claude Desktop / `.mcp.json`
 
 ```json
@@ -96,7 +107,8 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | see | `extension_dom_inspect` | CDP-free DOM snapshot |
 | see | `extension_list_extensions` | List loaded extensions (Chromium) |
 | see | `extension_logs` | Stream logs from every context |
-| act | `extension_eval` | Evaluate in a context (`--allow-eval`) |
+| see | `extension_doctor` | Diagnose the dev session leg by leg (ready contract, ports, token, executor, browser) |
+| act | `extension_eval` | Evaluate in a context (needs `allowEval: true` on `extension_dev`) |
 | act | `extension_storage` | Read/write `chrome.storage` |
 | act | `extension_reload` | Reload extension or tab |
 | act | `extension_open` | Open a surface / trigger `action`, `command` |

package/bin/extension-mcp.js

@@ -11,6 +11,5 @@ if (cmd && ['login', 'logout', 'whoami', 'release'].includes(cmd)) {
       process.exit(1)
     })
 } else {
-  // No subcommand: run as the MCP stdio server (the default and primary mode).
   startServer()
 }

package/dist/module.js

@@ -45,6 +45,12 @@ __webpack_require__.d(dev_namespaceObject, {
     handler: ()=>dev_handler,
     schema: ()=>dev_schema
 });
+var doctor_namespaceObject = {};
+__webpack_require__.r(doctor_namespaceObject);
+__webpack_require__.d(doctor_namespaceObject, {
+    handler: ()=>doctor_handler,
+    schema: ()=>doctor_schema
+});
 var dom_inspect_namespaceObject = {};
 __webpack_require__.r(dom_inspect_namespaceObject);
 __webpack_require__.d(dom_inspect_namespaceObject, {
@@ -183,7 +189,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"4.2.1","El":{"OP":"^4.0.8"}}');
+var package_namespaceObject = JSON.parse('{"rE":"4.3.0","El":{"OP":"^4.0.8"}}');
 const create_schema = {
     name: "extension_create",
     description: "Create a new browser extension project from a template in the extension.dev template catalog. Use extension_list_templates to see available options.",
@@ -371,6 +377,7 @@ const build_schema = {
                 type: "string",
                 enum: [
                     "chrome",
+                    "chromium",
                     "edge",
                     "firefox",
                     "chromium-based",
@@ -528,6 +535,7 @@ const dev_schema = {
                 type: "string",
                 enum: [
                     "chrome",
+                    "chromium",
                     "edge",
                     "firefox",
                     "chromium-based",
@@ -617,6 +625,7 @@ const start_schema = {
                 type: "string",
                 enum: [
                     "chrome",
+                    "chromium",
                     "edge",
                     "firefox",
                     "chromium-based",
@@ -687,6 +696,7 @@ const preview_schema = {
                 type: "string",
                 enum: [
                     "chrome",
+                    "chromium",
                     "edge",
                     "firefox",
                     "chromium-based",
@@ -902,6 +912,23 @@ async function get_template_source_handler(args) {
         } : {}
     });
 }
+const CHROMIUM_FAMILY = new Set([
+    "chrome",
+    "chromium",
+    "edge",
+    "chromium-based"
+]);
+const GECKO_FAMILY = new Set([
+    "firefox",
+    "gecko-based",
+    "firefox-based"
+]);
+function isChromiumFamily(browser) {
+    return CHROMIUM_FAMILY.has(browser);
+}
+function isGeckoFamily(browser) {
+    return GECKO_FAMILY.has(browser);
+}
 const manifest_validate_schema = {
     name: "extension_manifest_validate",
     description: "Validate a manifest.json file for correctness across browsers. Reports missing fields, invalid permissions, and cross-browser compatibility issues.",
@@ -961,15 +988,8 @@ async function manifest_validate_handler(args) {
     const chromiumManifest = filterKeysForThisBrowser(manifest, "chrome");
     if (!chromiumManifest.manifest_version) result.errors.push('Missing manifest_version. Use "chromium:manifest_version": 3 and "firefox:manifest_version": 2 for cross-browser support.');
     for (const browser of browsers){
-        const isChromium = [
-            "chrome",
-            "edge",
-            "chromium-based"
-        ].includes(browser);
-        const isFirefox = [
-            "firefox",
-            "gecko-based"
-        ].includes(browser);
+        const isChromium = isChromiumFamily(browser);
+        const isFirefox = isGeckoFamily(browser);
         const effective = filterKeysForThisBrowser(manifest, browser);
         const issues = [];
         if (isChromium) {
@@ -1620,6 +1640,66 @@ 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.",
@@ -1663,7 +1743,7 @@ const source_inspect_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             maxBytes: {
                 type: "number",
@@ -1682,21 +1762,16 @@ const source_inspect_schema = {
     }
 };
 async function source_inspect_handler(args) {
-    const browser = args.browser ?? "chrome";
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     const include = new Set(args.include ?? [
         "summary",
         "meta",
         "console"
     ]);
     const maxBytes = args.maxBytes ?? 262144;
-    const isChromium = [
-        "chrome",
-        "edge",
-        "chromium-based"
-    ].includes(browser);
-    if (!isChromium) return JSON.stringify({
+    if (!isChromiumFamily(browser)) return JSON.stringify({
         error: `Source inspection for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
-        hint: "Use --browser=chrome for source inspection, or use the CLI: npx extension dev --source"
+        hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
     });
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return JSON.stringify({
@@ -1797,7 +1872,7 @@ const list_extensions_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             }
         },
         required: [
@@ -1806,15 +1881,10 @@ const list_extensions_schema = {
     }
 };
 async function list_extensions_handler(args) {
-    const browser = args.browser ?? "chrome";
-    const isChromium = [
-        "chrome",
-        "edge",
-        "chromium-based"
-    ].includes(browser);
-    if (!isChromium) return JSON.stringify({
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
+    if (!isChromiumFamily(browser)) return JSON.stringify({
         error: `Listing extensions for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
-        hint: "Use --browser=chrome."
+        hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
     });
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return JSON.stringify({
@@ -1950,8 +2020,7 @@ const logs_schema_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium",
-                description: "Which dist/extension-js/<browser>/ to read. Defaults to chromium (the default dev target)."
+                description: "Which dist/extension-js/<browser>/ to read. Defaults to the active dev session's browser for this project (falls back to chromium)."
             },
             level: {
                 type: "string",
@@ -2092,10 +2161,14 @@ async function readFromFile(args, browser, limit) {
 }
 async function readFromStream(args, browser, limit) {
     const ready = readReadyContract(args.projectPath, browser);
-    if (!ready) return JSON.stringify({
-        error: `No active control channel found for ${browser}.`,
-        hint: `Run extension_dev (browser: ${browser}) and wait for it to be ready, then retry. For past logs without a live channel, call without follow.`
-    });
+    if (!ready) {
+        const running = knownSessionBrowsers(args.projectPath).filter((b)=>b !== browser);
+        const retarget = running.length ? `An active session exists for browser(s): ${running.join(", ")} — pass that as \`browser\`. Otherwise run` : "Run";
+        return JSON.stringify({
+            error: `No active control channel found for ${browser}.`,
+            hint: `${retarget} extension_dev (browser: ${browser}) and wait for it to be ready, then retry. For past logs without a live channel, call without follow.`
+        });
+    }
     const followMs = Math.min(Math.max(args.followMs ?? 4000, 500), 15000);
     const matches = makeFilter(args);
     const events = [];
@@ -2158,11 +2231,27 @@ async function readFromStream(args, browser, limit) {
     });
 }
 async function logs_handler(args) {
-    const browser = args.browser ?? "chromium";
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const limit = args.limit && args.limit > 0 ? args.limit : 200;
     if (args.follow) return readFromStream(args, browser, limit);
     return readFromFile(args, browser, limit);
 }
+function toMcpSpeak(text) {
+    return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/--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 running = knownSessionBrowsers(projectPath);
+    if (0 === running.length) return message;
+    return `${message} Active session browser(s) for this project: ${running.join(", ")} — pass that as \`browser\`, or restart it via extension_dev with allowControl: true if the control channel is off.`;
+}
+function translateFrame(frame, projectPath) {
+    if (!frame || false !== frame.ok) return frame;
+    if (frame.error && "string" == typeof frame.error.message) frame.error.message = withSessionContext(toMcpSpeak(frame.error.message), projectPath);
+    if ("string" == typeof frame.error?.hint) frame.error.hint = toMcpSpeak(frame.error.hint);
+    if ("string" == typeof frame.hint) frame.hint = toMcpSpeak(frame.hint);
+    return frame;
+}
 async function runActVerb(args, projectPath, timeoutMs) {
     const { code, stdout, stderr } = await runExtensionCli([
         ...args,
@@ -2174,14 +2263,16 @@ async function runActVerb(args, projectPath, timeoutMs) {
     });
     const out = stdout.trim();
     if (out) try {
-        JSON.parse(out);
+        const frame = JSON.parse(out);
+        if (frame && false === frame.ok) return JSON.stringify(translateFrame(frame, projectPath));
         return out;
     } catch  {}
+    const message = stderr.trim() || `extension exited with code ${code}`;
     return JSON.stringify({
         ok: false,
         error: {
             name: "CliError",
-            message: stderr.trim() || `extension exited with code ${code}`
+            message: withSessionContext(toMcpSpeak(message), projectPath)
         }
     });
 }
@@ -2196,7 +2287,7 @@ function commonFlags(args) {
 }
 const eval_schema = {
     name: "extension_eval",
-    description: "Evaluate an expression in a running extension context (service worker, content script, popup, options, sidebar). Requires the dev session to be started with --allow-eval (writes a 0600 session token the CLI reads). Wraps `extension eval`.",
+    description: "Evaluate an expression in a running extension context (service worker, content script, popup, options, sidebar). Requires the dev session to be started with allowEval: true (extension_dev; writes a 0600 session token the CLI reads). Wraps `extension eval`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2232,7 +2323,7 @@ const eval_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2246,16 +2337,20 @@ const eval_schema = {
     }
 };
 async function eval_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     return runActVerb([
         "eval",
         args.expression,
         args.projectPath,
-        ...commonFlags(args)
+        ...commonFlags({
+            ...args,
+            browser
+        })
     ], args.projectPath, args.timeout);
 }
 const storage_schema = {
     name: "extension_storage",
-    description: "Read or write chrome.storage in a running extension. Requires the dev session to be started with --allow-control. Wraps `extension storage get|set`.",
+    description: "Read or write chrome.storage in a running extension. Requires the dev session to be started with allowControl: true (extension_dev). Wraps `extension storage get|set`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2301,7 +2396,7 @@ const storage_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2315,6 +2410,7 @@ const storage_schema = {
     }
 };
 async function storage_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const cli = [
         "storage",
         args.action,
@@ -2333,13 +2429,13 @@ async function storage_handler(args) {
         cli.push("--value", JSON.stringify(args.value));
     }
     if (args.context) cli.push("--context", args.context);
-    if (args.browser) cli.push("--browser", args.browser);
+    cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
     return runActVerb(cli, args.projectPath, args.timeout);
 }
 const reload_schema = {
     name: "extension_reload",
-    description: "Reload a running extension (background) or a tab. Requires the dev session to be started with --allow-control. Wraps `extension reload`.",
+    description: "Reload a running extension (background) or a tab. Requires the dev session to be started with allowControl: true (extension_dev). Wraps `extension reload`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2362,7 +2458,7 @@ const reload_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2375,15 +2471,19 @@ const reload_schema = {
     }
 };
 async function reload_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     return runActVerb([
         "reload",
         args.projectPath,
-        ...commonFlags(args)
+        ...commonFlags({
+            ...args,
+            browser
+        })
     ], args.projectPath, args.timeout);
 }
 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 --allow-control. Wraps `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`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2408,7 +2508,7 @@ const open_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2422,19 +2522,20 @@ const open_schema = {
     }
 };
 async function open_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const cli = [
         "open",
         args.surface,
         args.projectPath
     ];
     if ("command" === args.surface && args.name) cli.push("--name", args.name);
-    if (args.browser) cli.push("--browser", args.browser);
+    cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
     return runActVerb(cli, args.projectPath, args.timeout);
 }
 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 --allow-control. 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). 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: {
@@ -2483,7 +2584,7 @@ const dom_inspect_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2519,7 +2620,7 @@ async function dom_inspect_handler(args) {
     if (args.include?.length) cli.push("--include", args.include.join(","));
     if (null != args.maxBytes) cli.push("--max-bytes", String(args.maxBytes));
     if (null != args.withConsole) cli.push("--with-console", String(args.withConsole));
-    if (args.browser) cli.push("--browser", args.browser);
+    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);
 }
@@ -2676,8 +2777,7 @@ const wait_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome",
-                description: "Browser to check readiness for"
+                description: "Browser to check readiness for. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2691,7 +2791,7 @@ const wait_schema = {
     }
 };
 async function wait_handler(args) {
-    const browser = args.browser ?? "chrome";
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     const timeout = args.timeout ?? 60000;
     const readyPath = node_path.resolve(args.projectPath, "dist", "extension-js", browser, "ready.json");
     const start = Date.now();
@@ -3156,7 +3256,7 @@ async function install_browser_handler(args) {
             status: "installed",
             browser: args.browser,
             duration: Date.now() - start,
-            hint: `Browser "${args.browser}" is now available. Use extension_dev or extension_start with --browser=${args.browser}.`
+            hint: `Browser "${args.browser}" is now available. Use extension_dev or extension_start with browser: "${args.browser}".`
         });
     } catch (err) {
         return JSON.stringify({
@@ -3452,6 +3552,63 @@ async function detect_browsers_handler(args) {
         hint: missing.length ? `Missing browser(s): ${missing.map((d)=>d.browser).join(", ")}. Use extension_install_browser to install them.` : "All requested browsers are available."
     });
 }
+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`.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root"
+            },
+            browser: {
+                type: "string",
+                description: "Browser session to diagnose. Defaults to the active dev session's browser for this project."
+            }
+        },
+        required: [
+            "projectPath"
+        ]
+    }
+};
+async function doctor_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+    const { code, stdout, stderr } = await runExtensionCli([
+        "doctor",
+        args.projectPath,
+        "--browser",
+        browser,
+        "--output",
+        "json"
+    ], {
+        cwd: args.projectPath
+    });
+    const out = stdout.trim();
+    try {
+        const checks = JSON.parse(out);
+        if (!Array.isArray(checks)) throw new Error("not a check array");
+        for (const check of checks){
+            if ("string" == typeof check.detail) check.detail = toMcpSpeak(check.detail);
+            if ("string" == typeof check.remediation) check.remediation = toMcpSpeak(check.remediation);
+        }
+        return JSON.stringify({
+            browser,
+            healthy: 0 === code,
+            checks
+        });
+    } catch  {
+        const message = stderr.trim() || `extension exited with code ${code}`;
+        return JSON.stringify({
+            ok: false,
+            error: {
+                name: "CliError",
+                message: toMcpSpeak(message),
+                hint: "extension doctor requires a recent extension CLI — the project's local install may predate it."
+            }
+        });
+    }
+}
 function typeOf(value) {
     if (Array.isArray(value)) return "array";
     if (null === value) return "null";
@@ -3544,7 +3701,8 @@ const tools = [
     logout_namespaceObject,
     install_browser_namespaceObject,
     list_browsers_namespaceObject,
-    detect_browsers_namespaceObject
+    detect_browsers_namespaceObject,
+    doctor_namespaceObject
 ];
 const toolMap = new Map();
 for (const tool of tools)toolMap.set(tool.schema.name, tool);

package/dist/src/__tests__/fixtures/ready-contract.d.ts

@@ -0,0 +1,7 @@
+export declare function writeModernContract(projectPath: string, browser: string, overrides?: Record<string, unknown>): string;
+export declare function writeLegacyContract(projectPath: string, browser: string, overrides?: Record<string, unknown>): string;
+export declare function writeErrorContract(projectPath: string, browser: string): string;
+export declare function writeLegacyEngineState(projectPath: string, browser: string): {
+    legacyPortFile: string;
+    legacyTokenFile: string;
+};

package/dist/src/index.d.ts

@@ -8,11 +8,4 @@ export interface ToolModule {
 }
 export declare const tools: ToolModule[];
 export declare function startServer(): Promise<void>;
-/**
- * Human-facing subcommands for `extension-mcp <cmd>`. Unlike the MCP tools
- * (which must return promptly and so resume across calls), the bin blocks on
- * the device flow because there is a person watching the terminal. Returns a
- * process exit code. All console output goes to stderr so it never pollutes a
- * machine-readable stdout if a script captures it.
- */
 export declare function runCli(cmd: string, args: string[]): Promise<number>;

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

@@ -1,14 +1,5 @@
-/**
- * Run an `extension <verb> … --output json` act command and return its result
- * JSON as a string (the MCP tool payload). The CLI prints the control-channel
- * result frame to stdout (for ok and !ok alike); connection/no-session failures
- * go to stderr with a non-zero exit. Either way we return a JSON object.
- *
- * Per lockstep invariant #1 the act tools wrap the CLI verb rather than talking
- * to the control WS directly — so MCP behavior can never drift from the CLI.
- */
+export declare function toMcpSpeak(text: string): string;
 export declare function runActVerb(args: string[], projectPath: string, timeoutMs?: number): Promise<string>;
-/** Shared input fields for act tools. */
 export interface ActArgs {
     projectPath: string;
     browser?: string;
@@ -17,5 +8,4 @@ export interface ActArgs {
     tab?: number;
     timeout?: number;
 }
-/** Build the trailing CLI flags common to act verbs. */
 export declare function commonFlags(args: ActArgs): string[];

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

@@ -0,0 +1,4 @@
+export declare const CHROMIUM_FAMILY: ReadonlySet<string>;
+export declare const GECKO_FAMILY: ReadonlySet<string>;
+export declare function isChromiumFamily(browser: string): boolean;
+export declare function isGeckoFamily(browser: string): boolean;

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

@@ -4,17 +4,6 @@ export interface CliResult {
     stdout: string;
     stderr: string;
 }
-/**
- * Resolve how to invoke the `extension` CLI for a given project.
- *
- * Preference order:
- * 1. The project's own `node_modules/.bin/extension` — the version the project
- *    pinned is the single source of behavior for that project (lockstep
- *    invariant), and spawning it needs no network.
- * 2. `npx extension@<pinned>` — pinned to the extension-develop version this
- *    package vendors, never a floating `latest`, so MCP behavior stays
- *    reproducible even without a project-local install.
- */
 export declare function resolveExtensionInvocation(projectDir?: string): {
     command: string;
     prefixArgs: string[];

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

@@ -0,0 +1,6 @@
+export interface ResolvedBrowser {
+    browser: string;
+    source: "explicit" | "session" | "contract" | "fallback";
+}
+export declare function knownSessionBrowsers(projectPath: string): string[];
+export declare function resolveSessionBrowser(projectPath: string, explicit: string | undefined, fallback?: string): ResolvedBrowser;

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

@@ -2,10 +2,5 @@ export interface InputIssue {
     path: string;
     message: string;
 }
-/**
- * Validate tools/call arguments against a tool inputSchema. Returns an empty
- * array when the args are acceptable.
- */
 export declare function validateToolInput(inputSchema: Record<string, unknown>, args: Record<string, unknown>): InputIssue[];
-/** Frozen-style error envelope for input validation failures. */
 export declare function inputValidationError(toolName: string, issues: InputIssue[]): string;

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

@@ -0,0 +1,22 @@
+export declare const schema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            projectPath: {
+                type: string;
+                description: string;
+            };
+            browser: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handler(args: {
+    projectPath: string;
+    browser?: string;
+}): Promise<string>;

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

@@ -38,7 +38,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

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

@@ -29,7 +29,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

package/dist/src/tools/list-extensions.d.ts

@@ -10,7 +10,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
         };
         required: string[];

package/dist/src/tools/logs-schema.d.ts

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

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

@@ -20,7 +20,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

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

@@ -20,7 +20,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

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

@@ -30,7 +30,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             maxBytes: {
                 type: string;

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

@@ -33,7 +33,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

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

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

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "4.2.1",
-  "description": "MCP server that lets AI agents build, run, inspect, and publish browser extensions. 28 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, and Firefox.",
+  "version": "4.3.0",
+  "description": "MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex) build, run, inspect, and publish browser extensions. 29 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, and Firefox. Powered by extension.dev and Extension.js.",
+  "mcpName": "io.github.extensiondev/mcp",
   "license": "MIT",
   "author": {
     "name": "Cezar Augusto",
@@ -16,11 +17,10 @@
   "bugs": {
     "url": "https://github.com/extensiondev/mcp/issues"
   },
-  "homepage": "https://github.com/extensiondev/mcp#readme",
+  "homepage": "https://extension.dev",
   "engines": {
     "node": ">=20.18"
   },
-  "packageManager": "pnpm@10.19.0",
   "exports": {
     ".": {
       "types": "./dist/module.d.ts",
@@ -36,25 +36,19 @@
     "dist",
     "bin",
     "claude",
+    ".claude-plugin",
+    "server.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
-  "scripts": {
-    "clean": "rm -rf dist",
-    "watch": "rslib build --watch",
-    "compile": "rslib build",
-    "build": "pnpm run compile",
-    "start": "node bin/extension-mcp.js",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm run test && pnpm run compile"
-  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
     "ai-agent",
     "agents",
@@ -62,14 +56,18 @@
     "claude-code",
     "claude-desktop",
     "cursor",
+    "github-copilot",
+    "codex",
     "browser-extension",
     "chrome-extension",
     "firefox-addon",
+    "edge-extension",
     "manifest-v3",
     "webextension",
     "cross-browser",
     "developer-tools",
-    "extension.dev"
+    "extension.dev",
+    "extension.js"
   ],
   "dependencies": {
     "@extension.dev/core": "^0.2.0",
@@ -87,5 +85,13 @@
     "@types/ws": "^8.18.1",
     "typescript": "6.0.2",
     "vitest": "^4.1.3"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "watch": "rslib build --watch",
+    "compile": "rslib build",
+    "build": "pnpm run compile",
+    "start": "node bin/extension-mcp.js",
+    "test": "vitest run"
   }
-}
+}

package/server.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "name": "io.github.extensiondev/mcp",
+  "description": "Build, run, inspect, and publish browser extensions from any MCP client. 29 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, and Firefox.",
+  "repository": {
+    "url": "https://github.com/extensiondev/mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://extension.dev",
+  "version": "4.3.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@extension.dev/mcp",
+      "version": "4.3.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}