@mehmoodqureshi/chrome-mcp 0.6.7 → 0.7.0

package/dist/src/mcp/locate.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * src/mcp/locate.ts — target an element by what it IS rather than by where it
+ * sits in the DOM.
+ *
+ * Today every action needs a CSS selector or a `ref` from a snapshot, so the
+ * cheapest way to click "Sign in" is to pull the whole accessibility tree first
+ * and read a ref out of it. That is a large read to perform one small action,
+ * and a hand-written selector is the alternative that breaks on the next
+ * redeploy.
+ *
+ * A locator closes that: `{ role: 'button', name: 'Sign in' }` resolves through
+ * one snapshot, server-side, and the caller never sees the tree. Matching runs
+ * strongest-first (exact, then case-insensitive, then contains) so an
+ * unambiguous name wins outright, and an ambiguous one fails loudly with the
+ * candidates rather than silently clicking the first row.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasLocator = hasLocator;
+exports.resolveLocator = resolveLocator;
+const validators_1 = require("./validators");
+/** Was a locator supplied at all? */
+function hasLocator(l) {
+    return !!l && (l.role !== undefined || l.name !== undefined || l.text !== undefined);
+}
+const norm = (s) => s.replace(/\s+/g, ' ').trim().toLowerCase();
+/**
+ * Rank a node against the locator. Higher is better; 0 means no match.
+ * The tiers are what make an exact name beat a substring of a longer label.
+ */
+function score(node, want) {
+    if (want.role && norm(node.role) !== norm(want.role))
+        return 0;
+    if (!want.name)
+        return 1; // role-only locator: any node of that role
+    const have = norm(node.name);
+    const need = norm(want.name);
+    if (!have)
+        return 0;
+    if (node.name.trim() === want.name.trim())
+        return 4; // exact, case-sensitive
+    if (have === need)
+        return 3; // exact, case-insensitive
+    if (have.startsWith(need))
+        return 2;
+    if (have.includes(need))
+        return 1;
+    return 0;
+}
+/**
+ * Resolve a locator to a `ref` by taking one snapshot of the target tab.
+ *
+ * Throws `McpToolError` when nothing matches or when the best tier is ambiguous
+ * — an ambiguous click is a wrong click, and the message lists what it found so
+ * the caller can narrow it (or pass `nth`).
+ */
+async function resolveLocator(ex, loc, opts = {}) {
+    const want = { role: loc.role, name: loc.name ?? loc.text };
+    const snap = await ex.snapshot({
+        tabId: opts.tabId,
+        interactiveOnly: false,
+        max: 400,
+        frameId: opts.frameId,
+        allFrames: opts.allFrames,
+    });
+    let best = 0;
+    let winners = [];
+    for (const node of snap.nodes) {
+        const s = score(node, want);
+        if (s === 0)
+            continue;
+        if (s > best) {
+            best = s;
+            winners = [node];
+        }
+        else if (s === best) {
+            winners.push(node);
+        }
+    }
+    const describe = (n) => `${n.role} "${n.name}"`;
+    if (winners.length === 0) {
+        const sample = snap.nodes
+            .filter((n) => !want.role || norm(n.role) === norm(want.role))
+            .slice(0, 8)
+            .map(describe);
+        throw new validators_1.McpToolError(`no element matches ${JSON.stringify(want)}. ` +
+            (sample.length
+                ? `Closest by role: ${sample.join(', ')}. `
+                : 'Nothing on the page has that role. ') +
+            'Take a `snapshot` to see what is there, or target by `selector` instead.');
+    }
+    if (loc.nth !== undefined) {
+        const picked = winners[loc.nth];
+        if (!picked) {
+            throw new validators_1.McpToolError(`nth=${loc.nth} is out of range: ${winners.length} element(s) match ${JSON.stringify(want)}`);
+        }
+        return { target: { ref: picked.ref }, node: picked, matches: winners.length };
+    }
+    if (winners.length > 1) {
+        throw new validators_1.McpToolError(`${winners.length} elements match ${JSON.stringify(want)}: ${winners.slice(0, 6).map(describe).join(', ')}. ` +
+            'Narrow the name, add a role, or pass `nth` to choose one.');
+    }
+    return { target: { ref: winners[0].ref }, node: winners[0], matches: 1 };
+}
+//# sourceMappingURL=locate.js.map

