safari-mcp 2.7.1 → 2.7.4

package/README.md

@@ -1,10 +1,6 @@
 <div align="center">
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/banner.svg">
-  <source media="(prefers-color-scheme: light)" srcset="assets/banner.svg">
-  <img src="assets/banner.svg" alt="Safari MCP — Native browser automation for AI agents" width="100%">
-</picture>
+<img src="social-preview.png" alt="Safari MCP Server — 80 native browser automation tools for AI agents on macOS" width="100%">
 
 <br/>
 
@@ -25,6 +21,7 @@
 
 <a href="vscode:mcp/install?%7B%22safari-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D%7D"><img src="https://img.shields.io/badge/VS_Code-Install_MCP_Server-0078d4?logo=visual-studio-code&logoColor=white" alt="Install in VS Code"></a>
 <a href="https://insiders.vscode.dev/redirect?url=vscode-insiders:mcp/install?%7B%22safari-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D%7D"><img src="https://img.shields.io/badge/VS_Code_Insiders-Install_MCP_Server-24bfa5?logo=visual-studio-code&logoColor=white" alt="Install in VS Code Insiders"></a>
+<a href="https://paypal.me/achiyaC123"><img src="https://img.shields.io/badge/Sponsor-PayPal-blue?logo=paypal" alt="Sponsor"></a>
 
 **80 tools** · **Zero dependencies** · **~5ms per command** · **60% less CPU than Chrome**
 
@@ -34,6 +31,8 @@
 
 </div>
 
+> **If Safari MCP saves you from running Chrome, consider giving it a star!** It helps others discover this project.
+
 ---
 
 > **TL;DR:** Use your real Safari with all your logins, cookies, and sessions. No headless browsers, no Chrome, no Puppeteer. Just pure AppleScript + JavaScript running natively on macOS — 60% less CPU/heat on Apple Silicon.
@@ -533,9 +532,41 @@ The codebase is two files:
 
 ---
 
