safari-mcp 2.1.5 → 2.1.7

package/README.md

@@ -9,13 +9,14 @@
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
 [![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)
+[![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)
 [![npm downloads](https://img.shields.io/npm/dm/safari-mcp)](https://www.npmjs.com/package/safari-mcp)
 [![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)
 
 **80 tools** · **Zero dependencies** · **~5ms per command** · **60% less CPU than Chrome**
 
-[Quick Start](#quick-start) · [All 80 Tools](#tools-80) · [Why Safari MCP?](#safari-mcp-vs-alternatives) · [Architecture](#architecture)
+[Quick Start](#quick-start) · [All 80 Tools](#tools-80) · [Examples](examples/) · [Why Safari MCP?](#safari-mcp-vs-alternatives) · [Architecture](#architecture) · [Changelog](CHANGELOG.md)
 
 ![Safari MCP Demo](https://github.com/achiya-automation/safari-mcp/releases/download/v2.1.2/safari-mcp-showcase.gif)
 
@@ -63,6 +64,12 @@
 
 ### Install
 
+**Option A — npm (recommended):**
+```bash
+npm install -g safari-mcp
+```
+
+**Option B — from source:**
 ```bash
 git clone https://github.com/achiya-automation/safari-mcp.git
 cd safari-mcp
@@ -447,7 +454,9 @@ Safari MCP works with any MCP-compatible client:
 
 ## Contributing
 
-PRs welcome! The codebase is two files:
+PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.
+
+The codebase is two files:
 - `safari.js` — Safari automation layer (AppleScript + JavaScript)
 - `index.js` — MCP server with tool definitions
 

package/extension/background.js

@@ -92,6 +92,11 @@ async function connect() {
           updateBadge("OFF");
           return; // Do NOT poll — let the correct profile's extension handle commands
         }
+        // Notify server that we passed profile verification
+        await fetch(`${HTTP_URL}/extension-verified`, {
+          method: "POST",
+          signal: AbortSignal.timeout(3000),
+        }).catch(() => {});
         await _discoverProfileWindow();
       }
       isConnected = true;
@@ -1548,6 +1553,8 @@ async function handleCommand(type, payload) {
 const _sessionTabCache = new Map();
 const TAB_CACHE_MS = 3000; // Re-verify tab URL match every 3s
 const _DEFAULT_SESSION = "__default__"; // Fallback for commands without sessionId
+const SESSION_MAX_AGE_MS = 5 * 60 * 1000; // 5 min — prune stale sessions
+const MAX_SESSIONS = 50; // Hard cap on session cache size
 
 function _getSessionCache(sessionId) {
   const sid = sessionId || _DEFAULT_SESSION;
@@ -1557,6 +1564,29 @@ function _getSessionCache(sessionId) {
   return _sessionTabCache.get(sid);
 }
 
+// Prune stale sessions — runs every 60s
+function _pruneSessionCache() {
+  const now = Date.now();
+  for (const [sid, cache] of _sessionTabCache) {
+    if (sid === _DEFAULT_SESSION) continue;
+    // Remove sessions with no active tab that haven't been used in 5 min
+    if (!cache.tabId && (now - cache.time) > SESSION_MAX_AGE_MS) {
+      _sessionTabCache.delete(sid);
+    }
+  }
+  // Hard cap: if still too many, remove oldest
+  if (_sessionTabCache.size > MAX_SESSIONS) {
+    const sorted = [..._sessionTabCache.entries()]
+      .filter(([sid]) => sid !== _DEFAULT_SESSION)
+      .sort((a, b) => a[1].time - b[1].time);
+    while (_sessionTabCache.size > MAX_SESSIONS && sorted.length) {
+      const [sid] = sorted.shift();
+      _sessionTabCache.delete(sid);
+    }
+  }
+}
+setInterval(_pruneSessionCache, 60000);
+
 function _setSessionTab(sessionId, tabId, tabUrl) {
   const cache = _getSessionCache(sessionId);
   cache.tabId = tabId;

package/glama.json

@@ -1,9 +1,11 @@
 {
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
   "name": "Safari MCP Server",
   "description": "Native Safari browser automation for AI agents. 80+ tools via AppleScript — zero overhead, keeps logins, runs silently in background.",
   "repository": "https://github.com/achiya-automation/safari-mcp",
   "homepage": "https://github.com/achiya-automation/safari-mcp",
   "author": "achiya-automation",
+  "maintainers": ["achiya-automation"],
   "license": "MIT",
   "categories": ["browser-automation", "web-scraping", "developer-tools"],
   "tags": ["safari", "macos", "browser", "automation", "applescript", "mcp"],

package/index.js

@@ -46,6 +46,77 @@ try {
 // ========== SESSION ID (unique per MCP process — enables per-session tab tracking) ==========
 const SESSION_ID = randomUUID().slice(0, 8);
 
+// ========== 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);
+const WEBKIT_MEMORY_LIMIT_MB = parseInt(process.env.MCP_WEBKIT_LIMIT_MB || "3000", 10);
+
+// Track tabs opened by THIS session (index → {url, openedAt})
+const _openedTabs = new Map();
+
+function _trackTab(tabIndex, url) {
+  _openedTabs.set(tabIndex, { url: url || "", openedAt: Date.now() });
+}
+
+function _untrackTab(tabIndex) {
+  _openedTabs.delete(tabIndex);
+}
+
+// Close all MCP-opened tabs on process exit
+async function _cleanupTabs() {
+  if (_openedTabs.size === 0) return;
+  console.error(`[Safari MCP] Cleanup: closing ${_openedTabs.size} MCP-opened tabs`);
+  const indices = [..._openedTabs.keys()].sort((a, b) => b - a);
+  for (const idx of indices) {
+    try {
+      safari.setActiveTabIndex(idx);
+      await safari.closeTab();
+    } catch {}
+  }
+  _openedTabs.clear();
+}
+
+// Periodic memory check — if WebKit exceeds limit, close oldest MCP tabs
+let _memoryCheckTimer = null;
+function _startMemoryMonitor() {
+  _memoryCheckTimer = setInterval(async () => {
+    try {
+      const psOut = execFileSync("bash", ["-c",
+        "ps aux | grep -i 'WebKit\\|WebContent' | grep -v grep | awk '{sum+=$6} END {print sum/1024}'"
+      ], { encoding: "utf8" }).trim();
+      const webkitMB = parseFloat(psOut) || 0;
+      if (webkitMB > WEBKIT_MEMORY_LIMIT_MB && _openedTabs.size > 1) {
+        console.error(`[Safari MCP] ⚠️ WebKit using ${Math.round(webkitMB)}MB (limit: ${WEBKIT_MEMORY_LIMIT_MB}MB) — closing oldest MCP tab`);
+        let oldestIdx = null, oldestTime = Infinity;
+        for (const [idx, info] of _openedTabs) {
+          if (info.openedAt < oldestTime) { oldestTime = info.openedAt; oldestIdx = idx; }
+        }
+        if (oldestIdx !== null) {
+          try {
+            safari.setActiveTabIndex(oldestIdx);
+            await safari.closeTab();
+          } catch {}
+          _untrackTab(oldestIdx);
+        }
+      }
+    } catch {}
+  }, MEMORY_CHECK_INTERVAL_MS);
+  _memoryCheckTimer.unref();
+}
+
+// Cleanup on exit
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, async () => {
+    await _cleanupTabs();
+    process.exit(0);
+  });
+}
+process.on("exit", () => {
+  if (_openedTabs.size > 0) {
+    console.error(`[Safari MCP] Exit: ${_openedTabs.size} tabs were tracked for cleanup`);
+  }
+});
+
 // ========== EXTENSION FOCUS SAFETY ==========
 // When SAFARI_PROFILE is set, the extension's browser.scripting.executeScript()
 // can steal window focus in Safari (bringing the automation window to front).
@@ -164,7 +235,9 @@ try {
 
     // POST /connect — extension announces it's alive
     if (req.method === "POST" && req.url === "/connect") {
-      if (!_extensionConnected) {
+      // When SAFARI_PROFILE is set, don't mark as connected until profile is verified.
+      // A personal-profile extension connecting first would incorrectly set the flag.
+      if (!process.env.SAFARI_PROFILE && !_extensionConnected) {
         _extensionConnected = true;
         console.error("[Safari MCP] Extension connected via HTTP polling");
       }
@@ -174,6 +247,18 @@ try {
       return;
     }
 
+    // POST /extension-verified — extension confirmed it's in the correct profile
+    if (req.method === "POST" && req.url === "/extension-verified") {
+      if (!_extensionConnected) {
+        _extensionConnected = true;
+        console.error("[Safari MCP] Extension connected and profile-verified via HTTP polling");
+      }
+      _extensionLastPollTime = Date.now();
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "verified" }));
+      return;
+    }
+
     // POST /verify-profile — extension asks server to check which profile has a nonce tab
     if (req.method === "POST" && req.url === "/verify-profile") {
       let body = "";
@@ -894,6 +979,22 @@ server.tool(
   "Open a new tab, optionally with a URL",
   { url: z.string().optional().describe("URL to open (empty for blank tab)") },
   async ({ url }) => {
+    // Enforce tab limit — close oldest MCP tab if at max
+    if (_openedTabs.size >= MAX_TABS) {
+      let oldestIdx = null, oldestTime = Infinity;
+      for (const [idx, info] of _openedTabs) {
+        if (info.openedAt < oldestTime) { oldestTime = info.openedAt; oldestIdx = idx; }
+      }
+      if (oldestIdx !== null) {
+        console.error(`[Safari MCP] Tab limit (${MAX_TABS}) reached — closing oldest tab #${oldestIdx}`);
+        try {
+          safari.setActiveTabIndex(oldestIdx);
+          await safari.closeTab();
+        } catch {}
+        _untrackTab(oldestIdx);
+      }
+    }
+
     const result = await extensionOrFallback(
       "new_tab", { url },
       () => safari.newTab(url)
@@ -901,6 +1002,7 @@ server.tool(
     // Sync safari.js tracking when extension handled new_tab
     if (result?.tabIndex) {
       safari.setActiveTabIndex(result.tabIndex);
+      _trackTab(result.tabIndex, url);
     }
     if (result?.url) {
       safari.setActiveTabURL(result.url);
@@ -914,7 +1016,9 @@ server.tool(
   "Close the current tab",
   {},
   async () => {
+    const activeIdx = safari.getActiveTabIndex();
     const result = await extensionOrFallback("close_tab", {}, () => safari.closeTab());
+    if (activeIdx !== null) _untrackTab(activeIdx);
     return { content: [{ type: "text", text: typeof result === 'string' ? result : JSON.stringify(result) }] };
   }
 );
@@ -1720,5 +1824,6 @@ server.tool(
 
 // ========== START SERVER ==========
 
+_startMemoryMonitor();
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safari-mcp",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "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.js

@@ -7,7 +7,7 @@ import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { tmpdir } from "node:os";
 import { join, dirname } from "node:path";
-import { readFile, writeFile, unlink } from "node:fs/promises";
+import { readFile, writeFile, unlink, appendFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 // Extension bridge is handled by index.js (WebSocket server on port 9223)
 
@@ -99,6 +99,16 @@ let _activeTabURL = null;   // URL-based tracking (stable even when tabs shift)
 let _lastResolveTime = 0;   // Cache: skip resolve if verified recently
 const RESOLVE_CACHE_MS = 1500; // Re-verify tab every 1.5 seconds (was 5s — too stale)
 
+// ========== DIAGNOSTIC LOG ==========
+// File-based log for profile/focus issues — survives MCP restart, visible to user
+const _LOG_FILE = '/tmp/safari-mcp-profile.log';
+function _logProfile(msg) {
+  const ts = new Date().toISOString().replace('T', ' ').substring(0, 19);
+  const line = `[${ts}] ${msg}\n`;
+  console.error(`[Safari MCP] ${msg}`);
+  appendFile(_LOG_FILE, line).catch(() => {});
+}
+
 // ========== PROFILE TARGETING ==========
 // Set SAFARI_PROFILE env var to target a specific Safari profile window.
 // Safari shows profile windows as: "ProfileName — Tab Title"
@@ -106,7 +116,7 @@ const SAFARI_PROFILE = process.env.SAFARI_PROFILE || null;
 let _targetWindowRef = null; // null = not yet discovered. Updated by refreshTargetWindow()
 let _targetWindowId = null;  // Numeric window ID (for CGEvent window targeting)
 let _targetWindowCacheTime = 0;
-const TARGET_WINDOW_CACHE_MS = 5000;
+const TARGET_WINDOW_CACHE_MS = 2000; // Reduced from 5s — faster detection of window changes
 let _profileWindowMissing = false; // True when profile window is not found
 
 // Get the target window ref, falling back to 'front window' ONLY when no profile is configured
@@ -125,14 +135,16 @@ async function refreshTargetWindow(force = false) {
   const now = Date.now();
   if (!force && _targetWindowRef && (now - _targetWindowCacheTime) < TARGET_WINDOW_CACHE_MS) return;
   const safeProfile = SAFARI_PROFILE.replace(/"/g, '\\"');
+  // Find profile window by name AND verify the window ID still matches
   const result = await osascriptFast(
-    `tell application "Safari"\n  repeat with w in every window\n    if name of w starts with "${safeProfile} \u2014" then return id of w\n  end repeat\n  return 0\nend tell`
-  ).catch(() => '0');
-  const id = Number(result);
+    `tell application "Safari"\n  repeat with w in every window\n    if name of w starts with "${safeProfile} \u2014" then return (id of w as text) & "|" & name of w\n  end repeat\n  return "0|"\nend tell`
+  ).catch(() => '0|');
+  const [idStr, windowName] = String(result).split('|');
+  const id = Number(idStr);
   if (id > 0) {
     const newRef = `window id ${id}`;
     if (_targetWindowRef && _targetWindowRef !== newRef) {
-      console.error(`[Safari MCP] Profile window changed: ${_targetWindowRef} → ${newRef}`);
+      _logProfile(`Profile window changed: ${_targetWindowRef} → ${newRef} ("${windowName}")`);
     }
     _targetWindowRef = newRef;
     _targetWindowId = id;
@@ -144,18 +156,46 @@ async function refreshTargetWindow(force = false) {
     _targetWindowId = null;
     _targetWindowCacheTime = 0;
     _profileWindowMissing = true;
-    console.error(`[Safari MCP] WARNING: Profile "${SAFARI_PROFILE}" window not found — refusing to use front window`);
+    _logProfile(`WARNING: Profile "${SAFARI_PROFILE}" window not found — refusing to use front window`);
   }
 }
 
+// Background verification: periodically check that cached window ID still belongs to profile
+if (SAFARI_PROFILE) {
+  setInterval(async () => {
+    if (!_targetWindowRef || !_targetWindowId) return;
+    try {
+      const name = await osascriptFast(
+        `tell application "Safari" to return name of ${_targetWindowRef}`
+      ).catch(() => '');
+      if (name && !name.startsWith(`${SAFARI_PROFILE} \u2014`)) {
+        // Window ID no longer belongs to profile — invalidate cache immediately
+        _logProfile(`SAFETY: Window ${_targetWindowRef} no longer belongs to profile "${SAFARI_PROFILE}" (name: "${name}") — invalidating`);
+        _targetWindowRef = null;
+        _targetWindowId = null;
+        _targetWindowCacheTime = 0;
+        _profileWindowMissing = true;
+        // Try to rediscover immediately
+        await refreshTargetWindow(true);
+      }
+    } catch {
+      // Window might have been closed — invalidate and rediscover
+      _targetWindowRef = null;
+      _targetWindowId = null;
+      _targetWindowCacheTime = 0;
+      await refreshTargetWindow(true);
+    }
+  }, 3000); // Check every 3 seconds
+}
+
 // Initialize profile window at startup (ES module top-level await)
 if (SAFARI_PROFILE) {
   await new Promise(r => setTimeout(r, 50)); // Let helper process initialize
   await refreshTargetWindow(true);
   if (_targetWindowRef) {
-    console.error(`[Safari MCP] Profile "${SAFARI_PROFILE}" → targeting ${_targetWindowRef}`);
+    _logProfile(`Startup: Profile "${SAFARI_PROFILE}" → targeting ${_targetWindowRef}`);
   } else {
-    console.error(`[Safari MCP] WARNING: Profile "${SAFARI_PROFILE}" window NOT found at startup`);
+    _logProfile(`WARNING: Profile "${SAFARI_PROFILE}" window NOT found at startup`);
   }
 }
 
@@ -811,11 +851,21 @@ const INJECT_MCP_HELPERS = `if(window.__mcpVersion!==5){window.__mcpVersion=5;
         clientX:r.left+r.width/2,clientY:r.top+r.height/2,pageX:r.left+r.width/2+window.scrollX,pageY:r.top+r.height/2+window.scrollY,
         preventDefault:function(){},stopPropagation:function(){},nativeEvent:new MouseEvent(type||'click'),persist:function(){},bubbles:true,cancelable:true};
     }
+    // For React radio/checkbox inputs, onChange is the primary handler (not onClick)
+    var isToggle=startNode.tagName==='INPUT'&&(startNode.type==='radio'||startNode.type==='checkbox');
+    function tryOnChange(propsObj,targetNode){
+      if(!isToggle||!propsObj.onChange)return false;
+      var newChecked=startNode.type==='radio'?true:!startNode.checked;
+      propsObj.onChange({target:{value:startNode.value,checked:newChecked,type:startNode.type,name:startNode.name,id:startNode.id,tagName:'INPUT'},
+        currentTarget:targetNode,preventDefault:function(){},stopPropagation:function(){},nativeEvent:new Event('change'),persist:function(){},bubbles:true,cancelable:true,type:'change'});
+      return true;
+    }
     var node=startNode;
     for(var depth=0;depth<15&&node;depth++){
       var pk=Object.keys(node).find(function(k){return k.startsWith('__reactProps$')});
       if(pk&&node[pk]){
         var props=node[pk];
+        if(tryOnChange(props,node))return true;
         if(props.onClick){props.onClick(makeSynth(node,'click'));return true}
         if(props.onMouseDown){props.onMouseDown(makeSynth(node,'mousedown'));return true}
         if(props.onPointerDown){props.onPointerDown(makeSynth(node,'pointerdown'));return true}
@@ -825,6 +875,7 @@ const INJECT_MCP_HELPERS = `if(window.__mcpVersion!==5){window.__mcpVersion=5;
         var f=node[fk];
         while(f){
           if(f.memoizedProps){
+            if(tryOnChange(f.memoizedProps,node))return true;
             if(f.memoizedProps.onClick){f.memoizedProps.onClick(makeSynth(node,'click'));return true}
             if(f.memoizedProps.onMouseDown){f.memoizedProps.onMouseDown(makeSynth(node,'mousedown'));return true}
             if(f.memoizedProps.onPointerDown){f.memoizedProps.onPointerDown(makeSynth(node,'pointerdown'));return true}
@@ -1527,30 +1578,35 @@ export async function replaceEditorContent({ text }) {
 export async function screenshot({ fullPage = false } = {}) {
   await refreshTargetWindow();
   const tmpFile = join(tmpdir(), `safari-screenshot-${Date.now()}.png`);
-  let savedTabIdx = null;
   try {
-    // If working on a background tab, temporarily switch to it for screenshot
+    // Check if target tab is a background tab — if so, use JS screenshot to avoid tab jumping
+    let isBackgroundTab = false;
     if (_activeTabIndex) {
       try {
         const currentIdx = await osascriptFast(
           `tell application "Safari" to return index of current tab of ${getTargetWindowRef()}`
         );
-        if (Number(currentIdx) !== _activeTabIndex) {
-          savedTabIdx = Number(currentIdx);
-          await osascriptFast(
-            `tell application "Safari" to set current tab of ${getTargetWindowRef()} to tab ${_activeTabIndex} of ${getTargetWindowRef()}`
-          );
-          await new Promise(r => setTimeout(r, 200)); // Let Safari render the tab
-        }
+        isBackgroundTab = Number(currentIdx) !== _activeTabIndex;
       } catch (_) {}
     }
-    const skipScreencapture = false; // Always try screencapture now
+    // When on a background tab, go straight to JS-based screenshot (no tab switch, no focus steal)
+    const skipScreencapture = isBackgroundTab;
 
     // Try screencapture — use osascript's do shell script to bypass VS Code permission issue
     const windowId = !skipScreencapture ? await osascript(
       `tell application "Safari" to return id of ${getTargetWindowRef()}`
     ).catch(() => null) : null;
 
+    // Save frontmost app BEFORE screencapture (it may steal focus on macOS Tahoe)
+    let previousApp = null;
+    if (windowId) {
+      try {
+        previousApp = (await osascriptFast(
+          `tell application "System Events" to return name of first application process whose frontmost is true`
+        )).trim();
+      } catch (_) {}
+    }
+
     if (windowId) {
       try {
         if (fullPage) {
@@ -1585,6 +1641,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(() => {});
+        }
         // Compress: convert PNG to JPEG (50% quality) + resize to max 1200px width
         // Cuts ~600KB PNG → ~60KB JPEG — critical for staying under 20MB context limit
         const jpgFile = tmpFile.replace('.png', '.jpg');
@@ -1638,14 +1700,6 @@ export async function screenshot({ fullPage = false } = {}) {
     throw new Error("screencapture failed — Screen Recording permission may have been lost. Grant permission in System Settings → Privacy & Security → Screen Recording, then restart Safari.");
   } finally {
     await unlink(tmpFile).catch(() => {});
-    // Restore user's tab if we switched
-    if (savedTabIdx) {
-      try {
-        await osascriptFast(
-          `tell application "Safari" to set current tab of ${getTargetWindowRef()} to tab ${savedTabIdx} of ${getTargetWindowRef()}`
-        );
-      } catch (_) {}
-    }
   }
 }