safari-mcp 2.7.8 → 2.7.10

package/README.md

@@ -426,13 +426,22 @@ The extension requires a one-time build with Xcode (free, included with macOS).
 # 1. Clone the repo (the npm package does not include the Xcode project)
 git clone https://github.com/achiya-automation/safari-mcp.git
 cd safari-mcp
+
+# 2. Build the extension
 xcodebuild -project "xcode/Safari MCP/Safari MCP.xcodeproj" \
   -scheme "Safari MCP (macOS)" -configuration Release build
 
-# 2. Find and open the built app
-open ~/Library/Developer/Xcode/DerivedData/Safari_MCP-*/Build/Products/Release/Safari\ MCP.app
+# 3. Ad-hoc sign the built app so Safari will load it
+# (xcodebuild without a signing identity produces a bundle Safari silently rejects)
+APP_PATH=$(find ~/Library/Developer/Xcode/DerivedData/Safari_MCP-*/Build/Products/Release -name "Safari MCP.app" -maxdepth 2 | head -1)
+codesign --sign - --force --deep "$APP_PATH"
+
+# 4. Open the app (needed once so Safari registers the extension)
+open "$APP_PATH"
 ```
 
+Alternatively, open `xcode/Safari MCP/Safari MCP.xcodeproj` directly in Xcode, select your Apple ID under Signing & Capabilities, and click Run. A free personal Apple Developer account is sufficient for local use.
+
 Then in Safari:
 1. Safari → Settings → Advanced → enable **Show features for web developers**
 2. Safari → Develop → **Allow Unsigned Extensions** (required each Safari restart)
@@ -456,8 +465,21 @@ Safari MCP needs these one-time permissions:
 | Permission | Where | Why |
 |-----------|-------|-----|
 | JavaScript from Apple Events | Safari → Develop menu | Required for `do JavaScript` |
-| Screen Recording | System Settings → Privacy | Required for `safari_screenshot` |
-| Accessibility | System Settings → Privacy | Required for `safari_save_pdf` only |
+| 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 |
+
+### Granting Automation → Safari (important for IDE users)
+
+macOS TCC grants Automation permission to the **parent process** that spawns the MCP server, not to `safari-mcp` itself. So you need to grant **Automation → Safari** to the app that runs Claude Code / Cursor / Windsurf — typically **Visual Studio Code** or **Terminal**.
+
+If the permission dialog never appears automatically, run this command once from a Terminal that already has Automation permission:
+
+```bash
+osascript -e 'tell application "Safari" to get URL of current tab of window 1'
+```
+
+That call registers the Terminal app in the Automation database and then triggers the prompt for Safari. After you approve it, subsequent MCP calls from any child process chain will work.
 
 ---
 
@@ -466,6 +488,7 @@ Safari MCP needs these one-time permissions:
 | Issue | Fix |
 |-------|-----|
 | "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) |
 | 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 |
@@ -515,7 +538,7 @@ Your support funds:
 
 ## Community
 
-**2,000+ weekly npm downloads** — developers are using Safari MCP to build AI agents on macOS.
+**2,000+ monthly npm downloads** — developers are using Safari MCP to build AI agents on macOS.
 
 - [GitHub Discussions](https://github.com/achiya-automation/safari-mcp/discussions) — ask questions, share use cases
 - [Issues](https://github.com/achiya-automation/safari-mcp/issues) — bug reports and feature requests

package/extension/popup/popup.html

@@ -37,42 +37,6 @@
       <span class="slider"></span>
     </label>
   </div>
-  <script>
-    // Inline script — cannot be cached separately by Safari
-    function setStatus(c, t, i) {
-      document.getElementById("statusDot").className = "dot " + c;
-      document.getElementById("statusText").textContent = t;
-      document.getElementById("info").textContent = i;
-    }
-    async function getVal(k, d) {
-      try { const r = await browser.storage.local.get(k); return r[k] !== undefined ? r[k] : d; }
-      catch { return d; }
-    }
-    async function check() {
-      const on = await getVal("mcpEnabled", true);
-      document.getElementById("enableToggle").checked = on;
-      if (!on) { setStatus("paused", "Paused", "Toggle to resume"); return; }
-      // Ask background script for real-time status first
-      try {
-        const resp = await browser.runtime.sendMessage({ action: "getStatus" });
-        if (resp) {
-          if (resp.connected) { setStatus("connected", "Connected", "Port 9224"); return; }
-          if (!resp.enabled) { setStatus("paused", "Paused", "Toggle to resume"); return; }
-        }
-      } catch {}
-      // Fallback: read from storage
-      const s = await getVal("mcpStatus", null);
-      if (s === "connected") setStatus("connected", "Connected", "Port 9224");
-      else if (s === "paused") setStatus("paused", "Paused", "Toggle to resume");
-      else if (s === "checking") setStatus("checking", "Connecting...", "Trying port 9224...");
-      else setStatus("disconnected", "Not connected", "Start the MCP server to connect");
-    }
-    document.getElementById("enableToggle").addEventListener("change", async (e) => {
-      await browser.storage.local.set({ mcpEnabled: e.target.checked });
-      try { browser.runtime.sendMessage({ action: "setEnabled", enabled: e.target.checked }); } catch {}
-      setTimeout(check, 500);
-    });
-    check();
-  </script>
+  <script src="popup.js"></script>
 </body>
 </html>

package/extension/popup/popup.js

@@ -0,0 +1,34 @@
+function setStatus(c, t, i) {
+  document.getElementById("statusDot").className = "dot " + c;
+  document.getElementById("statusText").textContent = t;
+  document.getElementById("info").textContent = i;
+}
+async function getVal(k, d) {
+  try { const r = await browser.storage.local.get(k); return r[k] !== undefined ? r[k] : d; }
+  catch { return d; }
+}
+async function check() {
+  const on = await getVal("mcpEnabled", true);
+  document.getElementById("enableToggle").checked = on;
+  if (!on) { setStatus("paused", "Paused", "Toggle to resume"); return; }
+  // Ask background script for real-time status first
+  try {
+    const resp = await browser.runtime.sendMessage({ action: "getStatus" });
+    if (resp) {
+      if (resp.connected) { setStatus("connected", "Connected", "Port 9224"); return; }
+      if (!resp.enabled) { setStatus("paused", "Paused", "Toggle to resume"); return; }
+    }
+  } catch {}
+  // Fallback: read from storage
+  const s = await getVal("mcpStatus", null);
+  if (s === "connected") setStatus("connected", "Connected", "Port 9224");
+  else if (s === "paused") setStatus("paused", "Paused", "Toggle to resume");
+  else if (s === "checking") setStatus("checking", "Connecting...", "Trying port 9224...");
+  else setStatus("disconnected", "Not connected", "Start the MCP server to connect");
+}
+document.getElementById("enableToggle").addEventListener("change", async (e) => {
+  await browser.storage.local.set({ mcpEnabled: e.target.checked });
+  try { browser.runtime.sendMessage({ action: "setEnabled", enabled: e.target.checked }); } catch {}
+  setTimeout(check, 500);
+});
+check();

package/index.js

@@ -13,9 +13,10 @@ import { WebSocketServer } from "ws";
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 
 const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10 MB cap on POST body — prevents DoS
 
@@ -51,6 +52,36 @@ try {
 // ========== SESSION ID (unique per MCP process — enables per-session tab tracking) ==========
 const SESSION_ID = randomUUID().slice(0, 8);
 
+// ========== PERSISTENT TAB OWNERSHIP ==========
+// The in-memory _ownedTabURLs set is wiped when the MCP process restarts
+// (Claude Code periodically recycles MCP servers). Without persistence, every
+// restart re-triggers "Tab safety: no tabs opened yet" errors forcing a
+// re-open of every tab. Persist the set to a JSON file with a TTL so tabs
+// remain "owned" across process restarts for up to OWNERSHIP_TTL_MS.
+const OWNERSHIP_DIR = join(homedir(), ".safari-mcp");
+const OWNERSHIP_FILE = join(OWNERSHIP_DIR, "owned-tabs.json");
+const OWNERSHIP_TTL_MS = 30 * 60 * 1000; // 30 minutes
+
+function _loadOwnershipFile() {
+  try {
+    if (!existsSync(OWNERSHIP_FILE)) return [];
+    const raw = readFileSync(OWNERSHIP_FILE, "utf8");
+    const data = JSON.parse(raw);
+    if (!Array.isArray(data)) return [];
+    const cutoff = Date.now() - OWNERSHIP_TTL_MS;
+    return data.filter(e => e && typeof e.url === "string" && typeof e.ts === "number" && e.ts > cutoff);
+  } catch { return []; }
+}
+
+function _saveOwnershipFile(urls) {
+  try {
+    if (!existsSync(OWNERSHIP_DIR)) mkdirSync(OWNERSHIP_DIR, { recursive: true });
+    const now = Date.now();
+    const entries = Array.from(urls).map(url => ({ url, ts: now }));
+    writeFileSync(OWNERSHIP_FILE, JSON.stringify(entries), { mode: 0o600 });
+  } catch { /* best-effort */ }
+}
+
 // ========== MEMORY GUARD: track & auto-close MCP-opened tabs ==========
 const MAX_TABS = parseInt(process.env.MCP_MAX_TABS || "6", 10);
 const MEMORY_CHECK_INTERVAL_MS = parseInt(process.env.MCP_MEMORY_CHECK_MS || "60000", 10);
@@ -63,7 +94,8 @@ const _openedTabs = new Map();
 // Tracks URLs of tabs opened by this MCP session.
 // Any tool that modifies a tab (navigate, click, fill, etc.) is blocked
 // unless the current tab was opened via safari_new_tab.
-const _ownedTabURLs = new Set();
+// Hydrated from ~/.safari-mcp/owned-tabs.json so ownership survives MCP restarts.
+const _ownedTabURLs = new Set(_loadOwnershipFile().map(e => e.url));
 
 function _isURLOwned(url) {
   if (!url) return false;
@@ -96,11 +128,17 @@ function _isURLOwned(url) {
 }
 
 function _addOwnedURL(url) {
-  if (url && url !== 'about:blank' && url !== 'favorites://') _ownedTabURLs.add(url);
+  if (url && url !== 'about:blank' && url !== 'favorites://') {
+    _ownedTabURLs.add(url);
+    _saveOwnershipFile(_ownedTabURLs);
+  }
 }
 
 function _removeOwnedURL(url) {
-  if (url) _ownedTabURLs.delete(url);
+  if (url) {
+    _ownedTabURLs.delete(url);
+    _saveOwnershipFile(_ownedTabURLs);
+  }
 }
 
 function _updateOwnedURL(oldUrl, newUrl) {
@@ -147,7 +185,7 @@ let _lastMemoryWarningTime = 0;
 
 function _getWebKitMemoryMB() {
   try {
-    const pids = execFileSync("pgrep", ["-Ef", "WebKit|WebContent"], { encoding: "utf8" }).trim();
+    const pids = execFileSync("pgrep", ["-f", "WebKit|WebContent"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
     if (!pids) return 0;
     const pidList = pids.split("\n").join(",");
     const psOut = execFileSync("ps", ["-p", pidList, "-o", "rss="], { encoding: "utf8" }).trim();
@@ -953,6 +991,24 @@ server.tool(
   }
 );
 
+server.tool(
+  "safari_native_hover",
+  "OS-level mouse hover via macOS CGEvent — moves the real cursor to an element to trigger native :hover / mouseenter handlers. Use for obfuscated UIs where JS-dispatched mouseenter isn't enough, like Discord server sidebars (tooltips only appear on real hover) or portal-rendered tooltips. After hover, call safari_wait_for or safari_evaluate to read the tooltip. Dwells for dwellMs to let tooltips render, then restores the original cursor position by default. Requires Safari window to be visible.",
+  {
+    ref: z.string().optional().describe("Ref ID from safari_snapshot"),
+    selector: z.string().optional().describe("CSS selector"),
+    text: z.string().optional().describe("Visible text to find and hover"),
+    x: z.coerce.number().optional().describe("Viewport X coordinate"),
+    y: z.coerce.number().optional().describe("Viewport Y coordinate"),
+    dwellMs: z.coerce.number().optional().default(500).describe("Milliseconds to dwell over the element so tooltips render (clamped 0-5000)"),
+    restoreMouse: z.boolean().optional().default(true).describe("Restore cursor to original position after dwell"),
+  },
+  async (args) => {
+    const result = await safari.nativeHover(args);
+    return { content: [{ type: "text", text: typeof result === 'string' ? result : JSON.stringify(result) }] };
+  }
+);
+
 // ========== FORM INPUT ==========
 
 server.tool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safari-mcp",
-  "version": "2.7.8",
+  "version": "2.7.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",
@@ -71,5 +71,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "ws": "^8.19.0"
+  },
+  "overrides": {
+    "hono": "^4.12.12",
+    "@hono/node-server": "^1.19.13"
   }
 }

package/safari-helper.swift

@@ -14,6 +14,53 @@ import Darwin
 import CoreGraphics
 import AppKit
 
+// ========== CGEvent Native Hover ==========
+// Moves the mouse cursor to a target position to trigger native :hover / mouseenter
+// without clicking. Used for revealing tooltips on obfuscated UIs (Discord sidebar,
+// virtualized server lists, custom React tooltips) where JS-dispatched mouseenter
+// events aren't enough because the rendering depends on CSS :hover or real pointer
+// position. Optionally restores the original cursor position after dwell.
+func performNativeHover(x: Double, y: Double, windowId: Int64 = 0, dwellMs: Int = 500, restoreMouse: Bool = true) -> [String: Any] {
+  let point = CGPoint(x: x, y: y)
+  let savedPosition = CGEvent(source: nil)?.location ?? CGPoint.zero
+
+  // Get Safari PID for process-targeted event posting (background hover, no focus steal)
+  var safariPID: pid_t = 0
+  if windowId > 0 {
+    let ws = NSWorkspace.shared
+    for app in ws.runningApplications {
+      if app.bundleIdentifier == "com.apple.Safari" {
+        safariPID = app.processIdentifier
+        break
+      }
+    }
+  }
+
+  let kWindowField = CGEventField(rawValue: 91)! // windowUnderMousePointer
+  let kWindowHandlerField = CGEventField(rawValue: 92)! // windowThatCanHandleThisEvent
+
+  func postMove(_ position: CGPoint) {
+    guard let ev = CGEvent(mouseEventSource: nil, mouseType: .mouseMoved, mouseCursorPosition: position, mouseButton: .left) else { return }
+    if windowId > 0 && safariPID > 0 {
+      ev.setIntegerValueField(kWindowField, value: windowId)
+      ev.setIntegerValueField(kWindowHandlerField, value: windowId)
+      ev.postToPid(safariPID)
+    } else {
+      ev.post(tap: .cghidEventTap)
+    }
+  }
+
+  postMove(point)
+  let ms = max(0, min(dwellMs, 5000)) // clamp 0-5000ms to prevent runaway blocking
+  usleep(UInt32(ms * 1000))
+  if restoreMouse {
+    postMove(savedPosition)
+  }
+
+  let targetInfo = windowId > 0 ? " (window \(windowId), background)" : ""
+  return ["result": "hovered at (\(Int(x)),\(Int(y))) for \(ms)ms\(targetInfo)\(restoreMouse ? " (mouse restored)" : "")"]
+}
+
 // ========== CGEvent Native Click ==========
 // Performs a REAL OS-level mouse click that produces isTrusted: true in the browser.
 // Requires Accessibility permissions (same as AppleScript automation).
@@ -256,6 +303,18 @@ while let line = readLine(strippingNewline: true) {
     continue
   }
 
+  // Handle CGEvent hover command — native mouse move to trigger real :hover / mouseenter
+  // {"hover": {"x": 500, "y": 300, "windowId": 4127, "dwellMs": 500, "restoreMouse": true}}
+  if let hoverData = json["hover"] as? [String: Any],
+     let x = hoverData["x"] as? Double,
+     let y = hoverData["y"] as? Double {
+    let windowId = Int64((hoverData["windowId"] as? Int) ?? 0)
+    let dwellMs = (hoverData["dwellMs"] as? Int) ?? 500
+    let restoreMouse = (hoverData["restoreMouse"] as? Bool) ?? true
+    respond(performNativeHover(x: x, y: y, windowId: windowId, dwellMs: dwellMs, restoreMouse: restoreMouse))
+    continue
+  }
+
   // Handle CGEvent keyboard command
   // {"keyboard": {"keyCode": 9, "flags": ["cmd"], "windowId": 4127}}
   // keyCode 9 = V, flags: cmd/shift/alt/ctrl

package/safari.js

@@ -545,6 +545,44 @@ function _helperNativeClick(x, y, doubleClick = false, windowId = 0, timeout = 5
   });
 }
 
+// Sends a CGEvent hover command to the Swift helper daemon.
+// Moves the cursor to (x, y), dwells to let tooltips render, optionally restores cursor.
+function _helperNativeHover(x, y, windowId = 0, dwellMs = 500, restoreMouse = true, timeout = 10000) {
+  return new Promise((resolve, reject) => {
+    if (!_helperProc) startHelper();
+    if (!_helperProc || !_helperProc.stdin || !_helperProc.stdin.writable) {
+      reject(new Error("safari-helper not available for native hover"));
+      return;
+    }
+    let resolved = false;
+    const timer = setTimeout(() => {
+      if (resolved) return;
+      resolved = true;
+      const idx = _helperQueue.indexOf(cb);
+      if (idx >= 0) _helperQueue[idx] = () => {};
+      reject(new Error("native hover timeout"));
+    }, timeout);
+
+    function cb(line) {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      try {
+        const parsed = JSON.parse(line);
+        if (parsed.error) reject(new Error(parsed.error));
+        else resolve(parsed.result ?? "");
+      } catch {
+        resolve(line);
+      }
+    }
+
+    _helperQueue.push(cb);
+    const cmd = { hover: { x, y, dwellMs, restoreMouse } };
+    if (windowId) cmd.hover.windowId = windowId;
+    _helperProc.stdin.write(JSON.stringify(cmd) + "\n");
+  });
+}
+
 // Sends a CGEvent keyboard command to the Swift helper daemon.
 // No focus stealing — sends key events directly to the target window via PID.
 function _helperNativeKeyboard(keyCode, flags = [], windowId = 0, timeout = 5000) {
@@ -1120,6 +1158,88 @@ export async function nativeClick({ selector, text, x, y, ref, doubleClick = fal
   return `${clickType}: ${label} at screen (${screenX},${screenY})`;
 }
 
+// ========== NATIVE HOVER (OS-level CGEvent mouse move — triggers real :hover and mouseenter) ==========
+// JS-dispatched mouseenter events work for most React components, but some UIs
+// (Discord sidebar, virtualized CSS :hover tooltips, custom portal-rendered
+// tooltips) only respond to a real OS-level cursor position. This function
+// moves the physical cursor to the target, dwells for tooltips to render,
+// then optionally restores the cursor to its original position.
+export async function nativeHover({ selector, text, x, y, ref, dwellMs = 500, restoreMouse = true }) {
+  await ensureHelpers();
+
+  // Step 1: Get element's viewport coordinates via JavaScript
+  let viewportCoords;
+  if (ref || selector || text) {
+    let jsExpr;
+    if (ref) {
+      jsExpr = `(function(){
+        var el = mcpFindRef('${ref}');
+        if (!el) return JSON.stringify({error: 'Element not found: ref=${ref}'});
+        el.scrollIntoView({block:'center', behavior:'instant'});
+        var rect = el.getBoundingClientRect();
+        return JSON.stringify({
+          x: Math.round(rect.left + rect.width / 2),
+          y: Math.round(rect.top + rect.height / 2),
+          tag: el.tagName,
+          text: (el.innerText || el.textContent || '').trim().substring(0, 50)
+        });
+      })()`;
+    } else if (selector) {
+      const sel = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+      jsExpr = `(function(){
+        var el = document.querySelector('${sel}');
+        if (!el) return JSON.stringify({error: 'Element not found: ${sel}'});
+        el.scrollIntoView({block:'center', behavior:'instant'});
+        var rect = el.getBoundingClientRect();
+        return JSON.stringify({
+          x: Math.round(rect.left + rect.width / 2),
+          y: Math.round(rect.top + rect.height / 2),
+          tag: el.tagName,
+          text: (el.innerText || el.textContent || '').trim().substring(0, 50)
+        });
+      })()`;
+    } else {
+      const safeText = text.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+      jsExpr = `(function(){
+        var el = mcpFindText('${safeText}', true) || mcpFindText('${safeText}', false);
+        if (!el) return JSON.stringify({error: 'Element not found with text: ${safeText}'});
+        el.scrollIntoView({block:'center', behavior:'instant'});
+        var rect = el.getBoundingClientRect();
+        return JSON.stringify({
+          x: Math.round(rect.left + rect.width / 2),
+          y: Math.round(rect.top + rect.height / 2),
+          tag: el.tagName,
+          text: (el.innerText || el.textContent || '').trim().substring(0, 50)
+        });
+      })()`;
+    }
+
+    const result = await runJS(jsExpr);
+    try {
+      viewportCoords = JSON.parse(result);
+    } catch {
+      throw new Error("Failed to get element coordinates: " + result);
+    }
+    if (viewportCoords.error) {
+      throw new Error(viewportCoords.error);
+    }
+  } else if (x !== undefined && y !== undefined) {
+    viewportCoords = { x: Number(x), y: Number(y), tag: 'point', text: '' };
+  } else {
+    throw new Error("nativeHover requires selector, text, ref, or x/y coordinates");
+  }
+
+  const geo = await _getSafariWindowGeometry();
+  const screenX = geo.windowX + viewportCoords.x;
+  const screenY = geo.windowY + geo.toolbarHeight + viewportCoords.y;
+
+  if (!geo.windowId) throw new Error("Cannot native-hover without Safari window ID — would move mouse and steal focus");
+  await _helperNativeHover(screenX, screenY, geo.windowId, dwellMs, restoreMouse);
+
+  const label = viewportCoords.tag + (viewportCoords.text ? ` "${viewportCoords.text}"` : '');
+  return `Native hovered: ${label} at screen (${screenX},${screenY}) for ${dwellMs}ms${restoreMouse ? ' (mouse restored)' : ''}`;
+}
+
 // ========== FORM INPUT ==========
 
 export async function fill({ selector, value, ref }) {