safari-mcp 2.7.3 → 2.7.5

package/README.md

@@ -8,22 +8,17 @@
 
 **The only MCP server for Safari — native browser automation for AI agents.**
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub release](https://img.shields.io/github/v/release/achiya-automation/safari-mcp)](https://github.com/achiya-automation/safari-mcp/releases)
 [![npm version](https://img.shields.io/npm/v/safari-mcp)](https://www.npmjs.com/package/safari-mcp)
 [![npm downloads](https://img.shields.io/npm/dm/safari-mcp)](https://www.npmjs.com/package/safari-mcp)
-[![CI](https://github.com/achiya-automation/safari-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/achiya-automation/safari-mcp/actions/workflows/ci.yml)
-[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![macOS](https://img.shields.io/badge/macOS-only-blue)](https://www.apple.com/macos/)
-[![MCP](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
 [![GitHub stars](https://img.shields.io/github/stars/achiya-automation/safari-mcp?style=social)](https://github.com/achiya-automation/safari-mcp/stargazers)
-[![achiya-automation/safari-mcp MCP server](https://glama.ai/mcp/servers/achiya-automation/safari-mcp/badges/score.svg)](https://glama.ai/mcp/servers/achiya-automation/safari-mcp)
 
-<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>
+<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_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_Server-24bfa5?logo=visual-studio-code&logoColor=white" alt="Install in VS Code Insiders"></a>
+<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=safari-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22safari-mcp%22%5D%7D"><img src="https://img.shields.io/badge/Cursor-Install_Server-f97316?logo=cursor&logoColor=white" alt="Install in Cursor"></a>
 
-**80 tools** · **Zero dependencies** · **~5ms per command** · **60% less CPU than Chrome**
+**80 tools** · **No Chrome/Puppeteer/Playwright needed** · **~5ms per command** · **60% less CPU than Chrome**
 
 [Quick Start](#quick-start) · [All 80 Tools](#tools-80) · [Examples](examples/) · [Why Safari MCP?](#safari-mcp-vs-alternatives) · [Architecture](#architecture) · [Changelog](CHANGELOG.md)
 
@@ -31,23 +26,18 @@
 
 </div>
 
----
-
-> **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.
+> **TL;DR:** Use your real Safari with all your logins, cookies, and sessions. No headless browsers, no Chrome, no Puppeteer. Just native AppleScript + JavaScript on macOS — 60% less CPU/heat on Apple Silicon.
 
-<details>
-<summary><b>🤔 Why not just use Playwright or Chrome DevTools MCP?</b></summary>
+### 🤔 Why not just use Playwright or Chrome DevTools MCP?
 
 | Problem | Safari MCP Solution |
 |---------|-------------------|
 | Chrome DevTools MCP heats up your Mac | Native WebKit — ~60% less CPU |
 | Playwright launches a new browser without your logins | Uses your **real Safari** with all sessions |
-| Puppeteer requires Chrome + debug port | Zero dependencies — just AppleScript |
+| Puppeteer requires Chrome + debug port | Just AppleScript — no extra browser |
 | Headless browsers can't access your authenticated sessions | Gmail, GitHub, Slack — already logged in |
 | Browser automation steals window focus | Safari stays in background, never interrupts |
 
-</details>
-
 ---
 
 ## Highlights
@@ -56,7 +46,7 @@
 - **Zero heat** — native WebKit on Apple Silicon, ~60% less CPU than Chrome
 - **Your real browser** — keeps all logins, cookies, sessions (Gmail, GitHub, Ahrefs, etc.)
 - **Background operation** — Safari stays in the background, no window stealing
-- **No dependencies** — no Puppeteer, no Playwright, no WebDriver, no Chrome
+- **No browser dependencies** — no Puppeteer, no Playwright, no WebDriver, no Chrome
 - **Persistent process** — reuses a single osascript process (~5ms per command vs ~80ms)
 - **Framework-compatible** — React, Vue, Angular, Svelte form filling via native setters
 
@@ -71,86 +61,60 @@
 - Safari → Settings → Advanced → **Show features for web developers** ✓
 - Safari → Develop → **Allow JavaScript from Apple Events** ✓
 
-### Install
+### Install (one command)
 
-**Option A — npm (recommended):**
 ```bash
-npm install -g safari-mcp
+npx safari-mcp
 ```
 
-**Option B — Homebrew:**
-```bash
-brew install achiya-automation/tap/safari-mcp
-```
+That's it — no global install needed. Or install permanently:
 
-**Option C — from source:**
 ```bash
-git clone https://github.com/achiya-automation/safari-mcp.git
-cd safari-mcp
-npm install
+npm install -g safari-mcp
 ```
 
-### Configure
+### Configure your MCP client
 
-Add to your MCP client config:
-
-<details>
-<summary><b>Claude Code</b> (~/.mcp.json)</summary>
+Add to your client's config file — all clients use the same JSON:
 
 ```json
 {
   "mcpServers": {
     "safari": {
-      "command": "node",
-      "args": ["/path/to/safari-mcp/index.js"]
+      "command": "npx",
+      "args": ["safari-mcp"]
     }
   }
 }
 ```
-</details>
 
 <details>
-<summary><b>Claude Desktop</b> (claude_desktop_config.json)</summary>
+<summary><b>Where does each client store this?</b></summary>
+
+| Client | Config file |
+|--------|------------|
+| **Claude Code** | `~/.mcp.json` |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| **Cursor** | `.cursor/mcp.json` in your project |
+| **Windsurf** | `.windsurf/mcp.json` in your project |
+| **VS Code + Continue** | `.vscode/mcp.json` in your project |
 
-```json
-{
-  "mcpServers": {
-    "safari": {
-      "command": "node",
-      "args": ["/path/to/safari-mcp/index.js"]
-    }
-  }
-}
-```
 </details>
 
 <details>
-<summary><b>Cursor</b> (.cursor/mcp.json)</summary>
+<summary><b>Alternative: Homebrew</b></summary>
 
-```json
-{
-  "mcpServers": {
-    "safari": {
-      "command": "node",
-      "args": ["/path/to/safari-mcp/index.js"]
-    }
-  }
-}
+```bash
+brew install achiya-automation/tap/safari-mcp
 ```
 </details>
 
 <details>
-<summary><b>Windsurf / VS Code + Continue</b></summary>
+<summary><b>Alternative: from source</b></summary>
 
-```json
-{
-  "mcpServers": {
-    "safari": {
-      "command": "node",
-      "args": ["/path/to/safari-mcp/index.js"]
-    }
-  }
-}
+```bash
+git clone https://github.com/achiya-automation/safari-mcp.git
+cd safari-mcp && npm install
 ```
 </details>
 
@@ -375,7 +339,7 @@ Safari MCP runs locally on your Mac with minimal attack surface:
 | CPU/Heat | 🟢 Minimal | 🔴 High | 🟡 Medium |
 | Your logins | ✅ Yes | ✅ Yes | ❌ No |
 | macOS native | ✅ WebKit | ❌ Chromium | ❌ Chromium/WebKit |
-| Dependencies | None | Chrome + debug port | Playwright runtime |
+| Browser dependencies | None | Chrome + debug port | Playwright runtime |
 | Tools | 80 | ~30 | ~25 |
 | File upload | JS (no dialog) | CDP | Playwright API |
 | Image paste | JS (no clipboard) | CDP | Playwright API |
@@ -451,12 +415,16 @@ The Safari MCP Extension is **optional but recommended**. Without it, ~80% of fu
 
 ### Installing the Extension
 
-The extension requires a one-time build with Xcode (free, included with macOS):
+The extension requires a one-time build with Xcode (free, included with macOS).
+
+> **Note for npm users:** The `xcode/` directory is not included in the npm package.
+> Clone the [GitHub repository](https://github.com/achiya-automation/safari-mcp) to build from source.
 
 **Prerequisites:** Xcode (install from App Store — free)
 
 ```bash
-# 1. Build the extension app
+# 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
 xcodebuild -project "xcode/Safari MCP/Safari MCP.xcodeproj" \
   -scheme "Safari MCP (macOS)" -configuration Release build
@@ -545,14 +513,34 @@ Your support funds:
 
 ---
 
-## Star History
+## Community
+
+**2,000+ weekly 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
+- [![Good First Issues](https://img.shields.io/github/issues/achiya-automation/safari-mcp/good%20first%20issue?color=7057ff&label=good%20first%20issues)](https://github.com/achiya-automation/safari-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — start contributing
+
+---
+
+## Like it? Give it a ⭐
+
+If Safari MCP saves you from Chrome overhead, **a star helps others discover it:**
 
-If Safari MCP saved you from Chrome overhead, consider giving it a ⭐
+[![Star this repo](https://img.shields.io/github/stars/achiya-automation/safari-mcp?style=social)](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](https://dev.to/)
 
 [![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)
 
 ---
 
+## Listed On
+
+[![Glama](https://glama.ai/mcp/servers/achiya-automation/safari-mcp/badges/score.svg)](https://glama.ai/mcp/servers/achiya-automation/safari-mcp) [![MCP Registry](https://img.shields.io/badge/MCP-Registry-purple)](https://registry.modelcontextprotocol.io/) [![CI](https://github.com/achiya-automation/safari-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/achiya-automation/safari-mcp/actions/workflows/ci.yml)
+
+---
+
 ## License
 
 MIT — use it however you want.

package/extension/manifest.json

@@ -20,6 +20,16 @@
   "host_permissions": ["<all_urls>"],
   "content_scripts": [{
     "matches": ["<all_urls>"],
+    "exclude_matches": [
+      "*://*.linkedin.com/*",
+      "*://*.x.com/*",
+      "*://*.twitter.com/*",
+      "*://*.producthunt.com/*",
+      "*://mail.google.com/*",
+      "*://calendar.google.com/*",
+      "*://chat.google.com/*",
+      "*://meet.google.com/*"
+    ],
     "js": ["content.js"],
     "run_at": "document_start",
     "world": "MAIN"

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

@@ -526,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)");
@@ -665,33 +665,53 @@ async function extensionOrFallback(extensionType, extensionPayload, fallbackFn)
       }
     }
   }
-  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;
 }
 
@@ -1094,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" }],
     };
@@ -1582,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/package.json

@@ -1,9 +1,10 @@
 {
   "name": "safari-mcp",
-  "version": "2.7.3",
+  "version": "2.7.5",
   "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"
@@ -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,47 @@ 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 is handled by the Node.js layer (osascript() function
+  // and extensionOrFallback). The daemon must NOT manage focus — it runs every
+  // 3 seconds for background checks, and restoring focus here steals Safari
+  // from the user whenever they switch to it.
+
   guard let nsScript = NSAppleScript(source: script) else {
     respond(["error": "failed to compile AppleScript"])
     continue

package/safari.js

@@ -177,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() {
@@ -273,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; }
@@ -342,6 +393,10 @@ 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,
@@ -360,6 +415,14 @@ 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(() => {});
+      }
+    }
   }
 }
 
@@ -520,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();
@@ -632,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,
@@ -640,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(() => {});
+      }
+    }
   }
 }
 
@@ -1504,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) {
@@ -1553,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