@mehmoodqureshi/chrome-mcp 0.1.0 → 0.3.0

package/extension-dist/background.js

@@ -19,6 +19,10 @@
     "screenshot",
     "get_text",
     "get_html",
+    "snapshot",
+    "select_option",
+    "get_cookies",
+    "storage",
     "eval",
     "wait_for",
     "download_file",
@@ -161,6 +165,68 @@
     return n;
   }
 
+  // shared/snapshot.ts
+  function collectSnapshot(interactiveOnly = true, max = 200) {
+    const INTERACTIVE = "a[href],button,input,select,textarea,[role=button],[role=link],[role=tab],[role=checkbox],[role=radio],[role=menuitem],[role=option],[role=switch],[contenteditable=true],[onclick]";
+    const LANDMARK = "h1,h2,h3,[role=heading],nav,main,header,footer,[role=navigation]";
+    const sel = interactiveOnly ? INTERACTIVE : `${INTERACTIVE},${LANDMARK}`;
+    const visible = (el) => {
+      const r = el.getBoundingClientRect();
+      if (r.width === 0 && r.height === 0) return false;
+      const s = window.getComputedStyle(el);
+      return s.visibility !== "hidden" && s.display !== "none";
+    };
+    const accName = (el) => {
+      const aria = el.getAttribute("aria-label");
+      if (aria) return aria.trim();
+      const labelledby = el.getAttribute("aria-labelledby");
+      if (labelledby) {
+        const t = labelledby.split(/\s+/).map((id) => document.getElementById(id)?.innerText ?? "").join(" ").trim();
+        if (t) return t;
+      }
+      const ph = el.getAttribute("placeholder");
+      if (ph) return ph.trim();
+      const title = el.getAttribute("title");
+      if (title) return title.trim();
+      const text = el.innerText ?? "";
+      if (text) return text.replace(/\s+/g, " ").trim().slice(0, 120);
+      const alt = el.querySelector("img[alt]")?.getAttribute("alt");
+      return (alt ?? "").trim();
+    };
+    const roleOf = (el) => {
+      const explicit = el.getAttribute("role");
+      if (explicit) return explicit;
+      const tag = el.tagName.toLowerCase();
+      if (tag === "a") return "link";
+      if (tag === "button") return "button";
+      if (tag === "select") return "combobox";
+      if (tag === "textarea") return "textbox";
+      if (tag === "input") {
+        const t = el.type;
+        if (t === "checkbox") return "checkbox";
+        if (t === "radio") return "radio";
+        if (t === "button" || t === "submit") return "button";
+        return "textbox";
+      }
+      return tag;
+    };
+    const els = Array.from(document.querySelectorAll(sel)).filter(visible);
+    const nodes = [];
+    let n = 0;
+    for (const el of els) {
+      if (nodes.length >= max) break;
+      const ref = `e${++n}`;
+      el.setAttribute("data-mcp-ref", ref);
+      const node = { ref, role: roleOf(el), name: accName(el), tag: el.tagName.toLowerCase() };
+      const v = el.value;
+      if (typeof v === "string" && v) node.value = v.slice(0, 200);
+      if (el.disabled) node.disabled = true;
+      if (el.checked) node.checked = true;
+      nodes.push(node);
+    }
+    return { url: location.href, title: document.title, nodes, truncated: els.length > nodes.length };
+  }
+
   // extension/src/sw/executor.ts
   var CmdError = class extends Error {
     constructor(code, message) {
@@ -210,9 +276,73 @@
       await delay(100);
     }
   }
