safari-mcp 2.10.8 → 2.10.9

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.9",
   "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/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}