@mehmoodqureshi/chrome-mcp 0.9.2 → 0.9.4

package/README.md

@@ -383,6 +383,33 @@ Renders through Chrome's own print pipeline and saves to the task's `results/`
 dir, returning the path and size. The bytes themselves are never returned — a
 PDF is megabytes of base64 no model can read.
 
+### Paying less per turn — `--tools`
+
+Every MCP server you connect costs context before you ask it anything: the host
+sends the whole tool catalog to the model on **every** turn. chrome-mcp's 39
+tools are 27 KB of JSON Schema, about 6.9k tokens, on each one.
+
+Most runs need a handful of them. `--tools` advertises only those:
+
+```
+npx -y @mehmoodqureshi/chrome-mcp \
+  --allow-domain app.example.com --enable-mutations \
+  --tools tabs_list,tab_new,navigate,snapshot,click,type,get_text
+```
+
+That surface is **6.0 KB, ~1.5k tokens** — an 82% cut against the full catalog,
+for a run that was never going to print a PDF or upload a file.
+
+- Comma-separated and repeatable: `--tools navigate,get_text --tools click`.
+- A tool left out is hidden from `tools/list` **and refused if called** — a
+  `batch` op naming it fails the same way an unknown tool does. Hiding a tool is
+  a real restriction, not a display filter. It is not a substitute for the
+  policy gate, though: `--tools eval` still does nothing without
+  `--unsafe-enable-eval`.
+- An unknown name fails at startup and prints the catalog, so a typo can never
+  quietly drop `click` from the surface.
+- `chrome-mcp --help` prints the full catalog of 39 names to pick from.
+
 ## Status
 
 v0.5.0 — **safe multi-tab concurrency.** Adds the `batch` fan-out tool, makes
@@ -502,5 +529,7 @@ the fallback.
 > `chrome.debugger` is used only where it's needed and worth it: `trusted: true`
 > input (real OS-level events on React/Vue inputs) and `screenshot` (captures a
 > specific tab **without** activating it — safe under parallel `batch` — with
-> true full-page and element capture). Those ops briefly show the debug banner
-> while attached.
+> true full-page and element capture). Those ops show the debug banner while
+> attached; the session lingers 1.5s after the last op so a burst of them
+> attaches once. Screenshots are JPEG (quality 70) at CSS-pixel size by
+> default — pass `format: "png"`, `quality`, or `scale` to change that.

package/dist/shared/page-fns.js

@@ -87,8 +87,6 @@ function pageOp(a) {
         return { dx, dy, exact: true, scrollX: win.scrollX, scrollY: win.scrollY };
     };
     const sel = typeof a.selector === 'string' && a.selector.length > 0 ? a.selector : null;
-    const el = sel ? deepQuery(sel) : null;
-    const missing = sel !== null && el === null;
     /** Set a value the way React/Vue see it (they patch the instance setter). */
     const setValue = (node, next) => {
         const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(node), 'value')?.set;
@@ -98,195 +96,223 @@ function pageOp(a) {
             node.value = next;
         node.dispatchEvent(new Event('input', { bubbles: true }));
     };
