safari-mcp 2.0.0 → 2.1.0

package/README.md

@@ -1,10 +1,38 @@
+<div align="center">
+
 # 🦁 Safari MCP
 
-**Native Safari automation for AI agents — zero Chrome overhead.**
+**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)
+[![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)
+[![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**
 
-Use your real Safari browser with all your logins, cookies, and sessions. No headless browsers, no Chrome, no Puppeteer. Just pure AppleScript + JavaScript running natively on macOS.
+[Quick Start](#quick-start) · [All 80 Tools](#tools-80) · [Why Safari MCP?](#safari-mcp-vs-alternatives) · [Architecture](#architecture)
+
+</div>
+
+---
 
-> **Why?** Chrome DevTools MCP heats up your Mac. Playwright launches a separate browser without your logins. Safari MCP uses your actual Safari — lightweight, native WebKit, and you stay logged in everywhere.
+> **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.
+
+<details>
+<summary><b>🤔 Why not just use Playwright or Chrome DevTools MCP?</b></summary>
+
+| 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 |
+| 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>
 
 ---
 
@@ -300,24 +328,80 @@ Add to your MCP client config:
 
 ## Architecture
 
+Safari MCP uses a **dual-engine** architecture — the Extension is preferred for speed and advanced capabilities, with AppleScript as an always-available fallback:
+
 ```
 Claude/Cursor/AI Agent
         ↓ MCP Protocol (stdio)
    Safari MCP Server (Node.js)
-        ↓ Persistent osascript process (~5ms/cmd)
-   AppleScript → Safari
-        ↓ do JavaScript in tab N
-   Page DOM (your real browser)
+        ↓                    ↓
+   Extension (HTTP)     AppleScript + Swift daemon
+   (~5-20ms/cmd)        (~5ms/cmd, always available)
+        ↓                    ↓
+   Content Script       do JavaScript in tab N
+        ↓                    ↓
+   Page DOM ←←←←←←←←←← Page DOM
 ```
 
 **Key design decisions:**
-- **Persistent osascript process** — one long-running process instead of spawning per command (16x faster)
+- **Dual engine with automatic fallback** — Extension is preferred; if not connected, AppleScript handles everything seamlessly
+- **Persistent Swift helper** — one long-running process instead of spawning per command (16x faster)
 - **Tab-indexed operations** — all JS runs on a specific tab by index, never steals visual focus
 - **JS-first approach** — typing, clicking, file upload all use JavaScript events (no System Events keyboard conflicts)
 - **No `activate`** — Safari is never brought to foreground
 
 ---
 
+## Safari Extension (Optional)
+
+The Safari MCP Extension is **optional but recommended**. Without it, ~80% of functionality works via AppleScript alone. The extension adds capabilities that AppleScript cannot provide:
+
+### What the Extension Adds
+
+| Capability | With Extension | AppleScript Only |
+|-----------|:--------------:|:----------------:|
+| Closed Shadow DOM (Reddit, Web Components) | ✅ Full access | ❌ Invisible |
+| Strict CSP sites | ✅ Bypasses via MAIN world | ❌ Often blocked |
+| React/Vue/Angular state manipulation | ✅ Deep (Fiber, ProseMirror) | ⚠️ Basic |
+| Loading state detection (spinners, skeletons) | ✅ Smart detection | ❌ No |
+| Dialog handling (alert/confirm) | ❌ | ✅ Only AppleScript |
+| Native OS-level click (CGEvent) | ❌ | ✅ Only AppleScript |
+| PDF export | ❌ | ✅ Only AppleScript |
+
+> **When do you need the extension?** If you're automating modern SPAs with closed shadow DOM (e.g., Reddit), sites with strict Content Security Policy, or framework-heavy editors (Draft.js, ProseMirror, Slate).
+
+### Installing the Extension
+
+The extension requires a one-time build with Xcode (free, included with macOS):
+
+**Prerequisites:** Xcode (install from App Store — free)
+
+```bash
+# 1. Build the extension app
+cd safari-mcp
+xcodebuild -project "xcode/Safari MCP/Safari MCP.xcodeproj" \
+  -scheme "Safari MCP (macOS)" -configuration Release build
+
+# 2. Find and open the built app
+open ~/Library/Developer/Xcode/DerivedData/Safari_MCP-*/Build/Products/Release/Safari\ MCP.app
+```
+
+Then in Safari:
+1. Safari → Settings → Advanced → enable **Show features for web developers**
+2. Safari → Develop → **Allow Unsigned Extensions** (required each Safari restart)
+3. Safari → Settings → Extensions → enable **Safari MCP Bridge**
+
+The extension connects automatically to the MCP server on port `9224`.
+
+> **Note:** "Allow Unsigned Extensions" resets every time Safari restarts. You'll need to re-enable it in the Develop menu after each restart. The extension itself stays installed.
+
+**Toolbar icon status:**
+- **ON** — connected to MCP server
+- **OFF** — manually disabled via popup
+- *(no badge)* — server not running, will auto-reconnect
+
+---
+
 ## macOS Permissions
 
 Safari MCP needs these one-time permissions:
@@ -343,6 +427,20 @@ Safari MCP needs these one-time permissions:
 
 ---
 
+## Works With
+
+Safari MCP works with any MCP-compatible client:
+
+| Client | Status |
+|--------|--------|
+| [Claude Code](https://claude.ai/claude-code) | ✅ Tested daily |
+| [Claude Desktop](https://claude.ai/download) | ✅ Tested |
+| [Cursor](https://cursor.sh) | ✅ Tested |
+| [Windsurf](https://codeium.com/windsurf) | ✅ Compatible |
+| [VS Code + Continue](https://continue.dev) | ✅ Compatible |
+
+---
+
 ## Contributing
 
 PRs welcome! The codebase is two files:
@@ -351,6 +449,14 @@ PRs welcome! The codebase is two files:
 
 ---
 
+## Star History
+
+If Safari MCP saved you from Chrome overhead, consider giving it a ⭐
+
+[![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)
+
+---
+
 ## License
 
-MIT
+MIT — use it however you want.