-  function selectorOf(cmd) {
+  function resolveSelector(cmd) {
     const s = cmd.params.selector;
-    return typeof s === "string" ? s : void 0;
+    if (typeof s === "string" && s.length > 0) return s;
+    const ref = cmd.params.ref;
+    if (typeof ref === "string" && ref.length > 0) return `[data-mcp-ref="${ref.replace(/["\\]/g, "\\$&")}"]`;
+    return void 0;
+  }
+  function selectorOf(cmd) {
+    return resolveSelector(cmd);
+  }
+  async function waitForSelector(tabId, selector, timeoutMs = 5e3) {
+    const start = Date.now();
+    for (; ; ) {
+      const present = await execInTab(tabId, (s) => !!document.querySelector(s), [selector]);
+      if (present) return true;
+      if (Date.now() - start > timeoutMs) return false;
+      await delay(120);
+    }
+  }
+  async function withDebugger(tabId, fn) {
+    const target = { tabId };
+    await chrome.debugger.attach(target, "1.3");
+    try {
+      return await fn(target);
+    } finally {
+      await chrome.debugger.detach(target).catch(() => void 0);
+    }
+  }
+  async function trustedType(tabId, selector, text, clear) {
+    const focused = await execInTab(
+      tabId,
+      (s, doClear) => {
+        const el = document.querySelector(s);
+        if (!el) return false;
+        el.focus();
+        if (doClear) {
+          const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), "value")?.set;
+          setter ? setter.call(el, "") : el.value = "";
+          el.dispatchEvent(new Event("input", { bubbles: true }));
+        }
+        return true;
+      },
+      [selector, clear]
+    );
+    if (!focused) return false;
+    await withDebugger(tabId, (t) => chrome.debugger.sendCommand(t, "Input.insertText", { text }));
+    return true;
+  }
+  async function trustedClick(tabId, selector) {
+    const pt = await execInTab(
+      tabId,
+      (s) => {
+        const el = document.querySelector(s);
+        if (!el) return null;
+        el.scrollIntoView({ block: "center", inline: "center" });
+        const r = el.getBoundingClientRect();
+        return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+      },
+      [selector]
+    );
+    if (!pt) return false;
+    await withDebugger(tabId, async (t) => {
+      const base = { x: pt.x, y: pt.y, button: "left", clickCount: 1 };
+      await chrome.debugger.sendCommand(t, "Input.dispatchMouseEvent", { type: "mousePressed", buttons: 1, ...base });
+      await chrome.debugger.sendCommand(t, "Input.dispatchMouseEvent", { type: "mouseReleased", buttons: 0, ...base });
+    });
+    return true;
   }
   async function tabInfo(tab, index = 0) {
     return {
@@ -240,6 +370,10 @@
     "screenshot",
     "get_text",
     "get_html",
+    "snapshot",
+    "select_option",
+    "get_cookies",
+    "storage",
     "eval",
     "wait_for",
     "download_file",
@@ -325,42 +459,155 @@
           );
           return { html: html ?? "" };
         }
