safari-mcp 2.14.0 → 2.15.0

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-<img src="social-preview.png" alt="Safari MCP Server — 80 native browser automation tools for AI agents on macOS" width="100%">
+<img src="social-preview.png" alt="Safari MCP Server — 96 native browser automation tools for AI agents on macOS" width="100%">
 
 <br/>
 
@@ -24,9 +24,9 @@
 <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** · **No Chrome/Puppeteer/Playwright needed** · **~5ms per command** · **60% less CPU than Chrome**
+**96 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)
+[Quick Start](#quick-start) · [All 96 Tools](#tools-96) · [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)
 
@@ -44,15 +44,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. 80 tools. One `npx` command. macOS only.
+Native WebKit. ~60% less CPU. Background operation. 96 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** (Safari Technology Preview 247, July 2026). It's built on `safaridriver` for isolated debugging sessions. safari-mcp drives the **real Safari you're already logged into** — on stable Safari, with 96 tools. See the full comparison below.
+
 ---
 
 ## Highlights
 
-- **80 tools** — navigation, clicks, forms, screenshots, network, storage, accessibility, and more
+- **96 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
@@ -302,7 +304,7 @@ The recommended pattern for AI agents using Safari MCP:
 
 ---
 
-## Tools (80)
+## Tools (96)
 
 <details>
 <summary><b>Click to expand the full tool list — organized by category</b></summary>
@@ -322,7 +324,7 @@ The recommended pattern for AI agents using Safari MCP:
 | `safari_get_source` | Get full HTML source |
 | `safari_navigate_and_read` | Navigate + read in one call |
 
-### Click & Interaction (5)
+### Click & Interaction (6)
 | Tool | Description |
 |------|-------------|
 | `safari_click` | Click by CSS selector, visible text, or coordinates |
@@ -330,8 +332,9 @@ The recommended pattern for AI agents using Safari MCP:
 | `safari_right_click` | Right-click (context menu) |
 | `safari_hover` | Hover over element |
 | `safari_click_and_wait` | Click + wait for navigation |
+| `safari_click_and_read` | Click then return the updated page — saves a round-trip (React Router + full loads) |
 
-### Form Input (7)
+### Form Input (11)
 | Tool | Description |
 |------|-------------|
 | `safari_fill` | Fill input (React/Vue/Angular compatible) |
@@ -341,6 +344,10 @@ The recommended pattern for AI agents using Safari MCP:
 | `safari_fill_and_submit` | Fill form + submit in one call |
 | `safari_type_text` | Type real keystrokes (JS-based, no System Events) |
 | `safari_press_key` | Press key with modifiers |
+| `safari_react_select_set` | Set a react-select v5 value via React fiber — bypasses the menu UI |
+| `safari_react_select_list_options` | List a react-select v5 dropdown's options without opening it |
+| `safari_replace_editor` | Replace all content in a code editor (Monaco, CodeMirror, Ace, ProseMirror) |
+| `safari_verify_state` | Verify an editor's framework-level state matches expected — catch stale DOM before Submit |
 
 ### Screenshots & PDF (3)
 | Tool | Description |
@@ -356,13 +363,14 @@ The recommended pattern for AI agents using Safari MCP:
 | `safari_scroll_to` | Scroll to exact position |
 | `safari_scroll_to_element` | Smooth scroll to element |
 
-### Tab Management (4)
+### Tab Management (5)
 | Tool | Description |
 |------|-------------|
 | `safari_list_tabs` | List all tabs (index, title, URL) |
 | `safari_new_tab` | Open new tab (background, no focus steal) |
 | `safari_close_tab` | Close tab |
 | `safari_switch_tab` | Switch to tab by index |
+| `safari_wait_for_new_tab` | Wait for a new tab (e.g. OAuth popup) and auto-switch to it |
 
 ### Wait (2)
 | Tool | Description |
@@ -383,10 +391,11 @@ The recommended pattern for AI agents using Safari MCP:
 | `safari_get_computed_style` | Computed CSS styles |
 | `safari_detect_forms` | Auto-detect all forms with field selectors |
 
-### Accessibility (1)
+### Accessibility (2)
 | Tool | Description |
 |------|-------------|
 | `safari_accessibility_snapshot` | Full a11y tree: roles, ARIA, focusable elements |
+| `safari_snapshot` | Accessibility tree with ref IDs for every interactive element — preferred way to see page state |
 
 ### Drag & Drop (1)
 | Tool | Description |
@@ -411,7 +420,7 @@ The recommended pattern for AI agents using Safari MCP:
 | `safari_emulate` | Emulate device (iPhone, iPad, Pixel, Galaxy) |
 | `safari_reset_emulation` | Reset to desktop |
 
-### Cookies & Storage (10)
+### Cookies & Storage (11)
 | Tool | Description |
 |------|-------------|
 | `safari_get_cookies` | Get all cookies |
@@ -464,7 +473,7 @@ The recommended pattern for AI agents using Safari MCP:
 | `safari_extract_images` | Images with dimensions and loading info |
 | `safari_extract_links` | Links with rel, external/nofollow detection |
 
-### Advanced (5)
+### Advanced (7)
 | Tool | Description |
 |------|-------------|
 | `safari_override_geolocation` | Override browser geolocation |
@@ -472,12 +481,22 @@ The recommended pattern for AI agents using Safari MCP:
 | `safari_get_indexed_db` | Read IndexedDB records |
 | `safari_css_coverage` | Find unused CSS rules |
 | `safari_analyze_page` | Full page analysis in one call |
+| `safari_doctor` | Diagnose the macOS permission + daemon chain (Apple Events, Accessibility, Screen Recording, codesign) with per-failure fixes |
+| `safari_reload_extension` | Hot-reload the Safari MCP Bridge extension without a manual toggle |
 
 ### Automation (1)
 | Tool | Description |
 |------|-------------|
 | `safari_run_script` | Run multiple actions in a single call (batch) |
 
+### Native Input — CGEvent (4)
+| Tool | Description |
+|------|-------------|
+| `safari_native_click` | OS-level mouse click (CGEvent, `isTrusted: true`) — bypasses WAF/bot detection when `safari_click` is blocked (405/403) |
+| `safari_native_hover` | OS-level cursor hover — triggers real `:hover`/`mouseenter` for tooltips and obfuscated UIs |
+| `safari_native_type` | Insert text via the real paste pipeline — ProseMirror/Slate/Draft.js process it natively so Submit sends real data |
+| `safari_native_keyboard` | OS-level keypress + modifiers to Safari, no focus steal — reaches React trust-gated handlers (Discord/Slack send) |
+
 ### iOS & WebKit Validation (4)
 | Tool | Description |
 |------|-------------|
@@ -512,7 +531,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 | 80 | ~30 | ~25 |
+| Tools | 96 | ~30 | ~25 |
 | File upload | JS (no dialog) | CDP | Playwright API |
 | Image paste | JS (no clipboard) | CDP | Playwright API |
 | Focus steal | ❌ Background | ❌ Background | ❌ Headless |
@@ -522,13 +541,31 @@ Safari MCP runs locally on your Mac with minimal attack surface:
 
 > **Tip:** Use Safari MCP for daily browsing tasks (95% of work) and Chrome DevTools MCP only for Lighthouse/Performance audits.
 
+### vs Apple's Official Safari MCP (safaridriver)
+
+In Safari Technology Preview 247 (July 2026), Apple shipped an **official** Safari MCP server built on `safaridriver`. That's great validation for the category — and it's built for a different job. Apple's server drives an **isolated WebDriver automation session** for debugging; safari-mcp drives the **real Safari you're already logged into**.
+
+| | 🦁 safari-mcp *(this repo)* | Apple `safaridriver --mcp` |
+|---|:---:|:---:|
+| **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 only |
+| **Background (no focus steal)** | ✅ Yes | ❌ Dedicated window with a "controlled by automation" banner |
+| **Tools** | **96** | ~17 |
+| **Storage** (cookies, localStorage, IndexedDB) | ✅ 10 tools | ❌ |
+| **Network mocking + throttling** | ✅ Yes | ❌ Read-only network inspection |
+| **Device emulation** (iPhone, iPad) | ✅ Yes | ⚠️ Viewport + media type only |
+| **Setup** | `npx safari-mcp` | Enable "remote automation and external agents" in STP |
+| **Official Apple support** | ❌ Community (MIT) | ✅ Apple, WebDriver-standard |
+
+> **When Apple's server is the right pick:** you specifically want a clean-room, WebDriver-standard session for compatibility debugging and you already run STP. **For everything else — daily automation on the browser you're already signed into, on stable Safari — safari-mcp is built for exactly that.**
+
 ### Why Safari MCP and Not the Other Safari MCP Projects?
 
 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** | **80** | ~10 | 23 | ~15 |
+| **Tools** | **96** | ~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 |
@@ -795,7 +832,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.%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/)
+[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.%2096%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/glama.json

@@ -1,7 +1,7 @@
 {
   "$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.",
+  "description": "Native Safari browser automation for AI agents. 96 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",

package/index.js

@@ -7,15 +7,20 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { startTransport } from "./transport.js";
 import { z } from "zod";
 import * as safari from "./safari.js";
-import { findOwnedMatch, pruneExpired } from "./ownership-match.js";
 import { textResult, jsonResult, imageResult, errorResult } from "./response.js";
+import {
+  OWNERSHIP_DIR, BLANK_TAB_SENTINEL,
+  _openedTabs, _ownedTabURLs,
+  _isURLOwned, _markBlankTabOpened, _addOwnedURL, _removeOwnedURL, _trackTab, _untrackTab,
+} from "./ownership-state.js";
 import { WebSocketServer } from "ws";
 import { createServer } from "node:http";
 import { randomUUID, randomBytes } from "node:crypto";
 import { execFile, execFileSync } from "node:child_process";
-import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
@@ -49,130 +54,20 @@ const PROXY_TOKEN = _getProxyToken();
 // ========== SESSION ID (unique per MCP process — enables per-session tab tracking) ==========
 const SESSION_ID = randomUUID().slice(0, 8);
 
-// ========== PERSISTENT TAB OWNERSHIP ==========
-// The in-memory _ownedTabURLs set is wiped when the MCP process restarts
-// (Claude Code periodically recycles MCP servers). Without persistence, every
-// restart re-triggers "Tab safety: no tabs opened yet" errors forcing a
-// re-open of every tab. Persist the set to a JSON file with a TTL so tabs
-// remain "owned" across process restarts for up to OWNERSHIP_TTL_MS.
-const OWNERSHIP_DIR = join(homedir(), ".safari-mcp");
-const OWNERSHIP_FILE = join(OWNERSHIP_DIR, "owned-tabs.json");
-const OWNERSHIP_TTL_MS = 30 * 60 * 1000; // 30 minutes
-
-function _loadOwnershipFile() {
-  try {
-    if (!existsSync(OWNERSHIP_FILE)) return [];
-    const raw = readFileSync(OWNERSHIP_FILE, "utf8");
-    const data = JSON.parse(raw);
-    if (!Array.isArray(data)) return [];
-    const cutoff = Date.now() - OWNERSHIP_TTL_MS;
-    return data.filter(e => e && typeof e.url === "string" && typeof e.ts === "number" && e.ts > cutoff);
-  } catch { return []; }
-}
-
-function _saveOwnershipFile(urls) {
-  try {
-    if (!existsSync(OWNERSHIP_DIR)) mkdirSync(OWNERSHIP_DIR, { recursive: true });
-    const now = Date.now();
-    const entries = Array.from(urls).map(url => ({ url, ts: _ownedTabTimestamps.get(url) ?? now }));
-    // Atomic write (tmp + rename) — concurrent MCP instances share this file; a partial
-    // write from one must never corrupt the JSON another instance reads.
-    const tmp = OWNERSHIP_FILE + ".tmp." + process.pid;
-    writeFileSync(tmp, JSON.stringify(entries), { mode: 0o600 });
-    renameSync(tmp, OWNERSHIP_FILE);
-  } catch { /* best-effort */ }
-}
+// Persistent tab-ownership state + its helpers now live in ownership-state.js
+// (OWNERSHIP_* consts, _ownedTabURLs/_ownedTabTimestamps, _loadOwnershipFile,
+// _saveOwnershipFile, _isURLOwned, _addOwnedURL, _trackTab, … — imported at the top).
+// OWNERSHIP_DIR is re-used below for the memory-monitor lock file.
 
 // ========== 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();
-
-// ========== TAB OWNERSHIP: prevent operating on user's tabs ==========
-// Tracks URLs of tabs opened by this MCP session.
-// Any tool that modifies a tab (navigate, click, fill, etc.) is blocked
-// unless the current tab was opened via safari_new_tab.
-// Hydrated from ~/.safari-mcp/owned-tabs.json so ownership survives MCP restarts.
-const _ownedTabURLs = new Set();
-// Preserve each entry's ORIGINAL timestamp so _saveOwnershipFile doesn't reset it to `now` on
-// every write — otherwise the 30-min TTL never expires anything while a session is active, and
-// stale ownership leaks onto the user's tabs across sessions.
-const _ownedTabTimestamps = new Map();
-for (const e of _loadOwnershipFile()) {
-  _ownedTabURLs.add(e.url);
-  _ownedTabTimestamps.set(e.url, e.ts);
-}
-
-// Touch-on-use + live TTL enforcement. The TTL exists so ownership doesn't outlive the
-// session's actual use of a tab: entries the session keeps asserting against stay fresh;
-// abandoned entries expire after OWNERSHIP_TTL_MS and can no longer match a user's tab.
-// (Previously the TTL was only applied when loading the file at startup, so a long-lived
-// session accumulated ownership forever.)
-function _touchOwned(ownedKey) {
-  _ownedTabTimestamps.set(ownedKey, Date.now());
-  return true;
-}
-function _pruneExpiredOwnership() {
-  if (pruneExpired(_ownedTabURLs, _ownedTabTimestamps, OWNERSHIP_TTL_MS)) {
-    _saveOwnershipFile(_ownedTabURLs);
-  }
-}
-
-// Matching semantics (exact / normalized / same-origin path-prefix with a segment
-// boundary) live in ownership-match.js, where test/ownership-match.test.mjs locks
-// them — including that owning /org never owns /org-evil, and that the broad
-// "own the whole origin" rule stays dead (it defeated tab-safety entirely).
-function _isURLOwned(url) {
-  if (!url) return false;
-  _pruneExpiredOwnership();
-  const match = findOwnedMatch(url, _ownedTabURLs);
-  return match !== null ? _touchOwned(match) : false;
-}
-
-// Sentinel persisted when a blank tab (about:blank) is opened by this session.
-// A blank tab has no unique URL to own, but ownership must still survive an MCP
-// process restart (_openedTabs is in-memory only) — otherwise reopening blank
-// tabs falsely trips the "no tabs opened yet" guard. The sentinel is never a
-// real tab URL, so it cannot falsely match a user's page in _isURLOwned().
-const BLANK_TAB_SENTINEL = "__mcp-blank-tab__";
-
-function _markBlankTabOpened() {
-  if (!_ownedTabURLs.has(BLANK_TAB_SENTINEL)) {
-    _ownedTabTimestamps.set(BLANK_TAB_SENTINEL, Date.now());
-    _ownedTabURLs.add(BLANK_TAB_SENTINEL);
-    _saveOwnershipFile(_ownedTabURLs);
-  }
-}
-
-function _addOwnedURL(url) {
-  if (url && url !== 'about:blank' && url !== 'favorites://') {
-    if (!_ownedTabTimestamps.has(url)) _ownedTabTimestamps.set(url, Date.now());
-    _ownedTabURLs.add(url);
-    _saveOwnershipFile(_ownedTabURLs);
-  }
-}
-
-function _removeOwnedURL(url) {
-  if (url) {
-    _ownedTabURLs.delete(url);
-    _ownedTabTimestamps.delete(url);
-    _saveOwnershipFile(_ownedTabURLs);
-  }
-}
-
-function _trackTab(tabIndex, url) {
-  _openedTabs.set(tabIndex, { url: url || "", openedAt: Date.now() });
-  _addOwnedURL(url);
-}
-
-function _untrackTab(tabIndex) {
-  const info = _openedTabs.get(tabIndex);
-  if (info?.url) _removeOwnedURL(info.url);
-  _openedTabs.delete(tabIndex);
-}
+// Tab-ownership state (_openedTabs / _ownedTabURLs / _ownedTabTimestamps), the on-disk
+// persistence + TTL, and the helpers (_isURLOwned, _markBlankTabOpened, _addOwnedURL,
+// _removeOwnedURL, _trackTab, _untrackTab, BLANK_TAB_SENTINEL) are imported from
+// ownership-state.js at the top of this file.
 
 // Close all MCP-opened tabs on process exit
 async function _cleanupTabs() {
@@ -885,6 +780,11 @@ async function extensionOrFallback(extensionType, extensionPayload, fallbackFn)
 
 // Read version from package.json to avoid hardcoded mismatch
 const _pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8')).version;
+// Factory so each MCP session (in HTTP mode) gets its own McpServer — McpServer is single-connection.
+// stdio mode calls this exactly once, identical to the historical inline server. Tool bodies are
+// unchanged; they close over the module-global safari state, which stays shared across sessions
+// (correct: one physical Safari window). See docs/http-transport-design.md.
+function buildServer() {
 const server = new McpServer({
   name: "safari-mcp",
   version: _pkgVersion,
@@ -1654,6 +1554,17 @@ server.tool(
   }
 );
 
+server.tool(
+  "safari_eval_file",
+  "Execute JavaScript read from a FILE path (avoids passing huge scripts inline / manual copy). Same engine as safari_evaluate: extension-first (no focus steal), AppleScript fallback. Use to upload binary via a generated .js containing base64.",
+  { path: z.string().describe("Absolute path to a .js file whose contents are the script to execute") },
+  async (args) => {
+    const script = readFileSync(args.path, "utf8");
+    const result = await extensionOrFallback("evaluate", { script }, () => safari.evaluate({ script }));
+    return { content: [{ type: "text", text: (typeof result === "string" ? result : JSON.stringify(result)) || "(no return value)" }] };
+  }
+);
+
 // ========== ELEMENT INFO ==========
 
 server.tool(
@@ -2460,6 +2371,9 @@ server.tool(
   }
 );
 
+  return server;
+}
+
 // ========== START SERVER ==========
 
 // One-time-per-day startup banner — visible CTA without spamming MCP logs.
@@ -2504,5 +2418,6 @@ _startMemoryMonitor();
   } catch { /* best-effort, never block startup */ }
 })();
 
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// Transport is chosen at runtime: default stdio (unchanged), or a shared HTTP instance when
+// SAFARI_MCP_HTTP=1 (many Claude sessions → one process). buildServer is the per-session factory.
+await startTransport(buildServer, process.env);

package/ownership-state.js

@@ -0,0 +1,141 @@
+// Tab-ownership state + tracking — the security-critical core that prevents the MCP
+// session from operating on the USER's tabs. Extracted verbatim from index.js so the
+// state and its helpers live in one reviewable, test-locked module (see
+// tests/ownership-state.test.mjs). The pure matching/pruning semantics live next door in
+// ownership-match.js; this module owns the *stateful* layer on top of them: the in-memory
+// sets, the on-disk persistence (so ownership survives MCP restarts), and the TTL.
+//
+// Every symbol here was previously a module-level binding in index.js. All exported state
+// is `const` (Map/Set) — mutated, never reassigned — so ESM live bindings keep index.js and
+// any future src/tools/* module pointing at the exact same objects.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { findOwnedMatch, pruneExpired } from "./ownership-match.js";
+
+// MCP opens tabs, but a restart re-triggers "Tab safety: no tabs opened yet" errors forcing
+// a re-open of every tab. Persist the set to a JSON file with a TTL so tabs remain "owned"
+// across process restarts for up to OWNERSHIP_TTL_MS.
+export const OWNERSHIP_DIR = join(homedir(), ".safari-mcp");
+export const OWNERSHIP_FILE = join(OWNERSHIP_DIR, "owned-tabs.json");
+export const OWNERSHIP_TTL_MS = 30 * 60 * 1000; // 30 minutes
+
+export function _loadOwnershipFile() {
+  try {
+    if (!existsSync(OWNERSHIP_FILE)) return [];
+    const raw = readFileSync(OWNERSHIP_FILE, "utf8");
+    const data = JSON.parse(raw);
+    if (!Array.isArray(data)) return [];
+    const cutoff = Date.now() - OWNERSHIP_TTL_MS;
+    return data.filter(
+      (e) => e && typeof e.url === "string" && typeof e.ts === "number" && e.ts > cutoff
+    );
+  } catch {
+    return [];
+  }
+}
+
+export function _saveOwnershipFile(urls) {
+  try {
+    if (!existsSync(OWNERSHIP_DIR)) mkdirSync(OWNERSHIP_DIR, { recursive: true });
+    const now = Date.now();
+    const entries = Array.from(urls).map((url) => ({
+      url,
+      ts: _ownedTabTimestamps.get(url) ?? now,
+    }));
+    // Atomic write (tmp + rename) — concurrent MCP instances share this file; a partial
+    // write from one must never corrupt the JSON another instance reads.
+    const tmp = OWNERSHIP_FILE + ".tmp." + process.pid;
+    writeFileSync(tmp, JSON.stringify(entries), { mode: 0o600 });
+    renameSync(tmp, OWNERSHIP_FILE);
+  } catch {
+    /* best-effort */
+  }
+}
+
+// Track tabs opened by THIS session (index → {url, openedAt})
+export const _openedTabs = new Map();
+
+// ========== TAB OWNERSHIP: prevent operating on user's tabs ==========
+// Tracks URLs of tabs opened by this MCP session.
+// Any tool that modifies a tab (navigate, click, fill, etc.) is blocked
+// unless the current tab was opened via safari_new_tab.
+// Hydrated from ~/.safari-mcp/owned-tabs.json so ownership survives MCP restarts.
+export const _ownedTabURLs = new Set();
+// Preserve each entry's ORIGINAL timestamp so _saveOwnershipFile doesn't reset it to `now` on
+// every write — otherwise the 30-min TTL never expires anything while a session is active, and
+// stale ownership leaks onto the user's tabs across sessions.
+export const _ownedTabTimestamps = new Map();
+for (const e of _loadOwnershipFile()) {
+  _ownedTabURLs.add(e.url);
+  _ownedTabTimestamps.set(e.url, e.ts);
+}
+
+// Touch-on-use + live TTL enforcement. The TTL exists so ownership doesn't outlive the
+// session's actual use of a tab: entries the session keeps asserting against stay fresh;
+// abandoned entries expire after OWNERSHIP_TTL_MS and can no longer match a user's tab.
+// (Previously the TTL was only applied when loading the file at startup, so a long-lived
+// session accumulated ownership forever.)
+export function _touchOwned(ownedKey) {
+  _ownedTabTimestamps.set(ownedKey, Date.now());
+  return true;
+}
+export function _pruneExpiredOwnership() {
+  if (pruneExpired(_ownedTabURLs, _ownedTabTimestamps, OWNERSHIP_TTL_MS)) {
+    _saveOwnershipFile(_ownedTabURLs);
+  }
+}
+
+// Matching semantics (exact / normalized / same-origin path-prefix with a segment
+// boundary) live in ownership-match.js, where test/ownership-match.test.mjs locks
+// them — including that owning /org never owns /org-evil, and that the broad
+// "own the whole origin" rule stays dead (it defeated tab-safety entirely).
+export function _isURLOwned(url) {
+  if (!url) return false;
+  _pruneExpiredOwnership();
+  const match = findOwnedMatch(url, _ownedTabURLs);
+  return match !== null ? _touchOwned(match) : false;
+}
+
+// Sentinel persisted when a blank tab (about:blank) is opened by this session.
+// A blank tab has no unique URL to own, but ownership must still survive an MCP
+// process restart (_openedTabs is in-memory only) — otherwise reopening blank
+// tabs falsely trips the "no tabs opened yet" guard. The sentinel is never a
+// real tab URL, so it cannot falsely match a user's page in _isURLOwned().
+export const BLANK_TAB_SENTINEL = "__mcp-blank-tab__";
+
+export function _markBlankTabOpened() {
+  if (!_ownedTabURLs.has(BLANK_TAB_SENTINEL)) {
+    _ownedTabTimestamps.set(BLANK_TAB_SENTINEL, Date.now());
+    _ownedTabURLs.add(BLANK_TAB_SENTINEL);
+    _saveOwnershipFile(_ownedTabURLs);
+  }
+}
+
+export function _addOwnedURL(url) {
+  if (url && url !== "about:blank" && url !== "favorites://") {
+    if (!_ownedTabTimestamps.has(url)) _ownedTabTimestamps.set(url, Date.now());
+    _ownedTabURLs.add(url);
+    _saveOwnershipFile(_ownedTabURLs);
+  }
+}
+
+export function _removeOwnedURL(url) {
+  if (url) {
+    _ownedTabURLs.delete(url);
+    _ownedTabTimestamps.delete(url);
+    _saveOwnershipFile(_ownedTabURLs);
+  }
+}
+
+export function _trackTab(tabIndex, url) {
+  _openedTabs.set(tabIndex, { url: url || "", openedAt: Date.now() });
+  _addOwnedURL(url);
+}
+
+export function _untrackTab(tabIndex) {
+  const info = _openedTabs.get(tabIndex);
+  if (info?.url) _removeOwnedURL(info.url);
+  _openedTabs.delete(tabIndex);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safari-mcp",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "mcpName": "io.github.achiya-automation/safari-mcp",
   "description": "Safari browser automation for AI agents — native macOS, zero Chrome overhead. 96 tools via AppleScript + JavaScript.",
   "type": "module",
@@ -66,6 +66,7 @@
     "response.js",
     "safari.js",
     "ownership-match.js",
+    "ownership-state.js",
     "mcp-helpers.js",
     "injected-validators.js",
     "injected-escape.js",
@@ -88,7 +89,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^25.9.3",
+    "@types/node": "^26.0.0",
     "eslint": "^10.5.0",
     "globals": "^17.6.0",
     "jsdom": "^29.1.1",

package/safari.js

@@ -4952,6 +4952,31 @@ export async function checkWebKitCompat() {
 // One-shot check of the whole macOS permission + daemon chain, so the
 // "it doesn't work even with permissions granted" failures (#14/#15/#29)
 // surface as one actionable checklist instead of scattered cryptic errors.
+// ========== macOS NATIVE-INPUT COMPAT ==========
+// CGEvent.postToPid (native clicks/keys/hover) can silently no-op on macOS 26+ (Tahoe) even
+// with Accessibility granted — the events are accepted by the API but never cross into Safari's
+// WebContent process (issue #29). doctor() prints the OS version so a bug report carries the
+// single most relevant fact, and flags the known-risky range so users reach for safari_evaluate
+// or extension-based clicks on trust-gated forms instead of chasing a phantom permission grant.
+// Pure (no I/O) so it's unit-tested directly — see test/macos-compat.test.mjs.
+export function macosCompatNote(productVersion) {
+  const raw = String(productVersion ?? "").trim();
+  const major = parseInt(raw.split(".")[0], 10);
+  if (!Number.isFinite(major)) {
+    return {
+      version: "unknown",
+      major: null,
+      risky: false,
+      line: "macOS version: unknown (sw_vers gave no parseable version)",
+    };
+  }
+  const risky = major >= 26;
+  const line = risky
+    ? `macOS ${raw} ⚠ CGEvent native clicks/keys may silently no-op on macOS 26+ even with Accessibility granted (issue #29) — for trust-gated forms prefer safari_evaluate or extension-based safari_click.`
+    : `macOS ${raw} — CGEvent native input supported.`;
+  return { version: raw, major, risky, line };
+}
+
 export async function doctor() {
   const checks = [];
   const add = (ok, label, detail, fix) => checks.push({ ok, label, detail, fix: ok ? null : fix });
@@ -5006,8 +5031,17 @@ export async function doctor() {
   add(idOk, "Helper codesign identity", idDetail,
     `Re-sign: codesign -s - -f --identifier com.achiya-automation.safari-mcp --entitlements safari-helper.entitlements "${helperPath}"`);
 
+  // macOS version — the single most relevant fact for #29-class "native clicks silently fail"
+  // reports. Best-effort: sw_vers is macOS-only and absent in sandboxes/CI, so never block doctor.
+  let osLine = null;
+  try {
+    const { stdout } = await execFileAsync("sw_vers", ["-productVersion"], { timeout: 2000 });
+    osLine = macosCompatNote(stdout).line;
+  } catch { /* sw_vers unavailable — skip the line, the permission checks still stand */ }
+
   const passed = checks.filter((c) => c.ok).length;
   const lines = [`Safari MCP doctor — ${passed}/${checks.length} checks passed`, ""];
+  if (osLine) lines.push(osLine, "");
   for (const c of checks) {
     lines.push(`${c.ok ? "✅" : "❌"} ${c.label}: ${c.detail}`);
     if (!c.ok && c.fix) lines.push(`   → ${c.fix}`);