safari-mcp 2.20.0 → 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/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";
@@ -1866,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}".`;
@@ -2781,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(
@@ -2805,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);
           }
@@ -2823,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) }] };
   }
 );
 

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.20.0",
+  "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}`);