safari-mcp 2.10.8 → 2.10.10

package/README.md

@@ -645,7 +645,23 @@ Safari MCP needs these one-time permissions:
 | JavaScript from Apple Events | Safari → Develop menu | Required for `do JavaScript` |
 | Automation → Safari | System Settings → Privacy & Security → Automation | Required for all AppleScript-backed tools |
 | Screen Recording | System Settings → Privacy & Security → Screen Recording | Required for `safari_screenshot` |
-| Accessibility | System Settings → Privacy & Security → Accessibility | Required for `safari_save_pdf` only |
+| Accessibility (safari-helper) | System Settings → Privacy & Security → Accessibility | Required for `safari_native_click`, `safari_native_keyboard`, `safari_native_hover` and `safari_save_pdf` |
+
+### Granting Accessibility to safari-helper (required for `safari_native_*`)
+
+The `safari_native_click`, `safari_native_keyboard` and `safari_native_hover` tools inject OS-level `CGEvent` events into Safari without stealing focus. macOS requires the underlying helper binary to be approved in **Accessibility** before those events can reach a non-frontmost window.
+
+1. Open **System Settings → Privacy & Security → Accessibility**.
+2. Click `+` (unlock with your password if needed).
+3. Navigate to the helper binary and add it:
+   - npm global install: `$(npm root -g)/safari-mcp/safari-helper`
+   - npx / project install: `./node_modules/safari-mcp/safari-helper`
+   - From source clone: `/path/to/safari-mcp/safari-helper`
+4. Make sure the toggle next to it is **ON**.
+
+The postinstall script re-signs the helper with a stable identifier (`com.achiya-automation.safari-mcp`) so this permission survives future upgrades — without that step, every `npm update` would silently revoke approval because the binary's adhoc-signed identifier changes per build.
+
+If `safari_native_click` reports success but the page doesn't react (no `isTrusted: true` click events fire), the helper is most likely missing this approval. The `safari_*` (non-`native_`) tools don't need it.
 
 ### Granting Automation → Safari (important for IDE users)
 
@@ -668,6 +684,7 @@ That call registers the Terminal app in the Automation database and then trigger
 | "AppleScript error" | Enable "Allow JavaScript from Apple Events" in Safari → Develop |
 | "Not authorized to send Apple events to Safari" | Grant Automation → Safari to your IDE (see above) |
 | "Not authorized" after `npm update` | Updating changes the binary's cdhash — macOS silently revokes Automation permission. Re-run the `osascript` one-liner above to re-grant it |
+| `safari_native_click` reports success but page doesn't react | Add `safari-helper` to **System Settings → Privacy & Security → Accessibility** (see [Granting Accessibility](#granting-accessibility-to-safari-helper-required-for-safari_native_) above). Confirm by attaching a `click` listener with `{capture:true}` in the page console — without the grant, no `isTrusted: true` event fires |
 | Screenshots empty | Grant Screen Recording permission to Terminal/VS Code |
 | Tab not found | Call `safari_list_tabs` to refresh tab indices |
 | Hebrew keyboard issues | All typing uses JS events — immune to keyboard layout |

package/package.json

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

package/safari.js