package/dist/src/mcp/redact.d.ts

@@ -0,0 +1,48 @@
+/**
+ * src/mcp/redact.ts — keep secrets that happen to be on the page out of the
+ * model's context.
+ *
+ * The premise of this tool is that it drives a browser you are already logged
+ * into. That is also the problem: `get_text` / `get_html` / `read_as_markdown` /
+ * `eval` return whatever is on the page, and on a logged-in page that routinely
+ * includes a session token rendered into a script tag, an API key on a settings
+ * screen, or the value sitting in a password field. The domain allowlist decides
+ * WHICH pages may be read; it has nothing to say about what comes back from one
+ * that is allowed.
+ *
+ * Two layers, deliberately different in strength:
+ *   - password-field values are ALWAYS suppressed. That one is unambiguous — no
+ *     caller ever wants the characters in a `<input type=password>` — so it
+ *     needs no flag and has no false positives.
+ *   - pattern redaction (JWTs, cloud keys, bearer tokens, private key blocks) is
+ *     opt-in via `--redact`, because a pattern can and will fire on something a
+ *     user legitimately asked to read.
+ */
+export interface RedactionConfig {
+    /** Pattern-based redaction (the opt-in layer). Password fields are handled regardless. */
+    enabled: boolean;
+    /** Extra caller-supplied patterns, already compiled. */
+    extra: RegExp[];
+}
+export declare const NO_REDACTION: RedactionConfig;
+/**
+ * Compile a user-supplied pattern. Invalid regexes are a configuration error
+ * worth failing loudly on — silently ignoring one would leave the user believing
+ * a secret is being scrubbed when it is not.
+ */
+export declare function compileRedactionPattern(source: string): RegExp;
+export interface Redacted<T> {
+    value: T;
+    /** How many substitutions were made, so a caller can see redaction happened. */
+    redactions: number;
+}
+/** Replace every match of the configured patterns with a labelled marker. */
+export declare function redactText(text: string, cfg: RedactionConfig): Redacted<string>;
+/**
+ * Strip the `value` of every password input, then apply pattern redaction.
+ *
+ * The value attribute is emptied rather than removed so the markup keeps its
+ * shape — a caller reasoning about the form still sees the field, just not
+ * what is in it.
+ */
+export declare function redactHtml(html: string, cfg: RedactionConfig): Redacted<string>;

