mcp-browser-extension 0.9.28 → 0.9.30

package/README.md

@@ -6,7 +6,7 @@
 
 **Website and docs:** [mcp-browser-extension.com](https://mcp-browser-extension.com) ·
 [Quickstart](https://mcp-browser-extension.com/docs/quickstart) ·
-[All 42 tools](https://mcp-browser-extension.com/docs/tools) ·
+[All 43 tools](https://mcp-browser-extension.com/docs/tools) ·
 [Install the extension from the Chrome Web Store](https://chromewebstore.google.com/detail/mcp-browser-extension/jelfhdlkhbfmlpbghoeaepijllcnplgh)
 
 **Let Claude use the Chrome you are already logged into.** Not a fresh
@@ -447,7 +447,7 @@ Reading the DOM tells you what a page looks like after it failed, not why. With
 and `fetch`/`XMLHttpRequest` traffic, and intercepts native dialogs:
 
 ```jsonc
-console_logs { "level": "error" }        // the exception the page swallowed
+console_logs { "level": "exception" }    // the uncaught error behind a broken page
 network_log  { "failedOnly": true }      // the 500 behind the blank screen
 dialogs      { "policy": "accept" }      // answer confirm() with true from here on
 ```
@@ -487,6 +487,24 @@ refs renumber in document order on every snapshot, so diffing on them would
 report an unchanged button as removed-and-re-added the moment anything above it
 appears.
 
+### Remember a page and catch changes later — `page_watch`
+
+Save a named accessibility checkpoint, then compare the current page against it
+in a later session. Checkpoints live under the active Chrome profile, so work
+and personal browser identities stay separate:
+
+```jsonc
+page_watch { "action": "create", "name": "Vendor pricing" }
+page_watch { "action": "compare", "watchId": "watch_…" }
+page_watch { "action": "list" }
+page_watch { "action": "delete", "watchId": "watch_…" }
+```
+
+The result shows added, removed and changed controls. It stores accessibility
+labels and control state, strips URL query strings, applies configured redaction,
+and never saves live form values. Creating or comparing a checkpoint still
+requires the page's domain to be allowed.
+
 ### Targeting by role and name
 
 Actions accept a locator instead of a CSS selector, so you don't need a snapshot

package/dist/shared/page-fns.d.ts

@@ -16,12 +16,18 @@
  * One resolver, used by every op, is what closes it.
  */
 /** Ops the page-side dispatcher understands. */
-export type PageOpName = 'probe' | 'text' | 'html' | 'click' | 'type' | 'focus' | 'point' | 'hover' | 'select' | 'measure' | 'scroll' | 'storage' | 'waitSelector' | 'waitFor';
+export type PageOpName = 'probe' | 'text' | 'html' | 'click' | 'check' | 'type' | 'focus' | 'point' | 'hover' | 'select' | 'measure' | 'scroll' | 'storage' | 'waitSelector' | 'waitFor';
 export interface PageOpArgs {
     op: PageOpName;
     selector?: string | null;
     text?: string;
     clear?: boolean;
+    /** type: send keydown/keypress/keyup around each character. */
+    keyEvents?: boolean;
+    /** type: press Enter after the text (submits the field's form like a person would). */
+    pressEnter?: boolean;
+    /** check: the state a checkbox/radio should end up in. */
+    checked?: boolean;
     outer?: boolean;
     values?: string[];
     x?: number | null;

package/dist/shared/page-fns.js

@@ -208,6 +208,18 @@ function pageOp(a) {
                 el.click();
                 return { found: true };
             }
+            case 'check': {
+                if (!el)
+                    return { found: false };
+                // Click only when the state differs: a click toggles, so clicking an
+                // already-checked box to "check" it would clear it.
+                const box = el;
+                if (box.checked !== (a.checked !== false)) {
+                    el.scrollIntoView({ block: 'center' });
+                    el.click();
+                }
+                return { found: true, checked: box.checked };
+            }
             case 'type': {
                 if (!el)
                     return { found: false };
@@ -226,9 +238,32 @@ function pageOp(a) {
                 if (!node)
                     return { found: false };
                 node.focus();
-                const next = (a.clear ? '' : node.value ?? '') + (a.text ?? '');
-                setValue(node, next);
+                if (a.keyEvents) {
+                    // One character at a time, each inside its own key events, for pages
+                    // that react to keystrokes rather than to the value.
+                    if (a.clear)
+                        setValue(node, '');
+                    for (const ch of a.text ?? '') {
+                        const ev = { key: ch, bubbles: true, cancelable: true };
+                        const go = node.dispatchEvent(new KeyboardEvent('keydown', ev));
+                        if (go && node.dispatchEvent(new KeyboardEvent('keypress', ev)))
+                            setValue(node, (node.value ?? '') + ch);
+                        node.dispatchEvent(new KeyboardEvent('keyup', ev));
+                    }
+                }
+                else {
+                    setValue(node, (a.clear ? '' : node.value ?? '') + (a.text ?? ''));
+                }
                 node.dispatchEvent(new Event('change', { bubbles: true }));
+                if (a.pressEnter) {
+                    const ev = { key: 'Enter', code: 'Enter', keyCode: 13, which: 13, bubbles: true, cancelable: true };
+                    const go = node.dispatchEvent(new KeyboardEvent('keydown', ev)) && node.dispatchEvent(new KeyboardEvent('keypress', ev));
+                    node.dispatchEvent(new KeyboardEvent('keyup', ev));
+                    // Synthetic key events never trigger implicit submission; do what the
+                    // browser would for Enter in a single-line field of a form.
+                    if (go && node instanceof HTMLInputElement && node.form)
+                        node.form.requestSubmit();
+                }
                 return { found: true };
             }
             case 'focus': {

package/dist/shared/policy.js

@@ -34,6 +34,12 @@ const READ_CONTENT = new Set([
     'frames_list',
     'observers',
     'print_pdf',
+    // The page's accessibility tree, its cookies (session secrets), and its
+    // web storage are content too. A storage write is refused in safe mode by
+    // the extension's storage handler; the domain gate here covers every op.
+    'snapshot',
+    'get_cookies',
+    'storage',
 ]);
 /** Content-mutating actions — URL-gated AND mutation-gated. */
 const MUTATE_CONTENT = new Set([
@@ -44,6 +50,7 @@ const MUTATE_CONTENT = new Set([
     'hover',
     'scroll',
     'fill_form',
+    'select_option',
 ]);
 /** Navigation — URL-gated by the DESTINATION url, and mutation-gated. */
 const NAVIGATION = new Set([
@@ -72,7 +79,9 @@ function isUrlGated(method) {
         MUTATE_CONTENT.has(method) ||
         NAVIGATION.has(method) ||
         method === 'eval' ||
-        method === 'upload_file');
+        method === 'upload_file' ||
+        // Gated on where the bytes come from: the URL when one is given, else the tab.
+        method === 'download_file');
 }
 // ---------------------------------------------------------------------------
 // Domain matching

package/dist/shared/snapshot.js

@@ -72,6 +72,13 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             if (t)
                 return t;
         }
+        // <label for> or a wrapping <label>: how ordinary forms name their fields.
+        const labels = el.labels;
+        if (labels && labels.length > 0) {
+            const t = Array.from(labels).map((l) => l.innerText).join(' ').replace(/\s+/g, ' ').trim();
+            if (t)
+                return t;
+        }
         const ph = el.getAttribute('placeholder');
         if (ph)
             return ph.trim();
@@ -113,8 +120,11 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
     // recursively. Defensive against null/closed shadow roots and re-visits.
     const seen = new Set();
     const candidates = [];
+    // Gather past `max` so hidden candidates dropped below still leave enough to
+    // fill it, and so a page with more than `max` can be reported as truncated.
+    const cap = Math.max(max * 2, max + 50);
     const collect = (root) => {
-        if (candidates.length >= max)
+        if (candidates.length >= cap)
             return;
         let matched;
         try {
@@ -124,7 +134,7 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             matched = [];
         }
         for (let i = 0; i < matched.length; i++) {
-            if (candidates.length >= max)
+            if (candidates.length >= cap)
                 break;
             const el = matched[i];
             if (seen.has(el))
@@ -142,7 +152,7 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
             hosts = [];
         }
         for (let i = 0; i < hosts.length; i++) {
-            if (candidates.length >= max)
+            if (candidates.length >= cap)
                 break;
             const sr = hosts[i].shadowRoot;
             if (sr)
@@ -230,7 +240,8 @@ function collectSnapshot(interactiveOnly = true, max = 200, locator = null) {
                 break;
             picked.push(read(el));
         }
-        truncated = els.length > picked.length;
+        // At the cap there may be more on the page than were even looked at.
+        truncated = els.length > picked.length || candidates.length >= cap;
     }
     // -- phase 2: writes (one attribute per returned node) ----------------------
     const nodes = [];

package/dist/src/bridge/host-claim.d.ts

@@ -0,0 +1,17 @@
+/**
+ * src/bridge/host-claim.ts — retire a server its MCP host has replaced.
+ *
+ * Some hosts (Claude Code's /mcp "Reconnect" among them) spawn a fresh child
+ * without closing the old one's stdin or signalling it. The old server then
+ * lingers with its OLD flags and, if it holds the port, keeps serving the
+ * browser: a reconnect that was meant to apply a new flag silently doesn't.
+ *
+ * Each stdio server claims `hosts/<parentPid>-<profile>` on start. The newest
+ * claim wins; an older server that finds someone else's pid in its claim file
+ * knows the same host replaced it and shuts itself down. Nothing is ever killed
+ * here, so a recycled pid cannot cause a wrong kill.
+ */
+/** Record this process as the current server for (parent, profile). */
+export declare function claimHost(dataDir: string, parentPid: number, profile: string, pid?: number): void;
+/** True when a newer server from the same parent has claimed (parent, profile). */
+export declare function supersededBy(dataDir: string, parentPid: number, profile: string, pid?: number): number | null;

package/dist/src/bridge/host-claim.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * src/bridge/host-claim.ts — retire a server its MCP host has replaced.
+ *
+ * Some hosts (Claude Code's /mcp "Reconnect" among them) spawn a fresh child
+ * without closing the old one's stdin or signalling it. The old server then
+ * lingers with its OLD flags and, if it holds the port, keeps serving the
+ * browser: a reconnect that was meant to apply a new flag silently doesn't.
+ *
+ * Each stdio server claims `hosts/<parentPid>-<profile>` on start. The newest
+ * claim wins; an older server that finds someone else's pid in its claim file
+ * knows the same host replaced it and shuts itself down. Nothing is ever killed
+ * here, so a recycled pid cannot cause a wrong kill.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claimHost = claimHost;
+exports.supersededBy = supersededBy;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const atomic_file_1 = require("../atomic-file");
+function claimPath(dataDir, parentPid, profile) {
+    const safe = profile.replace(/[^A-Za-z0-9._-]/g, '_') || 'default';
+    return (0, node_path_1.join)(dataDir, 'hosts', `${parentPid}-${safe}`);
+}
+/** Record this process as the current server for (parent, profile). */
+function claimHost(dataDir, parentPid, profile, pid = process.pid) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dataDir, 'hosts'), { recursive: true, mode: 0o700 });
+    (0, atomic_file_1.writeFileAtomic)(claimPath(dataDir, parentPid, profile), `${pid}\n`, 0o600);
+}
+/** True when a newer server from the same parent has claimed (parent, profile). */
+function supersededBy(dataDir, parentPid, profile, pid = process.pid) {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(claimPath(dataDir, parentPid, profile), 'utf8');
+    }
+    catch {
+        return null; // missing or unreadable: never retire on doubt
+    }
+    const owner = Number.parseInt(text.trim(), 10);
+    return Number.isInteger(owner) && owner > 0 && owner !== pid ? owner : null;
+}
+//# sourceMappingURL=host-claim.js.map

package/dist/src/cli.js

@@ -19,6 +19,8 @@ const tasks_1 = require("./bridge/tasks");
 const manager_1 = require("./executor/manager");
 const select_1 = require("./executor/select");
 const server_1 = require("./bridge/server");
+const policy_1 = require("./security/policy");
+const host_claim_1 = require("./bridge/host-claim");
 const datadir_1 = require("./bridge/datadir");
 const workspace_1 = require("./bridge/workspace");
 const auth_1 = require("./bridge/auth");
@@ -260,14 +262,10 @@ async function main() {
     (0, tools_1.setToolAllowlist)(cfg.tools);
     const dataDir = (0, datadir_1.ensureDataDir)(cfg.dataDir);
     const token = (0, auth_1.resolveToken)(dataDir, { persist: cfg.persistToken });
-    const { allowDomains, allowEval, allowDownloads, allowUploads, allowAllTabs, enableMutations } = cfg.policy;
     const bridge = new server_1.BridgeServer({
         token,
         serverVersion: version(),
-        // Wire-serializable policy subset (no local uploadsDir) so the extension mirrors the gate.
-        // `allowDomains` is passed BY REFERENCE: sites allowed from the extension's
-        // Options are spliced into this same array, which the tool gate reads too.
-        policy: { allowDomains, allowEval, allowDownloads, allowUploads, allowAllTabs, enableMutations },
+        policy: (0, policy_1.toWirePolicy)(cfg.policy),
         siteGrants: !cfg.noSiteGrants,
         latestExtensionVersion: bundledExtensionVersion(),
         port: cfg.wsPort,
@@ -436,9 +434,23 @@ async function main() {
     // holding the port, and its usage is never reported. Notice instead when the
     // parent is gone, or when writing to it fails.
     const parentPid = process.ppid;
+    // A host that "reconnects" by spawning a new child may leave us running with
+    // our old flags; the newest server from the same parent claims the slot.
+    const hostProfile = cfg.profile ?? 'default';
+    try {
+        (0, host_claim_1.claimHost)(dataDir, parentPid, hostProfile);
+    }
+    catch (err) {
+        (0, server_2.logDebug)(`host claim skipped: ${err.message}`);
+    }
     const watchdog = setInterval(() => {
         if (process.ppid !== parentPid)
             return shutdown(); // reparented: the parent exited
+        const newer = (0, host_claim_1.supersededBy)(dataDir, parentPid, hostProfile);
+        if (newer !== null) {
+            (0, server_2.logErr)(`replaced by a newer server (pid ${newer}) from the same MCP host; exiting`);
+            return shutdown();
+        }
         try {
             process.kill(parentPid, 0);
         }

package/dist/src/executor/cdp-executor.d.ts

@@ -97,6 +97,9 @@ export declare class CdpExecutor implements Executor {
     selectOption(t: Target, values: string[], opts?: {
         tabId?: TabId;
     }): Promise<ActionOk>;
+    setChecked(t: Target, checked: boolean, opts?: {
+        tabId?: TabId;
+    }): Promise<ActionOk>;
     fill(t: Target, value: string, opts?: {
         tabId?: TabId;
     }): Promise<ActionOk>;

package/dist/src/executor/cdp-executor.js

@@ -272,8 +272,15 @@ class CdpExecutor {
         catch (err) {
             const msg = err.message ?? '';
             if (CLOSED_TARGET.test(msg)) {
+                const stale = this.context;
                 this.context = null;
                 this.tabs.clear();
+                // A browser we launched is ours to close; otherwise the relaunch on the
+                // next call leaves this one running. Never close the user's Chrome.
+                if (this.opts.mode !== 'connect' && this.launched) {
+                    this.launched = false;
+                    void stale?.close().catch(() => undefined);
+                }
                 throw new types_1.ExecutorError('DETACHED', 'browser target closed or crashed; reconnect and retry');
             }
             throw err;
@@ -397,6 +404,13 @@ class CdpExecutor {
             return this.ok;
         });
     }
+    async setChecked(t, checked, opts) {
+        return this.guard(async () => {
+            const p = await this.resolveTab(opts?.tabId);
+            await this.locator(p, t).setChecked(checked);
+            return this.ok;
+        });
+    }
     async fill(t, value, opts) {
         return this.guard(async () => {
             const p = await this.resolveTab(opts?.tabId);

package/dist/src/executor/extension-executor.js

@@ -168,10 +168,20 @@ class ExtensionExecutor {
         return (await this.send('type', { ...targetParams(t), ...frameParams(opts), text: value, clear: true, keyEvents: false }, { tabId: opts?.tabId }));
     }
     async fillFields(fields, opts) {
-        // An extension that predates the op never advertised it: let the caller go field by field.
-        if (!this.bridge.hasCap(this.activeProfile(), protocol_1.WIRE_CAP_FILL_FORM))
-            return null;
-        const res = (await this.send('fill_form', { ops: fields, ...frameParams(opts) }, { tabId: opts?.tabId, timeoutMs: (0, protocol_1.fillFormTimeoutMs)(fields.length) }));
+        // No capability pre-check alone: a server relaying through another one (a
+        // second AI session) cannot see the extension's caps, so ask and read the
+        // answer. An extension that predates the op says it has no such method:
+        // then let the caller go field by field.
+        let res;
+        try {
+            res = (await this.send('fill_form', { ops: fields, ...frameParams(opts) }, { tabId: opts?.tabId, timeoutMs: (0, protocol_1.fillFormTimeoutMs)(fields.length) }));
+        }
+        catch (err) {
+            if (!this.bridge.hasCap(this.activeProfile(), protocol_1.WIRE_CAP_FILL_FORM) && err instanceof types_1.ExecutorError && /unhandled method/.test(err.message)) {
+                return null;
+            }
+            throw err;
+        }
         if (res.error) {
             // Say how far the batch got: the fields before this one DID land, and a
             // blind retry of the whole form would write them a second time.

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

@@ -361,6 +361,10 @@ export interface Executor {
     } & FrameOpts): Promise<{
         filled: number;
     } | null>;
+    /** Put a checkbox/radio into `checked` (no-op when it already is). */
+    setChecked?(t: Target, checked: boolean, opts?: {
+        tabId?: TabId;
+    } & FrameOpts): Promise<ActionOk>;
     /** Every frame of a tab that the extension can inject into, with its URL. */
     framesList?(opts?: {
         tabId?: TabId;

package/dist/src/mcp/helpers.js

@@ -166,8 +166,17 @@ async function fillForm(ex, args) {
         for (const { selector, value } of ops) {
             const target = { selector };
             if (typeof value === 'boolean') {
-                // Checkbox/radio: a click toggles it.
-                await ex.click(target, opts);
+                // Checkbox/radio: set the state. A bare click toggles, so it is only
+                // right for a backend that cannot set it, and only to turn it on.
+                if (ex.setChecked)
+                    await ex.setChecked(target, value, opts);
+                else if (value)
+                    await ex.click(target, opts);
+                else {
+                    // Unticking needs the current state, which this backend cannot read;
+                    // a silent no-op would report a field as filled that was not.
+                    throw new types_1.ExecutorError('UNSUPPORTED', `cannot set ${selector} to unchecked with this browser backend; update the MCP Browser Extension`);
+                }
             }
             else {
                 await ex.fill(target, value, opts);

package/dist/src/mcp/page-watch.d.ts

@@ -0,0 +1,12 @@
+import type { SnapshotResult } from '../executor/types';
+import type { SnapshotDiff, StoredSnapshot } from './snapdiff';
+export interface PageWatch extends StoredSnapshot {
+    name: string;
+}
+/** Keep enough structure for useful diffs while never persisting live form values. */
+export declare function safeSnapshot(snap: SnapshotResult, redact: (s: string) => string): SnapshotResult;
+export declare function createWatch(profileDir: string, name: string, snap: SnapshotResult): PageWatch;
+export declare function readWatch(profileDir: string, id: string): PageWatch;
+export declare function listWatches(profileDir: string): Array<Pick<PageWatch, 'id' | 'name' | 'ts' | 'url'>>;
+export declare function removeWatch(profileDir: string, id: string): void;
+export declare function compareWatch(previous: PageWatch, current: SnapshotResult, redact: (s: string) => string): SnapshotDiff;

package/dist/src/mcp/page-watch.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeSnapshot = safeSnapshot;
+exports.createWatch = createWatch;
+exports.readWatch = readWatch;
+exports.listWatches = listWatches;
+exports.removeWatch = removeWatch;
+exports.compareWatch = compareWatch;
+/** Persistent, profile-scoped accessibility checkpoints for pages the user allows. */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const snapdiff_1 = require("./snapdiff");
+function root(profileDir) {
+    const dir = (0, node_path_1.join)(profileDir, 'page-watches');
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+function watchPath(profileDir, id) {
+    if (!/^watch_[0-9a-f-]{36}$/i.test(id))
+        throw new Error('invalid watchId');
+    return (0, node_path_1.join)(root(profileDir), `${id}.json`);
+}
+/** Keep enough structure for useful diffs while never persisting live form values. */
+function safeSnapshot(snap, redact) {
+    const nodes = snap.nodes.slice(0, 500).map((node) => {
+        const { value: _privateValue, ...safe } = node;
+        return { ...safe, name: redact(safe.name) };
+    });
+    let url = snap.url;
+    try {
+        const parsed = new URL(url);
+        parsed.search = '';
+        parsed.hash = '';
+        url = parsed.toString();
+    }
+    catch { /* keep non-URL test fixtures as given */ }
+    return { url, title: redact(snap.title), nodes, truncated: snap.truncated };
+}
+function createWatch(profileDir, name, snap) {
+    const id = `watch_${(0, node_crypto_1.randomUUID)()}`;
+    const watch = { id, name, ts: Date.now(), url: snap.url, nodes: snap.nodes };
+    const dir = root(profileDir);
+    const temp = (0, node_path_1.join)(dir, `.${id}.${process.pid}.tmp`);
+    (0, node_fs_1.writeFileSync)(temp, JSON.stringify(watch), { mode: 0o600, flag: 'wx' });
+    (0, node_fs_1.renameSync)(temp, watchPath(profileDir, id));
+    return watch;
+}
+function readWatch(profileDir, id) {
+    const path = watchPath(profileDir, id);
+    if (!(0, node_fs_1.existsSync)(path))
+        throw new Error(`page watch not found: ${id}`);
+    const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    if (parsed.id !== id || !Array.isArray(parsed.nodes))
+        throw new Error('page watch file is invalid');
+    return parsed;
+}
+function listWatches(profileDir) {
+    return (0, node_fs_1.readdirSync)(root(profileDir)).filter((f) => /^watch_[0-9a-f-]{36}\.json$/i.test(f)).flatMap((file) => {
+        try {
+            const { id, name, ts, url } = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(root(profileDir), file), 'utf8'));
+            return [{ id, name, ts, url }];
+        }
+        catch {
+            return [];
+        }
+    }).sort((a, b) => b.ts - a.ts);
+}
+function removeWatch(profileDir, id) {
+    const path = watchPath(profileDir, id);
+    if (!(0, node_fs_1.existsSync)(path))
+        throw new Error(`page watch not found: ${id}`);
+    (0, node_fs_1.rmSync)(path);
+}
+function compareWatch(previous, current, redact) {
+    const clean = safeSnapshot(current, redact);
+    return (0, snapdiff_1.diffSnapshots)(previous, { ...clean, nodes: clean.nodes });
+}
+//# sourceMappingURL=page-watch.js.map