cli-anything-safari

cli-anything-safari

macOS 上の Safari ブラウザ自動化のためのコマンドラインインターフェースです。safari-mcp Node.js MCP サーバーを Python Click CLI でラップしています。

機能の同等性は保証されています。 すべての Click コマンドは、safari-mcp のツールスキーマ(resources/tools.json としてバンドル)から自動的に生成されます。84 個すべてのツールに、MCP サーバーが期待する正確な引数名と型でアクセスできます。

この CLI をいつ使うか

CLI の呼び出しごとに新しいサブプロセスが起動されるため、呼び出しごとにオーバーヘッドがあります。お使いのエージェントが MCP をネイティブに扱える場合(Claude Code、Cursor、Cline など)、MCP stdio 経由で safari-mcp を直接使うほうが高速です。

この CLI を使うのは次の場合です:

• お使いのエージェントフレームワークが MCP を扱えない場合(Codex CLI、GitHub Copilot CLI、カスタムスクリプト、古いエージェントフレームワーク)。
• bash からブラウザ自動化をスクリプト化したい場合 — cli-anything-safari --json tool snapshot | jq '...'。
• CI/CD で実行し、cron 可能でサブプロセスに適した出力が欲しい場合。
• Terminal から対話的にデバッグする場合。

インストール

前提条件

1. macOS — Safari MCP は macOS 専用です。
2. Safari — macOS にすでにインストールされています。
3. Node.js 18+ — brew install node または https://nodejs.org/ から。
4. Python 3.10+
5. Safari の Apple Events を有効化: Safari → Develop → Allow JavaScript from Apple Events

CLI のインストール

cd safari/agent-harness
pip install -e .

最初の tool 呼び出しで safari-mcp npm パッケージがダウンロードされます(1 回限り、数 MB)。

コマンド構造

CLI には 5 つのトップレベルコマンドがあります:

Command	Purpose
tool	safari-mcp の 84 個のツールのいずれかを呼び出す(動的、スキーマ駆動)
tools	バンドルされたツールレジストリを検査する(list、describe、count)
raw	エスケープハッチ — 完全名と生の JSON 引数でツールを呼び出す
session	インメモリのセッション状態(最後の URL、現在のタブ)
repl	対話型 REPL(サブコマンドを指定しない場合のデフォルト)

使用例

ツールサーフェスを発見する

# Count of tools (sanity check — must match safari-mcp's registered tools)
cli-anything-safari tools count
# → 84

# List every tool
cli-anything-safari tools list
cli-anything-safari tools list --filter click   # filter by substring

# Full schema for one tool (JSON or human format)
cli-anything-safari tools describe safari_scroll
cli-anything-safari --json tools describe safari_click

ツールを呼び出す(スキーマ駆動)

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

# Take a snapshot (preferred over screenshot — structured text with ref IDs)
cli-anything-safari --json tool snapshot

# Click by ref (refs come from snapshot; they expire on the next snapshot!)
cli-anything-safari tool click --ref 0_5

# Click by selector or visible text
cli-anything-safari tool click --selector "#submit"
cli-anything-safari tool click --text "Log in"

# Fill a field
cli-anything-safari tool fill --selector "#email" --value "[email protected]"

# Scroll by direction/amount (NOT x/y — note the schema!)
cli-anything-safari tool scroll --direction down --amount 500

# Drag one element onto another
cli-anything-safari tool drag \
    --source-selector ".card" \
    --target-selector ".trash"

# Screenshot — returns base64 JPEG in stdout. Decode with:
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']))"

# Save as PDF (this one writes to disk directly)
cli-anything-safari tool save-pdf --path /tmp/page.pdf

# Evaluate JavaScript (note: parameter is --script, not --code)
cli-anything-safari tool evaluate --script "document.title"

1 回のラウンドトリップでナビゲートして読み取る

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

フォーム入力(一括)

safari_fill_form は {selector, value} オブジェクトの配列を受け取ります。JSON 文字列として渡してください:

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

cli-anything-safari tools describe safari_fill_form を実行すると、safari-mcp が上流で追加する新しいフィールドを含む正確なスキーマを確認できます。

ネットワーク監視

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