-    switch (a.op) {
-        case 'probe':
-            return { found: true, url: location.href, title: document.title };
-        case 'text': {
-            if (missing)
-                return { found: false };
-            const root = el ?? document.body;
-            return { found: true, text: root ? root.innerText ?? '' : '' };
-        }
-        case 'html': {
-            if (missing)
-                return { found: false };
-            const root = el ?? document.documentElement;
-            if (!root)
-                return { found: true, html: '' };
-            const outer = a.outer === true || !sel;
-            return { found: true, html: outer ? root.outerHTML : root.innerHTML };
-        }
-        case 'click': {
-            if (!el)
-                return { found: false };
-            el.scrollIntoView({ block: 'center' });
-            el.click();
-            return { found: true };
-        }
-        case 'type': {
-            const node = el;
-            if (!node)
-                return { found: false };
-            node.focus();
-            const next = (a.clear ? '' : node.value ?? '') + (a.text ?? '');
-            setValue(node, next);
-            node.dispatchEvent(new Event('change', { bubbles: true }));
-            return { found: true };
-        }
-        case 'focus': {
-            const node = el;
-            if (!node)
-                return { found: false };
-            node.focus();
-            if (a.clear)
-                setValue(node, '');
-            return { found: true };
-        }
-        case 'point': {
-            if (!el)
-                return { found: false };
-            el.scrollIntoView({ block: 'center', inline: 'center' });
-            const r = el.getBoundingClientRect();
-            const off = frameOffset();
-            return {
-                found: true,
-                x: r.left + r.width / 2 + off.dx,
-                y: r.top + r.height / 2 + off.dy,
-                // false => this frame's coordinates cannot be mapped to the top viewport.
-                exact: off.exact,
-            };
-        }
-        case 'hover': {
-            if (!el)
-                return { found: false };
-            el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
-            el.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
-            return { found: true };
-        }
-        case 'select': {
-            const node = el;
-            if (!node || !node.options)
-                return { found: false };
-            const want = new Set(a.values ?? []);
-            let matched = false;
-            for (const opt of Array.from(node.options)) {
-                const on = want.has(opt.value) || want.has(opt.label) || want.has(opt.text);
-                opt.selected = on;
-                if (on)
-                    matched = true;
+    /** The op proper, against an element already resolved (or null). */
+    const perform = (el) => {
+        const missing = sel !== null && el === null;
+        switch (a.op) {
+            case 'probe':
+                return { found: true, url: location.href, title: document.title };
+            case 'text': {
+                if (missing)
+                    return { found: false };
+                const root = el ?? document.body;
+                return { found: true, text: root ? root.innerText ?? '' : '' };
             }
-            node.dispatchEvent(new Event('input', { bubbles: true }));
-            node.dispatchEvent(new Event('change', { bubbles: true }));
-            return { found: true, matched };
-        }
-        case 'measure': {
-            const d = document.documentElement;
-            const dims = {
-                w: window.innerWidth,
-                h: window.innerHeight,
-                fullW: Math.max(d.scrollWidth, d.clientWidth),
-                fullH: Math.max(d.scrollHeight, d.clientHeight),
-            };
-            if (!sel)
-                return { found: true, dims, element: null, missing: false };
-            if (!el)
-                return { found: true, dims, element: null, missing: true };
-            el.scrollIntoView({ block: 'center', inline: 'center' });
-            const r = el.getBoundingClientRect();
-            const off = frameOffset();
-            // viewport rect + this frame's offset + the TOP document's scroll ->
-            // document coordinates of the page the screenshot actually captures.
-            return {
-                found: true,
-                dims,
-                element: {
-                    x: r.left + off.dx + off.scrollX,
-                    y: r.top + off.dy + off.scrollY,
-                    w: r.width,
-                    h: r.height,
-                },
-                missing: false,
-                exact: off.exact,
-            };
-        }
-        case 'scroll': {
-            if (el)
-                el.scrollIntoView({ block: 'center' });
-            else if (a.x != null || a.y != null)
-                window.scrollTo(a.x ?? 0, a.y ?? 0);
-            else
-                window.scrollBy(a.deltaX ?? 0, a.deltaY ?? 0);
-            return { found: !missing };
-        }
-        case 'storage': {
-            const store = a.session ? window.sessionStorage : window.localStorage;
-            const op = a.storageOp;
-            if (op === 'set') {
-                store.setItem(String(a.key), String(a.value ?? ''));
-                return { found: true, ok: true };
+            case 'html': {
+                if (missing)
+                    return { found: false };
+                const root = el ?? document.documentElement;
+                if (!root)
+                    return { found: true, html: '' };
+                const outer = a.outer === true || !sel;
+                return { found: true, html: outer ? root.outerHTML : root.innerHTML };
             }
-            if (op === 'remove') {
-                store.removeItem(String(a.key));
-                return { found: true, ok: true };
+            case 'click': {
+                if (!el)
+                    return { found: false };
+                el.scrollIntoView({ block: 'center' });
+                el.click();
+                return { found: true };
             }
-            if (op === 'clear') {
-                store.clear();
-                return { found: true, ok: true };
+            case 'type': {
+                const node = el;
+                if (!node)
+                    return { found: false };
+                node.focus();
+                const next = (a.clear ? '' : node.value ?? '') + (a.text ?? '');
+                setValue(node, next);
+                node.dispatchEvent(new Event('change', { bubbles: true }));
+                return { found: true };
             }
-            if (a.key)
-                return { found: true, ok: true, value: store.getItem(a.key) };
-            const entries = {};
-            for (let i = 0; i < store.length; i++) {
-                const k = store.key(i);
-                if (k)
-                    entries[k] = store.getItem(k) ?? '';
+            case 'focus': {
+                const node = el;
+                if (!node)
+                    return { found: false };
+                node.focus();
+                if (a.clear)
+                    setValue(node, '');
+                return { found: true };
             }
-            return { found: true, ok: true, entries };
-        }
-        // -- the two polling ops: one injection that resolves in-page, rather than
-        //    one executeScript round-trip per tick --
-        case 'waitSelector': {
-            const deadline = Date.now() + (a.timeoutMs ?? 5_000);
-            const every = a.interval ?? 120;
-            return new Promise((resolve) => {
-                const tick = () => {
-                    if (sel && deepQuery(sel))
-                        return resolve({ found: true });
-                    if (Date.now() > deadline)
-                        return resolve({ found: false });
-                    setTimeout(tick, every);
+            case 'point': {
+                if (!el)
+                    return { found: false };
+                el.scrollIntoView({ block: 'center', inline: 'center' });
+                const r = el.getBoundingClientRect();
+                const off = frameOffset();
+                return {
+                    found: true,
+                    x: r.left + r.width / 2 + off.dx,
+                    y: r.top + r.height / 2 + off.dy,
+                    // false => this frame's coordinates cannot be mapped to the top viewport.
+                    exact: off.exact,
                 };
-                tick();
-            });
-        }
-        case 'waitFor': {
-            const deadline = Date.now() + (a.timeoutMs ?? 30_000);
-            const every = a.interval ?? 150;
-            const want = typeof a.textContains === 'string' && a.textContains.length > 0 ? a.textContains : null;
-            const gone = a.gone === true;
-            return new Promise((resolve) => {
-                const hit = () => {
-                    let present;
-                    if (sel)
-                        present = !!deepQuery(sel);
-                    else if (want)
-                        present = (document.body?.innerText ?? '').includes(want);
-                    else
-                        present = true;
-                    return gone ? !present : present;
+            }
+            case 'hover': {
+                if (!el)
+                    return { found: false };
+                el.dispatchEvent(new MouseEvent('mouseover', { bubbles: true }));
+                el.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+                return { found: true };
+            }
+            case 'select': {
+                const node = el;
+                if (!node || !node.options)
+                    return { found: false };
+                const want = new Set(a.values ?? []);
+                let matched = false;
+                for (const opt of Array.from(node.options)) {
+                    const on = want.has(opt.value) || want.has(opt.label) || want.has(opt.text);
+                    opt.selected = on;
+                    if (on)
+                        matched = true;
+                }
+                node.dispatchEvent(new Event('input', { bubbles: true }));
+                node.dispatchEvent(new Event('change', { bubbles: true }));
+                return { found: true, matched };
+            }
+            case 'measure': {
+                const d = document.documentElement;
+                const dims = {
+                    w: window.innerWidth,
+                    h: window.innerHeight,
+                    fullW: Math.max(d.scrollWidth, d.clientWidth),
+                    fullH: Math.max(d.scrollHeight, d.clientHeight),
+                    dpr: window.devicePixelRatio || 1,
+                    scrollX: window.scrollX,
+                    scrollY: window.scrollY,
                 };
-                const tick = () => {
-                    if (hit())
-                        return resolve({ found: true, matched: true });
-                    if (Date.now() > deadline)
-                        return resolve({ found: true, matched: false });
-                    setTimeout(tick, every);
+                if (!sel)
+                    return { found: true, dims, element: null, missing: false };
+                if (!el)
+                    return { found: true, dims, element: null, missing: true };
+                el.scrollIntoView({ block: 'center', inline: 'center' });
+                const r = el.getBoundingClientRect();
+                const off = frameOffset();
+                // viewport rect + this frame's offset + the TOP document's scroll ->
+                // document coordinates of the page the screenshot actually captures.
+                return {
+                    found: true,
+                    dims,
+                    element: {
+                        x: r.left + off.dx + off.scrollX,
+                        y: r.top + off.dy + off.scrollY,
+                        w: r.width,
+                        h: r.height,
+                    },
+                    missing: false,
+                    exact: off.exact,
                 };
-                tick();
-            });
+            }
+            case 'scroll': {
+                if (el)
+                    el.scrollIntoView({ block: 'center' });
+                else if (a.x != null || a.y != null)
+                    window.scrollTo(a.x ?? 0, a.y ?? 0);
+                else
+                    window.scrollBy(a.deltaX ?? 0, a.deltaY ?? 0);
+                return { found: !missing };
+            }
+            case 'storage': {
+                const store = a.session ? window.sessionStorage : window.localStorage;
+                const op = a.storageOp;
+                if (op === 'set') {
+                    store.setItem(String(a.key), String(a.value ?? ''));
+                    return { found: true, ok: true };
+                }
+                if (op === 'remove') {
+                    store.removeItem(String(a.key));
+                    return { found: true, ok: true };
+                }
+                if (op === 'clear') {
+                    store.clear();
+                    return { found: true, ok: true };
+                }
+                if (a.key)
+                    return { found: true, ok: true, value: store.getItem(a.key) };
+                const entries = {};
+                for (let i = 0; i < store.length; i++) {
+                    const k = store.key(i);
+                    if (k)
+                        entries[k] = store.getItem(k) ?? '';
+                }
+                return { found: true, ok: true, entries };
+            }
+            // -- the two polling ops: one injection that resolves in-page, rather than
+            //    one executeScript round-trip per tick --
+            case 'waitSelector': {
+                const deadline = Date.now() + (a.timeoutMs ?? 5_000);
+                const every = a.interval ?? 120;
+                return new Promise((resolve) => {
+                    const tick = () => {
+                        if (sel && deepQuery(sel))
+                            return resolve({ found: true });
+                        if (Date.now() > deadline)
+                            return resolve({ found: false });
+                        setTimeout(tick, every);
+                    };
+                    tick();
+                });
+            }
+            case 'waitFor': {
+                const deadline = Date.now() + (a.timeoutMs ?? 30_000);
+                const every = a.interval ?? 150;
+                const want = typeof a.textContains === 'string' && a.textContains.length > 0 ? a.textContains : null;
+                const gone = a.gone === true;
+                return new Promise((resolve) => {
+                    const hit = () => {
+                        let present;
+                        if (sel)
+                            present = !!deepQuery(sel);
+                        else if (want)
+                            present = (document.body?.innerText ?? '').includes(want);
+                        else
+                            present = true;
+                        return gone ? !present : present;
+                    };
+                    const tick = () => {
+                        if (hit())
+                            return resolve({ found: true, matched: true });
+                        if (Date.now() > deadline)
+                            return resolve({ found: true, matched: false });
+                        setTimeout(tick, every);
+                    };
+                    tick();
+                });
+            }
+            default:
+                return { found: false, error: `unknown page op: ${String(a.op)}` };
         }
-        default:
-            return { found: false, error: `unknown page op: ${String(a.op)}` };
+    };
+    const el = sel ? deepQuery(sel) : null;
+    // Element ops wait for their target IN THIS SAME injection when `timeoutMs`
+    // is set: a not-yet-rendered button costs a few in-page ticks, not a second
+    // executeScript round-trip (the old waitSelector-then-act pair).
+    const waits = a.op === 'click' || a.op === 'type' || a.op === 'focus' || a.op === 'point' || a.op === 'hover' || a.op === 'select';
+    if (waits && sel && !el && a.timeoutMs && a.timeoutMs > 0) {
+        const deadline = Date.now() + a.timeoutMs;
+        const every = a.interval ?? 120;
+        return new Promise((resolve) => {
+            const tick = () => {
+                const hit = deepQuery(sel);
+                if (hit)
+                    return resolve(perform(hit));
+                if (Date.now() > deadline)
+                    return resolve({ found: false });
+                setTimeout(tick, every);
+            };
+            setTimeout(tick, every);
+        });
     }
+    return perform(el);
 }
 //# sourceMappingURL=page-fns.js.map

package/dist/shared/screenshot.d.ts

@@ -14,7 +14,20 @@ export interface PageDims {
     /** Full content box (document) width/height. */
     fullW: number;
     fullH: number;
+    /** window.devicePixelRatio (default 1). Output pixels = CSS px * dpr * clip.scale. */
+    dpr?: number;
+    /** Current scroll offset of the top document (default 0,0); a viewport clip starts here. */
+    scrollX?: number;
+    scrollY?: number;
 }
+export type ScreenshotFormat = 'png' | 'jpeg';
+/** Default encoding: JPEG at this quality is ~5-10x smaller than PNG on a
+ *  typical page and still perfectly legible to a vision model. */
+export declare const DEFAULT_SCREENSHOT_FORMAT: ScreenshotFormat;
+export declare const DEFAULT_JPEG_QUALITY = 70;
+/** Output size multiplier relative to CSS pixels. 1 = CSS px (so a Retina
+ *  viewport is NOT captured at 2x); 2 = device px on a 2x display. */
+export declare const DEFAULT_SCREENSHOT_SCALE = 1;
 /** An element's box in DOCUMENT coordinates (viewport rect + scroll offset), CSS px. */
 export interface ElementRect {
     x: number;
@@ -55,4 +68,5 @@ export declare const MAX_CAPTURE_PX = 16384;
 export declare function planScreenshot(dims: PageDims, opts?: {
     fullPage?: boolean;
     element?: ElementRect | null;
+    scale?: number;
 }): ScreenshotPlan;

package/dist/shared/screenshot.js

@@ -8,8 +8,15 @@
  * `ScreenshotResult` reports. No chrome.* calls — just arithmetic.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_CAPTURE_PX = void 0;
+exports.MAX_CAPTURE_PX = exports.DEFAULT_SCREENSHOT_SCALE = exports.DEFAULT_JPEG_QUALITY = exports.DEFAULT_SCREENSHOT_FORMAT = void 0;
 exports.planScreenshot = planScreenshot;
+/** Default encoding: JPEG at this quality is ~5-10x smaller than PNG on a
+ *  typical page and still perfectly legible to a vision model. */
+exports.DEFAULT_SCREENSHOT_FORMAT = 'jpeg';
+exports.DEFAULT_JPEG_QUALITY = 70;
+/** Output size multiplier relative to CSS pixels. 1 = CSS px (so a Retina
+ *  viewport is NOT captured at 2x); 2 = device px on a 2x display. */
+exports.DEFAULT_SCREENSHOT_SCALE = 1;
 /**
  * Practical single-capture height ceiling. Skia/CDP cannot encode arbitrarily
  * tall images; beyond this we clamp the clip and flag `truncated`.
@@ -20,11 +27,15 @@ exports.MAX_CAPTURE_PX = 16384;
  * viewport capture. Heights are clamped to MAX_CAPTURE_PX with `truncated` set.
  */
 function planScreenshot(dims, opts = {}) {
+    // CDP's clip.scale multiplies on top of the device scale factor, so dividing
+    // by the DPR yields exactly `opts.scale` output pixels per CSS pixel.
+    const dpr = dims.dpr && dims.dpr > 0 ? dims.dpr : 1;
+    const scale = (opts.scale && opts.scale > 0 ? opts.scale : exports.DEFAULT_SCREENSHOT_SCALE) / dpr;
     if (opts.element) {
         const realH = Math.max(1, Math.round(opts.element.h));
         const clipH = Math.min(opts.element.h, exports.MAX_CAPTURE_PX);
         return {
-            clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale: 1 },
+            clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale },
             captureBeyondViewport: true,
             width: Math.max(1, Math.round(opts.element.w)),
             height: Math.min(realH, exports.MAX_CAPTURE_PX),
@@ -35,7 +46,7 @@ function planScreenshot(dims, opts = {}) {
     if (opts.fullPage) {
         const clipH = Math.min(dims.fullH, exports.MAX_CAPTURE_PX);
         return {
-            clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale: 1 },
+            clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale },
             captureBeyondViewport: true,
             width: dims.fullW,
             height: clipH,
@@ -43,8 +54,12 @@ function planScreenshot(dims, opts = {}) {
             fullHeight: dims.fullH,
         };
     }
-    // Plain viewport: no clip, capture what's visible.
+    // Plain viewport: capture what's visible. A clip is only needed to apply a
+    // scale; at scale 1 on a 1x display the bare capture is identical and cheaper.
     return {
+        ...(scale !== 1
+            ? { clip: { x: dims.scrollX ?? 0, y: dims.scrollY ?? 0, width: dims.w, height: dims.h, scale } }
+            : {}),
         captureBeyondViewport: false,
         width: dims.w,
         height: dims.h,

package/dist/shared/snapshot.d.ts

@@ -23,6 +23,28 @@ export interface RawSnapshot {
     title: string;
     nodes: RawSnapshotNode[];
     truncated: boolean;
+    /** Locator mode, nothing matched: up to 8 "role \"name\"" strings of the
+     *  same role, so the caller can say what WAS there without a second read. */
+    nearby?: string[];
 }
-/** Runs IN THE PAGE. Returns interactive (and optionally landmark) elements with fresh refs. */
-export declare function collectSnapshot(interactiveOnly?: boolean, max?: number): RawSnapshot;
+/** A role/name query resolved IN the page (see `collectSnapshot`). */
+export interface SnapshotLocator {
+    role?: string;
+    name?: string;
+}
+/**
+ * Runs IN THE PAGE. Returns interactive (and optionally landmark) elements with
+ * fresh refs.
+ *
+ * With a `locator`, the walk is the same but the SCORING happens here: only the
+ * strongest-tier matches come back (and only they get a ref), so resolving
+ * "the Sign in button" ships a handful of nodes instead of the whole tree and
+ * touches one or two DOM attributes instead of hundreds. The tiers mirror
+ * `src/mcp/locate.ts` exactly (exact, case-insensitive, prefix, contains), and
+ * the server re-scores what it receives, so both ends always agree.
+ *
+ * Reads (visibility, names, values) all happen BEFORE the ref attributes are
+ * written: interleaving them made every `innerText` after a `setAttribute`
+ * re-run style, which on a big page is most of the snapshot's cost.
+ */
+export declare function collectSnapshot(interactiveOnly?: boolean, max?: number, locator?: SnapshotLocator | null): RawSnapshot;