- Thursday
pyapple mail reply-draft --id 102917 --body-file reply.md
```
`--subject` still works and is a substring match; when it matches more than one
message the reply is refused, before anything is composed, and the candidates are
printed with their ids.
### Drafting mail
New in 1.4.0. `mail draft` files the message into the sending account's Drafts
and **opens no window**:
```bash
pyapple mail draft --to alex@example.com --subject "Re: Thursday" \
--body "Works for me." --from you@example.com
```
```
Draft to alex@example.com saved in Drafts. Nothing was sent.
```
`--show` opts into a visible compose window instead, and it is a **one-way door**:
a compose window Mail has opened cannot be closed again from AppleScript, so
dismissing it is yours to do by hand. That is why filing quietly is the default.
`--from` is worth setting. Without it Mail picks its own default account, which
on a machine with several is a choice the caller cannot see and the recipient
can.
### Long bodies, and formatted ones
On `mail send`, `mail draft`, `mail reply`, `mail reply-draft`, `mail forward` and
`mail forward-draft`.
`--body "$(cat draft.md)"` was the only way to write a real email through this,
and it is two problems: your shell re-expands what it interpolates, so a body
containing a backtick or a `$(` runs as a command, and `ARG_MAX` caps how long
the message can be. Both are now avoidable:
```bash
pyapple mail draft --to alex@example.com --subject "Thursday" --body-file reply.md
pyapple mail reply-draft --id 102917 --body - <<'EOF'
Works for me. I have put the figures in the attached.
EOF
```
`--body-file -` also reads standard input. `--body` and `--body-file` are
mutually exclusive and passing both is exit `2`: two sources for one value is a
question, and answering it quietly is how the wrong text ends up in somebody's
mail.
`--html` and `--html-file` compose a **formatted** body — bold, italics, sizes,
links. There is no scripting route to rich text on macOS (`html content` is
documented by Apple as doing nothing), so it goes on the pasteboard with a
`public.html` flavour and is pasted into the compose window, which is why it
needs the [Accessibility grant](#permissions-setup). `--body` is its plain-text
alternative and is derived from the markup if you leave it out; it is never
optional underneath, because it is what a reader with images off sees.
```bash
pyapple mail draft --to alex@example.com --subject "Thursday" \
--html 'Works for me — 10:30 in the usual place.
'
```
On `send` and `draft` the formatting **degrades**: without Accessibility, or if
the caret cannot be proved to be in the message body, the message is composed as
plain text and the result says the formatting was not applied. There is always a
correct plain body to fall back to there, because `content` works on a new
outgoing message. A reply has no such fallback and is refused instead.
Your clipboard is snapshotted before any of this — every item, every flavour, not
a transcription — and put back afterwards, whatever happens in between. The
result reports whether it went back rather than assuming so.
## Permission Policy
Both front ends read one policy object, so a restriction set for the MCP server
also binds the CLI and vice versa. One string expresses it, and it is identical
in an MCP config's `env` block and in a shell:
```json
{
"mcpServers": {
"pyapple": {
"command": "pyapple-mcp",
"env": {
"PYAPPLE_PERMS": "mail=read+draft,calendar=all,messages=read,*=read"
}
}
}
}
```
```bash
export PYAPPLE_PERMS="mail=read+draft,calendar=all,messages=read,*=read"
```
The grammar is `tool=class[+class…]`, comma separated. `all` is every class,
`none` removes the tool entirely, and `*` sets what happens to tools nobody
named.
> **A policy with no `*` narrows only the tools it names. Everything else keeps
> every operation.**
>
> ```bash
> PYAPPLE_PERMS="mail=read" # mail is read-only. The other nine are untouched
> PYAPPLE_PERMS="mail=read,*=read" # all ten are read-only
> PYAPPLE_PERMS="mail=read,*=none" # mail is read-only and the other nine are gone
> ```
>
> This is deliberate, and it is the single most misread thing in this file —
> two people in a row reported the first line as a bug. Writing `mail=read` says
> something about mail and nothing about your calendar, and a policy parser that
> silently disarmed the calendar would be removing a capability you never asked
> it to remove. **If you want a narrow default, say so with `*`.**
> `pyapple perms` prints which tools a policy left alone, so you never have to
> infer it from the table.
### The four classes
| Class | What it covers |
| --- | --- |
| `read` | changes nothing |
| `write` | changes this Mac, privately |
| `draft` | composes without transmitting |
| `send` | leaves the machine, reaches a person, irreversible |
The line that matters here is **not** read versus write. It is *"changes my Mac"*
against *"leaves my Mac and reaches another person"*. Deleting a note is private
and recoverable from the Trash; sending an email is neither, and no amount of
subsequent care retracts it. Those two are both writes and they belong in
different classes, which is why there are four rather than two.
**`messages` has no `draft` class**, and this surprises people. iMessage exposes
no draft object to AppleScript — there is no way to compose a message and leave
it unsent — so `messages=draft` grants nothing at all, which is the correct
amount. For that one tool the choice really is read or send.
**One `read` operation can still write, and it is named here rather than left to
be found.** `mail unread` accepts `--mark-read`, which clears the unread flag on
what it returns. The operation is classified `read` because that is its purpose
and the flag defaults to off — but it means a `mail=read` grant can change that
one piece of state. Enforcing it would need a per-argument gate, which the policy
does not have.
**`shortcuts run` is `send`, and it transmits nothing by itself.** It is the one
place a class is assigned from what an operation *could* do rather than from what
it does, because macOS gives no way to read a shortcut's actions —
[see above](#a-shortcuts-actions-cannot-be-read-which-is-why-run-is-a-send). At
any lower class, `PYAPPLE_READ_ONLY=1` would permit arbitrary user code that can
mail a stranger, and the shorthand would stop meaning what it says.
Of the 88 operations, 43 are `read`, 35 are `write`, 3 are `draft`
(`mail draft`, `replyDraft`, `forwardDraft`) and 7 are `send`.
### Confirming a send before it goes
The policy answers *may this caller send at all*. It answers it once, from an
environment variable, for the whole life of the process — which is the right
shape for a grant and the wrong shape for a decision about one particular message
to one particular person. A model granted `mail=send` is granted every future
send, including the one nobody has read yet.
`PYAPPLE_CONFIRM_SENDS=1` is the other half. **Confirmation is a phase of the
send, not a second operation:** call a send with no token and nothing is sent —
the answer is a rendering of what *would* go, plus a single-use ticket to send
exactly that.
```bash
$ export PYAPPLE_CONFIRM_SENDS=1
$ pyapple messages send --to "+15550000000" --message "Hello there"; echo $?
Would send to +15550000000:
Hello there
**Nothing was sent.** This install requires sends to be confirmed. Show the above to the user; to send exactly it, repeat this call with --confirm-token=zMWFqAAIpRWJRvGE (good once, for 300s). Changing any part of the message invalidates the token.
0
$ pyapple messages send --to "+15550000000" --message "Hello there" \
--confirm-token zMWFqAAIpRWJRvGE
```
**Exit `0`, and `isError: false` over MCP.** Nothing failed and nothing is
pending: the caller asked what would happen, was told, and was handed the means to
go ahead. A caller that treats it as a failure has misread it. Under `--json` the
same fact is `sent: false` and `confirmation_required: true`, with
`confirm_token`, `expires_in_seconds` and `digest` beside it, so a script never
has to parse English to find the token.
**The binding is the point, not the pause.** A confirmation that only asks "are
you sure?" is theatre — the caller previews a polite note and then sends something
else. So the ticket carries a digest of the *resolved* payload: recipients after
lookup and handle normalisation, the subject, the body, the file actually on disk.
The second call recomputes that digest from the arguments it was given, and a
message that moved between the two is refused with the fields named, never their
values, because a refusal ends up in a log.
```bash
$ pyapple messages send --to "+15550000000" --message "Different text" \
--confirm-token zMWFqAAIpRWJRvGE; echo $?
error: This is not the message that was confirmed: to, body changed. Nothing was sent. Preview again and confirm the new message.
1
```
| Variable | Default | What it does |
| --- | --- | --- |
| `PYAPPLE_CONFIRM_SENDS` | off | `1`, `true`, `yes` or `on` requires a ticket for every gated send |
| `PYAPPLE_CONFIRM_TTL` | `300` | how many seconds a ticket is good for. A value that is not a number falls back to the default and says so on stderr — the only thing in this package that fails soft, and it is safe only because every direction the fallback could be wrong in is the tighter one |
| `PYAPPLE_STATE_DIR` | `~/.pyapple` | where tickets live, under `/consent`, created and enforced `0700` |
Six things are worth knowing before you rely on it:
- **Gated today:** `mail send`, `mail reply`, `mail forward` (only when it
delivers), `messages send`, `messages sendAttachment`. The `draft` operations
are not gated, because a confirmation for something that reaches nobody is a
ceremony with nothing behind it.
- **A ticket file never contains the message.** Only a digest. The body of a
message somebody is composing is the most private thing this package touches,
and writing it under `~/.pyapple` would put it somewhere no Apple app put it,
outside every store macOS gates. The second call supplies the payload again, so
nothing has to be remembered.
- **It can only tighten.** There is no flag that turns the requirement off, for
the same reason `--perms` can only narrow: the first argument a prompt-injected
model would learn to pass is the one that disables the gate.
- **A ticket is good once, and it is spent before the send is attempted.** A
failed send does not give it back — that is `utils/applescript.py`'s argument
again, since a send that reported failure may already have left, and handing the
ticket back to be retried is how one approval becomes two messages. The cost is
a re-preview after a genuine failure, which is the direction to be wrong in.
- **An attachment is bound by resolved path, size and mtime, not by content
hash.** Hashing a 40MB video on every preview, to close a window in which
somebody can already write to your disk, is a bad trade. Because it is the
*resolved* path, a symlink repointed between the two calls is caught.
- **It does not stop a caller that previews and sends in the same breath**
without showing anybody. Nothing in a protocol can. What it buys is that a
client which does surface previews is now able to, and that the surfaced thing
and the sent thing are provably the same.
### Narrowing for one run
`--perms` on the command line **intersects** with the environment. It can only
take away, never grant:
```bash
# PYAPPLE_PERMS="*=read" is set; this does not give mail back
pyapple --perms "mail=all" perms
```
So someone who reached a terminal cannot undo the restriction an MCP
configuration put in place. `PYAPPLE_READ_ONLY=1` still works as the documented
shorthand for `*=read`, and it is applied first, so `PYAPPLE_PERMS` can only
narrow it further.
A malformed policy fails closed rather than failing open, and it is **exit 2** —
bad input, the same status as a bad command line, because the operation never
started. The message names the token it could not read *and which of the two
inputs it came from*:
```bash
$ pyapple --perms "mail=nonsense" mail accounts; echo $?
usage: --perms: 'mail=nonsense' names an unknown class 'nonsense'; the classes are: read, write, draft, send, plus 'all' and 'none'
2
$ PYAPPLE_PERMS="mail@read" pyapple perms; echo $?
usage: PYAPPLE_PERMS: 'mail@read' is not 'tool=class[+class…]'; the tools are: contacts, notes, messages, mail, reminders, calendar, maps, shortcuts, presence, doctor, or '*' for the rest
2
```
That holds on every entry point — `pyapple`, `python -m pyapple_mcp.cli`,
`--version`, and `pyapple perms` itself, which is the command you would type to
find out what is wrong. Nothing is printed on stdout: a half-written table is a
promise the command cannot keep.
The MCP server refuses to start for the same reason, with the same status, and
says so on stderr where a client's log will pick it up:
```
pyapple-mcp: not starting — PYAPPLE_PERMS cannot be read.
'mail@read' is not 'tool=class[+class…]'; the tools are: …
Fix PYAPPLE_PERMS in this server's "env" block, for example
"mail=read+draft,calendar=all,*=read", or remove it to allow everything.
```
There is no "could not understand, carrying on" path. A `--since` that fails open
returns too much data; a policy that fails open sends the email.
### Seeing what is in effect
The default is everything on — all **88** operations across the ten tools.
`*=read` leaves **43**. `pyapple perms` prints the effective policy and where
each part came from, which is the answer to the question that always follows a
refusal:
```bash
$ PYAPPLE_PERMS="mail=read+draft,calendar=all,messages=read,*=read" pyapple perms
Effective policy
contacts read search, lookup
notes read search, list, view, folders
messages read conversations, read, search, attachments, unread
mail read+draft unread, search, searchBodies, readMessage, thread, attachments, coverage, draft, replyDraft, forwardDraft, mailboxes, accounts
reminders read list, search, lists, open
calendar all search, list, calendars, free, coverage, create, reschedule, alarms, move, delete, open
maps read search, directions, listGuides
shortcuts read list, folders, describe, open
presence read snapshot, focus, app, idle, screen
doctor read report
From:
defaults all 10 tools, every operation
PYAPPLE_PERMS mail=read+draft,calendar=all,messages=read,*=read
```
That policy leaves **51** of the 88 — everything the assistant needs to read your
world, draft mail rather than send it, and run your calendar outright.
A policy with no `*` gets one more paragraph, naming the tools it decided
nothing about:
```bash
$ PYAPPLE_PERMS="mail=read" pyapple perms
Effective policy
contacts all search, lookup, add, addTo, rename, delete
…
From:
defaults all 10 tools, every operation
PYAPPLE_PERMS mail=read
No '*' entry, so the 9 tools the policy does not name keep
every operation: contacts, notes, messages, reminders, calendar, maps, shortcuts, presence, doctor.
Add '*=read' to narrow them, or '*=none' to remove them entirely.
```
Operations appear there under their canonical names, which is what a policy
string and the MCP schema both use. Fifteen are spelled with a hyphen on the
command line — `mail search-bodies`, `mail mark-read`, `mail reply-draft`,
`mail forward-draft`, `messages send-attachment`, `contacts add-to`,
`notes set-body`, `notes folder-create`, `notes folder-rename`,
`notes folder-delete`, `reminders list-create`, `reminders list-delete`,
`maps list-guides`, `maps create-guide` and `maps add-to-guide`. Both spellings
work as CLI subcommands for all of them. `readMessage` is the one that is not
merely rehyphenated: on the command line it is `pyapple mail read`.
On the server side a forbidden operation is removed from the tool's `operation`
enum, so a model cannot express it in the first place; on the CLI side it is
refused with exit `4`. Same policy, two enforcement points.
### What `tools/list` tells an MCP client
The tool annotations are **computed from the policy in force**, not hardcoded.
MCP annotates a *tool* while this package classifies an *operation*, and most of
these tools multiplex reads and writes behind one `operation` argument — so there
is no honest fixed answer to "is `mail` read-only?". Under `PYAPPLE_READ_ONLY=1`
it genuinely is, its enum says so, and `readOnlyHint` says so too; under a full
grant it does not. A hardcoded annotation would be wrong in one of those two
worlds, and the one it would be wrong in is the world where a client trusted it
and skipped a confirmation.
`openWorldHint` is true wherever a call can reach something that is not this Mac:
any tool retaining a `send`, plus `maps` in every policy, because its *reads*
geocode over the network. None of this is load-bearing for safety — a forbidden
operation is already unrepresentable — and these are hints a client may ignore.
They exist so that a client which does read them reaches the same decision this
package would.
## Development
### Local Setup
1. **Clone the repository**:
```bash
git clone https://github.com/54yyyu/pyapple-mcp.git
cd pyapple-mcp
```
2. **Install dependencies**:
```bash
pip install -e ".[dev]"
```
3. **Run the development server**:
```bash
python -m pyapple_mcp.server
```
4. **Or run the CLI from the source tree**, without installing the console
script:
```bash
python -m pyapple_mcp.cli --help
python -m pyapple_mcp.cli perms
```
### Running the tests
```bash
pytest
```
The suite builds its own Mail store in a temporary directory and reads nothing
of yours, so it needs no mailbox, no permissions and no network.
Two checks are worth knowing about if you add an operation. `tests/test_policy.py`
reads the operation list out of `server.py` and fails if it disagrees with
`policy.py`, so an operation with no permission class is caught when it is
written rather than when it is used. `tests/test_cli.py` then walks every leaf
the CLI parser accepts and asserts each lands on the correct side of the
read-only gate — which also catches a subcommand spelled differently from the
server's operation name, since the gate looks that name up in the policy and a
`send-message` where the server says `send` would be a write waved through.
### Testing with the MCP Inspector
```bash
npx @modelcontextprotocol/inspector pyapple-mcp
```
## Requirements
- **macOS 10.15+** (Catalina or later)
- **Python 3.10+**
- **Appropriate permissions** — see below. Fewer than you might expect: most of
this package now goes through system frameworks rather than through the apps
## Permissions Setup
These are macOS's own permissions — what the operating system will let the
process touch. They are a different thing from the
[Permission Policy](#permission-policy) above, which is what *you* choose to
allow out of what macOS has already granted. You need both: macOS decides
whether the mailbox can be opened at all, and `PYAPPLE_PERMS` decides what may
be done with it.
There are two kinds, and they are granted in different places:
**Privacy grants** — Contacts, Calendars, Reminders, and Full Disk Access for the
Mail and Messages databases. These cover almost everything, including every
`contacts`, `reminders` and `calendar` write, because those go through the
Contacts framework and EventKit rather than through the apps. Full Disk Access
also covers `presence focus`, which is the only presence operation that costs
anything; the other four read from a process holding no grant at all.
**`pyapple doctor report` is how you find out which of these you have.** It names
the missing grant per tool and where to click, it never prompts, and where it
cannot tell it says *undetermined* with the reason rather than guessing.
**An Accessibility grant** — new in 1.6.0, and load-bearing rather than
optional. `mail reply`, `mail reply-draft` and anything passing `--html` put the
body on the pasteboard and paste it into the compose window, because macOS
offers **no scripting route to the body of a reply and none to rich text at
all**: Mail's own dictionary describes `html content` as *"Does nothing at all
(deprecated)"*, and `content` is not a property of `outgoing message` — it works
on a new message and destroys the quoted original on a reply. Pasting needs
System Events to be allowed to send keystrokes.
Grant it in **System Settings → Privacy & Security → Accessibility**, to whatever
runs `pyapple` — your terminal, or your MCP client — and to *System Events* if it
is listed. Without it, a reply is **refused** rather than composed empty, and
`--html` on `send`/`draft` falls back to plain text and says so. Neither one
fails quietly, which is the whole reason this section exists.
**Automation grants** — *"control Mail"*, *"control Messages"*, *"control
Notes"*, *"control Calendar"*. These are the ones that pop up a dialog naming
another application. You need them only for what the table in
[Limits worth knowing](#almost-nothing-launches-an-app-any-more--but-mail-messages-and-notes-still-do)
lists: all of `notes`, mail's writes and its `mailboxes`, messages' `send`,
`sendAttachment` and `open`, `calendar open` and `create --invitees`, and
`reminders open`. Nothing in `contacts`, `maps`, `shortcuts`, `presence` or
`doctor` will ever ask.
The prompts are per-application, so granting them to Claude Desktop does not
grant them to your terminal. Running `pyapple` for the first time will prompt
again, on behalf of whichever terminal you ran it from.
## Troubleshooting
### Common Issues
**Permission Denied Errors**:
- Go to **System Settings > Privacy & Security**
- Grant access to the required applications
- Restart Claude Desktop
**Module Import Errors**:
- Ensure you're running on macOS
- Install PyObjC frameworks: `pip install pyobjc`
**AppleScript Execution Errors**:
- Check that the target applications are installed
- Verify automation permissions in System Settings
**Setup Issues**:
- Run `pyapple-mcp-setup --help` for setup options
- Check that pyapple-mcp is in your PATH: `which pyapple-mcp`
- Use `pyapple-mcp-setup --config-path /path/to/config` for custom config locations
### On the command line
**`refused: … is a 'write' operation` (exit `4`)**:
- Something narrowed the policy. `pyapple perms` prints what is in effect and
which setting produced it — an environment variable, a `--perms` on this
command line, or `--read-only`
- Remember that `--perms` can only take away. If the environment already set
`PYAPPLE_PERMS`, no flag will widen it
**`cannot read …` (exit `3`)**:
- This is macOS refusing, not the policy refusing. **Run `pyapple doctor report`**
— it names which grant is missing for that tool and where to click, and it
distinguishes a grant that is off from one it could not determine
- Check **System Settings > Privacy & Security** for the terminal you ran it
from, which is granted separately from Claude Desktop
**`Refused; edit it in Notes instead` on a note edit**:
- Not a bug. The note holds an image, attachment, link, heading or list, and
writing its body back would destroy that. See
[Notes editing refuses more than it accepts](#notes-editing-refuses-more-than-it-accepts)
**`Contacts will not save any change to …` (Cocoa error 134092)**:
- Also not a bug, and retrying will not help. A minority of cards refuse every
framework write, permanently. Edit that one card in the Contacts app
**A message you sent turning up in Drafts**:
- Expected, and it was still sent. Mail autosaves outgoing messages; see
[Every mail `send` leaves a copy in the sender's Drafts](#every-mail-send-leaves-a-copy-in-the-senders-drafts)
**`scan INCOMPLETE` from `search-bodies`**:
- The full line reads `N matches, scan INCOMPLETE: read the newest X of Y
candidates, stopped at --scan-limit X`, and a zero under it says nothing about
whether the term is in your mail — only that it was not found *yet*. The
complete form is `N matches, scanned all Y candidates`, and a zero under *that*
is an answer. In `--json` the flag is `scan_truncated`, and `total` is `null`
under a cut scan because the match count covers only what was reached. Both exit `0`: the
status answers "did the read run", and the completeness of the scan is carried
in the payload rather than in `$?`
- Narrow it with `--since` or `--account`, or raise `--scan-limit`. No setting
makes a body appear that was never downloaded — run `pyapple mail coverage` to
see which accounts have any
**An empty result you did not expect**:
- Check `$?` before believing it. A failed read exits non-zero and writes
nothing to stdout; a genuinely empty mailbox exits `0` and, under `--json`,
prints `{"results": [], "total": 0, "truncated": false, …}`. Never treat a
missing result as an empty one
- And check `truncated` before believing a *short* result. A read that was cut
says so there; `total` says how much it was cut from
**`usage: since must be an ISO 8601 timestamp …` (exit `2`)**:
- `--since` takes `2026-08-05` or `2026-08-05T09:00:00`, not prose. An
unparseable value is an error rather than a silently unfiltered result
### Logging
Both front ends send every log line to **stderr**, which is what keeps the CLI's
stdout carrying the result and only the result. The server logs at `INFO`; the
CLI logs at `WARNING`, so in normal use it is silent until something goes wrong.
```bash
pyapple mail unread 2>/dev/null # result only
pyapple mail unread >/dev/null # diagnostics only
```
There is no environment variable for verbose output. To see the traceback behind
an unexpected failure, lower the level in-process — `force=True` matters, since
importing the package configures logging first:
```bash
python -c "
import logging, sys
from pyapple_mcp.cli import main
logging.basicConfig(level=logging.DEBUG, stream=sys.stderr, force=True)
sys.exit(main(['mail', 'unread']))
"
```
`main()` returns the exit status rather than raising, which is also how the tests
drive a command without leaving the process.
## Architecture
```
pyapple-mcp/
├── pyapple_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server front end
│ ├── cli.py # command line front end
│ ├── handlers.py # the shared handler objects and the policy
│ ├── policy.py # permission classes, parsing and intersection
│ ├── consent.py # the two-phase send gate: tickets bound to a payload digest
│ ├── outcomes.py # one classifier for "did this fail", shared by both front ends
│ ├── setup_helper.py # setup and configuration helper
│ └── utils/
│ ├── __init__.py
│ ├── applescript.py # AppleScript execution
│ ├── calendar.py # Calendar, through EventKit
│ ├── contacts.py # Contacts, through CNContactStore
│ ├── doctor.py # which macOS grants this process holds, probed without prompting
│ ├── mail.py # Mail: reads from the Envelope Index, writes over Apple Events
│ ├── maps.py # Maps, through MapKit
│ ├── messages.py # Messages: reads from chat.db, sends over Apple Events
│ ├── notes.py # Notes, over Apple Events — the only route there is
│ ├── pasteboard.py # snapshot and restore, for the paste routes in mail
│ ├── phrasing.py # parameter naming and the stderr logger
│ ├── presence.py # Focus, frontmost app, idle, screen — read only, no setter
│ ├── reminders.py # Reminders, through EventKit
│ ├── shortcuts.py # Shortcuts, through /usr/bin/shortcuts — a subprocess
│ ├── timeparse.py # ISO 8601 parsing for --since
│ └── truncation.py # the {results, total, truncated, more_hint} envelope
├── tests/
├── requirements.txt
├── README.md
├── LICENSE
└── pyproject.toml
```
The shape worth knowing: **`cli.py` contains no Apple logic**. Every query,
AppleScript and framework call lives in `utils/`, and both front ends call the
same handler objects out of `handlers.py` — not two copies that can drift out of
agreement. `policy.py` is imported by both and by neither's dependencies, which
is what lets one permission string mean the same thing in an MCP config and in a
shell.
`utils/applescript.py` is smaller than it looks and carries one rule worth
repeating: a write that hits its timeout raises rather than returning
`success: False`, because a script killed mid-run may already have done what it
was asked. A caller that retries on a false negative repeats a mutation that
already happened.
## Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Run tests: `pytest`
5. Submit a pull request
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- Inspired by the original [apple-mcp](https://github.com/dhravya/apple-mcp) TypeScript implementation
- Built with [FastMCP](https://gofastmcp.com)
- Uses PyObjC for macOS system integration