chrome-extension-tester-mcp 2.1.0 → 2.3.0

package/README.md

@@ -6,6 +6,8 @@ An **MCP (Model Context Protocol) server** that lets Claude interactively test a
 
 ## Table of Contents
 
+- [Why](#why)
+- [Architecture](#architecture)
 - [Features](#features)
 - [Requirements](#requirements)
 - [Installation](#installation)
@@ -13,12 +15,31 @@ An **MCP (Model Context Protocol) server** that lets Claude interactively test a
 - [Setup with Claude Code (npx)](#setup-with-claude-code-npx)
 - [Available Tools](#available-tools)
 - [Testing Agent Prompt](#testing-agent-prompt)
+- [Example: testing an extension popup](#example-testing-an-extension-popup)
 - [Example Prompts](#example-prompts)
 - [Project Structure](#project-structure)
 - [Notes](#notes)
 
 ---
 
+## Why
+
+Testing a Chrome extension during development means manually clicking reload, opening the popup, checking storage in DevTools, watching the service worker console, and copy-pasting errors back to the agent on every iteration. This MCP server gives an AI coding agent direct access to all of that through tool calls, so the agent can iterate on its own. It exists because the manual loop made working with Claude Code on extensions too slow.
+
+---
+
+## Architecture
+
+```mermaid
+graph LR
+    A[AI Agent<br/>Claude / Cursor] -->|MCP protocol| B[This server<br/>14 tools]
+    B -->|Playwright| C[Chromium<br/>persistent context]
+    C -->|loads| D[Extension under test]
+    B -.->|reads / writes| E[(state.js<br/>browser, page, extensionId)]
+```
+
+---
+
 ## Features
 
 - Load and reload any unpacked Chrome extension
@@ -142,6 +163,76 @@ Add to your project's `.mcp.json` or user-level MCP config:
 | `simulate_tab_events` | Open, close, switch, list, or close all browser tabs |
 | `test_account_login` | Create or reuse a test account on any website using a disposable email; credentials are stored in `test-accounts.json` and reused across sessions |
 
+### `load_extension`
+Launch Chromium with an unpacked extension and capture its ID.
+**Inputs:** `extension_path` (string, required) — path to the unpacked extension folder.
+**Returns:** Text confirming the resolved path and the detected extension ID.
+
+### `interact_with_popup`
+Open the popup and click, type, or read its DOM.
+**Inputs:** `action` (string, required: `open` | `click` | `type` | `get_text` | `get_html`); `selector` (string); `value` (string, for `type`).
+**Returns:** Text describing the action result, or the requested text/HTML.
+
+### `open_options_page`
+Open the options page (or any extension page) and interact with it.
+**Inputs:** `page` (string, default `options.html`); `action` (string: `open` | `click` | `type` | `get_text` | `get_html`); `selector` (string); `value` (string).
+**Returns:** Text describing the action result, or the requested text/HTML.
+
+### `inspect_dom`
+Query a selector or evaluate JS in a page, optionally navigating first.
+**Inputs:** `url` (string); `selector` (string); `script` (string, overrides `selector`).
+**Returns:** Text with matched elements' outerHTML, or the JSON-serialized script result.
+
+### `get_service_worker_logs`
+Read buffered background service worker console logs.
+**Inputs:** `clear_after` (boolean, default `false`).
+**Returns:** Text listing captured log entries, or a "none captured yet" message.
+
+### `take_screenshot`
+Save a screenshot of the current page or popup.
+**Inputs:** `output_path` (string, default `./screenshot.png`); `full_page` (boolean, default `false`).
+**Returns:** Text with the saved file path.
+
+### `run_assertion`
+Assert an element exists/has text, or that a JS expression is truthy.
+**Inputs:** `description` (string, required); `selector` (string); `expected_text` (string); `script` (string, overrides `selector`).
+**Returns:** Text beginning with `PASS` or `FAIL`, followed by detail.
+
+### `extension_storage`
+Read from or write to `chrome.storage` (local / sync / session).
+**Inputs:** `action` (string, required: `get` | `set` | `remove` | `clear`); `area` (string, default `local`); `keys` (string[]); `data` (object, for `set`).
+**Returns:** Text with storage contents, or a confirmation of the write/removal.
+
+### `monitor_network`
+Capture and inspect network requests during navigation.
+**Inputs:** `action` (string, required: `navigate_and_capture` | `get_captured` | `clear`); `url` (string); `filter_pattern` (string); `include_types` (string[]).
+**Returns:** Text listing captured requests as `[method] [type] status url`.
+
+### `check_badge`
+Read or assert the action badge text and background color.
+**Inputs:** `action` (string, required: `get` | `assert_text` | `assert_color`); `tab_id` (number); `expected_text` (string); `expected_color` (number[] RGBA).
+**Returns:** Text with the badge value, or a `PASS` / `FAIL` assertion result.
+
+### `send_message_to_background`
+Send `chrome.runtime.sendMessage` from the popup and return the response.
+**Inputs:** `message` (object, required); `timeout_ms` (number, default `5000`).
+**Returns:** Text with the sent message and JSON response, or a failure message.
+
+### `test_context_menu`
+Check the `contextMenus` API, simulate a right-click, or trigger an item.
+**Inputs:** `action` (string, required: `check_api` | `right_click` | `trigger_item`); `url` (string); `selector` (string); `menu_item_id` (string); `page_url` (string).
+**Returns:** Text with API availability, dispatch confirmation, or trigger result.
+
+### `simulate_tab_events`
+Open, close, switch, list, or close all browser tabs.
+**Inputs:** `action` (string, required: `open` | `close` | `switch` | `list` | `close_all`); `url` (string); `tab_index` (number).
+**Returns:** Text describing the affected tab(s), or the list of open tabs.
+
+### `test_account_login`
+Create or reuse a test account on a site using a disposable email.
+**Inputs:** `action` (string, required: `auto` | `create` | `login`); `account_key` (string, required); `signup_url` / `login_url` (string); selector overrides (`email_selector`, `password_selector`, `submit_selector`, `pre_click_selector`); multi-step fields (`step2_url`, `step2_password_selector`, `step2_submit_selector`).
+**Returns:** Text reporting account creation/login status plus a screenshot path.
+
 ---
 
 ## Testing Agent Prompt
@@ -178,6 +269,52 @@ Claude will write the test plan, execute every test, and return a full report.
 
 ---
 
+## Example: testing an extension popup
+
+A typical loop the agent can run on its own:
+
+**1. Load the extension**
+
+```json
+{ "tool": "load_extension", "arguments": { "extension_path": "/tmp/my-extension" } }
+```
+
+```
+Extension loaded.
+Path: /tmp/my-extension
+Extension ID: ddnjmkpjnchafihagpljebmkdpejhaoj
+```
+
+**2. Open the popup and read its HTML**
+
+```json
+{ "tool": "interact_with_popup", "arguments": { "action": "open" } }
+```
+
+```html
+<body>
+  <h1>Tab Saver</h1>
+  <button id="save">Save open tabs</button>
+  <span id="count">0 saved</span>
+</body>
+```
+
+**3. Read local storage**
+
+```json
+{ "tool": "extension_storage", "arguments": { "action": "get", "area": "local" } }
+```
+
+```json
+storage.local contents:
+{
+  "savedTabs": [],
+  "enabled": true
+}
+```
+
+---
+
 ## Example Prompts
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chrome-extension-tester-mcp",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "MCP server for interactive Chrome extension testing via Playwright — load, interact, assert, inspect storage, network, badges, messaging, tabs, and more.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -7,11 +7,16 @@ import {
   ListPromptsRequestSchema,
   GetPromptRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "fs";
 import { TOOLS, HANDLERS } from "./tools/index.js";
 import { PROMPTS, PROMPT_HANDLERS } from "./prompts/index.js";
 
+// Read the version from package.json so it never drifts from the published value.
+const packageJsonUrl = new URL("../package.json", import.meta.url);
+const pkg = JSON.parse(readFileSync(packageJsonUrl, "utf-8"));
+
 const server = new Server(
-  { name: "chrome-extension-tester", version: "2.0.0" },
+  { name: "chrome-extension-tester", version: pkg.version },
   { capabilities: { tools: {}, prompts: {} } }
 );
 
@@ -64,4 +69,4 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("Chrome Extension Tester MCP server running (v2.0.0)...");
+console.error(`Chrome Extension Tester MCP server running (v${pkg.version})...`);

package/src/state.js

@@ -4,6 +4,10 @@ import path from "path";
 
 export const state = {
   browser: null,
+  // BrowserContext when connected via CDP (browser.contexts()[0]); null when using launchPersistentContext
+  context: null,
+  // "launched" = Playwright owns the browser process; "cdp" = attached to user's real browser
+  connectionMode: null,
   page: null,
   extensionId: null,
   swLogs: [],
@@ -23,21 +27,27 @@ export async function ensureBrowser(extensionPath) {
     ],
   });
 
-  await new Promise((r) => setTimeout(r, 1000));
-  const workers = state.browser.serviceWorkers();
-  if (workers.length > 0) {
-    const url = workers[0].url();
-    const match = url.match(/chrome-extension:\/\/([a-z]{32})\//);
-    if (match) state.extensionId = match[1];
+  // Prefer an already-registered service worker; otherwise wait for one to register.
+  const existingWorkers = state.browser.serviceWorkers();
+  let workerUrl = existingWorkers.length > 0 ? existingWorkers[0].url() : null;
+
+  if (!workerUrl) {
+    const worker = await state.browser.waitForEvent("serviceworker", { timeout: 5000 });
+    workerUrl = worker.url();
   }
 
+  const extensionIdMatch = workerUrl.match(/chrome-extension:\/\/([a-z]{32})\//);
+  if (extensionIdMatch) state.extensionId = extensionIdMatch[1];
+
+  state.connectionMode = "launched";
   state.page = await state.browser.newPage();
 }
 
 export async function ensurePage() {
   if (!state.page || state.page.isClosed()) {
-    if (!state.browser) throw new Error("Browser not started. Call load_extension first.");
-    state.page = await state.browser.newPage();
+    const ctx = state.context || state.browser;
+    if (!ctx) throw new Error("No browser connected. Call load_extension or connect_browser first.");
+    state.page = await ctx.newPage();
   }
   return state.page;
 }
@@ -51,19 +61,34 @@ export async function ensurePageStandalone() {
     state.browser = await chromium.launchPersistentContext("", {
       headless: false,
     });
+    state.connectionMode = "launched";
     state.page = await state.browser.newPage();
   }
 
   if (!state.page || state.page.isClosed()) {
-    state.page = await state.browser.newPage();
+    const ctx = state.context || state.browser;
+    state.page = await ctx.newPage();
   }
 
   return state.page;
 }
 
 export async function getServiceWorker() {
-  if (!state.browser) throw new Error("Browser not started. Call load_extension first.");
-  const workers = state.browser.serviceWorkers();
+  const ctx = state.context || state.browser;
+  if (!ctx) throw new Error("No browser connected. Call load_extension or connect_browser first.");
+  const workers = ctx.serviceWorkers();
+
+  if (state.extensionId) {
+    const targetWorker = workers.find((w) => w.url().includes(state.extensionId));
+    if (targetWorker) return targetWorker;
+    const workerList = workers.map((w) => `  ${w.url()}`).join("\n") || "  (none)";
+    throw new Error(
+      `No service worker found for extension ${state.extensionId}.\n` +
+      `Active workers:\n${workerList}\n` +
+      `Re-run connect_browser with the correct extension_id to retarget.`
+    );
+  }
+
   if (!workers.length) throw new Error("No service worker found. Extension may not have a background service worker.");
   return workers[0];
 }

package/src/tools/account-login.js

@@ -427,7 +427,7 @@ function buildCredentialEntry(email, password, args, verified, verifiedAt, verif
 export const definition = {
   name: "test_account_login",
   description:
-    "Create or reuse a test account for a website using a disposable email from temp-mail.org. " +
+    "Create or reuse a test account for a website using a disposable email from Guerrilla Mail. " +
     "Credentials are stored in test-accounts.json and reused across test sessions. " +
     "Use action='auto' to login if credentials exist or create new ones if they don't.",
   inputSchema: {
@@ -509,6 +509,7 @@ export async function handler(args) {
             `No stored credentials found for "${key}". ` +
             `Use action: "create" or "auto" to create an account first.`,
         }],
+        isError: true,
       };
     }
 
@@ -521,6 +522,7 @@ export async function handler(args) {
             `No login_url provided and none stored for "${key}". ` +
             `Pass login_url as an argument.`,
         }],
+        isError: true,
       };
     }
 
@@ -545,6 +547,7 @@ export async function handler(args) {
             `Login form interaction failed for "${key}": ${formError.message}\n` +
             `Screenshot: ${screenshotPath}`,
         }],
+        isError: true,
       };
     }
 
@@ -576,6 +579,7 @@ export async function handler(args) {
             `Use action: "create" to generate a new account.\n` +
             `Screenshot: ${screenshotPath}`,
         }],
+        isError: true,
       };
     }
 
@@ -586,7 +590,7 @@ export async function handler(args) {
           type: "text",
           text:
             `Logged in but the site is asking for email verification.\n` +
-            `Navigate to temp-mail.org to find and click the verification link.\n` +
+            `Navigate to Guerrilla Mail to find and click the verification link.\n` +
             `Screenshot: ${screenshotPath}`,
         }],
       };
@@ -608,6 +612,7 @@ export async function handler(args) {
           type: "text",
           text: `signup_url is required when action is "${args.action}".`,
         }],
+        isError: true,
       };
     }
 
