@agent360/browser-mcp 1.20.1 → 1.23.0

package/README.md

@@ -5,28 +5,63 @@
 [![GitHub stars](https://img.shields.io/github/stars/Agent360dk/browser-mcp)](https://github.com/Agent360dk/browser-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
+[![Chrome Web Store](https://img.shields.io/badge/Chrome_Web_Store-live-green)](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl)
 
 **Control your real Chrome from Claude Code — with your logins, cookies, and 2FA.**
 
 ![Browser MCP Demo](assets/demo.gif)
 
-The only browser MCP with **multi-session support** (10 concurrent AI sessions), **human-in-the-loop** (2FA, CAPTCHA, credentials), and **built-in provider integrations** (Stripe, HubSpot, Slack, and 6 more). 29 tools total.
+The only browser MCP with **multi-session support** (10 concurrent AI sessions), **human-in-the-loop** (2FA, CAPTCHA, credentials), and **built-in provider integrations** (Stripe, HubSpot, Slack, and 6 more). 34 tools total.
 
-## Install
+## Install — 2 steps (~60 seconds)
+
+### Step 1: Configure the MCP server
 
 ```bash
 npx @agent360/browser-mcp install
 ```
 
-This copies the Chrome extension to `~/.browser-mcp/extension/` and configures Claude Code automatically.
+This copies the Chrome extension files to `~/.browser-mcp/extension/` and adds the MCP server to your Claude Code config. **You'll see the path to the extension folder printed in the terminal — copy it.**
+
+### Step 2: Load the extension in Chrome
+
+> Chrome won't let extensions install themselves from npm — you load it manually one time. To **update** later, re-run the install command and reload it (see [Keeping it updated](#keeping-it-updated)). Prefer the [Chrome Web Store](#chrome-web-store-one-click-install) install if you'd rather have the extension auto-update.
+
+1. **Open Chrome** and type `chrome://extensions` in the address bar
+2. **Toggle "Developer mode"** ON (top right corner)
+3. **Click "Load unpacked"** (top left, next to "Pack extension")
+4. **Navigate to `~/.browser-mcp/extension/`** and click "Select"
+   - On Mac: Press `Cmd+Shift+G` in the file picker, paste `~/.browser-mcp/extension/`, press Enter
+   - On Windows: Paste `%USERPROFILE%\.browser-mcp\extension\` in the address bar
+   - On Linux: Type `~/.browser-mcp/extension/` in the path field
+5. **Restart Claude Code** so it picks up the new MCP server
+
+That's it. The Browser MCP icon will appear in your toolbar, and 34 browser tools are now available in Claude Code.
+
+### Alternative: Manual zip download (no npm)
+
+If you don't want to use npm, download the extension directly:
+
+1. [Download `browser-mcp-v1.23.0.zip`](https://github.com/Agent360dk/browser-mcp/releases/latest) from the latest GitHub release
+2. Unzip the file (anywhere — e.g. `~/Downloads/browser-mcp-extension/`)
+3. Follow Step 2 above, but select the unzipped folder instead of `~/.browser-mcp/extension/`
+4. Configure Claude Code manually by adding this to your `~/.claude.json` (or run `npx @agent360/browser-mcp install --skip-extension`):
+   ```json
+   {
+     "mcpServers": {
+       "browser-mcp": {
+         "command": "npx",
+         "args": ["@agent360/browser-mcp"]
+       }
+     }
+   }
+   ```
 
-Then load the extension in Chrome:
-1. Open `chrome://extensions`
-2. Enable **Developer mode** (top right)
-3. Click **Load unpacked** → select `~/.browser-mcp/extension/`
-4. Restart Claude Code
+### Chrome Web Store (one-click install)
 
-That's it. 29 browser tools are now available in Claude Code.
+[**Install from Chrome Web Store →**](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl)
+
+No Developer mode needed. Then run `npx @agent360/browser-mcp install --skip-extension` to configure Claude Code.
 
 ## Why This Over Playwright MCP / BrowserMCP?
 
@@ -43,7 +78,7 @@ That's it. 29 browser tools are now available in Claude Code.
 | **Custom dropdowns** | Angular Material, React Select support | Works (headless) | Limited |
 | **Install** | `npx @agent360/browser-mcp install` | `npx @anthropic-ai/mcp-playwright` | Manual clone |
 
-## 29 Tools
+## 34 Tools
 
 ### Navigation & Content
 | Tool | Description |
@@ -63,7 +98,10 @@ That's it. 29 browser tools are now available in Claude Code.
 | `browser_wait` | Wait for element to appear |
 | `browser_hover` | Hover for tooltips/dropdowns |
 | `browser_select_option` | Native `<select>` + custom dropdowns (Angular Material, React Select) |
-| `browser_handle_dialog` | Accept/dismiss alert/confirm/prompt dialogs |
+| `browser_set_combobox` | Autocomplete/combobox: type query → wait for filtered listbox → click option (multi-value chip support). Use when `browser_select_option` fails on lazy-rendered options |
+| `browser_set_date` | Robust date inputs: tries native value-set → masked typing → calendar-picker navigation (MUI/AntD/react-datepicker/Lexical). Use when `browser_fill` fails on date fields |
+| `browser_dismiss_overlays` | Bulk-dismiss popups/modals/tooltips/banners via aria-label/text/×-char heuristics. `non_critical` mode preserves dialogs with form data |
+| `browser_handle_dialog` | Accept/dismiss native alert/confirm/prompt dialogs |
 
 ### Tabs & Frames
 | Tool | Description |
@@ -103,6 +141,7 @@ That's it. 29 browser tools are now available in Claude Code.
 | `browser_set_local_storage` | Write localStorage values |
 | `browser_console_logs` | Capture console.log/warn/error messages from page |
 | `browser_upload_file` | Upload files to `<input type="file">` via Chrome Debugger API (no dialog) |
+| `browser_drop_file` | Upload via drop-zones: finds hidden `<input type="file">` in target subtree/parent (up to 2 levels). Use when `browser_upload_file` fails because the zone has no visible input |
 
 ## Multi-Session Support
 
@@ -145,7 +184,7 @@ extension/
 
 mcp-server/
   index.js            # MCP server (stdio) + WebSocket client
-  tools.js            # 29 tool definitions
+  tools.js            # 34 tool definitions
   bin/cli.js          # Install CLI
 ```
 
@@ -157,11 +196,19 @@ mcp-server/
 5. Commands flow: Claude Code → MCP → Extension → Chrome APIs
 6. Process auto-exits when Claude Code closes (stdin detection)
 
-## Auto-Updates
+## Keeping it updated
+
+Browser MCP has two parts, and they update independently — how the **extension** updates depends on how you installed it:
 
-The MCP server runs via `npx @agent360/browser-mcp@latest` — always the latest version from npm. No manual git pulls needed.
+| Part | Install method | How it updates |
+|------|----------------|----------------|
+| **MCP server** | any | **Automatic.** Runs via `npx @agent360/browser-mcp@latest`, so every Claude Code session pulls the newest from npm. Nothing to do. |
+| **Extension** | **Chrome Web Store** | **Automatic.** Chrome updates it in the background (usually within a few hours). Nothing to do. |
+| **Extension** | **Unpacked** (`npx … install` or manual zip) | **Manual.** Chrome never auto-updates a load-unpacked extension. Re-run `npx @agent360/browser-mcp install`, then open `chrome://extensions` → Browser MCP → **↻ reload**. |
 
-To update the extension: `npx @agent360/browser-mcp install` (re-copies files), then reload in `chrome://extensions`.
+**Not sure which you have?** Open `chrome://extensions` and find Browser MCP. If it shows a **"Loaded from /path/…"** line, it's unpacked (manual updates). If there's no such line, it came from the Chrome Web Store (auto-updates).
+
+**Want zero-maintenance updates?** Install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl), then run `npx @agent360/browser-mcp install --skip-extension` to wire up just the MCP server. After that, both parts stay current on their own.
 
 ## Troubleshooting
 
@@ -183,6 +230,21 @@ To update the extension: `npx @agent360/browser-mcp install` (re-copies files),
 - Idle timeout: 4 hours without commands → auto-exit
 - Manual cleanup: `lsof -i :9876-9885 | grep LISTEN`
 
+## 💡 Help Shape Browser MCP
+
+Browser MCP is built in the open and shaped by the people using it.
+
+### Browse what others want / built
+- 💡 **[Wishlist →](WISHLIST.md)** — features people are asking for
+- 🎯 **[Use-cases →](USE_CASES.md)** — what others have built (LinkedIn ICP scraping, vendor research, daily ops, …)
+
+### Contribute in 30 seconds
+- 💡 [Wish for a feature](https://github.com/Agent360dk/browser-mcp/issues/new?template=wish.yml)
+- 🎯 [Share a use-case](https://github.com/Agent360dk/browser-mcp/issues/new?template=use-case.yml)
+- 🐛 [Report a bug](https://github.com/Agent360dk/browser-mcp/issues/new?template=bug.yml)
+
+Or just **ask Claude** — it knows about the `browser_about` tool and will draft + submit on your behalf when you say things like *"I wish browser-mcp could …"* or *"share my browser-mcp use-case"*.
+
 ## License
 
 MIT — [Agent360](https://agent360.dk)

package/bin/cli.js

@@ -85,7 +85,7 @@ function install() {
   5. Navigate to and select this folder:
      ${extensionDir}
   6. The extension "Agent360 Browser MCP" appears with a puzzle icon
-  7. Restart Claude Code — 28 browser tools are now available!
+  7. Restart Claude Code — 34 browser tools are now available!
 
 🔄 Auto-updates (fully automatic):
    - MCP server: always fetches latest from npm (npx @latest)
@@ -93,6 +93,11 @@ function install() {
    - Extension reload: auto-triggered via WebSocket
    - You don't need to do anything — updates happen on every Claude Code session start
 
+💡 Help shape Browser MCP:
+   - Public wishlist:  https://github.com/Agent360dk/browser-mcp/blob/main/WISHLIST.md
+   - Use-case gallery: https://github.com/Agent360dk/browser-mcp/blob/main/USE_CASES.md
+   - Got an idea, bug, or cool thing you built? Just ask Claude — it can draft + submit for you.
+
 📖 Docs: https://browsermcp.dev
 `);
 }

package/extension/background.js

@@ -53,10 +53,45 @@ function getSession(port) {
   return sessions.get(port);
 }
 
+// LRU eviction cap: hver session må højst have N åbne tabs samtidigt.
+// Når en ny tab tilføjes ud over cap'en, lukkes den ÆLDSTE tab i sessionen
+// (insertion-order via Set) — bortset fra session.activeTabId (current tab).
+// Begrundelse: Claude Code-flows kan åbne 20+ navigate(new_tab=true) per session
+// over en længere conversation. Uden eviction akkumulerer disse i Chrome som
+// orphan-tabs der spiser RAM + giver "extension localhost 19+" tab-noise.
+const MAX_TABS_PER_SESSION = 10;
+
+async function evictOldestTabs(session, justAddedTabId) {
+  // Drop dead tab-ids først (user manually closed dem)
+  for (const id of [...session.tabIds]) {
+    try {
+      await chrome.tabs.get(id);
+    } catch {
+      session.tabIds.delete(id);
+    }
+  }
+  // Evict oldest indtil ≤ cap. Skip activeTabId og just-added tab.
+  const ordered = [...session.tabIds];
+  for (const oldId of ordered) {
+    if (session.tabIds.size <= MAX_TABS_PER_SESSION) break;
+    if (oldId === session.activeTabId) continue;
+    if (oldId === justAddedTabId) continue;
+    try {
+      await chrome.tabs.remove(oldId);
+    } catch {} // tab may already be closed
+    session.tabIds.delete(oldId);
+  }
+}
+
 async function addTabToSession(port, tabId) {
   const session = getSession(port);
   session.tabIds.add(tabId);
 
+  // LRU eviction: når sessionen overstiger cap, luk de ældste tabs.
+  if (session.tabIds.size > MAX_TABS_PER_SESSION) {
+    await evictOldestTabs(session, tabId);
+  }
+
   try {
     if (session.groupId !== null) {
       try {
@@ -176,17 +211,55 @@ async function getSessionTab(port, activate = false) {
 // Track which tabs have debugger attached to avoid repeated attach/detach
 const debuggerAttached = new Set();
 
+// Verify Chrome's actual debugger-truth before trusting local cache.
+// Fixes "ghost-attached" state where Set says attached but Chrome side is gone
+// (happens on SW lifecycle events, user-canceled banners, anti-automation evictions).
+async function verifyAttachedWithChrome(tabId) {
+  try {
+    const targets = await chrome.debugger.getTargets();
+    const t = targets.find(x => x.tabId === tabId);
+    return !!t?.attached;
+  } catch {
+    return false; // assume not-attached on API error
+  }
+}
+
 async function debuggerAttach(tabId) {
-  if (debuggerAttached.has(tabId)) return;
+  // First check local cache — fast path
+  if (debuggerAttached.has(tabId)) {
+    // Verify with Chrome before trusting cache (cheap, ~1ms)
+    if (await verifyAttachedWithChrome(tabId)) return;
+    // Cache was stale — Chrome doesn't actually have us attached
+    debuggerAttached.delete(tabId);
+  }
+
   try {
     await chrome.debugger.attach({ tabId }, '1.3');
-    debuggerAttached.add(tabId);
+    // Verify attach actually took effect (Chrome can silently no-op after user-cancel)
+    if (await verifyAttachedWithChrome(tabId)) {
+      debuggerAttached.add(tabId);
+      return;
+    }
+    throw new Error(
+      `Debugger detached (GHOST_ATTACH): chrome.debugger.attach returned success but Chrome state shows tab ${tabId} not attached. ` +
+      `This typically means the user clicked "Cancel" on Chrome's debugger banner. ` +
+      `Fix: reload Browser MCP extension (chrome://extensions/ → ↻) or restart Chrome.`
+    );
   } catch (e) {
     if (e.message?.includes('Already attached')) {
+      // Chrome side has session — sync local cache
       debuggerAttached.add(tabId);
-    } else {
-      throw e;
+      return;
     }
+    if (e.message?.includes('Cannot attach') || e.message?.includes('canceled') || e.message?.includes('GHOST_ATTACH') || e.message?.includes('Debugger detached')) {
+      throw new Error(
+        `Debugger detached (BLOCKED_BY_USER): Cannot attach debugger to tab ${tabId}. ` +
+        `Chrome blocks debugger attach — user likely clicked "Cancel" on debugger banner earlier this session. ` +
+        `Fix: chrome://extensions/ → Browser MCP → reload (↻) icon. Or restart Chrome. ` +
+        `Original error: ${e.message}`
+      );
+    }
+    throw e;
   }
 }
 
@@ -237,27 +310,39 @@ const RETRYABLE_CDP_METHODS = new Set([
 // For side-effectful methods, only re-attaches and throws — caller must decide.
 async function cdpSend(tabId, method, params = {}) {
   await debuggerAttach(tabId);
-  try {
-    return await chrome.debugger.sendCommand({ tabId }, method, params);
-  } catch (e) {
-    const msg = e?.message || String(e);
-    const isDetachError =
-      msg.includes('not attached') ||
-      msg.includes('Detached') ||
-      msg.includes('detached') ||
-      msg.includes('Debugger is gone') ||
-      msg.includes('No tab with given id');
-    if (!isDetachError) throw e;
-    debuggerAttached.delete(tabId);
-    if (!RETRYABLE_CDP_METHODS.has(method)) {
-      // Re-attach for next caller, but don't auto-retry side-effectful command
-      try { await debuggerAttach(tabId); } catch {}
-      throw new Error(`Debugger detached during ${method} — not auto-retried (side-effect risk). Original: ${msg}`);
+  let lastMsg = '';
+  // 4 total attempts (initial + 3 retries) for read-only methods; backoff 100/300/500ms.
+  // Handles aggressive auto-detach on anti-automation sites (Apple ASC, Salesforce, etc.)
+  // where Chrome re-detaches between attach and command execution.
+  for (let attempt = 0; attempt < 4; attempt++) {
+    try {
+      return await chrome.debugger.sendCommand({ tabId }, method, params);
+    } catch (e) {
+      const msg = e?.message || String(e);
+      const isDetachError =
+        msg.includes('not attached') ||
+        msg.includes('Detached') ||
+        msg.includes('detached') ||
+        msg.includes('Debugger is gone') ||
+        msg.includes('No tab with given id');
+      if (!isDetachError) throw e;
+      lastMsg = msg;
+      debuggerAttached.delete(tabId);
+      if (!RETRYABLE_CDP_METHODS.has(method)) {
+        // Side-effectful methods (Input.*) — re-attach for next caller but signal
+        // to handler so it can fall back to chrome.scripting (e.g., synthetic click).
+        try { await debuggerAttach(tabId); } catch {}
+        throw new Error(`Debugger detached during ${method} — not auto-retried (side-effect risk). Original: ${msg}`);
+      }
+      if (attempt < 3) {
+        await new Promise(r => setTimeout(r, 100 + attempt * 200));
+        try { await debuggerAttach(tabId); } catch (attachErr) {
+          throw new Error(`Re-attach failed during ${method}: ${attachErr.message}`);
+        }
+      }
     }
-    await new Promise(r => setTimeout(r, 100));
-    await debuggerAttach(tabId);
-    return await chrome.debugger.sendCommand({ tabId }, method, params);
   }
+  throw new Error(`Debugger detached repeatedly during ${method} (4 attempts). Last: ${lastMsg}`);
 }
 
 // Clean up debugger + session refs when tabs close
@@ -307,25 +392,58 @@ async function debuggerType(tabId, text) {
 async function debuggerClick(tabId, x, y) {
   await debuggerAttach(tabId);
   try {
+    // 0. Capture the DEEPEST target element under the point BEFORE dispatching.
+    //    Web-components (Google Ads <button-panel>, Material Web) keep their real
+    //    <button> inside an (open) shadow root, so we pierce shadow roots to reach
+    //    it. We stash it on window so the framework fallback (step 3) can verify it
+    //    is still connected — if the trusted click already navigated/re-rendered,
+    //    the ref is detached and we must NOT re-fire (avoids mis-clicks on the new
+    //    view / double-submits).
+    await cdpSend(tabId, 'Runtime.evaluate', {
+      expression: `(() => {
+        let el = document.elementFromPoint(${x}, ${y});
+        let host = el;
+        for (let i = 0; i < 20 && host && host.shadowRoot; i++) {
+          const inner = host.shadowRoot.elementFromPoint(${x}, ${y});
+          if (!inner || inner === host) break;
+          el = inner; host = inner;
+        }
+        window.__bmcpClickTarget = el || null;
+      })()`,
+    });
     // 1. mouseMoved first (triggers hover state, required by some frameworks)
     await cdpSend(tabId, 'Input.dispatchMouseEvent', {
       type: 'mouseMoved', x, y,
     });
     await new Promise(r => setTimeout(r, 30));
-    // 2. mousePressed + mouseReleased (fires trusted mousedown/mouseup)
+    // 2. mousePressed + mouseReleased. The `buttons` bitmask (1 while pressed,
+    //    0 on release) plus a small press→release gap are REQUIRED for Chrome to
+    //    synthesize a *trusted* 'click' from the pair. Without them, web-components
+    //    that gate on the trusted click event (Google Ads, Material Web) never fire.
     await cdpSend(tabId, 'Input.dispatchMouseEvent', {
-      type: 'mousePressed', x, y, button: 'left', clickCount: 1,
+      type: 'mousePressed', x, y, button: 'left', buttons: 1, clickCount: 1,
     });
+    await new Promise(r => setTimeout(r, 30));
     await cdpSend(tabId, 'Input.dispatchMouseEvent', {
-      type: 'mouseReleased', x, y, button: 'left', clickCount: 1,
+      type: 'mouseReleased', x, y, button: 'left', buttons: 0, clickCount: 1,
     });
-    // 3. CDP doesn't synthesize 'click' event from mousePressed/mouseReleased.
-    //    Fire JS click + React/Angular framework fallbacks.
+    // 3. Framework fallback — only if the captured target is STILL connected (i.e.
+    //    the trusted click in step 2 did not already handle it). Settle delay lets
+    //    SPA re-renders (Google Ads) detach the element first. Fires a full pointer
+    //    + mouse sequence on the shadow-pierced target, then React/Angular handlers.
+    await new Promise(r => setTimeout(r, 120));
     await cdpSend(tabId, 'Runtime.evaluate', {
       expression: `(() => {
-        const el = document.elementFromPoint(${x}, ${y});
-        if (!el) return;
-        el.click();
+        const el = window.__bmcpClickTarget;
+        try { delete window.__bmcpClickTarget; } catch (e) {}
+        if (!el || !el.isConnected) return;   // already navigated/handled — don't double-fire
+        const opts = { bubbles: true, cancelable: true, composed: true, view: window, clientX: ${x}, clientY: ${y} };
+        try { el.dispatchEvent(new PointerEvent('pointerdown', opts)); } catch (e) {}
+        el.dispatchEvent(new MouseEvent('mousedown', opts));
+        try { el.dispatchEvent(new PointerEvent('pointerup', opts)); } catch (e) {}
+        el.dispatchEvent(new MouseEvent('mouseup', opts));
+        el.dispatchEvent(new MouseEvent('click', opts));
+        if (typeof el.click === 'function') el.click();
 
         // React fiber fallback — find and call onClick handler directly
         const fiberKey = Object.keys(el).find(k => k.startsWith('__reactFiber') || k.startsWith('__reactInternalInstance'));
@@ -337,16 +455,11 @@ async function debuggerClick(tabId, x, y) {
           }
         }
 
-        // Angular fallback — trigger via Zone.js patched events + ngClick
+        // Angular Material fallback — ripple + internal handlers
         const ngKey = Object.keys(el).find(k => k.startsWith('__ng'));
         if (ngKey || el.getAttribute('ng-click') || el.getAttribute('(click)')) {
-          // Angular uses Zone.js which patches addEventListener — dispatch real events through it
-          el.dispatchEvent(new PointerEvent('pointerdown', {bubbles:true, cancelable:true}));
-          el.dispatchEvent(new PointerEvent('pointerup', {bubbles:true, cancelable:true}));
-          el.dispatchEvent(new MouseEvent('click', {bubbles:true, cancelable:true, view:window}));
-          // Angular Material components (mat-button, mat-checkbox, etc.) use ripple + internal handlers
-          const matRipple = el.closest('[mat-button], [mat-raised-button], [mat-icon-button], [mat-fab], mat-checkbox, mat-slide-toggle, mat-radio-button');
-          if (matRipple) matRipple.dispatchEvent(new MouseEvent('click', {bubbles:true, cancelable:true, view:window}));
+          const matRipple = el.closest && el.closest('[mat-button], [mat-raised-button], [mat-icon-button], [mat-fab], mat-checkbox, mat-slide-toggle, mat-radio-button');
+          if (matRipple) matRipple.dispatchEvent(new MouseEvent('click', opts));
         }
       })()`,
     });
@@ -437,6 +550,46 @@ async function debuggerEval(tabId, expression) {
   }
 }
 
+// Synthetic click via chrome.scripting — fallback when debugger detaches on
+// anti-automation sites (Apple ASC, etc.). Loses isTrusted=true but works for
+// the ~95% of sites that don't check it. Handles text= and :text() selectors.
+async function scriptingClick(tabId, selector) {
+  try {
+    const [result] = await chrome.scripting.executeScript({
+      target: { tabId },
+      world: 'MAIN',
+      func: (sel) => {
+        let el;
+        if (sel.startsWith('text=')) {
+          const text = sel.slice(5).trim();
+          el = Array.from(document.querySelectorAll('button, a, [role="button"], [role="menuitem"], [role="tab"], [role="option"], input, label, span, div, p, li, td'))
+            .find(e => (e.textContent || '').trim() === text);
+        } else {
+          const m = sel.match(/^([\w-]+):text\(([^)]+)\)$/);
+          if (m) {
+            const needle = m[2].trim();
+            el = Array.from(document.querySelectorAll(m[1]))
+              .find(e => (e.textContent || '').trim().includes(needle));
+          } else {
+            el = document.querySelector(sel);
+          }
+        }
+        if (!el) return { ok: false, reason: 'not_found' };
+        el.scrollIntoView({ block: 'center', behavior: 'instant' });
+        const opts = { bubbles: true, cancelable: true, view: window };
+        el.dispatchEvent(new MouseEvent('mousedown', opts));
+        el.dispatchEvent(new MouseEvent('mouseup', opts));
+        el.click();
+        return { ok: true, tag: el.tagName };
+      },
+      args: [selector],
+    });
+    return result?.result || { ok: false, reason: 'no_result' };
+  } catch (e) {
+    return { ok: false, reason: 'exception', error: e.message };
+  }
+}
+
 // Try executeScript first, fall back to debugger on CSP error
 async function safeExecuteScript(tabId, func, args = [], world = 'MAIN') {
   try {
@@ -1584,36 +1737,99 @@ async function dispatch(port, method, params) {
     }
 
     case 'execute_script': {
+      // v1.22.2 (DIAGNOSTIC): Try scripting paths but log all errors so we can see WHY they fail
       const tab = await getSessionTab(port);
       if (tab.url.startsWith('chrome://')) throw new Error('Cannot execute scripts on chrome:// pages');
+
+      const diag = { tried: [] };
+
+      // Step 1: try ISOLATED world
       try {
         const [result] = await chrome.scripting.executeScript({
           target: { tabId: tab.id },
-          func: new Function('return (' + params.code + ')'),
-          world: 'MAIN',
+          world: 'ISOLATED',
+          args: [params.code],
+          func: (codeStr) => {
+            try {
+              const fn = new Function('return (' + codeStr + ')');
+              return { __ok: true, value: fn() };
+            } catch (e) {
+              return { __scriptingError: true, message: String(e?.message || e), name: e?.name, world: 'ISOLATED' };
+            }
+          },
         });
-        return { result: result.result };
+        const r = result?.result;
+        diag.tried.push({ world: 'ISOLATED', result_keys: r ? Object.keys(r) : null, r_type: typeof r });
+        if (r && typeof r === 'object' && r.__ok) {
+          return { result: r.value, method: 'scripting-isolated' };
+        }
+        if (r && typeof r === 'object' && r.__scriptingError) {
+          diag.isolated_error = r.message;
+        }
       } catch (e) {
-        if (e.message?.includes('Content Security Policy') || e.message?.includes('unsafe-eval')) {
-          // CSP blocked — fall back to debugger Runtime.evaluate
-          const value = await debuggerEval(tab.id, params.code);
-          return { result: value, method: 'debugger' };
+        diag.isolated_throw = String(e?.message || e);
+      }
+
+      // Step 2: try MAIN world
+      try {
+        const [result] = await chrome.scripting.executeScript({
+          target: { tabId: tab.id },
+          world: 'MAIN',
+          args: [params.code],
+          func: (codeStr) => {
+            try {
+              const fn = new Function('return (' + codeStr + ')');
+              return { __ok: true, value: fn() };
+            } catch (e) {
+              return { __scriptingError: true, message: String(e?.message || e), name: e?.name, world: 'MAIN' };
+            }
+          },
+        });
+        const r = result?.result;
+        diag.tried.push({ world: 'MAIN', result_keys: r ? Object.keys(r) : null, r_type: typeof r });
+        if (r && typeof r === 'object' && r.__ok) {
+          return { result: r.value, method: 'scripting-main' };
         }
-        throw e;
+        if (r && typeof r === 'object' && r.__scriptingError) {
+          diag.main_error = r.message;
+        }
+      } catch (e) {
+        diag.main_throw = String(e?.message || e);
       }
+
+      // Step 3: DIAG MODE — don't fallback to debugger, return scripting-state info instead
+      return {
+        result: '__SCRIPTING_FAILED__',
+        method: 'scripting-failed',
+        diag,
+        note: 'Both ISOLATED + MAIN scripting paths returned null/error. See diag for details.',
+      };
     }
 
     case 'click': {
       const tab = await getSessionTab(port);
       if (tab.url.startsWith('chrome://')) throw new Error('Cannot interact with chrome:// pages');
 
-      // Resolve element (supports CSS + text selectors, auto-scrolls)
-      const el = await resolveElement(tab.id, params.selector);
-      if (!el) return { ok: false, error: 'Element not found: ' + params.selector };
+      // Wrap full click flow (incl. resolveElement) so debugger failures in EITHER
+      // resolveElement (text-selectors use debuggerEval) OR debuggerClick trigger
+      // the scripting-fallback. v1.21.2: previously only debuggerClick was wrapped,
+      // leaving text-selector clicks unrecoverable when debugger was user-blocked.
+      try {
+        const el = await resolveElement(tab.id, params.selector);
+        if (!el) return { ok: false, error: 'Element not found: ' + params.selector };
 
-      // Always use debugger mouse events — works on all sites including SPAs
-      await debuggerClick(tab.id, el.x, el.y);
-      return { ok: true, method: el.method || 'debugger', tag: el.tag, text: el.text };
+        // Primary path: debugger mouse events (isTrusted=true, works on React/Angular SPAs)
+        await debuggerClick(tab.id, el.x, el.y);
+        return { ok: true, method: el.method || 'debugger', tag: el.tag, text: el.text };
+      } catch (e) {
+        // Fallback: synthetic click via chrome.scripting for anti-automation sites
+        // (Apple ASC etc.) OR user-blocked-debugger scenarios.
+        if (/Debugger detached/.test(e?.message || '')) {
+          const r = await scriptingClick(tab.id, params.selector);
+          if (r.ok) return { ok: true, method: 'scripting-fallback', tag: r.tag };
+        }
+        throw e;
+      }
     }
 
     case 'fill': {
@@ -1785,11 +2001,24 @@ async function dispatch(port, method, params) {
     }
 
     case 'press_key': {
-      const tab = await getSessionTab(port);
+      // v1.22: activate tab so key-event lands in foreground (otherwise Chrome routes to active tab)
+      const tab = await getSessionTab(port, true);
       if (tab.url.startsWith('chrome://')) throw new Error('Cannot interact with chrome:// pages');
       const key = params.key; // e.g. "Enter", "Tab", "Escape", "ArrowDown"
       const modifiers = (params.ctrl ? 2 : 0) | (params.alt ? 1 : 0) | (params.shift ? 8 : 0) | (params.meta ? 4 : 0);
 
+      // v1.22: Chrome requires windowsVirtualKeyCode for navigation/system keys to trigger
+      // scroll/form-submit behavior. Without these, key-event is dispatched but page doesn't react.
+      const VK_CODES = {
+        'Backspace': 8, 'Tab': 9, 'Enter': 13, 'Shift': 16, 'Control': 17, 'Alt': 18,
+        'Escape': 27, 'Space': 32, ' ': 32,
+        'PageUp': 33, 'PageDown': 34, 'End': 35, 'Home': 36,
+        'ArrowLeft': 37, 'ArrowUp': 38, 'ArrowRight': 39, 'ArrowDown': 40,
+        'Delete': 46,
+      };
+      const vkCode = VK_CODES[key];
+      const vkParams = vkCode ? { windowsVirtualKeyCode: vkCode, nativeVirtualKeyCode: vkCode } : {};
+
       await debuggerAttach(tab.id);
       try {
         await cdpSend(tab.id, 'Input.dispatchKeyEvent', {
@@ -1798,12 +2027,14 @@ async function dispatch(port, method, params) {
           code: params.code || key,
           modifiers,
           text: key.length === 1 ? key : '',
+          ...vkParams,
         });
         await cdpSend(tab.id, 'Input.dispatchKeyEvent', {
           type: 'keyUp',
           key,
           code: params.code || key,
           modifiers,
+          ...vkParams,
         });
       } finally {
         await debuggerDetach(tab.id);
@@ -1812,6 +2043,8 @@ async function dispatch(port, method, params) {
     }
 
     case 'scroll': {
+      // v1.22: NO activate — CDP Input.dispatchMouseEvent goes via debugger directly to target,
+      // doesn't need active tab. Re-activating on every scroll-call destabilizes debugger.
       const tab = await getSessionTab(port);
       if (tab.url.startsWith('chrome://')) throw new Error('Cannot interact with chrome:// pages');
       // Scroll to element
@@ -1820,20 +2053,32 @@ async function dispatch(port, method, params) {
         if (!el) return { ok: false, error: 'Element not found: ' + params.selector };
         return { ok: true, scrolled_to: params.selector };
       }
-      // Scroll by pixels using CDP mouseWheel — works in React containers with overflow:scroll
+      // Scroll by pixels using CDP mouseWheel — split into smaller steps so IntersectionObservers fire.
+      // FB/Twitter/IG only trigger lazy-load on continuous wheel events, not a single large delta.
       const dx = params.x || 0;
       const dy = params.y || 0;
       try {
         await debuggerAttach(tab.id);
-        await cdpSend(tab.id, 'Input.dispatchMouseEvent', {
-          type: 'mouseWheel', x: 400, y: 300, deltaX: dx, deltaY: dy,
-        });
-        await debuggerDetach(tab.id);
-      } catch {
-        // Fallback to window.scrollBy for simple pages
+        const STEP_SIZE = 300; // pixels per wheel-event (matches a typical mouse-wheel notch)
+        const totalSteps = Math.max(1, Math.ceil(Math.max(Math.abs(dx), Math.abs(dy)) / STEP_SIZE));
+        const stepX = dx / totalSteps;
+        const stepY = dy / totalSteps;
+        for (let i = 0; i < totalSteps; i++) {
+          await cdpSend(tab.id, 'Input.dispatchMouseEvent', {
+            type: 'mouseWheel', x: 400, y: 300, deltaX: stepX, deltaY: stepY,
+          });
+          // Small delay between wheel-events so IntersectionObserver + lazy-load XHRs can fire
+          if (i < totalSteps - 1) await new Promise(r => setTimeout(r, 80));
+        }
+        // After last wheel-event, give FB/Twitter/IG ~600ms to start lazy-load XHRs
+        // before any subsequent commands run (caller often scrapes immediately after)
+        await new Promise(r => setTimeout(r, 600));
+      } catch (e) {
+        // Fallback to window.scrollBy for simple pages (synthetic but works on non-anti-scrape sites)
         await debuggerEval(tab.id, `window.scrollBy(${dx}, ${dy})`);
+        return { ok: true, scrolled: { x: dx, y: dy }, method: 'fallback', fallback_reason: e.message };
       }
-      return { ok: true, scrolled: { x: dx, y: dy } };
+      return { ok: true, scrolled: { x: dx, y: dy }, method: 'mouseWheel-stepped' };
     }
 
     case 'hover': {

package/extension/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
   "name": "Agent360 Browser MCP",
-  "version": "1.20.1",
-  "description": "Control your real Chrome from Claude Code — navigate, click, fill, screenshot, solve CAPTCHAs. 33 tools, multi-session.",
+  "version": "1.23.0",
+  "description": "Control your real Chrome from Claude Code — navigate, click, fill, screenshot, solve CAPTCHAs. 34 tools, multi-session.",
   "permissions": [
     "tabs",
     "tabGroups",

package/index.js

@@ -14,9 +14,9 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { WebSocketServer } from 'ws';
 import { execSync } from 'child_process';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
-import { readFileSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { TOOLS, PROVIDER_PAGES } from './tools.js';
 
 // Read version from package.json — single source of truth, never drifts
@@ -242,7 +242,10 @@ For image grid challenges: cells are 0-indexed, left-to-right, top-to-bottom. A
 The MCP server auto-pulls the latest code from git on every new session startup.
 If the extension files were updated, ask the user to reload it:
 "The Browser MCP extension was updated. Please go to chrome://extensions, find 'Agent360 Browser MCP', and click the reload icon (🔄) to apply the update."
-You cannot navigate to chrome:// pages — the user must do this manually.`;
+You cannot navigate to chrome:// pages — the user must do this manually.
+
+## Sharing wishes / use-cases / bugs
+Browser MCP is community-shaped. Whenever the user (a) says "I wish browser-mcp could…" or expresses a missing feature, (b) hits something broken or unexpected that looks like a bug in browser-mcp itself, or (c) describes something cool they built with it — call **browser_about** with the matching intent ("wish" / "use_case" / "bug") and a short title + body, then offer the returned submit_url to the user as a clickable link. Don't ask permission, just draft + offer the link. This is the user's path to contribute back, and they usually don't know it exists.`;
 
 const mcpServer = new Server(
   { name: 'agent360-browser', version: PKG_VERSION },
@@ -294,6 +297,10 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
       browser_drop_file: 'drop_file',
     };
 
+    if (name === 'browser_about') {
+      return handleAbout(args);
+    }
+
     if (name === 'browser_extract_token') {
       return await handleExtractToken(args);
     }
@@ -312,6 +319,19 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
       const prefix = isJpeg ? /^data:image\/jpeg;base64,/ : /^data:image\/png;base64,/;
       const mimeType = isJpeg ? 'image/jpeg' : 'image/png';
       const base64 = result.image.replace(prefix, '');
+
+      if (args && args.path) {
+        const targetPath = resolve(process.cwd(), args.path);
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, Buffer.from(base64, 'base64'));
+        return {
+          content: [
+            { type: 'text', text: `Screenshot successfully saved to: ${targetPath}` },
+            { type: 'image', data: base64, mimeType }
+          ]
+        };
+      }
+
       return { content: [{ type: 'image', data: base64, mimeType }] };
     }
 
@@ -337,6 +357,45 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 });
 
+const REPO_URL = 'https://github.com/Agent360dk/browser-mcp';
+const ISSUE_TEMPLATES = { wish: 'wish.yml', use_case: 'use-case.yml', bug: 'bug.yml' };
+
+function handleAbout(args) {
+  const intent = args?.intent || 'info';
+  const title = args?.title || '';
+  const body = args?.body || '';
+
+  const submit_url = intent === 'info' || !ISSUE_TEMPLATES[intent]
+    ? `${REPO_URL}/issues/new/choose`
+    : `${REPO_URL}/issues/new?template=${ISSUE_TEMPLATES[intent]}` +
+      (title ? `&title=${encodeURIComponent(title)}` : '') +
+      (body ? `&body=${encodeURIComponent(body)}` : '');
+
+  const instruction =
+    intent === 'wish'
+      ? `Share this exact submission link with the user as a clickable link, with a short note like "Click to submit your wish — it'll open a pre-filled GitHub issue you can review before submitting": ${submit_url}`
+      : intent === 'use_case'
+      ? `Share this exact submission link with the user as a clickable link, with a short note like "Click to share your use-case — pre-filled, you can edit before submitting": ${submit_url}`
+      : intent === 'bug'
+      ? `Share this exact bug-report link with the user as a clickable link, with a short note like "Click to report — pre-filled, please add reproduction steps before submitting": ${submit_url}`
+      : `Browser MCP is community-shaped. Open wishlist: ${REPO_URL}/blob/main/WISHLIST.md · Use-cases: ${REPO_URL}/blob/main/USE_CASES.md · Submit anything: ${REPO_URL}/issues/new/choose`;
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify({
+        name: 'Browser MCP by Agent360',
+        version: PKG_VERSION,
+        repo: REPO_URL,
+        wishlist: `${REPO_URL}/blob/main/WISHLIST.md`,
+        use_cases: `${REPO_URL}/blob/main/USE_CASES.md`,
+        submit_url,
+        instruction,
+      }, null, 2),
+    }],
+  };
+}
+
 async function handleExtractToken(args) {
   const { provider, store_in_vault } = args;
   const info = PROVIDER_PAGES[provider];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agent360/browser-mcp",
-  "version": "1.20.1",
-  "description": "Browser MCP — control your real Chrome from Claude Code. 33 tools, CAPTCHA solving, date pickers, autocomplete combobox, overlay dismissal, file upload, multi-session, human-in-the-loop.",
+  "version": "1.23.0",
+  "description": "Browser MCP — control your real Chrome from Claude Code. 34 tools, CAPTCHA solving, date pickers, autocomplete combobox, overlay dismissal, file upload, multi-session, human-in-the-loop.",
   "mcpName": "io.github.Agent360dk/browser-mcp",
   "type": "module",
   "main": "index.js",

package/tools.js

@@ -29,8 +29,13 @@ export const TOOLS = [
   },
   {
     name: 'browser_screenshot',
-    description: 'Take a screenshot of the visible area of the current tab. Returns base64 PNG.',
-    inputSchema: { type: 'object', properties: {} },
+    description: 'Take a screenshot of the visible area of the current tab. Returns base64 PNG, or saves to disk if path is provided.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'File path to save the screenshot to (e.g. /path/to/screenshot.png)' },
+      },
+    },
   },
   {
     name: 'browser_execute_script',
@@ -398,6 +403,28 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: 'browser_about',
+    description: 'Returns Browser MCP info and pre-filled URLs the user can click to submit feature wishes, share use-cases, or report bugs. Call this PROACTIVELY whenever the user (a) mentions a feature they wish existed ("I wish browser-mcp could...", "it would be nice if..."), (b) says something is missing, broken, or unexpected, (c) asks how Browser MCP works or who maintains it, or (d) describes something cool they built with browser-mcp. Pass intent="wish" | "use_case" | "bug" | "info" plus an optional title and body, and offer the returned submit_url to the user. Browser MCP is community-shaped — this tool is how the user contributes back.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: {
+          type: 'string',
+          enum: ['wish', 'use_case', 'bug', 'info'],
+          description: 'What the user wants to share. "wish" = feature request, "use_case" = share what they built, "bug" = something broken, "info" = general (default: "info").',
+        },
+        title: {
+          type: 'string',
+          description: 'Optional pre-filled issue title (e.g. "Support hCaptcha v3"). Will be URL-encoded into the submit link.',
+        },
+        body: {
+          type: 'string',
+          description: 'Optional pre-filled body / first-comment draft. Will be URL-encoded into the submit link. Keep it short; user can expand on GitHub.',
+        },
+      },
+    },
+  },
 ];
 
 // Known provider token pages for browser_extract_token