Overview
What MacFly is, why it pairs Rust with AppleScript/JXA, and how the documentation is organized.
MacFly is a local, model-independent Rust CLI and stdio MCP server that
puts a deterministic execution layer and security firewall between AI
agents (or shell workflows) and your personal macOS data:
- Apple Notes: hierarchical folder overview, cleanup audit, search, read with fidelity guard, and lossless batch moves.
- Apple Mail: account & mailbox overview, direct signature lookup from Apple Mail, search, quote-trimmed reading, and safe draft creation.
- Apple Calendar & Reminders: upcoming events, open/overdue reminders,
and a unified
daily-briefcontext pack across all four apps.
Core design principles
- Deterministic Rust core, minimal macOS boundary: All security, policy,
DLP redaction, HTML normalization, hashing, and journaling logic is pure
Rust. macOS automation happens through static, embedded JXA scripts
receiving JSON over
stdin. - Security on both sides (Read & Write): Most automation tools only guard writes (if at all). MacFly protects reads via profile scopes and automatic DLP redaction, and writes via tamper-evident SHA-256 plans and interactive approval.
- Single Point of Truth: One central
~/.config/macfly/config.jsonfor scopes and DLP rules. Email accounts stay in Apple Mail, and email signatures are read straight from Apple Mail instead of being duplicated. - Honest guarantees: Operations declare their risk level (
low,medium,high) and reversibility (reversible,best_effort,irreversible), and rich Apple Notes are explicitly protected against destructive edits.
Where to go next
- Getting Started: Build, permissions, config schema, and everyday CLI commands.
- Plans & Workflows: Full
reference for
Plan → Inspect → Approve → Applyand all supported mutations. - Migrations & Backups: Two-way pipelines between Apple apps and Markdown, CSV, JSON, JSONL, and HTML.
- Cleaning Up Apple Notes: Structure-agnostic 4-phase field guide & real-world Apple Notes edge cases.
- Apple Shortcuts & Automation:
Allowlist-gated
shortcuts runfor Focus modes, HomeKit scenes, and App Intents. - MCP & AI Agents: Connecting Claude Desktop, Cursor, Codex, or custom agents safely.
- Why Rust + AppleScript/JXA: Architectural rationale for determinism, maintainability, and zero SDK drift.
- Security Model: Full threat model, DLP rules, prompt-injection defense, and trust boundaries.