ストレージ

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 returns JSON to stdout — no --path arg. Pipe to a file:
cli-anything-safari --json tool export-storage > /tmp/storage.json

生の JSON エスケープハッチ

複雑なネストされたオブジェクトを渡す必要がある場合や、事前に構築された JSON blob から CLI を操作したい場合:

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

対話型 REPL

cli-anything-safari

REPL のバナーはこの SKILL.md への絶対パスを出力するので、エージェントは機能を自己発見できます。

JSON 出力

すべてのコマンドはグローバルフラグとして --json をサポートします:

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

状態管理

CLI は REPL 表示専用に少量のインメモリ状態を保持します:

• last_url — CLI が最後にナビゲートした URL(成功した tool navigate、tool navigate-and-read、または tool new-tab のたびに更新されます)
• current_tab_index — 最後に認識されたアクティブなタブのインデックス

永続セッションはありません。undo/redo もドキュメントモデルもありません。CLI の呼び出しごとに新しい状態で開始します。Safari MCP 自体は呼び出しごとにステートレスです。各 tool コマンドは新しい npx safari-mcp サブプロセスを起動し、アクションを実行して終了します。これは意図的な設計上の選択です。標準の undo/redo パターンからの逸脱の理由については HARNESS.md と TEST.md を参照してください。

出力形式

すべてのコマンドは 2 つの出力モードをサポートします:

• 人間が読みやすい形式(デフォルト): dict の結果にはインデントされたキーと値のテキスト、配列には箇条書き、それ以外はプレーンテキスト
• 機械が読み取れる形式(--json フラグ): エージェントが利用するための構造化 JSON

# Human output
cli-anything-safari tool snapshot

# JSON output for agents
cli-anything-safari --json tool snapshot
cli-anything-safari --json tools list
cli-anything-safari --json tools describe safari_click

AI エージェント向け

この CLI をプログラムから利用する場合:

1. 常に --json フラグを使用してください — 解析可能な出力を得るためです。
2. リターンコードを確認してください — 0 は成功、非ゼロはエラーです（URL 検証の失敗、MCP 呼び出しの失敗、不正な JSON 引数）。
3. エラーメッセージは stderr を解析してください; データには stdout を使用します。
4. ファイルを扱うツールはパス引数の名前が一貫していません — 常に 最初に tools describe <name> を確認してください:
   • tool save-pdf --path /tmp/x.pdf
   • tool upload-file --selector ... --file-path /tmp/x.txt (注意: --file-path であり、--path ではありません)
   • tool export-storage — パス引数はありません; JSON 出力をファイルにパイプしてください
   • tool import-storage --path /tmp/x.json
   • tool screenshot / screenshot-element — JSON レスポンスで base64 を 返します; パス引数はありません（自分でデコードしてください）
5. クリックの前にスナップショット — tool snapshot の ref は 次のスナップショットで失効します。常にスナップショット → ref を検索 → クリックを 連続して行ってください。
6. tools list でツールを発見してください — 同梱のレジストリが 利用可能なものの信頼できる情報源です。上流で変更される可能性のある ツール名をハードコードしないでください。
7. tools describe <name> を使用して、呼び出しを構築する前に正確なスキーマ （必須引数、enum の選択肢、JSON 型の引数）を確認してください。 説明からパラメータ名を推測しないでください — 例えば、 safari_evaluate は説明に「実行する JavaScript コード」と書かれていても --script を取ります（--code ではありません）。

エージェント固有のガイダンス

適切なツールの見つけ方

イントロスペクションコマンドを使用してください。CLI は MCP サーバーを 1:1 で反映することが保証されています:

# Find all click-related tools
cli-anything-safari tools list --filter click

# Get the full schema (including every argument with type, description,
# required/optional, enum choices, defaults)
cli-anything-safari --json tools describe safari_click

ツール選択の戦略

1. tool screenshot より tool snapshot — ref ID 付きの構造化テキスト は桁違いに安価で、クリックに必要な ref を保持しています。
2. tool click --selector より tool click --ref — ref は 単一のスナップショット内で安定していますが、セレクタは壊れやすい可能性があります。
3. navigate + read-page より tool navigate-and-read — 1 回の 往復を節約できます。
4. click + read-page より tool click-and-read — 1 回の往復を節約できます。
5. tool native-click は通常のクリックが 405/403 で失敗した場合のみ （WAF ブロック、G2、Cloudflare） — カーソルを物理的に移動します。

