safari-mcp 2.21.2 → 2.21.4

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="social-preview.png" alt="Safari MCP Server — 97 native browser automation tools for AI agents on macOS" width="100%">
+<img src="social-preview.png" alt="Safari MCP Server — 98 native browser automation tools for AI agents on macOS" width="100%">
 
 <br/>
 
@@ -19,9 +19,9 @@
 [VS Code Insiders](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) ·
 [Install in Cursor](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)
 
-**97 tools** · **No Chrome/Puppeteer/Playwright needed** · **~5ms per command** · **60% less CPU than Chrome**
+**98 tools** · **No Chrome/Puppeteer/Playwright needed** · **~5ms per command** · **60% less CPU than Chrome**
 
-[Quick Start](#quick-start) · [All 97 Tools](#tools-97) · [Examples](examples/) · [Why Safari MCP?](#safari-mcp-vs-alternatives) · [Architecture](#architecture) · [Changelog](CHANGELOG.md)
+[Quick Start](#quick-start) · [All 98 Tools](#tools-98) · [Examples](examples/) · [Why Safari MCP?](#safari-mcp-vs-alternatives) · [Architecture](#architecture) · [Changelog](CHANGELOG.md)
 
 ![Safari MCP Demo](https://github.com/achiya-automation/safari-mcp/raw/main/assets/safari-mcp-promo.gif)
 
@@ -39,17 +39,17 @@ Your AI agent needs to browse. So it either:
 
 Your AI drives the **Safari you're already logged into** — Gmail, GitHub, Ahrefs, Slack, banking.
 
-Native WebKit. ~60% less CPU. Background operation. 97 tools. One `npx` command. macOS only.
+Native WebKit. ~60% less CPU. Background operation. 98 tools. One `npx` command. macOS only.
 
 > 📰 **Featured on freeCodeCamp:** [How to Connect Your AI Coding Agent to a Browser on macOS](https://www.freecodecamp.org/news/how-to-connect-your-ai-coding-agent-to-a-browser-on-macos/) · [HackerNoon: Reverse-Engineering React, Shadow DOM, and CSP](https://hackernoon.com/i-had-to-reverse-engineer-react-shadow-dom-and-csp-to-automate-safari-without-chrome)
 
-> 🍎 **Apple shipped an official Safari MCP** (July 2026 — Safari Technology Preview 247+ and the Safari 27 beta). It's built on `safaridriver` for isolated debugging sessions. safari-mcp drives the **real Safari you're already logged into** — on the stable Safari that ships with macOS today, with 97 tools. See the full comparison below.
+> 🍎 **Apple shipped an official Safari MCP** (July 2026 — Safari Technology Preview 247+ and the Safari 27 beta). It's built on `safaridriver` for isolated debugging sessions. safari-mcp drives the **real Safari you're already logged into** — on the stable Safari that ships with macOS today, with 98 tools. See the full comparison below.
 
 ---
 
 ## Highlights
 
-- **97 tools** — navigation, clicks, forms, screenshots, network, storage, accessibility, and more
+- **98 tools** — navigation, clicks, forms, screenshots, network, storage, accessibility, and more
 - **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
@@ -390,7 +390,7 @@ What the flag deliberately does *not* do:
 
 ---
 
-## Tools (97)
+## Tools (98)
 
 <details>
 <summary><b>Click to expand the full tool list — organized by category</b></summary>
@@ -464,11 +464,12 @@ What the flag deliberately does *not* do:
 | `safari_wait_for` | Wait for element, text, or URL change |
 | `safari_wait` | Wait for specified milliseconds |
 
-### JavaScript (1)
+### JavaScript (3)
 | Tool | Description |
 |------|-------------|
 | `safari_evaluate` | Execute arbitrary JavaScript, return result |
 | `safari_eval_file` | Execute JavaScript read from a file path (avoids huge inline scripts) |
+| `safari_list_frames` | List every document in the tab (main page + each iframe) with frameId, URL and text length — pass a frameId to `safari_evaluate`'s `frame` to run inside a cross-origin iframe |
 
 ### Element Inspection (4)
 | Tool | Description |
@@ -618,7 +619,7 @@ Safari MCP runs locally on your Mac with minimal attack surface:
 | Your logins | ✅ Yes | ✅ Yes | ❌ No |
 | macOS native | ✅ WebKit | ❌ Chromium | ❌ Chromium/WebKit |
 | Browser dependencies | None | Chrome + debug port | Playwright runtime |
-| Tools | 97 | ~30 | ~25 |
+| Tools | 98 | ~30 | ~25 |
 | File upload | JS (no dialog) | CDP | Playwright API |
 | Image paste | JS (no clipboard) | CDP | Playwright API |
 | Focus steal | ❌ Background | ❌ Background | ❌ Headless |
@@ -639,7 +640,7 @@ It has not reached a stable Safari release yet: on macOS 26.5.2 with Safari 26.5
 | **Your real logins / cookies** | ✅ Your actual Safari | ⚠️ Isolated automation session — no access to AutoFill or browsing activity |
 | **Runs on** | ✅ Stable Safari, every Mac | ⚠️ Safari Technology Preview 247+ or the Safari 27 beta — not in stable Safari 26.5 |
 | **Background (no focus steal)** | ✅ Yes | ❌ Dedicated window with a "controlled by automation" banner |
-| **Tools** | **97** | ~17 |
+| **Tools** | **98** | ~17 |
 | **Storage** (cookies, localStorage, IndexedDB) | ✅ 10 tools | ❌ |
 | **Network mocking + throttling** | ✅ Yes | ❌ Read-only network inspection |
 | **Device emulation** (iPhone, iPad) | ✅ Yes | ⚠️ Viewport + media type only |
@@ -654,7 +655,7 @@ There are several "safari-mcp" projects floating around. Here's how they compare
 
 | Feature | **🦁 safari-mcp** *(this repo)* | [lxman/safari-mcp-server](https://github.com/lxman/safari-mcp-server) | [Epistates/MCPSafari](https://github.com/Epistates/MCPSafari) | [HayoDev/safari-devtools-mcp](https://github.com/HayoDev/safari-devtools-mcp) |
 |---------|:------------------------------:|:----------------------:|:------------:|:----------------------:|
-| **Tools** | **97** | ~10 | 23 | ~15 |
+| **Tools** | **98** | ~10 | 23 | ~15 |
 | **Install** | `npx safari-mcp` | Manual | Binary | `npx` |
 | **Engine** | **Dual** (Extension + AppleScript) | WebDriver | Extension only | DevTools Protocol |
 | **Keeps your real Safari logins** | ✅ Yes | ⚠️ Limited | ✅ Yes | ❌ Debug session |
@@ -923,7 +924,7 @@ If Safari MCP saves you from Chrome overhead, **a star helps others discover it:
 
 [![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.%2097%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/)
+[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.%2098%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)
 

package/extension/background.js

@@ -2761,7 +2761,16 @@ async function handleCommand(type, payload) {
         if (mainResult && JSON.parse(mainResult).length > 0) return mainResult;
       } catch { return mainResult; }
       const frameResult = await execAcrossFrames(queryFn, [payload.selector, payload.limit || 20], tabId);
-      return frameResult || mainResult;
+      if (!frameResult) return mainResult;
+      // Reaching here means the main frame matched nothing, so every element below came
+      // from a child frame and its x/y are that frame's viewport coordinates. Say so in
+      // the payload: the caller is an agent reading this JSON, and the click tools take
+      // page coordinates — a comment in this file never reaches it.
+      try {
+        return JSON.stringify(JSON.parse(frameResult).map((el) => ({ ...el, frameRelative: true })));
+      } catch {
+        return frameResult;
+      }
     }
 
     default:

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.10.11",
+  "version": "2.10.12",
   "icons": {
     "48": "images/icon-48.png",
     "96": "images/icon-96.png",

package/index.js

@@ -3014,7 +3014,7 @@ server.tool(
 
 server.tool(
   "safari_query_all",
-  "Find all elements matching a CSS selector (returns tag, text, href, value)",
+  "Find all elements matching a CSS selector (returns tag, text, href, value). x/y are relative to each element's own frame viewport — for matches inside an iframe, click by selector or snapshot ref, not by these coordinates",
   {
     selector: z.string().describe("CSS selector"),
     limit: z.coerce.number().optional().describe("Max results (default: 20)"),
@@ -3025,6 +3025,15 @@ server.tool(
       "query_all", { selector: args.selector, limit: args.limit, ..._explicitReceipt(args) },
       () => safari.querySelectorAll(args)
     );
+    // The matches live inside a child frame, so their x/y are that frame's viewport
+    // coordinates while safari_click and friends take page coordinates. Warn in the
+    // result text, which is the only part of this an agent actually reads.
+    if (typeof result === "string" && result.includes('"frameRelative":true')) {
+      return textResult(
+        result +
+          "\n\nNote: these matches are inside a child frame. Their x/y are relative to that frame's viewport (see \"frame\"), not to the page — click them by selector or by a safari_snapshot ref; passing these coordinates to safari_click lands somewhere else."
+      );
+    }
     return textResult(result);
   }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safari-mcp",
-  "version": "2.21.2",
+  "version": "2.21.4",
   "mcpName": "io.github.achiya-automation/safari-mcp",
   "description": "Safari browser automation for AI agents — native macOS, zero Chrome overhead. 97 tools via AppleScript + JavaScript.",
   "type": "module",