@@ -216,9 +216,14 @@ async function refreshTargetWindow(force = false) {
   if (!force && _targetWindowRef && (now - _targetWindowCacheTime) < TARGET_WINDOW_CACHE_MS) return;
   const safeProfile = SAFARI_PROFILE.replace(/"/g, '\\"');
   // Find profile window by name AND verify the window ID still matches
-  const result = await osascriptFast(
-    `tell application "Safari"\n  repeat with w in every window\n    if name of w starts with "${safeProfile} \u2014" then return (id of w as text) & "|" & name of w\n  end repeat\n  return "0|"\nend tell`
-  ).catch(() => '0|');
+  const detectScript = `tell application "Safari"\n  repeat with w in every window\n    if name of w starts with "${safeProfile} \u2014" then return (id of w as text) & "|" & name of w\n  end repeat\n  return "0|"\nend tell`;
+  let result = await osascriptFast(detectScript).catch(() => '0|');
+  // The persistent helper occasionally returns '0|' for a window that genuinely
+  // exists (daemon timeout / restart race). Before concluding the window is
+  // missing, retry once with a plain osascript subprocess \u2014 slower but reliable.
+  if (String(result).split('|')[0] === '0') {
+    result = await osascript(detectScript).catch(() => '0|');
+  }
   const [idStr, windowName] = String(result).split('|');
   const id = Number(idStr);
   if (id > 0) {
@@ -243,7 +248,12 @@ async function refreshTargetWindow(force = false) {
 // Background verification: periodically check that cached window ID still belongs to profile
 if (SAFARI_PROFILE) {
   setInterval(async () => {
-    if (!_targetWindowRef || !_targetWindowId) return;
+    // No cached window (e.g. flaky detection at startup) — keep trying to
+    // rediscover it so the server self-heals instead of staying stuck.
+    if (!_targetWindowRef || !_targetWindowId) {
+      await refreshTargetWindow(true).catch(() => {});
+      return;
+    }
     try {
       const name = await osascriptFast(
         `tell application "Safari" to return name of ${_targetWindowRef}`
@@ -374,15 +384,17 @@ async function resolveActiveTab() {
 
   // Strategy 1: window.__mcpTabMarker (bulletproof — survives navigation, redirects, query changes)
   // Only attempted if we have a marker AND a cached index hint
-  if (_activeTabMarker && _activeTabIndex) {
+  if (_activeTabMarker) {
     try {
       const safeMarker = _activeTabMarker.replace(/'/g, "\\'");
       // Single JS call: check cached index first, then walk all tabs to find marker
       const checkScript = `(function(){return window.__mcpTabMarker==='${safeMarker}'?'1':'0'})()`;
-      const matchAtCached = await osascriptFast(
-        `tell application "Safari" to do JavaScript "${checkScript}" in tab ${_activeTabIndex} of ${getTargetWindowRef()}`
-      ).catch(() => '0');
-      if (String(matchAtCached).trim() === '1') return _activeTabIndex;
+      if (_activeTabIndex) {
+        const matchAtCached = await osascriptFast(
+          `tell application "Safari" to do JavaScript "${checkScript}" in tab ${_activeTabIndex} of ${getTargetWindowRef()}`
+        ).catch(() => '0');
+        if (String(matchAtCached).trim() === '1') return _activeTabIndex;
+      }
       // Cached index doesn't match — scan all tabs for marker
       const tabCountStr = await osascriptFast(
         `tell application "Safari" to return count of tabs of ${getTargetWindowRef()}`
@@ -764,13 +776,18 @@ async function runJS(js, { tabIndex, timeout = 15000 } = {}) {
   if (!idx && _activeTabIndex && _activeTabURL && (Date.now() - _lastResolveTime < RESOLVE_CACHE_MS)) {
     // Recently verified and tab count unchanged — use cached index
     idx = _activeTabIndex;
-  } else if (!idx && _activeTabURL && _activeTabURL !== '') {
-    // Resolve by URL — verify index is still correct
+  } else if (!idx && (_activeTabURL || _activeTabMarker)) {
+    // Resolve by URL or marker — the marker scan still finds an owned tab
+    // even after _activeTabURL has been cleared by a failed URL lookup.
     const resolved = await resolveActiveTab();
     if (resolved) { idx = resolved; _lastResolveTime = Date.now(); }
   }
   // ALWAYS fall back to _activeTabIndex — never clear it from resolve failures
   if (!idx) idx = _activeTabIndex;
+  // Once this session owns a tab, never silently run on the user's current tab.
+  if (!idx && _hasOwnedTab && SAFARI_PROFILE) {
+    throw new Error('Tab tracking lost during runJS — refusing to target the user\'s current tab. Call safari_new_tab to reopen.');
+  }
   const target = idx
     ? `tab ${idx} of ${getTargetWindowRef()}`
     : getFallbackTarget();

package/scripts/postinstall.cjs

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-// Safari MCP — postinstall welcome message
+// Safari MCP — postinstall: codesign helper + welcome message
 // Skipped silently in CI and when stdout is not a TTY (npm install in scripts).
 
-if (process.env.CI || process.env.SAFARI_MCP_SILENT_INSTALL === "1") process.exit(0);
+const path = require("path");
+const { execSync } = require("child_process");
+const fs = require("fs");
 
 const c = {
   reset: "\x1b[0m",
@@ -12,8 +14,36 @@ const c = {
   yellow: "\x1b[33m",
   magenta: "\x1b[35m",
   green: "\x1b[32m",
+  red: "\x1b[31m",
 };
 
+// Re-sign safari-helper with a stable identifier so macOS Accessibility approval persists.
+// The package ships with an adhoc-signed binary whose codesign Identifier is a one-off hash
+// (e.g. `safari-helper-555549441c166aa237e130ddbe3d95629266ecaf`). macOS TCC keys grants by
+// that identifier, so a fresh npm install or rebuild silently invalidates any previously-granted
+// Accessibility approval — the helper keeps running but CGEvent injections to non-frontmost Safari
+// windows stop reaching WebKit content (no isTrusted click events fire on the page).
+// Re-signing here with the fixed identifier `com.achiya-automation.safari-mcp` keeps the grant
+// stable across installs.
+function ensureCodesign() {
+  if (process.platform !== "darwin") return;
+  const helper = path.join(__dirname, "..", "safari-helper");
+  if (!fs.existsSync(helper)) return;
+  try {
+    // Check current identifier; only re-sign if it doesn't already match.
+    const current = execSync(`codesign -d -- "${helper}" 2>&1 | grep ^Identifier=`, { encoding: "utf8" }).trim();
+    if (current.includes("com.achiya-automation.safari-mcp")) return;
+    const entitlements = path.join(__dirname, "..", "safari-helper.entitlements");
+    const entFlag = fs.existsSync(entitlements) ? `--entitlements "${entitlements}"` : "";
+    execSync(`codesign -s - -f --identifier com.achiya-automation.safari-mcp ${entFlag} "${helper}" 2>/dev/null`);
+  } catch (_e) {
+    // codesign may fail in environments without the toolchain; binary still works adhoc-signed.
+  }
+}
+ensureCodesign();
+
+if (process.env.CI || process.env.SAFARI_MCP_SILENT_INSTALL === "1") process.exit(0);
+
 const msg = `
 ${c.bold}${c.cyan}🦁 Safari MCP installed${c.reset} ${c.dim}— 80 native browser tools for AI agents${c.reset}
 
@@ -21,6 +51,9 @@ ${c.bold}Next steps:${c.reset}
   1. Enable Safari → Develop → ${c.yellow}Allow JavaScript from Apple Events${c.reset}
   2. Add to your MCP client config:
      ${c.dim}{ "mcpServers": { "safari": { "command": "npx", "args": ["safari-mcp"] } } }${c.reset}
+  3. ${c.bold}For native_click / native_keyboard${c.reset} (no focus stealing):
+     System Settings → Privacy & Security → ${c.yellow}Accessibility${c.reset} → add
+     ${c.dim}node_modules/safari-mcp/safari-helper${c.reset} ${c.dim}(or the global install path)${c.reset}
 
 ${c.bold}${c.magenta}⭐ Found this useful?${c.reset} A star helps others discover it:
    ${c.cyan}https://github.com/achiya-automation/safari-mcp${c.reset}