cli-anything-safari

Was macht cli-anything-safari?

Eine Befehlszeilenschnittstelle für die Safari-Browserautomatisierung auf macOS. Umhüllt den safari-mcp Node.js MCP-Server in einem Python-Click-CLI.

Feature-Parität ist garantiert. Jeder Click-Befehl wird automatisch aus dem Tool-Schema von safari-mcp generiert (gebündelt als resources/tools.json). Alle 84 Tools sind mit den genauen Argumentnamen und -typen erreichbar, die der MCP-Server erwartet.

Wann dieses CLI verwendet werden sollte

Jeder CLI-Aufruf startet einen neuen Unterprozess, daher entsteht pro Aufruf ein gewisser Overhead. Wenn Ihr Agent nativ MCP spricht (Claude Code, Cursor, Cline usw.), ist die direkte Verwendung von safari-mcp über MCP stdio schneller.

Verwenden Sie dieses CLI, wenn:

• Ihr Agenten-Framework kein MCP spricht (Codex CLI, GitHub Copilot CLI, benutzerdefinierte Skripte, ältere Agenten-Frameworks).
• Sie Browserautomatisierung von bash aus skripten müssen – cli-anything-safari --json tool snapshot | jq '...'.
• Sie in CI/CD laufen und cron-fähige, unterprozessfreundliche Ausgabe wünschen.
• Sie interaktiv vom Terminal aus debuggen.

Installation

Voraussetzungen

1. macOS – Safari MCP ist nur für macOS verfügbar.
2. Safari – bereits auf macOS installiert.
3. Node.js 18+ – brew install node oder von https://nodejs.org/
4. Python 3.10+
5. Apple Events für Safari aktivieren: Safari → Entwickeln → JavaScript von Apple Events erlauben

CLI installieren

cd safari/agent-harness
pip install -e .

Der erste tool-Aufruf lädt das safari-mcp npm-Paket herunter (einmalig, einige MB).

Befehlsstruktur

Das CLI hat 5 Hauptbefehle:

Befehl	Zweck
tool	Eines der 84 Tools von safari-mcp aufrufen (dynamisch, schemagesteuert)
tools	Das gebündelte Tool-Register inspizieren (list, describe, count)
raw	Notausstieg – ein Tool mit vollem Namen und rohen JSON-Argumenten aufrufen
session	In-Memory-Sitzungszustand (letzte URL, aktueller Tab)
repl	Interaktive REPL (Standard, wenn kein Unterbefehl angegeben wird)

Anwendungsbeispiele

Die Tool-Oberfläche entdecken

# Anzahl der Tools (Gesundheitscheck – muss mit den registrierten Tools von safari-mcp übereinstimmen)
cli-anything-safari tools count
# → 84

# Alle Tools auflisten
cli-anything-safari tools list
cli-anything-safari tools list --filter click   # nach Teilzeichenkette filtern

# Vollständiges Schema für ein Tool (JSON oder menschenlesbares Format)
cli-anything-safari tools describe safari_scroll
cli-anything-safari --json tools describe safari_click

Ein Tool aufrufen (schemagesteuert)

# Navigieren
cli-anything-safari tool navigate --url https://example.com

# Einen Snapshot erstellen (Screenshot vorzuziehen – strukturierter Text mit Referenz-IDs)
cli-anything-safari --json tool snapshot

# Nach Referenz klicken (Referenzen stammen aus dem Snapshot; sie verfallen beim nächsten Snapshot!)
cli-anything-safari tool click --ref 0_5

# Nach Selektor oder sichtbarem Text klicken
cli-anything-safari tool click --selector "#submit"
cli-anything-safari tool click --text "Anmelden"

# Ein Feld ausfüllen
cli-anything-safari tool fill --selector "#email" --value "[email protected]"

# In eine Richtung/um einen Betrag scrollen (NICHT x/y – beachten Sie das Schema!)
cli-anything-safari tool scroll --direction down --amount 500

# Ein Element auf ein anderes ziehen
cli-anything-safari tool drag \
    --source-selector ".card" \
    --target-selector ".trash"