package/dist/src/mcp/redact.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * src/mcp/redact.ts — keep secrets that happen to be on the page out of the
+ * model's context.
+ *
+ * The premise of this tool is that it drives a browser you are already logged
+ * into. That is also the problem: `get_text` / `get_html` / `read_as_markdown` /
+ * `eval` return whatever is on the page, and on a logged-in page that routinely
+ * includes a session token rendered into a script tag, an API key on a settings
+ * screen, or the value sitting in a password field. The domain allowlist decides
+ * WHICH pages may be read; it has nothing to say about what comes back from one
+ * that is allowed.
+ *
+ * Two layers, deliberately different in strength:
+ *   - password-field values are ALWAYS suppressed. That one is unambiguous — no
+ *     caller ever wants the characters in a `<input type=password>` — so it
+ *     needs no flag and has no false positives.
+ *   - pattern redaction (JWTs, cloud keys, bearer tokens, private key blocks) is
+ *     opt-in via `--redact`, because a pattern can and will fire on something a
+ *     user legitimately asked to read.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_REDACTION = void 0;
+exports.compileRedactionPattern = compileRedactionPattern;
+exports.redactText = redactText;
+exports.redactHtml = redactHtml;
+exports.NO_REDACTION = { enabled: false, extra: [] };
+/** Well-known secret shapes. Each is anchored enough not to fire on prose. */
+const BUILTIN = [
+    { kind: 'private-key', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]{0,8000}?-----END [A-Z ]*PRIVATE KEY-----/g },
+    { kind: 'jwt', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+    { kind: 'aws-key', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+    { kind: 'github-token', re: /\bgh[pousr]_[A-Za-z0-9]{30,}\b/g },
+    { kind: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+    { kind: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/g },
+    { kind: 'api-key', re: /\bsk-[A-Za-z0-9_-]{20,}\b/g },
+    { kind: 'bearer', re: /\bBearer\s+[A-Za-z0-9._~+/-]{20,}={0,2}/g },
+];
+/**
+ * Compile a user-supplied pattern. Invalid regexes are a configuration error
+ * worth failing loudly on — silently ignoring one would leave the user believing
+ * a secret is being scrubbed when it is not.
+ */
+function compileRedactionPattern(source) {
+    return new RegExp(source, 'g');
+}
+/** Replace every match of the configured patterns with a labelled marker. */
+function redactText(text, cfg) {
+    if (!cfg.enabled || !text)
+        return { value: text, redactions: 0 };
+    let out = text;
+    let count = 0;
+    for (const { kind, re } of BUILTIN) {
+        out = out.replace(new RegExp(re.source, re.flags), () => {
+            count++;
+            return `[redacted:${kind}]`;
+        });
+    }
+    for (const re of cfg.extra) {
+        out = out.replace(new RegExp(re.source, re.flags.includes('g') ? re.flags : `${re.flags}g`), () => {
+            count++;
+            return '[redacted:custom]';
+        });
+    }
+    return { value: out, redactions: count };
+}
+/** Matches one complete `<input …>` tag so its attributes can be inspected. */
+const INPUT_TAG = /<input\b[^>]*>/gi;
+const VALUE_ATTR = /\bvalue\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/i;
+const PASSWORD_TYPE = /\btype\s*=\s*["']?password["']?/i;
+/**
+ * Strip the `value` of every password input, then apply pattern redaction.
+ *
+ * The value attribute is emptied rather than removed so the markup keeps its
+ * shape — a caller reasoning about the form still sees the field, just not
+ * what is in it.
+ */
+function redactHtml(html, cfg) {
+    if (!html)
+        return { value: html, redactions: 0 };
+    let count = 0;
+    let out = html.replace(INPUT_TAG, (tag) => {
+        if (!PASSWORD_TYPE.test(tag) || !VALUE_ATTR.test(tag))
+            return tag;
+        count++;
+        return tag.replace(VALUE_ATTR, 'value="[redacted:password]"');
+    });
+    const patterned = redactText(out, cfg);
+    out = patterned.value;
+    return { value: out, redactions: count + patterned.redactions };
+}
+//# sourceMappingURL=redact.js.map

package/dist/src/mcp/snapdiff.d.ts

@@ -0,0 +1,43 @@
+/**
+ * src/mcp/snapdiff.ts — remember the last accessibility snapshot per tab and
+ * answer "what changed" instead of re-sending the page.
+ *
+ * A snapshot is the most token-expensive read in the tool surface, and the agent
+ * loop that leans on it hardest — snapshot, click, snapshot, click — re-sends a
+ * page that is mostly identical every time. The diff is what the caller actually
+ * wanted: this button appeared, that error text is new, submit is no longer
+ * disabled.
+ *
+ * Refs (`e1`, `e2`, ...) are minted in document order on every snapshot, so they
+ * are NOT identity across snapshots: `e7` is a different element the moment
+ * anything above it is inserted. Nodes are therefore matched on role + tag +
+ * accessible name, and every diff entry carries the CURRENT ref, so anything the
+ * caller is told about is immediately targetable.
+ */
+import type { SnapshotNode, SnapshotResult } from '../executor/types';
+export interface StoredSnapshot {
+    id: string;
+    ts: number;
+    url: string;
+    nodes: SnapshotNode[];
+}
+export interface SnapshotDiff {
+    /** The snapshot this was compared against, or null when there was none. */
+    since: string | null;
+    added: SnapshotNode[];
+    removed: SnapshotNode[];
+    changed: Array<{
+        node: SnapshotNode;
+        was: Partial<SnapshotNode>;
+    }>;
+    unchanged: number;
+}
+/** Identity of a node ACROSS snapshots - deliberately not the ref. */
+export declare function nodeKey(n: SnapshotNode): string;
+/** Scope key: snapshots are per browser profile and per tab. */
+export declare function scopeOf(profile: string, tabId?: string): string;
+export declare function rememberSnapshot(scope: string, snap: SnapshotResult): StoredSnapshot;
+export declare function lastSnapshot(scope: string): StoredSnapshot | undefined;
+/** Forget everything - for tests, and whenever the active profile changes. */
+export declare function resetSnapshots(): void;
+export declare function diffSnapshots(prev: StoredSnapshot | undefined, next: SnapshotResult): SnapshotDiff;

package/dist/src/mcp/snapdiff.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * src/mcp/snapdiff.ts — remember the last accessibility snapshot per tab and
+ * answer "what changed" instead of re-sending the page.
+ *
+ * A snapshot is the most token-expensive read in the tool surface, and the agent
+ * loop that leans on it hardest — snapshot, click, snapshot, click — re-sends a
+ * page that is mostly identical every time. The diff is what the caller actually
+ * wanted: this button appeared, that error text is new, submit is no longer
+ * disabled.
+ *
+ * Refs (`e1`, `e2`, ...) are minted in document order on every snapshot, so they
+ * are NOT identity across snapshots: `e7` is a different element the moment
+ * anything above it is inserted. Nodes are therefore matched on role + tag +
+ * accessible name, and every diff entry carries the CURRENT ref, so anything the
+ * caller is told about is immediately targetable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeKey = nodeKey;
+exports.scopeOf = scopeOf;
+exports.rememberSnapshot = rememberSnapshot;
+exports.lastSnapshot = lastSnapshot;
+exports.resetSnapshots = resetSnapshots;
+exports.diffSnapshots = diffSnapshots;
+/** How many tabs' snapshots to keep. Small: a convenience cache, not state. */
+const MAX_SCOPES = 32;
+const store = new Map();
+let counter = 0;
+/** Identity of a node ACROSS snapshots - deliberately not the ref. */
+function nodeKey(n) {
+    return `${n.role} | ${n.tag} | ${n.name}`;
+}
+/** Scope key: snapshots are per browser profile and per tab. */
+function scopeOf(profile, tabId) {
+    return `${profile} | ${tabId ?? 'active'}`;
+}
+function rememberSnapshot(scope, snap) {
+    const stored = { id: `snap_${++counter}`, ts: Date.now(), url: snap.url, nodes: snap.nodes };
+    store.set(scope, stored);
+    // Bounded: drop the oldest insertion once over the ceiling.
+    while (store.size > MAX_SCOPES) {
+        const oldest = store.keys().next();
+        if (oldest.done)
+            break;
+        store.delete(oldest.value);
+    }
+    return stored;
+}
+function lastSnapshot(scope) {
+    return store.get(scope);
+}
+/** Forget everything - for tests, and whenever the active profile changes. */
+function resetSnapshots() {
+    store.clear();
+    counter = 0;
+}
+/** The state fields a diff reports as "changed" (the ref is expected to move). */
+const STATE_FIELDS = ['value', 'disabled', 'checked'];
+function diffSnapshots(prev, next) {
+    if (!prev) {
+        return { since: null, added: next.nodes, removed: [], changed: [], unchanged: 0 };
+    }
+    const before = new Map();
+    for (const n of prev.nodes)
+        if (!before.has(nodeKey(n)))
+            before.set(nodeKey(n), n);
+    const added = [];
+    const changed = [];
+    let unchanged = 0;
+    const matched = new Set();
+    for (const n of next.nodes) {
+        const key = nodeKey(n);
+        const old = before.get(key);
+        if (!old) {
+            added.push(n);
+            continue;
+        }
+        matched.add(key);
+        const was = {};
+        for (const f of STATE_FIELDS) {
+            if (old[f] !== n[f])
+                was[f] = old[f];
+        }
+        if (Object.keys(was).length > 0)
+            changed.push({ node: n, was });
+        else
+            unchanged++;
+    }
+    const removed = prev.nodes.filter((n) => !matched.has(nodeKey(n)));
+    return { since: prev.id, added, removed, changed, unchanged };
+}
+//# sourceMappingURL=snapdiff.js.map