+## Sponsors
+
+Safari MCP is free and open source. If it saves you time or CPU cycles, consider supporting its development:
+
+<a href="https://paypal.me/achiyaC123"><img src="https://img.shields.io/badge/Sponsor-PayPal-blue?logo=paypal" alt="Sponsor via PayPal"></a>
+
+Your support funds:
+- 🧪 Testing across macOS versions and Safari releases
+- 🛠️ New tools and features
+- 📖 Documentation and examples
+
+[Become the first sponsor!](https://paypal.me/achiyaC123)
+
+---
+
+## Community
+
+Safari MCP is used by developers building AI agents on macOS. [Share your use case in Discussions](https://github.com/achiya-automation/safari-mcp/discussions)
+
+---
+
+## Spread the Word
+
+If you find Safari MCP useful, help others discover it:
+
+- [Star this repo](https://github.com/achiya-automation/safari-mcp)
+- [Share on Twitter/X](https://twitter.com/intent/tweet?text=Safari%20MCP%20%E2%80%94%20Stop%20running%20Chrome%20just%20so%20your%20AI%20agent%20can%20browse.%2080%20tools%2C%20native%20Safari%2C%2060%25%20less%20CPU.&url=https%3A%2F%2Fgithub.com%2Fachiya-automation%2Fsafari-mcp)
+- [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2Fachiya-automation%2Fsafari-mcp)
+- Write about it on dev.to or your blog
+
+---
+
 ## Star History
 
-If Safari MCP saved you from Chrome overhead, consider giving it a ⭐
+If Safari MCP saved you from Chrome overhead, consider giving it a star!
 
 [![Star History Chart](https://api.star-history.com/svg?repos=achiya-automation/safari-mcp&type=Date)](https://star-history.com/#achiya-automation/safari-mcp&Date)
 

package/extension/background.js

@@ -5,7 +5,7 @@
 const HTTP_URL = "http://127.0.0.1:9224";
 let isConnected = false;
 let pollAbort = null;
-let _targetProfile = null;   // Profile name from server (e.g. "אוטומציות")
+let _targetProfile = null;   // Profile name from server (e.g. "Automations")
 let _profileWindowId = null; // Discovered windowId for the profile
 let _enabled = true;         // Toggle from popup — when false, stops polling and rejects commands
 let _reconnectTimer = null;  // Single reconnect timer — prevents exponential growth
@@ -1735,7 +1735,7 @@ browser.tabs.onRemoved.addListener((tabId) => {
 
 // Verify this extension instance is running in the expected profile.
 // Safari extensions see only their own profile's windows/tabs.
-// If the server expects "אוטומציות" but this worker's windows don't match, we're in the wrong profile.
+// If the server expects a specific profile but this worker's windows don't match, we're in the wrong profile.
 async function _verifyProfileMatch(expectedProfile) {
   try {
     const allWindows = await browser.windows.getAll({ populate: true });

package/extension/content.js

@@ -1,6 +1,6 @@
 // Content script — runs at document_start in MAIN world (before page scripts)
 // Purpose: Monkey-patch attachShadow to capture CLOSED shadow roots.
-// Without this, Reddit 2026 and other sites using closed shadow DOM
+// Without this, Reddit and other sites using closed shadow DOM
 // are invisible to snapshot/click/fill.
 // Runs in MAIN world via manifest "world": "MAIN" — no script injection needed,
 // so CSP cannot block it.

package/extension/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": 3,
   "name": "Safari MCP Bridge",
   "description": "Connects AI agents to Safari — fast JS execution, screenshots, clicks with your real cookies/logins",
-  "version": "2.4",
+  "version": "2.7.2",
   "icons": {
     "48": "images/icon-48.png",
     "96": "images/icon-96.png",
@@ -20,6 +20,12 @@
   "host_permissions": ["<all_urls>"],
   "content_scripts": [{
     "matches": ["<all_urls>"],
+    "exclude_matches": [
+      "*://*.linkedin.com/*",
+      "*://*.x.com/*",
+      "*://*.twitter.com/*",
+      "*://*.producthunt.com/*"
+    ],
     "js": ["content.js"],
     "run_at": "document_start",
     "world": "MAIN"

package/extension/popup/popup.html

@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html dir="ltr">
+<html lang="en" dir="ltr">
 <head>
   <meta charset="utf-8">
   <style>

package/index.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Safari MCP — TypeScript type declarations
+ * Covers all ~83 registered tools and the MCP server export.
+ */
+
+// ========== CORE TYPES ==========
+
+export type MCPContent =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string };
+
+export interface MCPToolResult {
+  content: MCPContent[];
+  isError?: boolean;
+}
+
+export interface MCPToolInputSchema {
+  type: "object";
+  properties: Record<string, { type: string; description?: string; enum?: string[] }>;
+  required?: string[];
+}
+
+export interface MCPTool<TInput extends Record<string, unknown> = Record<string, unknown>> {
+  name: string;
+  description: string;
+  inputSchema: MCPToolInputSchema;
+  handler: (input: TInput) => Promise<MCPToolResult>;
+}
+
+
+// ========== TOOL INPUT TYPES ==========
+
+// Navigation
+export interface SafariNavigateInput { url: string }
+export interface SafariGoBackInput {}
+export interface SafariGoForwardInput {}
+export interface SafariReloadInput { hard?: boolean }
+export interface SafariNavigateAndReadInput { url: string; maxLength?: number; timeout?: number }
+
+// Page Info
+export interface SafariReadPageInput { selector?: string; maxLength?: number }
+export interface SafariGetSourceInput { maxLength?: number }
+export interface SafariSnapshotInput { selector?: string }
+
+// Click
+export interface SafariClickInput { ref?: string; selector?: string; text?: string; x?: number; y?: number }
+export interface SafariClickAndReadInput { text?: string; selector?: string; x?: number; y?: number; wait?: number; maxLength?: number }
+export interface SafariDoubleClickInput { selector?: string; x?: number; y?: number }
+export interface SafariRightClickInput { selector?: string; x?: number; y?: number }
+export interface SafariNativeClickInput { ref?: string; selector?: string; text?: string; x?: number; y?: number; doubleClick?: boolean }
+
+// Form Input
+export interface SafariFillInput { ref?: string; selector?: string; value: string }
+export interface SafariClearFieldInput { selector: string }
+export interface SafariSelectOptionInput { selector: string; value: string }
+export interface SafariFillFormField { selector: string; value: string }
+export interface SafariFillFormInput { fields: SafariFillFormField[] }
+
+// Keyboard
+export interface SafariPressKeyInput { key: string; modifiers?: string[] }
+export interface SafariTypeTextInput { text: string; ref?: string; selector?: string }
+
+// Code Editor
+export interface SafariReplaceEditorInput { text: string }
+
+// Screenshot
+export interface SafariScreenshotInput { fullPage?: boolean }
+export interface SafariScreenshotElementInput { selector: string }
+
+// Scroll
+export interface SafariScrollInput { direction?: "up" | "down"; amount?: number }
+export interface SafariScrollToInput { x?: number; y?: number }
+export interface SafariScrollToElementInput {
+  selector?: string;
+  text?: string;
+  block?: "start" | "center" | "end" | "nearest";
+  timeout?: number;
+}
+
+// Tab Management
+export interface SafariListTabsInput {}
+export interface SafariNewTabInput { url?: string }
+export interface SafariCloseTabInput {}
+export interface SafariSwitchTabInput { index: number }
+export interface SafariWaitForNewTabInput { timeout?: number; urlContains?: string }
+
+// Wait
+export interface SafariWaitForInput { selector?: string; text?: string; timeout?: number }
+export interface SafariWaitInput { ms: number }
+
+// Evaluate
+export interface SafariEvaluateInput { script: string }
+
+// Element Info
+export interface SafariGetElementInput { selector: string }
+export interface SafariQueryAllInput { selector: string; limit?: number }
+
+// Hover
+export interface SafariHoverInput { ref?: string; selector?: string; x?: number; y?: number }
+
+// Dialog
+export interface SafariHandleDialogInput { action?: "accept" | "dismiss"; text?: string }
+
+// Window
+export interface SafariResizeInput { width: number; height: number }
+
+// Drag
+export interface SafariDragInput {
+  sourceSelector?: string;
+  targetSelector?: string;
+  sourceX?: number;
+  sourceY?: number;
+  targetX?: number;
+  targetY?: number;
+}
+
+// File / Image
+export interface SafariUploadFileInput { selector: string; filePath: string }
+export interface SafariPasteImageInput { filePath: string }
+
+// Emulation
+export interface SafariEmulateInput { device?: string; width?: number; height?: number; userAgent?: string; scale?: number }
+export interface SafariResetEmulationInput {}
+
+// Cookies & Storage
+export interface SafariGetCookiesInput {}
+export interface SafariLocalStorageInput { key?: string }
+export interface SafariSetCookieInput {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: string;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+export interface SafariDeleteCookiesInput { name?: string; all?: boolean }
+export interface SafariSessionStorageInput { key?: string }
+export interface SafariSetSessionStorageInput { key: string; value: string }
+export interface SafariSetLocalStorageInput { key: string; value: string }
+export interface SafariDeleteLocalStorageInput { key?: string }
+export interface SafariDeleteSessionStorageInput { key?: string }
+export interface SafariExportStorageInput {}
+export interface SafariImportStorageInput { state: string }
+
+// Clipboard
+export interface SafariClipboardReadInput {}
+export interface SafariClipboardWriteInput { text: string }
+
+// Network
+export interface SafariNetworkInput { limit?: number }
+export interface SafariMockRouteResponse { status?: number; body?: string; contentType?: string }
+export interface SafariMockRouteInput { urlPattern: string; response: SafariMockRouteResponse }
+export interface SafariClearMocksInput {}
+export interface SafariStartNetworkCaptureInput {}
+export interface SafariNetworkDetailsInput { limit?: number; filter?: string }
+export interface SafariClearNetworkInput {}
+export interface SafariThrottleNetworkInput { profile?: string; latency?: number; downloadKbps?: number }
+
+// Console
+export interface SafariStartConsoleInput {}
+export interface SafariGetConsoleInput {}
+export interface SafariClearConsoleInput {}
+export interface SafariConsoleFilterInput { level: "log" | "warn" | "error" | "info" }
+
+// PDF
+export interface SafariSavePDFInput { path: string }
+
+// Accessibility
+export interface SafariAccessibilitySnapshotInput { selector?: string; maxDepth?: number }
+
+// Performance
+export interface SafariPerformanceMetricsInput {}
+export interface SafariCSSCoverageInput {}
+
+// Data Extraction
+export interface SafariExtractTablesInput { selector?: string; limit?: number }
+export interface SafariExtractMetaInput {}
+export interface SafariExtractImagesInput { limit?: number }
+export interface SafariExtractLinksInput { limit?: number; filter?: string }
+
+// Geolocation
+export interface SafariOverrideGeolocationInput { latitude: number; longitude: number; accuracy?: number }
+
+// Computed Styles
+export interface SafariGetComputedStyleInput { selector: string; properties?: string[] }
+
+// IndexedDB
+export interface SafariListIndexedDBsInput {}
+export interface SafariGetIndexedDBInput { dbName: string; storeName: string; limit?: number }
+
+// Form Detection
+export interface SafariDetectFormsInput {}
+
+// Batch / Combo Tools
+export interface SafariRunScriptStep { action: string; args?: Record<string, unknown> }
+export interface SafariRunScriptInput { steps: SafariRunScriptStep[] }
+export interface SafariClickAndWaitInput { selector?: string; text?: string; waitFor?: string; timeout?: number }
+export interface SafariFillAndSubmitInput { fields: SafariFillFormField[]; submitSelector?: string }
+export interface SafariAnalyzePageInput {}
+
+// ========== TAB INFO ==========
+
+export interface SafariTab {
+  index: number;
+  title: string;
+  url: string;
+}
+
+// ========== MODULE DECLARATION ==========
+export interface McpServer {
+  connect(transport: unknown): Promise<void>;
+  tool(name: string, description: string, schema: unknown, handler: (input: unknown) => Promise<MCPToolResult>): unknown;
+  close(): Promise<void>;
+}
+
+declare const server: McpServer;
+export default server;

package/index.js

@@ -3,7 +3,7 @@
 // 1. Safari Web Extension (fast, ~5-20ms, keeps logins) — when extension is connected
 // 2. AppleScript + Swift daemon (~5ms, keeps logins) — always available
 //
-// Extension transport: WebSocket (Chrome) OR HTTP polling (Safari — WebSocket blocked by Apple)
+// Extension transport: HTTP polling (Safari — WebSocket blocked by Apple)
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -84,6 +84,13 @@ function _isURLOwned(url) {
         if (new URL(owned).origin === urlOrigin && urlBase.startsWith(normalize(owned))) return true;
       } catch {}
     }
+    // Broader same-origin check: if we own ANY URL on this origin, treat all same-origin URLs as owned.
+    // This handles redirects like /article/new → /article/edit/ID where path prefix doesn't match.
+    for (const owned of _ownedTabURLs) {
+      try {
+        if (new URL(owned).origin === urlOrigin) return true;
+      } catch {}
+    }
   } catch {}
   return false;
 }
@@ -386,6 +393,14 @@ try {
           const { execFile: execFileCb } = await import("node:child_process");
           const { promisify: pfy } = await import("node:util");
           const execFileAsync = pfy(execFileCb);
+          // Don't launch Safari if it's not running
+          try {
+            await execFileAsync("pgrep", ["-x", "Safari"], { timeout: 2000 });
+          } catch {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ match: false, error: "Safari is not running" }));
+            return;
+          }
           const script = `tell application "Safari"
             repeat with w in every window
               repeat with t in every tab of w
@@ -511,11 +526,11 @@ async function _proxyToExtension(type, payload, timeoutMs = 30000) {
 }
 
 let _extensionLastPollTime = 0;
-// Detect stale HTTP connection (no poll in 10s = disconnected)
+// Detect stale HTTP connection (no poll in 30s = disconnected)
 // Only applies to primary instance (extension host) — not proxy mode
 setInterval(() => {
   if (_isExtensionHost && _extensionConnected && !_extensionWs && _extensionLastPollTime > 0) {
-    if (Date.now() - _extensionLastPollTime > 10000) {
+    if (Date.now() - _extensionLastPollTime > 30000) {
       _extensionConnected = false;
       _drainOnDisconnect("HTTP poll timeout");
       console.error("[Safari MCP] Extension disconnected (HTTP poll timeout)");
@@ -635,44 +650,68 @@ async function extensionOrFallback(extensionType, extensionPayload, fallbackFn)
   // must target an owned tab. This prevents navigating/clicking in user's tabs.
   if (!_noOwnershipCheck.has(extensionType)) {
     const currentUrl = safari.getActiveTabURL();
-    if (_ownedTabURLs.size === 0) {
+    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 "${extensionType}".`;
       console.error(`[Safari MCP] ${msg}`);
       throw new Error(msg);
     } else if (currentUrl && !_isURLOwned(currentUrl)) {
-      const msg = `⚠️ Tab safety: refusing "${extensionType}" — current tab (${currentUrl}) was not opened by this MCP session. Use safari_new_tab or safari_switch_tab to target your own tab.`;
-      console.error(`[Safari MCP] ${msg}`);
-      throw new Error(msg);
+      // about:blank tabs are owned if we have any tracked tabs (new_tab creates them at about:blank)
+      const isBlankOwned = (currentUrl === 'about:blank' || currentUrl === 'missing value') && _openedTabs.size > 0;
+      if (!isBlankOwned) {
+        const msg = `⚠️ Tab safety: refusing "${extensionType}" — current tab (${currentUrl}) was not opened by this MCP session. Use safari_new_tab or safari_switch_tab to target your own tab.`;
+        console.error(`[Safari MCP] ${msg}`);
+        throw new Error(msg);
+      }
     }
   }
-  if (_extensionConnected && !_preferAppleScript) {
-    try {
-      const t0 = Date.now();
-      const tabUrl = safari.getActiveTabURL();
-      const payload = { ...extensionPayload, sessionId: SESSION_ID, ...(tabUrl ? { tabUrl } : {}) };
-      const timeout = _commandTimeouts[extensionType] || 30000;
-      const result = await sendToExtension(extensionType, payload, timeout);
-      const isCspError = typeof result === 'string' && (result.includes('unsafe-eval') || result.includes('trusted-types') || result.includes('Trusted Type') || result.includes('Content Security Policy'));
-      const isPermissionDenied = typeof result === 'string' && result.includes('__SCREENSHOT_PERMISSION_DENIED__');
-      const isFailed = result === null || (typeof result === 'string' && result.startsWith('Element not found'));
-      if (isPermissionDenied) {
-        console.error(`[Safari MCP] ${extensionType} permission denied (${Date.now() - t0}ms) — falling back to AppleScript`);
-      } else if (isCspError) {
-        console.error(`[Safari MCP] ${extensionType} CSP blocked: ${result?.substring(0, 100)} (${Date.now() - t0}ms) — falling back to AppleScript`);
-      } else if (isFailed && _nullMeansFailure.has(extensionType)) {
-        console.error(`[Safari MCP] ${extensionType} extension failed: ${result} (${Date.now() - t0}ms) — falling back to AppleScript`);
-      } else {
-        console.error(`[Safari MCP] ${extensionType} via extension (${Date.now() - t0}ms)`);
-        return result;
+
+  // ========== FOCUS PRESERVATION ==========
+  // Safari AppleScript/extension can steal focus (bring Safari window to front).
+  // Save the frontmost app before the operation and restore it after if Safari stole focus.
+  // Set focusGuard flag so inner osascript/runJSLarge calls skip their own focus logic.
+  const savedApp = await safari.saveFrontmostApp();
+  safari.setFocusGuard(true);
+
+  let result;
+  let usedExtension = false;
+  try {
+    if (_extensionConnected && !_preferAppleScript) {
+      try {
+        const t0 = Date.now();
+        const tabUrl = safari.getActiveTabURL();
+        const payload = { ...extensionPayload, sessionId: SESSION_ID, ...(tabUrl ? { tabUrl } : {}) };
+        const timeout = _commandTimeouts[extensionType] || 30000;
+        result = await sendToExtension(extensionType, payload, timeout);
+        const isCspError = typeof result === 'string' && (result.includes('unsafe-eval') || result.includes('trusted-types') || result.includes('Trusted Type') || result.includes('Content Security Policy'));
+        const isPermissionDenied = typeof result === 'string' && result.includes('__SCREENSHOT_PERMISSION_DENIED__');
+        const isFailed = result === null || (typeof result === 'string' && result.startsWith('Element not found'));
+        if (isPermissionDenied) {
+          console.error(`[Safari MCP] ${extensionType} permission denied (${Date.now() - t0}ms) — falling back to AppleScript`);
+        } else if (isCspError) {
+          console.error(`[Safari MCP] ${extensionType} CSP blocked: ${result?.substring(0, 100)} (${Date.now() - t0}ms) — falling back to AppleScript`);
+        } else if (isFailed && _nullMeansFailure.has(extensionType)) {
+          console.error(`[Safari MCP] ${extensionType} extension failed: ${result} (${Date.now() - t0}ms) — falling back to AppleScript`);
+        } else {
+          console.error(`[Safari MCP] ${extensionType} via extension (${Date.now() - t0}ms)`);
+          usedExtension = true;
+        }
+      } catch (err) {
+        console.error(`[Safari MCP] ${extensionType} extension failed: ${err.message} — falling back to AppleScript`);
       }
-    } catch (err) {
-      console.error(`[Safari MCP] ${extensionType} extension failed: ${err.message} — falling back to AppleScript`);
     }
+    if (!usedExtension) {
+      const t0 = Date.now();
+      result = await fallbackFn();
+      console.error(`[Safari MCP] ${extensionType} via AppleScript (${Date.now() - t0}ms)`);
+    }
+  } finally {
+    safari.setFocusGuard(false);
   }
-  const t0 = Date.now();
-  const result = await fallbackFn();
-  console.error(`[Safari MCP] ${extensionType} via AppleScript (${Date.now() - t0}ms)`);
+
+  // Restore focus if Safari stole it
+  await safari.restoreFocusIfStolen(savedApp);
+
   return result;
 }
 
@@ -1075,7 +1114,10 @@ server.tool(
   "Take a screenshot of a specific element (by CSS selector). Returns base64 PNG image.",
   { selector: z.string().describe("CSS selector of the element to capture") },
   async ({ selector }) => {
-    const base64 = await safari.screenshotElement({ selector });
+    const base64 = await extensionOrFallback(
+      "screenshot_element", { selector },
+      () => safari.screenshotElement({ selector })
+    );
     return {
       content: [{ type: "image", data: base64, mimeType: "image/jpeg" }],
     };
@@ -1203,9 +1245,13 @@ server.tool(
         const parsed = typeof tabs === 'string' ? JSON.parse(tabs) : tabs;
         const target = parsed.find(t => t.index === index);
         if (target && target.url && !_isURLOwned(target.url)) {
-          const msg = `⚠️ Tab safety: refusing switch_tab to index ${index} (${target.url}) — not opened by this MCP session. Use safari_new_tab to open your own tab.`;
-          console.error(`[Safari MCP] ${msg}`);
-          return { content: [{ type: "text", text: msg }], isError: true };
+          // about:blank / missing value tabs are owned if tracked in _openedTabs
+          const isBlankOwned = (target.url === 'about:blank' || target.url === 'missing value') && _openedTabs.has(index);
+          if (!isBlankOwned) {
+            const msg = `⚠️ Tab safety: refusing switch_tab to index ${index} (${target.url}) — not opened by this MCP session. Use safari_new_tab to open your own tab.`;
+            console.error(`[Safari MCP] ${msg}`);
+            return { content: [{ type: "text", text: msg }], isError: true };
+          }
         }
       } catch {}
     }
@@ -1559,7 +1605,7 @@ server.tool(
 
 server.tool(
   "safari_save_pdf",
-  "Save the current page as a PDF file. Uses Safari's native Export as PDF. WARNING: This STEALS FOCUS — Safari comes to foreground briefly for the Export menu.",
+  "Save the current page as a PDF file. Uses screencapture + PDF rendering (no Safari UI interaction needed).",
   { path: z.string().describe("Absolute file path to save the PDF (e.g. /Users/am/Downloads/page.pdf)") },
   async (args) => {
     const result = await safari.savePDF(args);

package/mcp-helpers.js

@@ -1,7 +1,7 @@
 // MCP Click/Interaction Helpers — injected into every page
 // This file is loaded by safari.js at startup, escaped, and injected via AppleScript `do JavaScript`.
 // It is also used by the extension's execInTab for the AppleScript fallback path.
-// IMPORTANT: Keep this file compatible with all browsers — no ES6+ modules, use var where possible.
+// IMPORTANT: Keep compatible with all browsers — no ES6+ modules, use var where possible.
 
 if (window.__mcpVersion !== 5) {
   window.__mcpVersion = 5;

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "safari-mcp",
-  "version": "2.7.1",
+  "version": "2.7.4",
   "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",
+  "types": "index.d.ts",
   "main": "index.js",
   "bin": {
     "safari-mcp": "index.js"
@@ -39,8 +40,8 @@
   "license": "MIT",
   "homepage": "https://achiya-automation.com",
   "funding": {
-    "type": "github",
-    "url": "https://github.com/sponsors/achiya-automation"
+    "type": "individual",
+    "url": "https://paypal.me/achiyaC123"
   },
   "repository": {
     "type": "git",
@@ -64,7 +65,8 @@
     "extension/",
     "glama.json",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "index.d.ts"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",

package/safari-helper.swift

@@ -278,12 +278,52 @@ while let line = readLine(strippingNewline: true) {
     continue
   }
 
+  // Handle getFrontApp — returns frontmost application bundle ID (native, ~0.1ms)
+  if json["getFrontApp"] != nil {
+    let frontApp = NSWorkspace.shared.frontmostApplication
+    respond(["result": frontApp?.localizedName ?? "", "bundleId": frontApp?.bundleIdentifier ?? ""])
+    continue
+  }
+
+  // Handle activateApp — activate a specific app by bundle ID (native, ~1ms)
+  // Used to restore focus to previous app instead of hiding Safari (less jarring)
+  if let bundleId = json["activateApp"] as? String {
+    if let app = NSRunningApplication.runningApplications(withBundleIdentifier: bundleId).first {
+      app.activate()
+      respond(["result": "activated"])
+    } else {
+      respond(["error": "app not found: \(bundleId)"])
+    }
+    continue
+  }
+
+  // Handle hideSafari — hide Safari to prevent focus stealing (native, ~1ms)
+  if json["hideSafari"] != nil {
+    if let safariApp = NSRunningApplication.runningApplications(withBundleIdentifier: "com.apple.Safari").first {
+      safariApp.hide()
+      respond(["result": "hidden"])
+    } else {
+      respond(["error": "Safari not running"])
+    }
+    continue
+  }
+
   // Handle AppleScript command
   guard let script = json["script"] as? String else {
-    respond(["error": "invalid input — expected 'script', 'click', or 'keyboard'"])
+    respond(["error": "invalid input — expected 'script', 'click', 'keyboard', 'getFrontApp', or 'hideSafari'"])
     continue
   }
 
+  // ========== FOCUS PRESERVATION ==========
+  // Save the frontmost app BEFORE executing AppleScript.
+  // Safari AppleScript can steal focus — we re-activate the previous app immediately after.
+  // Re-activating is better than hiding Safari because:
+  // 1. No jarring hide animation on Safari windows
+  // 2. User's Safari windows stay visible (just not in front)
+  // 3. Almost instantaneous — previous app just comes back to foreground
+  let savedBundleId = NSWorkspace.shared.frontmostApplication?.bundleIdentifier
+  let wasSafari = savedBundleId == "com.apple.Safari"
+
   guard let nsScript = NSAppleScript(source: script) else {
     respond(["error": "failed to compile AppleScript"])
     continue
@@ -292,6 +332,15 @@ while let line = readLine(strippingNewline: true) {
   var errorDict: NSDictionary?
   let result = nsScript.executeAndReturnError(&errorDict)
 
+  // Restore focus to previous app if Safari stole it (only if caller wasn't already in Safari)
+  if !wasSafari,
+     NSWorkspace.shared.frontmostApplication?.bundleIdentifier == "com.apple.Safari" {
+    if let savedId = savedBundleId,
+       let previousApp = NSRunningApplication.runningApplications(withBundleIdentifier: savedId).first {
+      previousApp.activate()
+    }
+  }
+
   if let error = errorDict {
     let msg = (error["NSAppleScriptErrorMessage"] as? String) ?? "AppleScript error"
     respond(["error": msg])

package/safari.js

@@ -89,6 +89,21 @@ function cleanupHelper() {
 process.on("exit", cleanupHelper);
 process.on("uncaughtException", (err) => { console.error("Uncaught:", err); cleanupHelper(); process.exit(1); });
 
+// ========== SAFARI RUNNING CHECK ==========
+// Prevent AppleScript from auto-launching Safari when it's closed
+async function isSafariRunning() {
+  try {
+    const { stdout } = await execFileAsync("pgrep", ["-x", "Safari"], { timeout: 2000 });
+    return stdout.trim().length > 0;
+  } catch {
+    return false; // pgrep exits 1 when no match
+  }
+}
+
+function safariNotRunningError() {
+  return new Error("Safari is not running. Open Safari manually before using Safari MCP tools.");
+}
+
 // ========== CLIPBOARD LOCK ==========
 // Prevents concurrent clipboard operations from clobbering the user's clipboard.
 // While locked, any new clipboard operation waits until the current one completes.
@@ -162,6 +177,7 @@ let _targetWindowId = null;  // Numeric window ID (for CGEvent window targeting)
 let _targetWindowCacheTime = 0;
 const TARGET_WINDOW_CACHE_MS = 1000; // Short cache — fast detection of window changes
 let _profileWindowMissing = false; // True when profile window is not found
+let _focusGuardActive = false; // True when an outer caller already handles focus save/restore
 
 // Get the target window ref, falling back to 'front window' ONLY when no profile is configured
 function getTargetWindowRef() {
@@ -258,6 +274,56 @@ function getFallbackTarget() {
 // Quick JS execution — exposed for smart-wait checks in index.js
 export async function runJSQuick(js) { return runJS(js); }
 
+// ========== FOCUS PRESERVATION ==========
+// Safari AppleScript can steal focus (bring Safari window to front).
+// We hide Safari instead of activating the previous app — prevents ANY Safari window from flashing.
+export async function saveFrontmostApp() {
+  const app = await _helperGetFrontApp();
+  return app?.bundleId || null;
+}
+export async function restoreFocusIfStolen(savedBundleId) {
+  if (!savedBundleId || savedBundleId === "com.apple.Safari") return;
+  const current = await _helperGetFrontApp();
+  if (current?.bundleId === "com.apple.Safari") {
+    await _helperActivateApp(savedBundleId);
+  }
+}
+
+function _helperHideSafari(timeout = 2000) {
+  return new Promise((resolve) => {
+    if (!_helperProc || !_helperProc.stdin?.writable) { resolve(); return; }
+    let resolved = false;
+    const timer = setTimeout(() => { if (!resolved) { resolved = true; resolve(); } }, timeout);
+    function cb() {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      resolve();
+    }
+    _helperQueue.push(cb);
+    try { _helperProc.stdin.write('{"hideSafari":true}\n'); }
+    catch { clearTimeout(timer); resolve(); }
+  });
+}
+
+function _helperActivateApp(bundleId, timeout = 2000) {
+  return new Promise((resolve) => {
+    if (!_helperProc || !_helperProc.stdin?.writable) { resolve(); return; }
+    let resolved = false;
+    const timer = setTimeout(() => { if (!resolved) { resolved = true; resolve(); } }, timeout);
+    function cb() {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      resolve();
+    }
+    _helperQueue.push(cb);
+    try { _helperProc.stdin.write(JSON.stringify({ activateApp: bundleId }) + '\n'); }
+    catch { clearTimeout(timer); resolve(); }
+  });
+}
+
+export function setFocusGuard(active) { _focusGuardActive = active; }
 export function getActiveTabIndex() { return _activeTabIndex; }
 export function setActiveTabIndex(idx) { _activeTabIndex = idx; }
 export function getActiveTabURL() { return _activeTabURL; }
@@ -326,6 +392,11 @@ async function resolveActiveTab() {
 
 // Run AppleScript — uses execFile (safe, isolated, for complex scripts)
 async function osascript(script, { timeout = 10000 } = {}) {
+  if (!(await isSafariRunning())) throw safariNotRunningError();
+  // Save frontmost app via daemon BEFORE subprocess (~0.1ms)
+  // Skip if an outer caller (extensionOrFallback) already handles focus
+  const shouldGuardFocus = !_focusGuardActive;
+  const frontApp = shouldGuardFocus ? await _helperGetFrontApp() : null;
   try {
     const { stdout } = await execFileAsync("osascript", ["-e", script], {
       timeout,
@@ -344,11 +415,20 @@ async function osascript(script, { timeout = 10000 } = {}) {
       }
     }
     throw new Error(`AppleScript error: ${err.stderr || err.message}`);
+  } finally {
+    // Re-activate previous app if Safari stole focus (~1ms)
+    if (shouldGuardFocus && frontApp?.bundleId && frontApp.bundleId !== 'com.apple.Safari') {
+      const current = await _helperGetFrontApp();
+      if (current?.bundleId === 'com.apple.Safari') {
+        _helperActivateApp(frontApp.bundleId).catch(() => {});
+      }
+    }
   }
 }
 
 // osascriptFast: uses persistent Swift daemon (~5ms) — 18x faster than subprocess (~90ms)
 async function osascriptFast(script, { timeout = 10000 } = {}) {
+  if (!(await isSafariRunning())) throw safariNotRunningError();
   if (!_helperProc) startHelper();
   if (_helperProc) {
     try {
@@ -503,6 +583,26 @@ function _helperNativeKeyboard(keyCode, flags = [], windowId = 0, timeout = 5000
   });
 }
 
+// ========== NATIVE FOCUS OPERATIONS VIA DAEMON ==========
+// Uses NSRunningApplication — ~0.1ms for get, ~1ms for activate (vs ~90ms AppleScript)
+
+function _helperGetFrontApp(timeout = 2000) {
+  return new Promise((resolve) => {
+    if (!_helperProc || !_helperProc.stdin?.writable) { resolve(null); return; }
+    let resolved = false;
+    const timer = setTimeout(() => { if (!resolved) { resolved = true; resolve(null); } }, timeout);
+    function cb(line) {
+      if (resolved) return;
+      resolved = true;
+      clearTimeout(timer);
+      try { resolve(JSON.parse(line)); } catch { resolve(null); }
+    }
+    _helperQueue.push(cb);
+    try { _helperProc.stdin.write('{"getFrontApp":true}\n'); }
+    catch { clearTimeout(timer); resolve(null); }
+  });
+}
+
 // Get Safari window bounds, toolbar height, and window ID for coordinate calculation
 async function _getSafariWindowGeometry() {
   await refreshTargetWindow();
@@ -615,6 +715,10 @@ async function runJSLarge(js, { tabIndex, timeout = 30000 } = {}) {
   const appleScript = `tell application "Safari" to do JavaScript "${escaped}" in ${target}`;
   const tmpFile = join(tmpdir(), `safari-mcp-${Date.now()}.scpt`);
   await writeFile(tmpFile, appleScript, "utf8");
+  // Save frontmost app via daemon before subprocess execution
+  // Skip if outer caller already handles focus
+  const shouldGuard = !_focusGuardActive;
+  const frontApp = shouldGuard ? await _helperGetFrontApp() : null;
   try {
     const { stdout } = await execFileAsync("osascript", [tmpFile], {
       timeout,
@@ -623,6 +727,13 @@ async function runJSLarge(js, { tabIndex, timeout = 30000 } = {}) {
     return stdout.trim();
   } finally {
     unlink(tmpFile).catch(() => {});
+    // Re-activate previous app if Safari stole focus (~1ms)
+    if (shouldGuard && frontApp?.bundleId && frontApp.bundleId !== 'com.apple.Safari') {
+      const current = await _helperGetFrontApp();
+      if (current?.bundleId === 'com.apple.Safari') {
+        _helperActivateApp(frontApp.bundleId).catch(() => {});
+      }
+    }
   }
 }
 
@@ -659,7 +770,7 @@ export async function navigate(url) {
         const state = await runJS('document.readyState', { timeout: 5000 });
         if (state === 'complete' || state === 'interactive') {
           result = await runJS(
-            `JSON.stringify({title:document.title,url:location.href,blocked:document.title.includes('cannot open')||document.title.includes('אין אפשרות')})`,
+            `JSON.stringify({title:document.title,url:location.href,blocked:document.title.includes('cannot open')||document.title.includes('\u05D0\u05D9\u05DF \u05D0\u05E4\u05E9\u05E8\u05D5\u05EA')})`,
             { timeout: 5000 }
           );
           if (state === 'complete') break;
@@ -1487,15 +1598,11 @@ export async function screenshot({ fullPage = false } = {}) {
     ).catch(() => null) : null;
 
     // On macOS Tahoe, screencapture -l may briefly steal focus.
-    // Save frontmost app so we can detect if focus was stolen and restore it.
-    let previousApp = null;
+    // Save frontmost app via daemon so we can hide Safari if it stole focus.
+    let previousBundleId = null;
     if (windowId) {
-      try {
-        // Use NSWorkspace via AppleScript (lighter than System Events — no AX needed)
-        previousApp = (await osascriptFast(
-          `tell application "System Events" to return name of first application process whose frontmost is true`
-        )).trim();
-      } catch (_) {}
+      const fa = await _helperGetFrontApp();
+      previousBundleId = fa?.bundleId || null;
     }
 
     if (windowId) {
@@ -1536,11 +1643,12 @@ export async function screenshot({ fullPage = false } = {}) {
             );
           }
         }
-        // Restore focus if screencapture stole it (common on macOS Tahoe)
-        if (previousApp && previousApp !== "Safari") {
-          await osascriptFast(
-            `tell application "${previousApp}" to activate`
-          ).catch(() => {});
+        // Re-activate previous app if screencapture stole focus (common on macOS Tahoe)
+        if (previousBundleId && previousBundleId !== "com.apple.Safari") {
+          const cur = await _helperGetFrontApp();
+          if (cur?.bundleId === "com.apple.Safari") {
+            await _helperActivateApp(previousBundleId).catch(() => {});
+          }
         }
         // Compress: convert PNG to JPEG (50% quality) + resize to max 1200px width
         // Cuts ~600KB PNG → ~60KB JPEG — critical for staying under 20MB context limit
@@ -2069,7 +2177,7 @@ export async function uploadFile({ selector, filePath }) {
               click button "Cancel" of sheet 1 of w
             on error
               try
-                click button "ביטול" of sheet 1 of w
+                click button "\u05D1\u05D9\u05D8\u05D5\u05DC" of sheet 1 of w  -- "Cancel" in Hebrew locale
               on error
                 key code 53
               end try

package/extension/popup/popup.js

@@ -1,57 +0,0 @@
-// v6 — asks background script for real-time status, falls back to storage
-async function checkStatus() {
-  const enabled = await getVal("mcpEnabled", true);
-  document.getElementById("enableToggle").checked = enabled;
-
-  if (!enabled) {
-    setStatus("paused", "Paused", "Toggle to resume");
-    return;
-  }
-
-  // Ask background script for real-time status
-  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 status = await getVal("mcpStatus", "checking");
-  switch (status) {
-    case "connected":
-      setStatus("connected", "Connected", "Port 9224");
-      break;
-    case "paused":
-      setStatus("paused", "Paused", "Toggle to resume");
-      break;
-    case "checking":
-      setStatus("checking", "Connecting...", "Trying port 9224...");
-      break;
-    default:
-      setStatus("disconnected", "Not connected", "Start the MCP server to connect");
-  }
-}
-
-function setStatus(dotClass, text, info) {
-  document.getElementById("statusDot").className = "dot " + dotClass;
-  document.getElementById("statusText").textContent = text;
-  document.getElementById("info").textContent = info;
-}
-
-document.getElementById("enableToggle").addEventListener("change", async (e) => {
-  const enabled = e.target.checked;
-  await browser.storage.local.set({ mcpEnabled: enabled });
-  try { browser.runtime.sendMessage({ action: "setEnabled", enabled }); } catch {}
-  setTimeout(checkStatus, 500);
-});
-
-async function getVal(key, defaultVal) {
-  try {
-    const data = await browser.storage.local.get(key);
-    return data[key] !== undefined ? data[key] : defaultVal;
-  } catch { return defaultVal; }
-}
-
-checkStatus();