Ref の失効

tool snapshot の ref は新しいスナップショットを取得すると失効します:

• 最初のスナップショット: ref 0_1、0_2、0_3...
• 2 回目のスナップショット: ref 1_1、1_2、1_3...

常にスナップショット → クリックを連続して行ってください。不明な場合は、再度スナップショットを取得してください。

タブ所有権の安全性

Safari MCP はセッションごとにタブの所有権を追跡します。タブを変更するツール （navigate、click、fill）は、そのセッションが開いていないタブではブロックされます。 特定のページを操作するには、常に tool new-tab --url ... から始めてください。

エラーハンドリング

一般的なエラー:

• npx not found → Node.js 18+ をインストールしてください
• safari-mcp package not found on npm registry → ネットワークを確認してください
• Not macOS → harness は macOS 専用です
• AppleScript denied → Safari で「Apple Events からの JavaScript を許可」を有効にしてください → 開発
• Blocked URL scheme: file → URL 検証が入力を拒否しました（仕様によるものです）

URL 検証

CLI は URL を safari_navigate、 safari_navigate_and_read、safari_new_tab に渡す前に検証します。ブロックされるスキーム: file、javascript、data、vbscript、about、chrome、safari、 webkit、x-apple、その他のブラウザ内部スキーム。raw コマンドもナビゲーションツールに対してこれを同様に適用します。

マルチセッションの警告

Safari MCP は 10 秒より古い古い Node.js プロセスを kill することで、単一のアクティブセッションを強制します。2 つの CLI インスタンスを同時に実行すると、 一方がもう一方のバックエンドを kill します。現在デーモン モードはありません — レイテンシに敏感なワークフローでは、 cli_anything.safari.utils.safari_backend.call() を直接 import する 長時間実行の Python スクリプトから CLI を操作して、呼び出しごとにサブプロセスを 再生成するのを避けてください。

リンク

• Safari MCP GitHub
• Safari MCP on npm
• CLI-Anything
• MCP Backend Pattern Guide

セキュリティに関する考慮事項

URL 検証

すべてのナビゲーションツール(tool navigate、tool navigate-and-read、tool new-tab、および raw safari_navigate*)は、url 引数を utils/security.py に通します。このモジュールは危険なスキームをブロックし、オプションでプライベートネットワークをブロックします(CLI_ANYTHING_SAFARI_BLOCK_PRIVATE=1 を設定)。

タブの分離

Safari MCP はアップストリームでセッションごとのタブの所有権を強制します — ツールは、そのセッションが開いていないタブを操作できません。

プロファイルの分離

自動化用に別の Safari プロファイルを使用するには、SAFARI_PROFILE 環境変数を設定します:

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

これにより、Cookie、ログイン情報、履歴がユーザーのメインブラウジングから分離されます。

JavaScript の実行

tool evaluate と tool run-script は、ページコンテキストで任意の JavaScript を実行します。信頼できない入力は、動的コード実行パスと同様に慎重に扱ってください。

クリップボード

tool clipboard-read と tool clipboard-write はシステムのクリップボードにアクセスします。ユーザーのアクティブなセッション内で実行する場合は注意してください — タスクの途中でクリップボードを上書きすると支障をきたします。

ツールレジストリの再生成

safari-mcp をアップグレードした場合は、バンドルされたスキーマを再生成してください:

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

パリティテスト(test_parity.py)は、期待されるツール数を固定しています。アップストリームのツールリストが変更されたら、これを更新してください。

詳細情報

• 完全なドキュメント: パッケージ内の cli_anything/safari/README.md
• テストカバレッジ: パッケージ内の cli_anything/safari/tests/TEST.md
• アーキテクチャ分析: safari/agent-harness/SAFARI.md
• 方法論: cli-anything-plugin/HARNESS.md
• MCP バックエンドパターン: cli-anything-plugin/guides/mcp-backend.md

バージョン

1.0.0 — safari-mcp 2.7.8(84 ツール)を対象としています。バンドルされたツールレジストリは、safari-mcp のアップグレード時に scripts/extract_tools.py を介して再生成されます。