@extension.dev/mcp 4.1.2 → 4.2.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 4.2.0
+
+Session lifecycle + determinism release. Tool count 27 -> 28.
+
+- New tool `extension_stop`: terminates a dev/start/preview session (dev
+  server AND the browser it launched) via a process-group signal with
+  SIGTERM -> SIGKILL escalation. Finds the pid in the in-memory session
+  registry, falling back to the `ready.json` contract when the MCP server
+  restarted since the session began, and removes the stale contract so
+  `extension_wait` cannot report a dead session as ready. Supports
+  `all: true` to stop everything the server started.
+- Sessions self-clean: dev/start/preview register an exit listener so a
+  session that dies on its own is no longer reported as stoppable.
+  `extension_preview` sessions are now registered (and stoppable) too.
+- `extension_create` gains `parentDir`: control where the project lands
+  instead of inheriting the MCP server's working directory. `nextSteps`
+  now reports the full project path.
+- CLI spawns are deterministic: dev/start/preview and the act tools now
+  prefer the project's own `node_modules/.bin/extension`, falling back to
+  `npx extension@<pinned>` where the pin derives from the vendored
+  `extension-develop` version — never a floating `latest`.
+- Session registry keys are path-normalized, so a stop with an absolute
+  path matches a session registered with a relative one.
+- Tests: registry suite now asserts against the exported `tools` array
+  (the old hand-maintained mirror had drifted to 26 while the server
+  registered 27); new stop + CLI-resolution suites (123 tests total).
+
 ## 4.1.2
 
 README: restore the `@extension.dev/skill` pairing section (hands +

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. 27 MCP tools that scaffold, run, inspect, debug, and publish cross-browser extensions.
+> Give your AI agent hands for browser extension development. 28 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%" />
 
@@ -89,6 +89,7 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | run | `extension_start` | Build + preview |
 | run | `extension_preview` | Preview the production build |
 | run | `extension_wait` | Poll the dev-server ready contract |
+| run | `extension_stop` | Stop a dev/start/preview session (server + browser) |
 | see | `extension_manifest_validate` | Cross-browser manifest validation |
 | see | `extension_inspect` | Build output analysis |
 | see | `extension_source_inspect` | Live DOM inspection (CDP) |
@@ -108,12 +109,22 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | platform | `extension_publish` | Publish a shareable preview to extension.dev |
 | platform | `extension_release_promote` | Promote a build to a release channel, headless |
 
-Browser-launching tools (`dev`, `start`, `preview`) shell out to the `extension` CLI; everything else runs in-process.
+Browser-launching tools (`dev`, `start`, `preview`) shell out to the `extension` CLI — the project's own `node_modules/.bin/extension` when present, otherwise `npx extension@<pinned>` at the version this package is verified against; everything else runs in-process.
 
 ## From preview to store
 
 The four platform tools connect agents to [extension.dev](https://extension.dev): `extension_login` runs a GitHub device-code flow and stores a project-scoped token locally (never returned to the agent), `extension_publish` turns a build into a shareable preview URL, and `extension_release_promote` promotes a tested build to a release channel from CI or an agent session, no browser required. To automate store submission itself (Chrome Web Store, Edge Add-ons, Firefox AMO), pair with [`@extension.dev/deploy`](https://www.npmjs.com/package/@extension.dev/deploy).
 
+## The extension.dev stack
+
+| Package | Use it to |
+| --- | --- |
+| [`@extension.dev/skill`](https://www.npmjs.com/package/@extension.dev/skill) | Teach AI agents the judgment half: cross-browser rules, gotchas, playbooks |
+| [`@extension.dev/deploy`](https://www.npmjs.com/package/@extension.dev/deploy) | Ship to Chrome, Firefox, and Edge stores from CI |
+| [`@extension.dev/core`](https://www.npmjs.com/package/@extension.dev/core) | Authenticate and publish to the extension.dev platform |
+
+All of it rides on [Extension.js](https://github.com/extension-js/extension.js), the open-source cross-browser extension framework.
+
 ## Community
 
 - Join the [Discord](https://discord.gg/v9h2RgeTSN) for help and feedback

package/claude/rules/mcp-tools.md

@@ -612,6 +612,47 @@ The `similarTemplates` field lists templates from the catalog with similar surfa
 
 ---
 
+#### `extension_stop`
+
+**Source:** MCP `lib/process-manager` + the `ready.json` contract (no CLI verb)
+
+**Purpose:** Terminate a running dev/start/preview session — the dev server AND the browser it launched. The lifecycle counterpart to `extension_dev`/`extension_start`.
+
+```json
+{
+  "name": "extension_stop",
+  "description": "Stop a running dev, start, or preview session: terminates the dev server and the browser it launched.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "projectPath": {
+        "type": "string",
+        "description": "Path to the extension project root"
+      },
+      "browser": {
+        "type": "string",
+        "default": "chrome",
+        "description": "Browser of the session to stop"
+      },
+      "all": {
+        "type": "boolean",
+        "default": false,
+        "description": "Stop every session this server started"
+      }
+    },
+    "required": []
+  }
+}
+```
+
+**Returns:** `{ projectPath, browser, pid, stopped, detail }` (or `{ stopped: [...] }` with `all: true`).
+
+**How it finds the process:** the in-memory session registry first; if the MCP server restarted since the session began, it falls back to the `pid` recorded in the `ready.json` contract. It signals the whole process group (sessions are spawned detached), escalates SIGTERM → SIGKILL, and removes the stale `ready.json` so a later `extension_wait` cannot report a dead session as ready.
+
+**Why this matters for MCP:** without a stop tool, every `extension_dev` call leaks a dev server and a browser window that outlive the agent's task. Agents should stop sessions when verification is done.
+
+---
+
 ### Tier 3 — Browser management tools
 
 #### `extension_install_browser`
@@ -721,6 +762,7 @@ The `similarTemplates` field lists templates from the catalog with similar surfa
 | `extension_source_inspect`      | `programs/extension` | CDP client / RDP transport                | Live browser via debugging protocol         | Wire to running session                    |
 | `extension_list_extensions`     | MCP `lib/cdp`        | `Extensions.getExtensionInfo` (read-only) | Live browser via CDP (Chromium)             | MCP tool (no CLI verb)                      |
 | `extension_wait`                | `programs/extension` | `dev-wait.ts`                             | `ready.json` contract file                  | Thin wrapper (exists in CLI)               |
+| `extension_stop`                | MCP `lib/process-manager` | session registry + group signal      | Session registry + `ready.json` pid         | MCP tool (no CLI verb)                      |
 | `extension_add_feature`         | New                  | `extension_get_template_source`           | examples repo patterns                      | Codegen from examples                      |
 | **Agent bridge — act / triggers** |                    |                                           |                                             |                                            |
 | `extension_eval`                | `programs/extension` | bridge control channel                    | Live extension context                      | Wraps `extension eval` (`--allow-eval`)     |

package/dist/module.js

@@ -2,15 +2,15 @@ import { __webpack_require__ } from "./rslib-runtime.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import node_path, { join } from "node:path";
 import { extensionCreate } from "extension-create";
 import node_fs, { existsSync, readdirSync, statSync } from "node:fs";
-import node_path, { join } from "node:path";
 import node_os from "node:os";
 import { extensionBuild } from "extension-develop";
 import cross_spawn from "cross-spawn";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
-import node_net from "node:net";
 import ws from "ws";
+import node_http from "node:http";
 import { clearCredentials, exchangeAndPersist, fetchLoginConfig, pollForToken, publish, readCredentials, resolveApiBase, resolveToken, safeApiBase, startDeviceCode } from "@extension.dev/core";
 import { extensionInstall, getManagedBrowsersCacheRoot } from "extension-install";
 import { execFile } from "node:child_process";
@@ -31,7 +31,7 @@ var create_namespaceObject = {};
 __webpack_require__.r(create_namespaceObject);
 __webpack_require__.d(create_namespaceObject, {
     handler: ()=>create_handler,
-    schema: ()=>schema
+    schema: ()=>create_schema
 });
 var detect_browsers_namespaceObject = {};
 __webpack_require__.r(detect_browsers_namespaceObject);
@@ -159,6 +159,12 @@ __webpack_require__.d(start_namespaceObject, {
     handler: ()=>start_handler,
     schema: ()=>start_schema
 });
+var stop_namespaceObject = {};
+__webpack_require__.r(stop_namespaceObject);
+__webpack_require__.d(stop_namespaceObject, {
+    handler: ()=>stop_handler,
+    schema: ()=>stop_schema
+});
 var storage_namespaceObject = {};
 __webpack_require__.r(storage_namespaceObject);
 __webpack_require__.d(storage_namespaceObject, {
@@ -177,10 +183,8 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = {
-    rE: "4.1.2"
-};
-const schema = {
+var package_namespaceObject = JSON.parse('{"rE":"4.2.1","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.",
     inputSchema: {
@@ -190,6 +194,10 @@ const schema = {
                 type: "string",
                 description: "Name of the extension project (used as directory name)"
             },
+            parentDir: {
+                type: "string",
+                description: "Directory to create the project inside. Defaults to the MCP server's working directory, which may not be where you expect — pass this explicitly when you care where the project lands."
+            },
             template: {
                 type: "string",
                 default: "typescript",
@@ -208,8 +216,9 @@ const schema = {
 };
 async function create_handler(args) {
     const start = Date.now();
+    const projectInput = args.parentDir ? node_path.resolve(args.parentDir, args.projectName) : args.projectName;
     try {
-        const result = await extensionCreate(args.projectName, {
+        const result = await extensionCreate(projectInput, {
             template: args.template ?? "typescript",
             install: args.install ?? true,
             logger: {
@@ -224,7 +233,7 @@ async function create_handler(args) {
             depsInstalled: result.depsInstalled,
             duration: Date.now() - start,
             nextSteps: [
-                `cd ${result.projectName}`,
+                `cd ${result.projectPath}`,
                 "npm run dev"
             ]
         });
@@ -392,7 +401,8 @@ async function build_handler(args) {
         const summary = await extensionBuild(args.projectPath, {
             browser: args.browser ?? "chrome",
             zip: args.zip ?? false,
-            zipSource: args.zipSource ?? false
+            zipSource: args.zipSource ?? false,
+            exitOnError: false
         });
         return JSON.stringify({
             success: true,
@@ -407,10 +417,34 @@ async function build_handler(args) {
         });
     }
 }
+const PINNED_CLI_VERSION = String(package_namespaceObject.El.OP ?? "latest").replace(/^[\^~]/, "");
+function pinnedCliVersion() {
+    const override = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
+    return override || PINNED_CLI_VERSION;
+}
+function resolveExtensionInvocation(projectDir) {
+    if (projectDir) {
+        const bin = node_path.join(projectDir, "node_modules", ".bin", "win32" === process.platform ? "extension.cmd" : "extension");
+        try {
+            node_fs.accessSync(bin, node_fs.constants.X_OK);
+            return {
+                command: bin,
+                prefixArgs: []
+            };
+        } catch  {}
+    }
+    return {
+        command: "npx",
+        prefixArgs: [
+            `extension@${pinnedCliVersion()}`
+        ]
+    };
+}
 function runExtensionCli(args, options) {
+    const { command, prefixArgs } = resolveExtensionInvocation(options?.cwd);
     return new Promise((resolve)=>{
-        const child = cross_spawn("npx", [
-            "extension",
+        const child = cross_spawn(command, [
+            ...prefixArgs,
             ...args
         ], {
             cwd: options?.cwd,
@@ -443,8 +477,9 @@ function runExtensionCli(args, options) {
     });
 }
 function spawnExtensionCli(args, options) {
-    const child = cross_spawn("npx", [
-        "extension",
+    const { command, prefixArgs } = resolveExtensionInvocation(options?.projectDir ?? options?.cwd);
+    const child = cross_spawn(command, [
+        ...prefixArgs,
         ...args
     ], {
         cwd: options?.cwd,
@@ -463,12 +498,21 @@ function spawnExtensionCli(args, options) {
     child.unref();
     return child;
 }
-const sessions = new Map();
+const process_manager_sessions = new Map();
 function sessionKey(projectPath, browser) {
-    return `${projectPath}::${browser}`;
+    return `${node_path.resolve(projectPath)}::${browser}`;
 }
 function registerSession(info) {
-    sessions.set(sessionKey(info.projectPath, info.browser), info);
+    process_manager_sessions.set(sessionKey(info.projectPath, info.browser), info);
+}
+function getSession(projectPath, browser) {
+    return process_manager_sessions.get(sessionKey(projectPath, browser));
+}
+function removeSession(projectPath, browser) {
+    process_manager_sessions.delete(sessionKey(projectPath, browser));
+}
+function listSessions() {
+    return Array.from(process_manager_sessions.values());
 }
 const dev_schema = {
     name: "extension_dev",
@@ -528,7 +572,9 @@ async function dev_handler(args) {
     if (args.noBrowser) cliArgs.push("--no-browser");
     if (args.allowControl) cliArgs.push("--allow-control");
     if (args.allowEval) cliArgs.push("--allow-eval");
-    const child = spawnExtensionCli(cliArgs);
+    const child = spawnExtensionCli(cliArgs, {
+        projectDir: args.projectPath
+    });
     const pid = child.pid;
     registerSession({
         pid,
@@ -537,6 +583,7 @@ async function dev_handler(args) {
         projectPath: args.projectPath,
         command: "dev"
     });
+    child.on("exit", ()=>removeSession(args.projectPath, browser));
     let earlyOutput = "";
     const collector = (data)=>{
         earlyOutput += data.toString();
@@ -552,7 +599,7 @@ async function dev_handler(args) {
         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.",
+        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.",
         earlyOutput: earlyOutput.slice(0, 500)
     });
 }
@@ -597,7 +644,9 @@ async function start_handler(args) {
         browser
     ];
     if (false === args.polyfill) cliArgs.push("--no-polyfill");
-    const child = spawnExtensionCli(cliArgs);
+    const child = spawnExtensionCli(cliArgs, {
+        projectDir: args.projectPath
+    });
     const pid = child.pid;
     registerSession({
         pid,
@@ -605,6 +654,7 @@ async function start_handler(args) {
         projectPath: args.projectPath,
         command: "start"
     });
+    child.on("exit", ()=>removeSession(args.projectPath, browser));
     let earlyOutput = "";
     const collector = (data)=>{
         earlyOutput += data.toString();
@@ -619,7 +669,7 @@ async function start_handler(args) {
         browser,
         projectPath: args.projectPath,
         status: "started",
-        hint: "Use extension_wait to check when the build and browser launch are complete.",
+        hint: "Use extension_wait to check when the build and browser launch are complete. When you are done, call extension_stop to shut down the session.",
         earlyOutput: earlyOutput.slice(0, 500)
     });
 }
@@ -658,13 +708,134 @@ async function preview_handler(args) {
         "--browser",
         browser
     ];
-    const child = spawnExtensionCli(cliArgs);
+    const child = spawnExtensionCli(cliArgs, {
+        projectDir: args.projectPath
+    });
+    const pid = child.pid;
+    registerSession({
+        pid,
+        browser,
+        projectPath: args.projectPath,
+        command: "preview"
+    });
+    child.on("exit", ()=>removeSession(args.projectPath, browser));
     return JSON.stringify({
-        pid: child.pid,
+        pid,
         browser,
         projectPath: args.projectPath,
-        status: "launched"
+        status: "launched",
+        hint: "Call extension_stop when you are done to close the preview browser."
+    });
+}
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            projectPath: {
+                type: "string",
+                description: "Path to the extension project root"
+            },
+            browser: {
+                type: "string",
+                default: "chrome",
+                description: "Browser of the session to stop (matches the browser passed to extension_dev/extension_start)"
+            },
+            all: {
+                type: "boolean",
+                default: false,
+                description: "Stop every session this server started, across projects and browsers. When true, projectPath/browser are ignored."
+            }
+        },
+        required: []
+    }
+};
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function signal(pid, sig) {
+    try {
+        process.kill(-pid, sig);
+        return true;
+    } catch  {
+        try {
+            process.kill(pid, sig);
+            return true;
+        } catch  {
+            return false;
+        }
+    }
+}
+function readyJsonPath(projectPath, browser) {
+    return node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+}
+function pidFromReadyContract(projectPath, browser) {
+    try {
+        const raw = node_fs.readFileSync(readyJsonPath(projectPath, browser), "utf8");
+        const contract = JSON.parse(raw);
+        return "number" == typeof contract.pid ? contract.pid : null;
+    } catch  {
+        return null;
+    }
+}
+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)."
+    };
+    let detail;
+    if (isAlive(pid)) {
+        signal(pid, "SIGTERM");
+        await new Promise((resolve)=>setTimeout(resolve, 1500));
+        if (isAlive(pid)) {
+            signal(pid, "SIGKILL");
+            await new Promise((resolve)=>setTimeout(resolve, 250));
+        }
+        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.";
+    removeSession(projectPath, browser);
+    try {
+        node_fs.rmSync(readyJsonPath(projectPath, browser), {
+            force: true
+        });
+    } catch  {}
+    return {
+        projectPath,
+        browser,
+        pid,
+        stopped: !isAlive(pid),
+        detail
+    };
+}
+async function stop_handler(args) {
+    if (args.all) {
+        const sessions = listSessions();
+        if (0 === sessions.length) return JSON.stringify({
+            stopped: [],
+            message: "No sessions registered in this server."
+        });
+        const outcomes = [];
+        for (const s of sessions)outcomes.push(await stopOne(s.projectPath, s.browser));
+        return JSON.stringify({
+            stopped: outcomes
+        });
+    }
+    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");
+    return JSON.stringify(outcome);
 }
 const RAW_BASE = "https://raw.githubusercontent.com/extension-js/examples/main/examples";
 const get_template_source_schema = {
@@ -1405,6 +1576,50 @@ class CDPClient extends CDPConnection {
         return result ?? null;
     }
 }
+async function resolveCdpPort(projectPath, browser, options) {
+    const waitMs = options?.waitMs ?? 20000;
+    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+    const deadline = Date.now() + waitMs;
+    let contractSeen = false;
+    for(;;){
+        try {
+            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+            contractSeen = true;
+            if ("number" == typeof contract.cdpPort) return {
+                port: contract.cdpPort,
+                source: "contract"
+            };
+        } catch  {
+            if (!contractSeen) break;
+        }
+        if (Date.now() >= deadline) break;
+        await new Promise((resolve)=>setTimeout(resolve, 500));
+    }
+    if (!contractSeen && await isCdpEndpoint(9222)) return {
+        port: 9222,
+        source: "default-probe"
+    };
+    return null;
+}
+const CDP_PORT_MISSING_HINT = "The session's ready contract has no CDP port (the browser may still be binding its debug port, or was launched without one). Confirm the session with extension_wait, give it a moment, and retry.";
+function isCdpEndpoint(port) {
+    return new Promise((resolve)=>{
+        const req = node_http.get({
+            host: "127.0.0.1",
+            port,
+            path: "/json/version",
+            timeout: 1000
+        }, (res)=>{
+            res.resume();
+            resolve(200 === res.statusCode);
+        });
+        req.on("error", ()=>resolve(false));
+        req.on("timeout", ()=>{
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
 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.",
@@ -1466,28 +1681,6 @@ const source_inspect_schema = {
         ]
     }
 };
-async function findCdpPort(projectPath, browser) {
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-    try {
-        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-        if ("number" == typeof contract.cdpPort) return contract.cdpPort;
-    } catch  {}
-    const defaultPort = 9222;
-    return new Promise((resolve)=>{
-        const socket = new node_net.Socket();
-        socket.setTimeout(1000);
-        socket.on("connect", ()=>{
-            socket.destroy();
-            resolve(defaultPort);
-        });
-        socket.on("error", ()=>resolve(null));
-        socket.on("timeout", ()=>{
-            socket.destroy();
-            resolve(null);
-        });
-        socket.connect(defaultPort, "127.0.0.1");
-    });
-}
 async function source_inspect_handler(args) {
     const browser = args.browser ?? "chrome";
     const include = new Set(args.include ?? [
@@ -1505,11 +1698,12 @@ async function source_inspect_handler(args) {
         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"
     });
-    const cdpPort = await findCdpPort(args.projectPath, browser);
-    if (!cdpPort) return JSON.stringify({
+    const resolved = await resolveCdpPort(args.projectPath, browser);
+    if (!resolved) return JSON.stringify({
         error: "No active dev session found. Cannot connect to Chrome DevTools Protocol.",
-        hint: "Start a dev session first with extension_dev, then use extension_wait to confirm it is ready."
+        hint: `Start a dev session first with extension_dev, then use extension_wait to confirm it is ready. ${CDP_PORT_MISSING_HINT}`
     });
+    const cdpPort = resolved.port;
     const cdp = new CDPClient();
     try {
         const allTargets = await CDPClient.discoverTargets(cdpPort);
@@ -1622,16 +1816,27 @@ async function list_extensions_handler(args) {
         error: `Listing extensions for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
         hint: "Use --browser=chrome."
     });
-    const cdpPort = await list_extensions_findCdpPort(args.projectPath, browser);
-    if (!cdpPort) return JSON.stringify({
+    const resolved = await resolveCdpPort(args.projectPath, browser);
+    if (!resolved) return JSON.stringify({
         error: "No active dev session found. Cannot connect to Chrome DevTools Protocol.",
-        hint: "Start a dev session first with extension_dev, then use extension_wait to confirm it is ready."
+        hint: `Start a dev session first with extension_dev, then use extension_wait to confirm it is ready. ${CDP_PORT_MISSING_HINT}`
     });
+    const cdpPort = resolved.port;
     const cdp = new CDPClient();
     try {
-        const browserWsUrl = await CDPClient.discoverBrowserWsUrl(cdpPort);
-        await cdp.connect(browserWsUrl);
-        const targets = await cdp.getTargets();
+        let targets = null;
+        let lastError = null;
+        for(let attempt = 0; attempt < 3; attempt++)try {
+            const browserWsUrl = await CDPClient.discoverBrowserWsUrl(cdpPort);
+            await cdp.connect(browserWsUrl);
+            targets = await cdp.getTargets();
+            break;
+        } catch (error) {
+            lastError = error;
+            cdp.disconnect();
+            if (attempt < 2) await new Promise((resolve)=>setTimeout(resolve, 800));
+        }
+        if (!targets) throw lastError;
         const byId = new Map();
         for (const t of targets){
             const url = String(t.url ?? "");
@@ -1683,28 +1888,6 @@ async function list_extensions_handler(args) {
         cdp.disconnect();
     }
 }
-async function list_extensions_findCdpPort(projectPath, browser) {
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-    try {
-        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-        if ("number" == typeof contract.cdpPort) return contract.cdpPort;
-    } catch  {}
-    const defaultPort = 9222;
-    return new Promise((resolve)=>{
-        const socket = new node_net.Socket();
-        socket.setTimeout(1000);
-        socket.on("connect", ()=>{
-            socket.destroy();
-            resolve(defaultPort);
-        });
-        socket.on("error", ()=>resolve(null));
-        socket.on("timeout", ()=>{
-            socket.destroy();
-            resolve(null);
-        });
-        socket.connect(defaultPort, "127.0.0.1");
-    });
-}
 const CONTROL_WS_PATH = "/extjs-control";
 const LEVEL_ORDER = [
     "error",
@@ -3269,6 +3452,70 @@ 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."
     });
 }
+function typeOf(value) {
+    if (Array.isArray(value)) return "array";
+    if (null === value) return "null";
+    return typeof value;
+}
+function checkPrimitive(path, value, schema, issues) {
+    if (schema.type && [
+        "string",
+        "number",
+        "boolean"
+    ].includes(schema.type)) {
+        if (typeOf(value) !== schema.type) return void issues.push({
+            path,
+            message: `expected ${schema.type}, got ${typeOf(value)}`
+        });
+    }
+    if ("array" === schema.type) {
+        if (!Array.isArray(value)) return void issues.push({
+            path,
+            message: `expected array, got ${typeOf(value)}`
+        });
+        const itemSchema = schema.items;
+        if (itemSchema) value.forEach((item, i)=>checkPrimitive(`${path}[${i}]`, item, itemSchema, issues));
+        return;
+    }
+    if (Array.isArray(schema.enum) && schema.enum.length) {
+        if (!schema.enum.includes(value)) issues.push({
+            path,
+            message: `must be one of: ${schema.enum.map(String).join(", ")}`
+        });
+    }
+}
+function validateToolInput(inputSchema, args) {
+    const schema = inputSchema;
+    const issues = [];
+    const properties = schema.properties ?? {};
+    for (const key of schema.required ?? [])if (void 0 === args[key]) issues.push({
+        path: key,
+        message: "required argument is missing"
+    });
+    for (const [key, value] of Object.entries(args)){
+        const propSchema = properties[key];
+        if (!propSchema) {
+            const known = Object.keys(properties);
+            issues.push({
+                path: key,
+                message: `unknown argument${known.length ? ` (known: ${known.join(", ")})` : ""}`
+            });
+            continue;
+        }
+        if (void 0 !== value) checkPrimitive(key, value, propSchema, issues);
+    }
+    return issues;
+}
+function inputValidationError(toolName, issues) {
+    return JSON.stringify({
+        ok: false,
+        error: {
+            name: "InputValidationError",
+            message: `Invalid arguments for ${toolName}: ${issues.map((i)=>`${i.path}: ${i.message}`).join("; ")}`,
+            issues
+        }
+    });
+}
 const tools = [
     create_namespaceObject,
     list_templates_namespaceObject,
@@ -3276,6 +3523,7 @@ const tools = [
     dev_namespaceObject,
     start_namespaceObject,
     preview_namespaceObject,
+    stop_namespaceObject,
     get_template_source_namespaceObject,
     manifest_validate_namespaceObject,
     inspect_namespaceObject,
@@ -3331,6 +3579,16 @@ async function startServer() {
             ],
             isError: true
         };
+        const issues = validateToolInput(tool.schema.inputSchema, args ?? {});
+        if (issues.length) return {
+            content: [
+                {
+                    type: "text",
+                    text: inputValidationError(name, issues)
+                }
+            ],
+            isError: true
+        };
         try {
             const result = await tool.handler(args ?? {});
             return {

package/dist/src/index.d.ts

@@ -1,3 +1,12 @@
+export interface ToolModule {
+    schema: {
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+    };
+    handler: (args: any) => Promise<string>;
+}
+export declare const tools: ToolModule[];
 export declare function startServer(): Promise<void>;
 /**
  * Human-facing subcommands for `extension-mcp <cmd>`. Unlike the MCP tools

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

@@ -0,0 +1,7 @@
+export declare function resolveCdpPort(projectPath: string, browser: string, options?: {
+    waitMs?: number;
+}): Promise<{
+    port: number;
+    source: "contract" | "default-probe";
+} | null>;
+export declare const CDP_PORT_MISSING_HINT = "The session's ready contract has no CDP port (the browser may still be binding its debug port, or was launched without one). Confirm the session with extension_wait, give it a moment, and retry.";

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

@@ -4,10 +4,26 @@ 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[];
+};
 export declare function runExtensionCli(args: string[], options?: {
     cwd?: string;
     timeoutMs?: number;
 }): Promise<CliResult>;
 export declare function spawnExtensionCli(args: string[], options?: {
     cwd?: string;
+    projectDir?: string;
 }): ChildProcess;

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

@@ -63,6 +63,6 @@ export interface ProcessInfo {
     browser: string;
     port?: number;
     projectPath: string;
-    command: "dev" | "start";
+    command: "dev" | "start" | "preview";
 }
 export type BrowserType = "chrome" | "edge" | "firefox" | "chromium-based" | "gecko-based";

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

@@ -0,0 +1,11 @@
+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/create.d.ts

@@ -8,6 +8,10 @@ export declare const schema: {
                 type: string;
                 description: string;
             };
+            parentDir: {
+                type: string;
+                description: string;
+            };
             template: {
                 type: string;
                 default: string;
@@ -24,6 +28,7 @@ export declare const schema: {
 };
 export declare function handler(args: {
     projectName: string;
+    parentDir?: string;
     template?: string;
     install?: boolean;
 }): Promise<string>;

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

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "4.1.2",
-  "description": "MCP server that lets AI agents build, run, inspect, and publish browser extensions. 27 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, and Firefox.",
+  "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.",
   "license": "MIT",
   "author": {
     "name": "Cezar Augusto",
@@ -20,6 +20,7 @@
   "engines": {
     "node": ">=20.18"
   },
+  "packageManager": "pnpm@10.19.0",
   "exports": {
     ".": {
       "types": "./dist/module.d.ts",
@@ -39,6 +40,15 @@
     "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"
@@ -77,13 +87,5 @@
     "@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"
   }
-}
+}