@extension.dev/mcp 4.2.2 → 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,36 @@
 # 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

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,6 +107,7 @@ 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 |
+| 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 |

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.2","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) {
@@ -1749,13 +1769,7 @@ async function source_inspect_handler(args) {
         "console"
     ]);
     const maxBytes = args.maxBytes ?? 262144;
-    const isChromium = [
-        "chrome",
-        "chromium",
-        "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: 'Pass browser: "chrome" (against a Chromium-family dev session).'
     });
@@ -1868,13 +1882,7 @@ const list_extensions_schema = {
 };
 async function list_extensions_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
-    const isChromium = [
-        "chrome",
-        "chromium",
-        "edge",
-        "chromium-based"
-    ].includes(browser);
-    if (!isChromium) return JSON.stringify({
+    if (!isChromiumFamily(browser)) return JSON.stringify({
         error: `Listing extensions for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
         hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
     });
@@ -3544,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";
@@ -3636,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,26 +1,5 @@
-/**
- * Translate CLI-speak in an error message into the MCP tool surface
- * (fresh-eyes walk, friction #2). The CLI's hints say things like
- * "Run `extension dev --browser=chromium --allow-control` first" — correct
- * for a human at a terminal, a dead end for an agent that only has the MCP
- * tools. Rewrite flags to their tool-argument names so the hint is actionable
- * on the surface the caller is actually using. Result data is never touched —
- * only error/hint prose.
- */
 export declare function toMcpSpeak(text: string): string;
-/**
- * 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.
- * Error PROSE is the one exception: hints are rewritten from CLI flags to MCP
- * tool arguments before returning (see toMcpSpeak).
- */
 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;
@@ -29,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

@@ -2,6 +2,5 @@ export interface ResolvedBrowser {
     browser: string;
     source: "explicit" | "session" | "contract" | "fallback";
 }
-/** Browsers with a live session for this project (registry + disk contracts). */
 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/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "4.2.2",
-  "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,7 +17,7 @@
   "bugs": {
     "url": "https://github.com/extensiondev/mcp/issues"
   },
-  "homepage": "https://github.com/extensiondev/mcp#readme",
+  "homepage": "https://extension.dev",
   "engines": {
     "node": ">=20.18"
   },
@@ -35,6 +36,8 @@
     "dist",
     "bin",
     "claude",
+    ".claude-plugin",
+    "server.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -45,6 +48,7 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
     "ai-agent",
     "agents",
@@ -52,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",

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"
+      }
+    }
+  ]
+}