safari-mcp 2.19.1 → 2.21.0

package/README.md

@@ -348,6 +348,31 @@ Prefer stdio (one process per agent) over a persistent daemon? That works too
 
 ---
 
+## Acting on a tab you already have open
+
+By default the server touches only tabs it opened itself. Point it at one of yours and it refuses:
+
+```
+Tab safety: refusing "click" — current tab (https://mail.example.com/inbox) was not
+opened by this MCP session. Use safari_new_tab or safari_switch_tab to target your own tab.
+```
+
+That default exists because early versions did click into and close people's tabs. But "read the article I'm looking at" and "fill in the form on my screen" are real, and reopening the page loses the session state that made your tab worth using. Set `SAFARI_MCP_ALLOW_USER_TABS=1` and an **explicit** `safari_switch_tab` adopts the tab instead of refusing it; from then on the session works in it like one of its own, and says so:
+
+```json
+{ "tabIndex": 3, "safeUrl": "https://mail.example.com/inbox", "note": "(user tab, opted-in)" }
+```
+
+What the flag deliberately does *not* do:
+
+- **It unlocks adoption, not the guards.** Only `safari_switch_tab` adopts, and only the tab you named. An ordinary click or navigate still never lands on whatever tab happens to be in front — the server acts on the tab you pointed it at, not the one you wandered to.
+- **`safari_close_tab` still refuses.** Closing is the one action whose cost you cannot undo, so an adopted tab is writable, never disposable. Close it yourself.
+- **Adoption is session-local.** Nothing is written to the shared ownership file, so it ends with the session rather than leaking to the next process on the machine.
+
+`safari_doctor` prints the flag's state, and every operation on an adopted tab logs `(user tab, opted-in)` — so "why did it touch my tab" has an answer instead of being a mystery. Default off; set it only for agents you want working inside your own browsing session. Designed in [#92](https://github.com/achiya-automation/safari-mcp/issues/92).
+
+---
+
 ## Environment variables
 
 | Variable | Default | What it does |
@@ -355,6 +380,7 @@ Prefer stdio (one process per agent) over a persistent daemon? That works too
 | `SAFARI_MCP_HTTP` | off | Run one shared HTTP daemon instead of a process per client (see above). |
 | `SAFARI_MCP_HTTP_PORT` | `9225` | Port for that daemon. |
 | `SAFARI_PROFILE` | unset | Bind sessions to a named Safari profile. Unset = your ordinary windows. |
+| `SAFARI_MCP_ALLOW_USER_TABS` | off | Let `safari_switch_tab` adopt a tab **you** already had open, instead of refusing it (see below). |
 | `SAFARI_MCP_RAISE_ON_NAVIGATE` | off | Let navigation bring Safari to the front, and stop the focus guard from putting your previous app back. |
 | `SAFARI_MCP_SCREENSHOT_MAX_WIDTH` | unset | Downscale every `safari_screenshot` to this pixel width (Retina captures are 2× the viewport). Per-call `maxWidth` overrides it. |
 | `SAFARI_MCP_KEEPALIVE_TAB` | off | Keep one daemon-served page open in the profile window so Safari never parks the extension worker between commands. |

package/extension/background.js