@@ -620,5 +625,6 @@ export async function handler(args) {
       type: "text",
       text: `Unknown action: "${args.action}". Valid values are "auto", "create", or "login".`,
     }],
+    isError: true,
   };
 }

package/src/tools/assertion.js

@@ -50,7 +50,7 @@ export async function handler(args) {
         detail = `Element "${args.selector}" exists`;
       }
     } else {
-      return { content: [{ type: "text", text: "Provide a selector or script for the assertion." }] };
+      return { content: [{ type: "text", text: "Provide a selector or script for the assertion." }], isError: true };
     }
   } catch (e) {
     passed = false;

package/src/tools/badge.js

@@ -46,7 +46,7 @@ export async function handler(args) {
     return {
       content: [{
         type: "text",
-        text: `Badge Text: "${badge.text || "(empty)"}\nBadge Color (RGBA): [${badge.color.join(", ")}]`,
+        text: `Badge Text: "${badge.text || "(empty)"}"\nBadge Color (RGBA): [${badge.color.join(", ")}]`,
       }],
     };
   }
@@ -63,7 +63,7 @@ export async function handler(args) {
 
   if (args.action === "assert_color") {
     if (!args.expected_color?.length) {
-      return { content: [{ type: "text", text: "Provide an 'expected_color' RGBA array for assert_color." }] };
+      return { content: [{ type: "text", text: "Provide an 'expected_color' RGBA array for assert_color." }], isError: true };
     }
     const passed = args.expected_color.every((v, i) => v === badge.color[i]);
     return {

package/src/tools/connect-browser.js

@@ -0,0 +1,423 @@
+import { spawn } from "child_process";
+import os from "os";
+import fs from "fs";
+import { chromium } from "playwright";
+import { state } from "../state.js";
+
+const DEBUG_PORT_RANGE_START = 9222;
+const DEBUG_PORT_RANGE_END = 9231;
+const LAUNCH_TIMEOUT_MS = 15000;
+const POLL_INTERVAL_MS = 500;
+
+const KNOWN_BROWSERS = [
+  {
+    name: "Brave",
+    executable: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+    userDataDir: `${os.homedir()}/Library/Application Support/BraveSoftware/Brave-Browser`,
+    extensionsDir: `${os.homedir()}/Library/Application Support/BraveSoftware/Brave-Browser/Default/Extensions`,
+  },
+  {
+    name: "Chrome",
+    executable: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    userDataDir: `${os.homedir()}/Library/Application Support/Google/Chrome`,
+    extensionsDir: `${os.homedir()}/Library/Application Support/Google/Chrome/Default/Extensions`,
+  },
+  {
+    name: "Chromium",
+    executable: "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    userDataDir: `${os.homedir()}/Library/Application Support/Chromium`,
+    extensionsDir: `${os.homedir()}/Library/Application Support/Chromium/Default/Extensions`,
+  },
+];
+
+function readExtensionManifest(extensionsDir, extensionId) {
+  try {
+    const versionDirs = fs.readdirSync(`${extensionsDir}/${extensionId}`);
+    for (const version of versionDirs) {
+      const manifestPath = `${extensionsDir}/${extensionId}/${version}/manifest.json`;
+      if (fs.existsSync(manifestPath)) {
+        return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function listInstalledExtensions(extensionsDir) {
+  if (!fs.existsSync(extensionsDir)) return [];
+  const ids = fs.readdirSync(extensionsDir).filter((d) => /^[a-z]{32}$/.test(d));
+  return ids.map((id) => {
+    const manifest = readExtensionManifest(extensionsDir, id);
+    const name = manifest?.name || "(unknown)";
+    return { id, name };
+  });
+}
+
+// Accepts a 32-char extension ID or a name substring; returns the resolved ID or throws on ambiguity.
+function resolveExtensionId(nameOrId, extensionsDir) {
+  if (/^[a-z]{32}$/.test(nameOrId)) return nameOrId;
+  const extensions = listInstalledExtensions(extensionsDir);
+  const needle = nameOrId.toLowerCase();
+  const matches = extensions.filter((e) => e.name.toLowerCase().includes(needle));
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    const list = matches.map((e) => `  ${e.id}  ${e.name}`).join("\n");
+    throw new Error(`"${nameOrId}" matched ${matches.length} extensions — pass the full ID instead:\n${list}`);
+  }
+  return matches[0].id;
+}
+
+async function fetchCdpVersionInfo(port) {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 800);
+    const response = await fetch(`http://localhost:${port}/json/version`, {
+      signal: controller.signal,
+    });
+    clearTimeout(timeoutId);
+    if (response.ok) return await response.json();
+  } catch {}
+  return null;
+}
+
+async function fetchCdpTargets(port) {
+  try {
+    const response = await fetch(`http://localhost:${port}/json`);
+    if (response.ok) return await response.json();
+  } catch {}
+  return [];
+}
+
+async function scanRunningBrowsers() {
+  const results = [];
+  for (let port = DEBUG_PORT_RANGE_START; port <= DEBUG_PORT_RANGE_END; port++) {
+    const info = await fetchCdpVersionInfo(port);
+    if (info) {
+      results.push({ port, browser: info.Browser });
+    }
+  }
+  return results;
+}
+
+function detectInstalledBrowsers() {
+  return KNOWN_BROWSERS.filter((b) => fs.existsSync(b.executable));
+}
+
+function extractExtensionIdFromUrl(url) {
+  const match = url?.match(/chrome-extension:\/\/([a-z]{32})\//);
+  return match ? match[1] : null;
+}
+
+function findExtensionIdFromWorkers(workers) {
+  for (const worker of workers) {
+    const id = extractExtensionIdFromUrl(worker.url());
+    if (id) return id;
+  }
+  return null;
+}
+
+async function findExtensionIdFromTargets(port) {
+  const targets = await fetchCdpTargets(port);
+  for (const target of targets) {
+    const id = extractExtensionIdFromUrl(target.url);
+    if (id) return id;
+  }
+  return null;
+}
+
+function attachSwLogListeners(context) {
+  const attachToWorker = (sw) => {
+    sw.on("console", (msg) => {
+      // Check state.extensionId at capture time so retargeting takes effect immediately.
+      const workerExtId = extractExtensionIdFromUrl(sw.url());
+      if (!state.extensionId || workerExtId === state.extensionId) {
+        state.swLogs.push(`[${new Date().toISOString()}] ${msg.type()}: ${msg.text()}`);
+      }
+    });
+  };
+
+  context.serviceWorkers().forEach(attachToWorker);
+  context.on("serviceworker", attachToWorker);
+}
+
+export async function teardownExistingConnection() {
+  if (!state.browser) return;
+  try {
+    await state.browser.close();
+  } catch {}
+  state.browser = null;
+  state.context = null;
+  state.page = null;
+  state.extensionId = null;
+  state.connectionMode = null;
+  state.swLogs.length = 0;
+  state.networkCaptures.length = 0;
+}
+
+async function connectToDebugPort(port) {
+  const endpoint = `http://localhost:${port}`;
+  const browser = await chromium.connectOverCDP(endpoint);
+
+  const contexts = browser.contexts();
+  const context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+
+  const swWorkers = context.serviceWorkers();
+  let extensionId = findExtensionIdFromWorkers(swWorkers);
+  if (!extensionId) {
+    extensionId = await findExtensionIdFromTargets(port);
+  }
+
+  const openPages = context.pages();
+  const page = openPages.length > 0 ? openPages[openPages.length - 1] : await context.newPage();
+
+  state.browser = browser;
+  state.context = context;
+  state.page = page;
+  state.extensionId = extensionId;
+  state.connectionMode = "cdp";
+
+  attachSwLogListeners(context);
+
+  return extensionId;
+}
+
+async function pollUntilCdpReady(port) {
+  const deadline = Date.now() + LAUNCH_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const info = await fetchCdpVersionInfo(port);
+    if (info) return true;
+    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+  }
+  return false;
+}
+
+async function launchBrowserProcess(browserConfig, port) {
+  const launchArgs = [
+    `--remote-debugging-port=${port}`,
+    `--user-data-dir=${browserConfig.userDataDir}`,
+    "--no-first-run",
+    "--no-default-browser-check",
+  ];
+
+  const child = spawn(browserConfig.executable, launchArgs, {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+
+  const ready = await pollUntilCdpReady(port);
+  if (!ready) {
+    throw new Error(
+      `${browserConfig.name} did not expose debugging on port ${port} within ${LAUNCH_TIMEOUT_MS}ms. ` +
+      `If ${browserConfig.name} is already running with the same profile, close it first and try again.`
+    );
+  }
+}
+
+export const definition = {
+  name: "connect_browser",
+  description:
+    "Connect to an existing Brave/Chrome/Chromium browser using your real logged-in sessions. " +
+    "Use action 'scan' first to see what's available, then 'connect' to attach to a running browser " +
+    "or 'launch' to start one with debugging enabled. Your logins and tabs are preserved.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["scan", "connect", "launch", "list_extensions"],
+        description:
+          "'scan' — list running debuggable browsers and installed browsers. " +
+          "'connect' — attach to a browser already running with --remote-debugging-port. " +
+          "'launch' — start an installed browser with your real profile and remote debugging, then connect. " +
+          "'list_extensions' — list all installed extensions with their IDs and names.",
+      },
+      port: {
+        type: "number",
+        description: "CDP debug port to connect to (for 'connect' action). Defaults to 9222.",
+      },
+      browser_name: {
+        type: "string",
+        enum: ["Brave", "Chrome", "Chromium"],
+        description: "Which browser to launch (for 'launch' action). Defaults to 'Brave'.",
+      },
+      debug_port: {
+        type: "number",
+        description: "Port to use for remote debugging when launching (for 'launch' action). Defaults to 9222.",
+      },
+      extension_id: {
+        type: "string",
+        description: "Extension ID (32 lowercase chars) or name substring to target (for 'connect' and 'launch' actions). Overrides auto-detection — pass the name (e.g. 'AudiTex') or full ID to pick the right extension when multiple are installed.",
+      },
+      browser_name_for_extensions: {
+        type: "string",
+        enum: ["Brave", "Chrome", "Chromium"],
+        description: "Which browser's extensions directory to scan (for 'list_extensions' action). Defaults to 'Brave'.",
+      },
+    },
+    required: ["action"],
+  },
+};
+
+function getExtensionsDirForBrowser(browserName) {
+  const name = browserName || "Brave";
+  const config = KNOWN_BROWSERS.find((b) => b.name === name);
+  return config?.extensionsDir || null;
+}
+
+export async function handler(args) {
+  const { action } = args;
+
+  if (action === "list_extensions") {
+    const extensionsDir = getExtensionsDirForBrowser(args.browser_name_for_extensions);
+    if (!extensionsDir || !fs.existsSync(extensionsDir)) {
+      throw new Error(`Extensions directory not found: ${extensionsDir}`);
+    }
+    const extensions = listInstalledExtensions(extensionsDir);
+    const lines = extensions.map((e) => `  ${e.id}  ${e.name}`);
+    return {
+      content: [{
+        type: "text",
+        text: `Installed extensions (${extensions.length}):\n${lines.join("\n")}\n\nPass the ID or name substring as extension_id when connecting.`,
+      }],
+    };
+  }
+
+  if (action === "scan") {
+    const runningBrowsers = await scanRunningBrowsers();
+    const installedBrowsers = detectInstalledBrowsers();
+
+    const runningSection =
+      runningBrowsers.length > 0
+        ? runningBrowsers.map((b) => `  Port ${b.port}: ${b.browser}`).join("\n")
+        : "  None — browsers must be started with --remote-debugging-port to appear here.";
+
+    const installedSection =
+      installedBrowsers.length > 0
+        ? installedBrowsers.map((b) => `  ${b.name}: ${b.executable}`).join("\n")
+        : "  None found in /Applications.";
+
+    const nextStep =
+      runningBrowsers.length > 0
+        ? `Use action:"connect" with port:${runningBrowsers[0].port} to attach.`
+        : `Use action:"launch" with browser_name:"${installedBrowsers[0]?.name || "Brave"}" to start one.\n` +
+          `Note: close your existing ${installedBrowsers.map((b) => b.name).join("/")} window first — ` +
+          `Chrome-based browsers won't open a second instance with the same profile.`;
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            "Running browsers with remote debugging:",
+            runningSection,
+            "",
+            "Installed browsers:",
+            installedSection,
+            "",
+            nextStep,
+          ].join("\n"),
+        },
+      ],
+    };
+  }
+
+  if (action === "connect") {
+    const port = args.port || 9222;
+    const versionInfo = await fetchCdpVersionInfo(port);
+    if (!versionInfo) {
+      throw new Error(
+        `No browser with remote debugging found on port ${port}. ` +
+        `Run action:"scan" to see what's available, or use action:"launch" to start one.`
+      );
+    }
+
+    await teardownExistingConnection();
+    await connectToDebugPort(port);
+
+    if (args.extension_id) {
+      const extensionsDir = getExtensionsDirForBrowser("Brave");
+      const resolved = extensionsDir ? resolveExtensionId(args.extension_id, extensionsDir) : null;
+      if (!resolved) throw new Error(`No installed extension found matching "${args.extension_id}". Run action:"list_extensions" to see available extensions.`);
+      state.extensionId = resolved;
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            `Connected to ${versionInfo.Browser} on port ${port}.`,
+            `Extension ID: ${state.extensionId || "not detected — run list_extensions to find it"}`,
+            "",
+            "Your existing tabs and logged-in sessions are preserved.",
+            "All other tools (interact_with_popup, inspect_dom, etc.) will now use this browser.",
+          ].join("\n"),
+        },
+      ],
+    };
+  }
+
+  if (action === "launch") {
+    const browserName = args.browser_name || "Brave";
+    const port = args.debug_port || 9222;
+
+    const browserConfig = KNOWN_BROWSERS.find((b) => b.name === browserName);
+    if (!browserConfig) {
+      const validNames = KNOWN_BROWSERS.map((b) => b.name).join(", ");
+      throw new Error(`Unknown browser "${browserName}". Choose from: ${validNames}`);
+    }
+    if (!fs.existsSync(browserConfig.executable)) {
+      throw new Error(`${browserName} not found at: ${browserConfig.executable}`);
+    }
+
+    const resolveTarget = (nameOrId) => {
+      if (!nameOrId) return null;
+      const resolved = resolveExtensionId(nameOrId, browserConfig.extensionsDir);
+      if (!resolved) throw new Error(`No installed extension found matching "${nameOrId}". Run action:"list_extensions" to see available extensions.`);
+      return resolved;
+    };
+
+    // If a browser is already debugging on the target port, just connect to it.
+    const alreadyRunning = await fetchCdpVersionInfo(port);
+    if (alreadyRunning) {
+      await teardownExistingConnection();
+      await connectToDebugPort(port);
+      if (args.extension_id) state.extensionId = resolveTarget(args.extension_id);
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `Browser already running with debugging on port ${port}. Connected to ${alreadyRunning.Browser}.`,
+              `Extension ID: ${state.extensionId || "not detected"}`,
+            ].join("\n"),
+          },
+        ],
+      };
+    }
+
+    await teardownExistingConnection();
+    await launchBrowserProcess(browserConfig, port);
+    await connectToDebugPort(port);
+    if (args.extension_id) state.extensionId = resolveTarget(args.extension_id);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: [
+            `Launched ${browserName} with remote debugging on port ${port}.`,
+            `Profile: ${browserConfig.userDataDir}`,
+            `Extension ID: ${state.extensionId || "not detected — run list_extensions to find it"}`,
+            "",
+            "All your existing logins are available.",
+            "All other tools (interact_with_popup, inspect_dom, etc.) will now use this browser.",
+          ].join("\n"),
+        },
+      ],
+    };
+  }
+
+  throw new Error(`Unknown action "${action}". Valid actions: "scan", "connect", "launch", "list_extensions".`);
+}

