safari-mcp 2.7.9 → 2.7.11

package/README.md

@@ -538,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/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) {
@@ -953,6 +991,37 @@ 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) }] };
+  }
+);
+
+server.tool(
+  "safari_native_keyboard",
+  "OS-level keyboard event via macOS CGEvent — sends a real keypress (with optional modifiers) to the Safari window WITHOUT activating Safari or stealing focus. Use when safari_press_key's JS path doesn't reach React trust-gated handlers (Discord ProseMirror Enter, Slack send, virtualized editors). Keys: enter, return, tab, escape, space, delete, backspace, up/down/left/right, home, end, pageup, pagedown, f1-f6, a-z, 0-9 and common punctuation. Modifiers: cmd, shift, alt, ctrl. Produces isTrusted:true events. Never activates Safari — runs entirely in the background.",
+  {
+    key: z.string().describe("Key name: enter, escape, tab, space, arrow keys, letters, digits, etc."),
+    modifiers: z.array(z.string()).optional().default([]).describe("Modifier keys: cmd, shift, alt, ctrl"),
+  },
+  async (args) => {
+    const result = await safari.nativeKeyboard(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.9",
+  "version": "2.7.11",
   "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-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
@@ -324,13 +383,30 @@ while let line = readLine(strippingNewline: true) {
     continue
   }
 
-  var errorDict: NSDictionary?
-  let result = nsScript.executeAndReturnError(&errorDict)
+  // Execute on a background thread to avoid blocking stdin reading.
+  // Heavy pages (SourceForge, etc.) can cause executeAndReturnError() to block
+  // for 10-30+ seconds, preventing ALL subsequent commands from being read.
+  let semaphore = DispatchSemaphore(value: 0)
+  var scriptResult: NSAppleEventDescriptor?
+  var scriptError: NSDictionary?
+
+  DispatchQueue.global(qos: .userInitiated).async {
+    var errorDict: NSDictionary?
+    scriptResult = nsScript.executeAndReturnError(&errorDict)
+    scriptError = errorDict
+    semaphore.signal()
+  }
+
+  // Wait up to 30 seconds for the script to complete.
+  // If it times out, respond with error but don't block the loop forever.
+  let waitResult = semaphore.wait(timeout: .now() + 30.0)
 
-  if let error = errorDict {
+  if waitResult == .timedOut {
+    respond(["error": "AppleScript execution timed out (30s)"])
+  } else if let error = scriptError {
     let msg = (error["NSAppleScriptErrorMessage"] as? String) ?? "AppleScript error"
     respond(["error": msg])
   } else {
-    respond(["result": result.stringValue ?? ""])
+    respond(["result": scriptResult?.stringValue ?? ""])
   }
 }

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 }) {
@@ -1277,6 +1397,44 @@ const jsKeyMap = {
   f1: "F1", f2: "F2", f3: "F3", f4: "F4", f5: "F5", f6: "F6",
 };
 
+// macOS virtual key codes for CGEvent keyboard (used by _helperNativeKeyboard).
+// These are the HID-level codes that postToPid uses, NOT JS keyCode values.
+const macKeyCodeMap = {
+  enter: 36, return: 36, "numpad-enter": 76,
+  tab: 48, space: 49, delete: 51, backspace: 51, escape: 53,
+  up: 126, "arrowup": 126, down: 125, "arrowdown": 125,
+  left: 123, "arrowleft": 123, right: 124, "arrowright": 124,
+  home: 115, end: 119, pageup: 116, pagedown: 121,
+  f1: 122, f2: 120, f3: 99, f4: 118, f5: 96, f6: 97,
+  a: 0, s: 1, d: 2, f: 3, h: 4, g: 5, z: 6, x: 7, c: 8, v: 9,
+  b: 11, q: 12, w: 13, e: 14, r: 15, y: 16, t: 17,
+  "1": 18, "2": 19, "3": 20, "4": 21, "6": 22, "5": 23,
+  "=": 24, "9": 25, "7": 26, "-": 27, "8": 28, "0": 29,
+  "]": 30, o: 31, u: 32, "[": 33, i: 34, p: 35,
+  l: 37, j: 38, "'": 39, k: 40, ";": 41, "\\": 42,
+  ",": 43, "/": 44, n: 45, m: 46, ".": 47, "`": 50,
+};
+
+// Native keyboard via CGEvent — sends a single key (with optional modifiers)
+// to the Safari window WITHOUT activating Safari or moving the mouse.
+// This produces isTrusted:true events that bypass React trust checks (Discord ProseMirror,
+// Slack virtualized editors, etc.) without any focus stealing. Requires Safari window ID.
+export async function nativeKeyboard({ key, modifiers = [] }) {
+  await ensureHelpers();
+  if (!key) throw new Error("nativeKeyboard requires 'key'");
+  const k = String(key).toLowerCase();
+  const keyCode = macKeyCodeMap[k];
+  if (keyCode === undefined) {
+    throw new Error(`nativeKeyboard: unsupported key "${key}". Supported: ${Object.keys(macKeyCodeMap).join(", ")}`);
+  }
+  const geo = await _getSafariWindowGeometry();
+  if (!geo.windowId) throw new Error("Cannot native-key without Safari window ID — would steal focus");
+  const normalized = (modifiers || []).map(m => String(m).toLowerCase());
+  await _helperNativeKeyboard(keyCode, normalized, geo.windowId);
+  const modsLabel = normalized.length ? normalized.join("+") + "+" : "";
+  return `Native key: ${modsLabel}${k} (CGEvent to window ${geo.windowId}, no focus steal)`;
+}
+
 // System Events key codes — only used for paste_image, upload_file, save_pdf
 // (functions that truly require OS-level UI interaction)