@@ -1116,6 +1116,10 @@ async function handleCommand(type, payload) {
     // --- JavaScript Execution — multi-strategy to handle CSP restrictions ---
     // Strategy 1: indirect eval (fast, works when CSP allows unsafe-eval)
     // Strategy 2: script element injection (bypasses CSP in MAIN world context)
+    case "list_frames": {
+      return await listFrames(tabId);
+    }
+
     case "evaluate": {
       // Strategy 0: pages that stall injection outright. Every strategy below reaches
       // the page through scripting.executeScript, which on business.facebook.com never
@@ -1124,6 +1128,12 @@ async function handleCommand(type, payload) {
       // it FIRST once a tab is known to block injection, and fall back to it below
       // when a fresh tab turns out to block it too.
       const evalTabId = tabId || (await getActiveTab()).id;
+      // A frame selector short-circuits every strategy below: those all target the
+      // main frame, which is exactly what makes an embedded app unreachable.
+      if (payload.frame !== undefined && payload.frame !== null && payload.frame !== "") {
+        const _fid = await resolveFrameId(evalTabId, payload.frame);
+        return await evaluateInFrame(evalTabId, _fid, payload.script);
+      }
       const viaBridge = async () => {
         const r = await sendContentCommand(
           evalTabId, "mcp-content-eval", { source: payload.script }, 10000
@@ -4170,6 +4180,86 @@ function _isFrameMiss(value) {
 // Execute in ALL frames (including cross-origin iframes) and return the first real
 // match.  A top-frame `Element not found` is a semantic miss, not a result: allowing
 // it to win used to hide valid matches in every child frame behind it.
+// --- Frame targeting -------------------------------------------------------
+// Every other command reaches only the tab's main frame, so a cross-origin
+// iframe — a micro-frontend app shell, an embedded checkout, GoHighLevel's
+// workflow builder — was effectively invisible: read_page returned the outer
+// shell's loader text and evaluate ran outside the app entirely. Safari's
+// scripting.executeScript can address one frame by id, so these expose the
+// frame list and let a script run inside a chosen frame.
+async function listFrames(tabId = null) {
+  const id = tabId || (await getActiveTab()).id;
+  const results = await _executeAllFrames(() => ({
+    url: location.href,
+    title: document.title,
+    textLength: ((document.body && document.body.innerText) || "").length,
+  }), [], id);
+  return results.map((r, i) => (
+    r && r.error
+      ? { index: i, frameId: Number.isInteger(r.frameId) ? r.frameId : null, error: String(r.error) }
+      : { index: i, frameId: Number.isInteger(r && r.frameId) ? r.frameId : null, ...((r && r.result) || {}) }
+  ));
+}
+
+// Resolve a caller's frame selector to one concrete frameId. `frame` is either a
+// numeric frameId or a substring matched against each frame's URL. Ambiguity is
+// an error rather than a guess: silently picking one of several matching frames
+// is how an automation ends up acting on the wrong document.
+async function resolveFrameId(tabId, frame) {
+  if (typeof frame === "number" && Number.isInteger(frame)) return frame;
+  const needle = String(frame == null ? "" : frame).toLowerCase();
+  if (!needle) throw new Error("frame must be a frameId number or a URL substring");
+  const frames = await listFrames(tabId);
+  const hits = frames.filter((f) => !f.error && typeof f.url === "string" && f.url.toLowerCase().includes(needle));
+  if (hits.length === 0) {
+    throw new Error("No frame matched " + JSON.stringify(String(frame)) + ". Frames present: " +
+      (frames.map((f) => f.url || ("#" + f.index)).join(" | ") || "(none)"));
+  }
+  if (hits.length > 1) {
+    throw new Error("Frame selector " + JSON.stringify(String(frame)) + " matched " + hits.length +
+      " frames — narrow it: " + hits.map((f) => f.url).join(" | "));
+  }
+  if (!Number.isInteger(hits[0].frameId)) throw new Error("Matched frame has no stable frameId");
+  return hits[0].frameId;
+}
+
+// Run one script inside a single frame. MAIN world first so the script sees the
+// page's own globals; ISOLATED as the fallback for frames whose CSP blocks eval —
+// it still reads and mutates the DOM, which is what clicking and filling need.
+async function evaluateInFrame(tabId, frameId, script) {
+  const id = tabId || (await getActiveTab()).id;
+  const runner = async (src) => {
+    try {
+      const result = await (0, eval)(src);
+      if (result === undefined || result === null) return null;
+      return typeof result === "object" ? JSON.stringify(result) : String(result);
+    } catch (e) {
+      const m = String(e && e.message);
+      if (m.includes("unsafe-eval") || m.includes("trusted-types") || m.includes("Trusted Type")) {
+        return "__CSP_BLOCKED__";
+      }
+      return "Error: " + m;
+    }
+  };
+  const run = async (world) => {
+    const results = await _withInjectionDeadline(browser.scripting.executeScript({
+      target: { tabId: id, frameIds: [frameId] },
+      world,
+      func: runner,
+      args: [script],
+    }));
+    const first = results[0];
+    if (first && first.error) throw new Error(first.error);
+    return first && first.result;
+  };
+  const mainResult = await run("MAIN");
+  if (mainResult !== "__CSP_BLOCKED__") return mainResult;
+  const isolated = await run("ISOLATED");
+  return isolated === "__CSP_BLOCKED__"
+    ? "Error: eval is blocked by CSP in both MAIN and ISOLATED worlds for this frame"
+    : isolated;
+}
+
 async function execInAllFrames(func, args = [], tabId = null) {
   try {
     const results = await _executeAllFrames(func, args, tabId);

package/extension/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": 3,
   "name": "Safari MCP Bridge",
   "description": "Connects AI agents to Safari — fast JS execution, screenshots, clicks with your real cookies/logins",
-  "version": "2.10.10",
+  "version": "2.10.11",
   "icons": {
     "48": "images/icon-48.png",
     "96": "images/icon-96.png",
@@ -65,4 +65,4 @@
       "run_at": "document_start"
     }
   ]
-}
+}

package/index.js

@@ -16,6 +16,7 @@ import {
   OWNERSHIP_DIR, BLANK_TAB_SENTINEL,
   _openedTabs, _ownedTabURLs,
   _isURLOwned, _markBlankTabOpened, _addOwnedURL, _removeOwnedURL, _trackTab, _untrackTab,
+  allowUserTabs, _adoptUserTab, _isAdoptedURL,
 } from "./ownership-state.js";
 import { WebSocketServer } from "ws";
 import { createServer } from "node:http";
@@ -1445,6 +1446,7 @@ const _noOwnershipCheck = new Set([
   "reload_extension",
   // Read-only — don't modify the page
   "read_page", "get_source", "snapshot", "accessibility_snapshot",
+  "list_frames",
   "get_element", "query_all", "screenshot", "screenshot_element",
   "get_console", "list_console_messages", "start_console",
   "get_network", "list_network_requests", "start_network_capture",
@@ -1865,11 +1867,24 @@ async function _runExtensionBatchAction(action, args = {}) {
 // an owned tab — this is what prevents navigating/clicking in the user's tabs.
 function _assertTabOwnership(opType, extensionPayload = {}) {
   if (_noOwnershipCheck.has(opType)) return;
+  // Closing is the one op the opt-in never unlocks (#92, condition 2). Adoption makes a
+  // user's tab writable, not disposable — a wrong close costs work that cannot be undone
+  // (#68). Checked before every early return so the batch action and the tool share it.
+  if (opType === "close_tab" && _isAdoptedURL(safari.getActiveTabURL())) {
+    const msg = `⚠️ Tab safety: refusing "close_tab" — this tab was adopted from you via SAFARI_MCP_ALLOW_USER_TABS, not opened by this MCP session. Close it yourself, or open your own tab with safari_new_tab.`;
+    console.error(`[Safari MCP] ${msg}`);
+    throw new Error(msg);
+  }
   // In a named profile the extension is the authority. A bearer receipt may be
   // presented after a stateless reconnect; only the extension can validate its exact
   // tab binding, freshness, digest, and origin.
   if (_preferAppleScript && _receiptToken(extensionPayload.receipt || _getActiveReceipt())) return;
   const currentUrl = safari.getActiveTabURL();
+  // An adopted tab (#92) is the session's target even though the session opened nothing.
+  if (_isAdoptedURL(currentUrl)) {
+    console.error(`[Safari MCP] "${opType}" on ${_safeUrlForOutput(currentUrl)} (user tab, opted-in)`);
+    return;
+  }
   if (_ownedTabURLs.size === 0 && _openedTabs.size === 0) {
     // No tabs opened yet — block everything except read-only ops
     const msg = `⚠️ Tab safety: no tabs opened yet. Call safari_new_tab first before "${opType}".`;
@@ -2780,7 +2795,12 @@ server.tool(
     }
 
     // Tab ownership check: verify target tab is one we opened
-    if (!process.env.SAFARI_PROFILE && _ownedTabURLs.size > 0) {
+    let adopted = false;
+    // `_ownedTabURLs.size > 0` alone skipped this whole lookup for a session that had opened
+    // nothing — fine while switch_tab could only reach owned tabs, but adoption (#92) has to
+    // work from a cold session, which is precisely the "read the article in my current tab"
+    // case the opt-in exists for.
+    if (!process.env.SAFARI_PROFILE && (_ownedTabURLs.size > 0 || allowUserTabs())) {
       // Get target tab's URL via list_tabs before switching
       try {
         const tabs = await extensionOrFallback(
@@ -2804,8 +2824,16 @@ server.tool(
           // fallback (which has no ownership check of its own) stays guarded.
           const trackedOrigin = _originOf(_openedTabs.get(index)?.url);
           const isTrackedRedirect = !!trackedOrigin && trackedOrigin === _originOf(target.url);
-          if (!isBlankOwned && !isTrackedRedirect) {
-            const msg = `⚠️ Tab safety: refusing switch_tab to index ${index} (${_safeUrlForOutput(target.url)}) — not opened by this MCP session. Use safari_new_tab to open your own tab.`;
+          if (!isBlankOwned && !isTrackedRedirect && allowUserTabs()) {
+            // The opt-in turns this refusal into a deliberate, named adoption (#92). Both
+            // spellings of the URL go in: the tool layer hands callers the query-stripped
+            // form and later compares against it, while list_tabs reported the raw one.
+            _adoptUserTab(target.url);
+            _adoptUserTab(_safeUrlForOutput(target.url));
+            adopted = true;
+            console.error(`[Safari MCP] switch_tab adopted ${_safeUrlForOutput(target.url)} (user tab, opted-in via SAFARI_MCP_ALLOW_USER_TABS)`);
+          } else if (!isBlankOwned && !isTrackedRedirect) {
+            const msg = `⚠️ Tab safety: refusing switch_tab to index ${index} (${_safeUrlForOutput(target.url)}) — not opened by this MCP session. Use safari_new_tab to open your own tab, or set SAFARI_MCP_ALLOW_USER_TABS=1 to let switch_tab adopt a tab you already had open.`;
             console.error(`[Safari MCP] ${msg}`);
             return errorResult(msg);
           }
@@ -2822,7 +2850,10 @@ server.tool(
     if (resolvedIndex) safari.setActiveTabIndex(resolvedIndex);
     if (safeResult?.safeUrl) safari.setActiveTabURL(safeResult.safeUrl);
     if (safeResult?.receipt || token) _setActiveReceipt(safeResult?.receipt || token);
-    return { content: [{ type: "text", text: JSON.stringify(safeResult) }] };
+    // Say so in the result, not only in the log: an agent that adopted a user's tab should
+    // be able to see that from the answer it got (#92, condition 3).
+    const reported = adopted ? { ...safeResult, note: "(user tab, opted-in)" } : safeResult;
+    return { content: [{ type: "text", text: JSON.stringify(reported) }] };
   }
 );
 
@@ -2906,6 +2937,23 @@ server.tool(
   }
 );
 
+// ========== FRAMES ==========
+
+server.tool(
+  "safari_list_frames",
+  "List every document in the tab — the main page plus each iframe — with its frameId, URL and text length. Use when a page's content lives in a cross-origin iframe (an embedded app, a micro-frontend shell, a payment field): safari_read_page and safari_evaluate see only the main document there and come back empty or with a loader. Pass the frameId or a URL substring as safari_evaluate's `frame` to run inside it.",
+  {
+    receipt: z.string().optional().describe("Opaque extension-issued tab receipt"),
+  },
+  async (args) => {
+    const result = await extensionOrFallback(
+      "list_frames", { ..._explicitReceipt(args) },
+      () => { throw new Error("safari_list_frames needs the extension — AppleScript cannot enumerate frames. Check safari_doctor."); }
+    );
+    return { content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result, null, 2) }] };
+  }
+);
+
 // ========== EVALUATE JAVASCRIPT ==========
 
 server.tool(
@@ -2913,12 +2961,19 @@ server.tool(
   "Execute JavaScript in the current page (a returned Promise is awaited — fetch/timers work in background tabs; requestAnimationFrame never fires there). Automatically falls back to AppleScript when CSP blocks execution (e.g. Google Search Console, LinkedIn). For reading data, prefer safari_read_page or safari_snapshot. For interactions, prefer safari_click/fill with refs.",
   {
     script: z.string().describe("JavaScript code to execute"),
+    frame: z.union([z.string(), z.number()]).optional().describe("Run inside a sub-frame instead of the main document: a frameId from safari_list_frames, or a substring of the frame's URL (must match exactly one). Needed for cross-origin iframes — micro-frontend app shells, embedded checkouts — where the main document only holds a loader."),
     receipt: z.string().optional().describe("Opaque extension-issued tab receipt — pass the one safari_new_tab returned to keep targeting that tab after an MCP reconnect"),
   },
   async (args) => {
     const result = await extensionOrFallback(
-      "evaluate", { script: args.script, ..._explicitReceipt(args) },
-      () => safari.evaluate(args)
+      "evaluate",
+      { script: args.script, ...(args.frame === undefined ? {} : { frame: args.frame }), ..._explicitReceipt(args) },
+      () => {
+        if (args.frame !== undefined) {
+          throw new Error("safari_evaluate: frame targeting needs the extension — AppleScript reaches only the main document. Check the extension is connected (safari_doctor).");
+        }
+        return safari.evaluate(args);
+      }
     );
     return { content: [{ type: "text", text: (typeof result === 'string' ? result : JSON.stringify(result)) || "(no return value)" }] };
   }

package/ownership-state.js

@@ -62,6 +62,10 @@ export function _saveOwnershipFile(urls, removed = []) {
     const mergedTs = new Map();
     for (const e of _loadOwnershipFile()) mergedTs.set(e.url, e.ts);
     for (const url of urls) {
+      // Adopted user tabs (#92) are session-local by construction — see _adoptUserTab. This
+      // is the one place that writes the file, so the exclusion belongs here rather than at
+      // each caller: _pruneExpiredOwnership() also saves, and it does not know about adoption.
+      if (_adoptedTabURLs.has(url)) continue;
       const localTs = _ownedTabTimestamps.get(url) ?? now;
       mergedTs.set(url, Math.max(localTs, mergedTs.get(url) ?? 0));
     }
@@ -148,6 +152,47 @@ export function _markBlankTabOpened() {
   }
 }
 
+// ========== OPT-IN TAB ADOPTION (#92) ==========
+// With SAFARI_MCP_ALLOW_USER_TABS set, an EXPLICIT safari_switch_tab may adopt a tab the
+// user already had open, and the session then acts on it like one of its own. The flag
+// deliberately unlocks adoption rather than blanket-skipping the guards: "the server acts
+// on the tab you pointed it at, not the one you wandered to" is the property that makes the
+// opt-in safe, and an ambient op landing on whatever tab is frontmost is the exact failure
+// the guards were built against. Read from the environment on each call so a host can flip
+// it without a restart and so tests need no module reload.
+export function allowUserTabs() {
+  const v = String(process.env.SAFARI_MCP_ALLOW_USER_TABS || "").trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
+// URLs adopted from the user, as opposed to opened by this session. Two rules ride on this
+// set: closing is refused for every member (#68 — a wrong close costs the user work that a
+// wrong read never does), and nothing in it is ever written to the shared ownership file.
+export const _adoptedTabURLs = new Set();
+
+// Adoption is in-memory ONLY. owned-tabs.json is shared by every safari-mcp process on the
+// machine and outlives this session, so a persisted adoption would hand the user's tab to
+// the next process — one that has no _adoptedTabURLs entry and would therefore let
+// close_tab through. Session-local is also the honest lifetime: the opt-in is "act on the
+// tab I pointed you at", not "own it from now on".
+export function _adoptUserTab(url) {
+  if (!allowUserTabs()) return false;
+  if (!url || url === "about:blank" || url === "missing value" || url === "favorites://") return false;
+  _adoptedTabURLs.add(url);
+  if (!_ownedTabTimestamps.has(url)) _ownedTabTimestamps.set(url, Date.now());
+  _ownedTabURLs.add(url);
+  return true;
+}
+
+export function _isAdoptedURL(url) {
+  if (!url) return false;
+  if (_adoptedTabURLs.has(url)) return true;
+  // The caller may hold the query-stripped form of the URL (origin+pathname) that the tool
+  // layer hands back, while adoption recorded the raw one, or the reverse. Both name the
+  // same adopted document, and only a refusal hangs off this answer.
+  return findOwnedMatch(url, _adoptedTabURLs) !== null;
+}
+
 export function _addOwnedURL(url) {
   if (url && url !== "about:blank" && url !== "favorites://") {
     if (!_ownedTabTimestamps.has(url)) _ownedTabTimestamps.set(url, Date.now());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safari-mcp",
-  "version": "2.19.1",
+  "version": "2.21.0",
   "mcpName": "io.github.achiya-automation/safari-mcp",
   "description": "Safari browser automation for AI agents — native macOS, zero Chrome overhead. 97 tools via AppleScript + JavaScript.",
   "type": "module",

package/safari.js

@@ -14,6 +14,7 @@ import { randomUUID } from "node:crypto";
 import { VIEWPORT_SCRIPT, SAFE_AREA_SCRIPT, PWA_SCRIPT, WEBKIT_COMPAT_SCRIPT } from "./injected-validators.js";
 import { escJsSingleQuote, escAppleScriptString } from "./injected-escape.js";
 import { currentSessionId } from "./session-context.js";
+import { allowUserTabs } from "./ownership-state.js";
 // Extension bridge is handled by index.js (WebSocket server on port 9223)
 
 const execFileAsync = promisify(execFile);
@@ -5781,6 +5782,14 @@ export async function doctor() {
   const passed = checks.filter((c) => c.ok).length;
   const lines = [`Safari MCP doctor — ${passed}/${checks.length} checks passed`, ""];
   if (osLine) lines.push(osLine, "");
+  // Not a pass/fail check — a state the user has to be able to see here rather than dig out
+  // of the host's env, so "why did it touch my tab" has an answer in the same report (#92).
+  lines.push(
+    allowUserTabs()
+      ? "ℹ️ Tab adoption (SAFARI_MCP_ALLOW_USER_TABS): ON — safari_switch_tab may adopt a tab you already had open. safari_close_tab still refuses an adopted tab."
+      : "ℹ️ Tab adoption (SAFARI_MCP_ALLOW_USER_TABS): off (default) — the session acts only on tabs it opened itself.",
+    "",
+  );
   for (const c of checks) {
     lines.push(`${c.ok ? "✅" : "❌"} ${c.label}: ${c.detail}`);
     if (!c.ok && c.fix) lines.push(`   → ${c.fix}`);