+        // -- accessibility snapshot (tags elements with data-mcp-ref so refs work) --
+        case "snapshot": {
+          const id = await targetTab(cmd);
+          const interactiveOnly = cmd.params.interactiveOnly !== false;
+          const max = typeof cmd.params.max === "number" ? cmd.params.max : 200;
+          const raw = await execInTab(
+            id,
+            collectSnapshot,
+            [interactiveOnly, max]
+          );
+          return raw ?? { url: "", title: "", nodes: [], truncated: false };
+        }
+        // -- <select> option(s) by value or visible label --
+        case "select_option": {
+          const id = await targetTab(cmd);
+          const sel = requireSelector(cmd);
+          const values = Array.isArray(cmd.params.values) ? cmd.params.values.map(String) : [];
+          await waitForSelector(id, sel);
+          const matched = await execInTab(
+            id,
+            (s, vals) => {
+              const el = document.querySelector(s);
+              if (!el || !el.options) return false;
+              const set = new Set(vals);
+              let hit = false;
+              for (const opt of Array.from(el.options)) {
+                const on = set.has(opt.value) || set.has(opt.label) || set.has(opt.text);
+                opt.selected = on;
+                if (on) hit = true;
+              }
+              el.dispatchEvent(new Event("input", { bubbles: true }));
+              el.dispatchEvent(new Event("change", { bubbles: true }));
+              return hit;
+            },
+            [sel, values]
+          );
+          if (!matched) throw new CmdError("SELECTOR_NOT_FOUND", `no <select> option matched for ${sel}`);
+          return { ok: true };
+        }
+        // -- cookies for the tab's URL (chrome.cookies; needs "cookies" permission) --
+        case "get_cookies": {
+          const id = await targetTab(cmd);
+          const t = await chrome.tabs.get(id);
+          const url = typeof cmd.params.url === "string" ? cmd.params.url : t.url;
+          if (!url) throw new CmdError("BAD_ARGS", "no url to read cookies for");
+          const cookies = await chrome.cookies.getAll({ url });
+          return {
+            cookies: cookies.map((c) => ({
+              name: c.name,
+              value: c.value,
+              domain: c.domain,
+              path: c.path,
+              secure: c.secure,
+              httpOnly: c.httpOnly,
+              expires: c.expirationDate
+            }))
+          };
+        }
+        // -- localStorage / sessionStorage (isolated world) --
+        case "storage": {
+          const id = await targetTab(cmd);
+          const op = String(cmd.params.op);
+          const key = typeof cmd.params.key === "string" ? cmd.params.key : null;
+          const value = typeof cmd.params.value === "string" ? cmd.params.value : null;
+          const session = cmd.params.session === true;
+          const res = await execInTab(
+            id,
+            (o, k, v, s) => {
+              const store = s ? window.sessionStorage : window.localStorage;
+              if (o === "set") {
+                store.setItem(String(k), String(v ?? ""));
+                return { ok: true };
+              }
+              if (o === "remove") {
+                store.removeItem(String(k));
+                return { ok: true };
+              }
+              if (o === "clear") {
+                store.clear();
+                return { ok: true };
+              }
+              if (k) return { ok: true, value: store.getItem(k) };
+              const entries = {};
+              for (let i = 0; i < store.length; i++) {
+                const kk = store.key(i);
+                if (kk) entries[kk] = store.getItem(kk) ?? "";
+              }
+              return { ok: true, entries };
+            },
+            [op, key, value, session]
+          );
+          return res ?? { ok: false };
+        }
         // -- interaction (synthetic events in the isolated world) --
         case "click": {
           const id = await targetTab(cmd);
+          const sel = requireSelector(cmd);
+          if (!await waitForSelector(id, sel)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+          if (cmd.params.trusted === true) {
+            if (!await trustedClick(id, sel)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+            return { ok: true };
+          }
           const found = await execInTab(
             id,
-            (sel) => {
-              const el = document.querySelector(sel);
+            (s) => {
+              const el = document.querySelector(s);
               if (!el) return false;
               el.scrollIntoView({ block: "center" });
               el.click();
               return true;
             },
-            [requireSelector(cmd)]
+            [sel]
           );
-          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${requireSelector(cmd)}`);
+          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           return { ok: true };
         }
         case "type": {
           const id = await targetTab(cmd);
+          const sel = requireSelector(cmd);
           const text = String(cmd.params.text ?? "");
           const clear = cmd.params.clear === true;
+          if (!await waitForSelector(id, sel)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+          if (cmd.params.trusted === true) {
+            if (!await trustedType(id, sel, text, clear)) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
+            if (cmd.params.pressEnter === true) {
+              await withDebugger(id, async (t) => {
+                for (const type of ["keyDown", "keyUp"]) {
+                  await chrome.debugger.sendCommand(t, "Input.dispatchKeyEvent", { type, key: "Enter", code: "Enter", windowsVirtualKeyCode: 13 });
+                }
+              });
+            }
+            return { ok: true };
+          }
           const found = await execInTab(
             id,
-            (sel, value, doClear) => {
-              const el = document.querySelector(sel);
+            (s, value, doClear) => {
+              const el = document.querySelector(s);
               if (!el) return false;
               el.focus();
-              if (doClear) el.value = "";
-              el.value = (el.value ?? "") + value;
+              const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), "value")?.set;
+              const next = (doClear ? "" : el.value ?? "") + value;
+              setter ? setter.call(el, next) : el.value = next;
               el.dispatchEvent(new Event("input", { bubbles: true }));
               el.dispatchEvent(new Event("change", { bubbles: true }));
               return true;
             },
-            [requireSelector(cmd), text, clear]
+            [sel, text, clear]
           );
-          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${requireSelector(cmd)}`);
+          if (!found) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${sel}`);
           return { ok: true };
         }
         case "press": {
@@ -380,13 +627,16 @@
         }
         case "hover": {
           const id = await targetTab(cmd);
+          const sel = requireSelector(cmd);
+          await waitForSelector(id, sel);
           await execInTab(
             id,
-            (sel) => {
-              const el = document.querySelector(sel);
+            (s) => {
+              const el = document.querySelector(s);
               el?.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+              el?.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
             },
-            [requireSelector(cmd)]
+            [sel]
           );
           return { ok: true };
         }
@@ -402,17 +652,33 @@
           );
           return { ok: true };
         }
-        // -- screenshot (visible tab) --
+        // -- screenshot (captureVisibleTab grabs the ACTIVE visible tab, so activate the target first) --
         case "screenshot": {
           const id = await targetTab(cmd);
-          const t = await chrome.tabs.get(id);
+          let t = await chrome.tabs.get(id);
+          if (!t.active) {
+            await chrome.tabs.update(id, { active: true });
+            await chrome.windows.update(t.windowId, { focused: true }).catch(() => void 0);
+            await delay(150);
+            t = await chrome.tabs.get(id);
+          }
+          const dims = await execInTab(
+            id,
+            () => ({ w: window.innerWidth, h: window.innerHeight, full: document.documentElement.scrollHeight }),
+            []
+          );
           const dataUrl = await chrome.tabs.captureVisibleTab(t.windowId, { format: "png" });
+          const fullPage = cmd.params.fullPage === true;
+          const viewportH = dims?.h ?? 0;
+          const fullH = dims?.full ?? viewportH;
           return {
             dataBase64: dataUrl.split(",")[1] ?? "",
             mimeType: "image/png",
-            width: 0,
-            height: 0,
-            truncated: false
+            width: dims?.w ?? 0,
+            height: viewportH,
+            // The scripting backend can only capture the viewport; flag when a fullPage was asked but clipped.
+            truncated: fullPage && fullH > viewportH,
+            fullHeight: fullPage ? fullH : void 0
           };
         }
         // -- eval (MAIN world; may be blocked by strict page CSP) --
@@ -472,11 +738,11 @@
     }
   };
   function requireSelector(cmd) {
-    const s = cmd.params.selector;
-    if (typeof s !== "string" || s.length === 0) {
-      throw new CmdError("BAD_ARGS", "this command needs a CSS selector (the scripting backend does not support refs)");
+    const sel = resolveSelector(cmd);
+    if (!sel) {
+      throw new CmdError("BAD_ARGS", 'this command needs a "selector" or a "ref" from snapshot()');
     }
-    return s;
+    return sel;
   }
 
   // extension/src/sw/router.ts
@@ -523,12 +789,28 @@
   });
   async function getConfig() {
     const { wsPort, token } = await chrome.storage.local.get(["wsPort", "token"]);
-    if (typeof wsPort === "number" && typeof token === "string" && token.length > 0) {
+    if (typeof wsPort === "number" && wsPort > 0 && typeof token === "string" && token.length > 0) {
       return { wsPort, token };
     }
     return null;
   }
+  var BADGE = {
+    connected: { text: "\u25CF", color: "#16a34a", title: "Chrome MCP \u2014 connected" },
+    connecting: { text: "\u2026", color: "#ca8a04", title: "Chrome MCP \u2014 connecting" },
+    unauthorized: { text: "!", color: "#dc2626", title: "Chrome MCP \u2014 rejected (bad/stale token; re-pair)" },
+    idle: { text: "\u25CB", color: "#6b7280", title: "Chrome MCP \u2014 not connected (open options to pair)" }
+  };
+  function reflectBadge(state) {
+    const b = BADGE[state] ?? BADGE.idle;
+    try {
+      void chrome.action.setBadgeText({ text: b.text });
+      void chrome.action.setBadgeBackgroundColor({ color: b.color });
+      void chrome.action.setTitle({ title: b.title });
+    } catch {
+    }
+  }
   async function persistState(state) {
+    reflectBadge(state);
     await chrome.storage.local.set({ connState: state });
   }
   async function ensureConnected() {

package/extension-dist/manifest.json

@@ -1,12 +1,12 @@
 {
   "manifest_version": 3,
   "name": "Chrome MCP Bridge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lets a local chrome-mcp server drive this browser. Pair it with the server's handshake token.",
   "minimum_chrome_version": "116",
   "background": { "service_worker": "background.js" },
-  "permissions": ["tabs", "scripting", "activeTab", "downloads", "storage", "alarms"],
-  "host_permissions": ["http://*/*", "https://*/*"],
+  "permissions": ["tabs", "scripting", "activeTab", "downloads", "storage", "alarms", "cookies", "debugger"],
+  "host_permissions": ["<all_urls>"],
   "options_page": "options.html",
   "action": { "default_title": "Chrome MCP — open options to pair" }
 }

package/extension-dist/options.js

@@ -1,5 +1,8 @@
 "use strict";
 (() => {
+  // shared/protocol.ts
+  var DEFAULT_WS_PORT = 38017;
+
   // extension/src/options/options.ts
   var portEl = document.getElementById("port");
   var tokenEl = document.getElementById("token");
@@ -7,7 +10,7 @@
   var statusEl = document.getElementById("status");
   async function loadExisting() {
     const { wsPort, connState } = await chrome.storage.local.get(["wsPort", "connState"]);
-    if (typeof wsPort === "number") portEl.value = String(wsPort);
+    portEl.value = typeof wsPort === "number" && wsPort > 0 ? String(wsPort) : String(DEFAULT_WS_PORT);
     render(typeof connState === "string" ? connState : "idle");
   }
   function render(state) {
@@ -22,8 +25,8 @@
   saveEl.addEventListener("click", async () => {
     const wsPort = Number(portEl.value);
     const token = tokenEl.value.trim();
-    if (!Number.isInteger(wsPort) || wsPort < 0 || !token) {
-      statusEl.textContent = "Status: enter a valid port and token";
+    if (!Number.isInteger(wsPort) || wsPort <= 0 || !token) {
+      statusEl.textContent = "Status: enter a valid port (> 0) and token";
       return;
     }
     await chrome.storage.local.set({ wsPort, token });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Drive a real Chrome browser over MCP. A stdio MCP server (CLI) plus an MV3 extension, behind one pluggable Executor (extension via chrome.scripting, or a Playwright CDP fallback).",
   "author": "Mehmood Ur Rehman Qureshi",
   "license": "MIT",
@@ -64,6 +64,6 @@
     "typescript": "^5.7.2"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=18.0.0"
   }
 }