# Screenshot – gibt base64-JPEG in stdout zurück. Dekodieren mit:
cli-anything-safari --json tool screenshot --full-page \
    | python3 -c "import sys,json,base64; \
        d=json.load(sys.stdin); \
        open('/tmp/shot.jpg','wb').write(base64.b64decode(d['data']))"

# Als PDF speichern (dieser Befehl schreibt direkt auf die Festplatte)
cli-anything-safari tool save-pdf --path /tmp/page.pdf

# JavaScript ausführen (Achtung: Der Parameter heißt --script, nicht --code)
cli-anything-safari tool evaluate --script "document.title"

Navigieren und Lesen in einem Durchgang

cli-anything-safari --json tool navigate-and-read --url https://example.com

Massenhaftes Ausfüllen von Formularen

safari_fill_form erwartet ein Array von {selector, value}-Objekten. Übergeben Sie es als JSON-String:

cli-anything-safari tool fill-form --fields '[
  {"selector": "#email",    "value": "[email protected]"},
  {"selector": "#password", "value": "hunter2"}
]'

Führen Sie cli-anything-safari tools describe safari_fill_form aus, um das genaue Schema zu sehen, einschließlich aller neuen Felder, die safari-mcp upstream hinzufügt.

Netzwerküberwachung

cli-anything-safari tool start-network-capture
cli-anything-safari tool navigate --url https://example.com
cli-anything-safari --json tool network
cli-anything-safari tool performance-metrics

Speicher

cli-anything-safari tool get-cookies
cli-anything-safari tool set-cookie --name session --value abc123 --domain example.com
cli-anything-safari tool local-storage --key theme
# export-storage gibt JSON an stdout zurück – kein --path-Argument. In eine Datei pipen:
cli-anything-safari --json tool export-storage > /tmp/storage.json

Roher JSON-Notausstieg

Wenn Sie ein komplexes, verschachteltes Objekt übergeben müssen oder das CLI von einem vorgefertigten JSON-Blob aus steuern möchten:

cli-anything-safari raw safari_evaluate \
    --json-args '{"code":"[...document.querySelectorAll(\"a\")].map(a => a.href)"}'

Interaktive REPL

cli-anything-safari

Der REPL-Banner gibt den absoluten Pfad zu dieser SKILL.md aus, damit Agenten ihre Fähigkeiten selbst entdecken können.

JSON-Ausgabe

Alle Befehle unterstützen --json als globales Flag:

cli-anything-safari --json tool snapshot
cli-anything-safari --json tool list-tabs
cli-anything-safari --json tools list

Zustandsverwaltung

Das CLI verwaltet einen kleinen In-Memory-Zustand nur für die REPL-Anzeige:

• last_url – letzte URL, zu der das CLI navigiert ist (aktualisiert nach jedem erfolgreichen tool navigate, tool navigate-and-read oder tool new-tab)
• current_tab_index – letzter bekannter aktiver Tab-Index

Es gibt keine persistente Sitzung, kein Rückgängig/Wiederholen, kein Dokumentmodell. Jeder CLI-Aufruf beginnt mit einem frischen Zustand. Safari MCP selbst ist zustandslos pro Aufruf: Jeder tool-Befehl startet einen neuen npx safari-mcp-Unterprozess, führt die Aktion aus und beendet sich. Dies ist eine bewusste Designentscheidung; siehe HARNESS.md und TEST.md für die Begründung der Abweichung vom üblichen Rückgängig/Wiederholen-Muster.

Ausgabeformate

Alle Befehle unterstützen zwei Ausgabemodi:

• Menschenlesbar (Standard): eingerückter Schlüssel-Wert-Text für dict-Ergebnisse, Aufzählungslisten für Arrays, ansonsten Klartext
• Maschinenlesbar (--json-Flag): strukturiertes JSON für den Agentenkonsum

# Menschliche Ausgabe
cli-anything-safari tool snapshot

# JSON-Ausgabe für Agenten
cli-anything-safari --json tool snapshot
cli-anything-safari --json tools list
cli-anything-safari --json tools describe safari_click