package/src/tools/context-menu.js

@@ -50,7 +50,7 @@ export async function handler(args) {
   }
 
   if (args.action === "right_click") {
-    if (!args.selector) return { content: [{ type: "text", text: "Provide a 'selector' for right_click action." }] };
+    if (!args.selector) return { content: [{ type: "text", text: "Provide a 'selector' for right_click action." }], isError: true };
     const p = await ensurePage();
     if (args.url) await p.goto(args.url, { waitUntil: "domcontentloaded" });
     await p.click(args.selector, { button: "right" });
@@ -63,7 +63,7 @@ export async function handler(args) {
   }
 
   if (args.action === "trigger_item") {
-    if (!args.menu_item_id) return { content: [{ type: "text", text: "Provide a 'menu_item_id' to trigger." }] };
+    if (!args.menu_item_id) return { content: [{ type: "text", text: "Provide a 'menu_item_id' to trigger." }], isError: true };
     const sw = await getServiceWorker();
     // Directly invoke the onClicked listener by dispatching a synthetic event via the SW
     const result = await sw.evaluate(({ menuItemId, pageUrl }) => {

package/src/tools/dom.js

@@ -43,5 +43,5 @@ export async function handler(args) {
     };
   }
 
-  return { content: [{ type: "text", text: "Provide either a selector or a script." }] };
+  return { content: [{ type: "text", text: "Provide either a selector or a script." }], isError: true };
 }

package/src/tools/index.js

@@ -1,4 +1,5 @@
 import * as loadExtension from "./load-extension.js";
+import * as connectBrowser from "./connect-browser.js";
 import * as popup from "./popup.js";
 import * as dom from "./dom.js";
 import * as logs from "./logs.js";
@@ -15,6 +16,7 @@ import * as accountLogin from "./account-login.js";
 
 const allTools = [
   loadExtension,
+  connectBrowser,
   popup,
   dom,
   logs,

package/src/tools/load-extension.js

@@ -20,6 +20,8 @@ export async function handler(args) {
   if (state.browser) {
     await state.browser.close();
     state.browser = null;
+    state.context = null;
+    state.connectionMode = null;
     state.page = null;
     state.extensionId = null;
     state.swLogs.length = 0;

package/src/tools/messaging.js

@@ -21,7 +21,7 @@ export const definition = {
 
 export async function handler(args) {
   if (!state.extensionId) {
-    return { content: [{ type: "text", text: "Extension ID not detected. Call load_extension first." }] };
+    return { content: [{ type: "text", text: "Extension ID not detected. Call load_extension first." }], isError: true };
   }
 
   const p = await ensurePage();
@@ -54,7 +54,7 @@ export async function handler(args) {
   );
 
   if (result.error) {
-    return { content: [{ type: "text", text: `Message failed: ${result.error}` }] };
+    return { content: [{ type: "text", text: `Message failed: ${result.error}` }], isError: true };
   }
 
   return {

package/src/tools/network.js

@@ -50,7 +50,7 @@ export async function handler(args) {
   }
 
   if (args.action === "navigate_and_capture") {
-    if (!args.url) return { content: [{ type: "text", text: "Provide a 'url' to navigate to." }] };
+    if (!args.url) return { content: [{ type: "text", text: "Provide a 'url' to navigate to." }], isError: true };
 
     const p = await ensurePage();
     const captured = [];

package/src/tools/options-page.js

@@ -29,7 +29,7 @@ export const definition = {
 
 export async function handler(args) {
   if (!state.extensionId) {
-    return { content: [{ type: "text", text: "Extension ID not detected. Call load_extension first." }] };
+    return { content: [{ type: "text", text: "Extension ID not detected. Call load_extension first." }], isError: true };
   }
 
   const pageName = args.page || "options.html";

package/src/tools/popup.js

@@ -28,6 +28,7 @@ export async function handler(args) {
   if (!state.extensionId && args.action === "open") {
     return {
       content: [{ type: "text", text: "Extension ID not detected. Make sure the extension has a background service worker." }],
+      isError: true,
     };
   }
 

package/src/tools/storage.js

@@ -47,7 +47,7 @@ export async function handler(args) {
 
   if (args.action === "set") {
     if (!args.data || !Object.keys(args.data).length) {
-      return { content: [{ type: "text", text: "Provide a 'data' object for the set action." }] };
+      return { content: [{ type: "text", text: "Provide a 'data' object for the set action." }], isError: true };
     }
     await sw.evaluate(
       ({ area, data }) => new Promise((resolve) => chrome.storage[area].set(data, resolve)),
@@ -60,7 +60,7 @@ export async function handler(args) {
 
   if (args.action === "remove") {
     if (!args.keys?.length) {
-      return { content: [{ type: "text", text: "Provide 'keys' array for the remove action." }] };
+      return { content: [{ type: "text", text: "Provide 'keys' array for the remove action." }], isError: true };
     }
     await sw.evaluate(
       ({ area, keys }) => new Promise((resolve) => chrome.storage[area].remove(keys, resolve)),

package/src/tools/tabs.js

@@ -25,10 +25,11 @@ export const definition = {
 };
 
 export async function handler(args) {
-  if (!state.browser) throw new Error("Browser not started. Call load_extension first.");
+  const ctx = state.context || state.browser;
+  if (!ctx) throw new Error("No browser connected. Call load_extension or connect_browser first.");
 
   if (args.action === "list") {
-    const pages = state.browser.pages();
+    const pages = ctx.pages();
     const list = await Promise.all(
       pages.map(async (p, i) => {
         const title = await p.title().catch(() => "(no title)");
@@ -41,17 +42,17 @@ export async function handler(args) {
 
   if (args.action === "open") {
     const url = args.url || "about:blank";
-    const newPage = await state.browser.newPage();
+    const newPage = await ctx.newPage();
     if (args.url) await newPage.goto(url, { waitUntil: "domcontentloaded" });
     state.page = newPage;
-    const index = state.browser.pages().length - 1;
+    const index = ctx.pages().length - 1;
     return { content: [{ type: "text", text: `Opened new tab [${index}]: ${url}` }] };
   }
 
   if (args.action === "switch") {
-    const pages = state.browser.pages();
+    const pages = ctx.pages();
     if (args.tab_index === undefined || args.tab_index < 0 || args.tab_index >= pages.length) {
-      return { content: [{ type: "text", text: `Invalid tab_index ${args.tab_index}. Run 'list' to see available tabs.` }] };
+      return { content: [{ type: "text", text: `Invalid tab_index ${args.tab_index}. Run 'list' to see available tabs.` }], isError: true };
     }
     state.page = pages[args.tab_index];
     await state.page.bringToFront();
@@ -59,22 +60,22 @@ export async function handler(args) {
   }
 
   if (args.action === "close") {
-    const pages = state.browser.pages();
+    const pages = ctx.pages();
     if (args.tab_index === undefined || args.tab_index < 0 || args.tab_index >= pages.length) {
-      return { content: [{ type: "text", text: `Invalid tab_index ${args.tab_index}. Run 'list' to see available tabs.` }] };
+      return { content: [{ type: "text", text: `Invalid tab_index ${args.tab_index}. Run 'list' to see available tabs.` }], isError: true };
     }
     const toClose = pages[args.tab_index];
     const closedUrl = toClose.url();
     await toClose.close();
     if (state.page === toClose || state.page?.isClosed()) {
-      const remaining = state.browser.pages();
+      const remaining = ctx.pages();
       state.page = remaining.length ? remaining[remaining.length - 1] : null;
     }
     return { content: [{ type: "text", text: `Closed tab [${args.tab_index}]: ${closedUrl}` }] };
   }
 
   if (args.action === "close_all") {
-    const pages = state.browser.pages();
+    const pages = ctx.pages();
     const closed = [];
     for (const p of pages) {
       const url = p.url();