Für KI-Agenten

Bei programmatischer Verwendung dieses CLIs:

1. Verwenden Sie immer das --json-Flag für analysierbare Ausgabe.
2. Überprüfen Sie die Rückgabecodes – 0 für Erfolg, ungleich Null für Fehler (URL-Validierungsfehler, MCP-Aufruffehler, ungültige JSON-Argumente).
3. Analysieren Sie stderr auf Fehlermeldungen; verwenden Sie stdout für Daten.
4. Dateibezogene Tools haben inkonsistente Pfadargumentnamen – überprüfen Sie immer zuerst tools describe <name>:
   • tool save-pdf --path /tmp/x.pdf
   • tool upload-file --selector ... --file-path /tmp/x.txt (Achtung: --file-path, nicht --path)
   • tool export-storage – kein Pfadargument; JSON-Ausgabe in eine Datei pipen
   • tool import-storage --path /tmp/x.json
   • tool screenshot / screenshot-element – geben base64 in der JSON-Antwort zurück, kein Pfadargument (selbst dekodieren)
5. Snapshot vor Klick – Referenzen aus tool snapshot verfallen beim nächsten Snapshot. Immer Snapshot → Referenz finden → Klick in kurzer Abfolge.
6. Tools über tools list entdecken – das gebündelte Register ist die maßgebliche Quelle dafür, was verfügbar ist. Härten Sie keine Toolnamen ein, die sich upstream ändern könnten.
7. Verwenden Sie tools describe <name>, um das genaue Schema (erforderliche Argumente, Aufzählungsoptionen, JSON-typisierte Argumente) zu lernen, bevor Sie einen Aufruf konstruieren. Gehen Sie niemals von Parameternamen aus der Beschreibung aus – zum Beispiel akzeptiert safari_evaluate --script (nicht --code), obwohl die Beschreibung "JavaScript code to execute" lautet.

Agentspezifische Anleitung

Das richtige Tool finden

Verwenden Sie die Introspektionsbefehle. Das CLI garantiert eine 1:1-Abbildung des MCP-Servers:

# Alle klickbezogenen Tools finden
cli-anything-safari tools list --filter click

# Vollständiges Schema abrufen (einschließlich jedes Arguments mit Typ, Beschreibung,
# erforderlich/optional, Aufzählungsoptionen, Standardwerten)
cli-anything-safari --json tools describe safari_click

Tool-Auswahlstrategie

1. tool snapshot vor tool screenshot – strukturierter Text mit Referenz-IDs ist um Größenordnungen günstiger und enthält die für Klicks benötigten Referenzen.
2. tool click --ref vor tool click --selector – Referenzen sind innerhalb eines einzelnen Snapshots stabil, Selektoren können spröde sein.
3. tool navigate-and-read vor navigate + read-page – spart einen Durchgang.
4. tool click-and-read vor click + read-page – spart einen Durchgang.
5. tool native-click nur, wenn ein normaler Klick mit 405/403 fehlschlägt (WAF-Blöcke, G2, Cloudflare) – es bewegt den Cursor physisch.

Referenzen verfallen

Referenzen aus tool snapshot verfallen, wenn Sie einen neuen Snapshot erstellen:

• Erster Snapshot: Referenzen 0_1, 0_2, 0_3...
• Zweiter Snapshot: Referenzen 1_1, 1_2, 1_3...

Immer Snapshot → Klick in kurzer Abfolge. Im Zweifelsfall erneut einen Snapshot erstellen.

Tab-Besitz-Sicherheit

Safari MCP verfolgt den Tab-Besitz pro Sitzung. Tools, die einen Tab modifizieren (navigieren, klicken, ausfüllen), sind auf Tabs blockiert, die die Sitzung nicht geöffnet hat. Beginnen Sie immer mit tool new-tab --url ..., um auf einer bestimmten Seite zu arbeiten.

Fehlerbehandlung

Häufige Fehler:

• npx not found → Node.js 18+ installieren
• safari-mcp package not found on npm registry → Netzwerk prüfen
• Not macOS – Das Tool ist nur für macOS verfügbar
• AppleScript denied → "JavaScript von Apple Events erlauben" in Safari → Entwickeln aktivieren
• Blocked URL scheme: file – URL-Validierung hat die Eingabe abgelehnt (absichtlich)

URL-Validierung

Das CLI validiert URLs, bevor es sie an safari_navigate, safari_navigate_and_read und safari_new_tab übergibt. Blockierte Schemata: file, javascript, data, vbscript, about, chrome, safari, webkit, x-apple und andere browserinterne Schemata. Der raw-Befehl erzwingt dies ebenfalls für Navigationstools.

Warnung zu mehreren Sitzungen

Safari MCP erzwingt eine einzelne aktive Sitzung, indem es veraltete Node.js-Prozesse, die älter als 10 Sekunden sind, beendet. Wenn Sie zwei CLI-Instanzen gleichzeitig ausführen, wird eine die Backend-Instanz der anderen beenden. Es gibt derzeit keinen Daemon-Modus – für latenzempfindliche Workflows steuern Sie das CLI über ein langlebiges Python-Skript, das cli_anything.safari.utils.safari_backend.call() direkt importiert, um das erneute Starten des Unterprozesses bei jedem Aufruf zu vermeiden.

Links

• Safari MCP GitHub
• Safari MCP auf npm
• CLI-Anything
• MCP-Backend-Muster-Anleitung

Sicherheitsaspekte

URL-Validierung

Alle Navigationstools (tool navigate, tool navigate-and-read, tool new-tab und raw safari_navigate*) leiten das url-Argument durch utils/security.py, das gefährliche Schemata blockiert und optional private Netzwerke blockiert (setzen Sie CLI_ANYTHING_SAFARI_BLOCK_PRIVATE=1).

Tab-Isolation

Safari MCP erzwingt upstream den Tab-Besitz pro Sitzung – Tools können nicht auf Tabs operieren, die die Sitzung nicht geöffnet hat.

Profilisolation

Setzen Sie die Umgebungsvariable SAFARI_PROFILE, um ein separates Safari-Profil für die Automatisierung zu verwenden:

export SAFARI_PROFILE="Automation"
cli-anything-safari tool navigate --url https://example.com

Dies hält Cookies/Anmeldungen/Verlauf vom Hauptbrowsing des Benutzers getrennt.

JavaScript-Ausführung

tool evaluate und tool run-script führen beliebiges JavaScript im Seitenkontext aus. Behandeln Sie nicht vertrauenswürdige Eingaben mit derselben Sorgfalt wie jeden anderen Pfad zur dynamischen Codeausführung.

Zwischenablage

tool clipboard-read und tool clipboard-write greifen auf die Systemzwischenablage zu. Seien Sie vorsichtig, wenn Sie innerhalb einer aktiven Benutzersitzung laufen – das Überschreiben der Zwischenablage mitten in einer Aufgabe ist störend.

Neugenerieren des Tool-Registers

Wenn Sie safari-mcp aktualisieren, generieren Sie das gebündelte Schema neu:

python scripts/extract_tools.py \
    "$(npm root -g)/safari-mcp/index.js" \
    cli_anything/safari/resources/tools.json

Der Paritätstest (test_parity.py) fixiert die erwartete Tool-Anzahl; aktualisieren Sie ihn, wenn sich die Upstream-Tool-Liste ändert.

Weitere Informationen

• Vollständige Dokumentation: cli_anything/safari/README.md im Paket
• Testabdeckung: cli_anything/safari/tests/TEST.md im Paket
• Architekturanalyse: safari/agent-harness/SAFARI.md
• Methodik: cli-anything-plugin/HARNESS.md
• MCP-Backend-Muster: cli-anything-plugin/guides/mcp-backend.md

Version

1.0.0 – Ziel: safari-mcp 2.7.8 (84 Tools). Gebündeltes Tool-Register wird über scripts/extract_tools.py neu generiert, wenn safari-mcp aktualisiert wird.