macos-apps-mcp: Instructions file for Codex

CLAUDE.md — macos-apps-mcp

One consolidated MCP server for native macOS apps. Python + FastMCP, managed with uv. Full design and rationale: DESIGN.md.

Touching Mail? Read docs/mail-applescript-facts.md FIRST. Device-verified traps that code review cannot catch — delete after send is a silent no-op, a compose window is a recipient-less outgoing message, writing content on a forward destroys the attachments, and Mail's Drafts autosave lands ~15s late so a 3-second check reports a clean mailbox and lies — and a move out of a Gmail label reads ok, then the copy is back ~2 min later (observe Gmail writes at +2 and +15 min). Verify every Mail write by running it and inspecting the resulting message; three reviews and a green suite once passed a forward that delivered empty mail and ate 7 attachments.

Our count disagrees with Mail's own counter? Our query is wrong until proven otherwise. Compare against mailboxes.total_count / unread_count (#251, #287): a Gmail INBOX mismatch was once filed as stale counters, and Mail's counter was right. Exception: a Gmail label made by create_mailbox has no source, and its counter stays 0 — compare against an AppleScript count there (#291).

Architecture (don't drift)

• FastMCP standalone. Tools in macos_apps_mcp/server.py are thin dispatch to adapters — no business logic in the tool layer.
• Adapters = typed Protocol (macos_apps_mcp/contracts.py): reads uniform (get_pointers -> list[Pointer]), writes per-adapter typed (create_reminder(ReminderData), create_event(CalendarEventData)). No ABC, no plugin registry (YAGNI). Pointer(id, summary, deeplink) is the citation contract — pointers, not payload (no full bodies by default).
• All EventKit / native access goes through macos_apps_mcp/runtime.run_native() — a single serialized worker thread (EKEventStore thread-affinity + TCC). Never call EventKit off arbitrary threads, and never widen the executor past max_workers=1.
• One adapter module per app under macos_apps_mcp/adapters/. Adding an app = add a module + mount its tools in server.py + (if the app is reached via osascript/Automation) add its name to doctor._AUTOMATION_APPS and its bundle id to doctor._AUTOMATION_BUNDLES so doctor checks it (a pin test fails when they disagree); it must not reach into another adapter. This is what lets a module later harden into a lyfe native data-plane adapter unchanged.
• The shim↔daemon hop has NO read deadline (daemon._uds_client_factory, Timeout(None, connect=10.0)). A call's duration is the daemon's business — a bulk Mail pass runs HOURS — and it is a local socket with no network to time out on. Per-operation limits belong in the adapter, which knows what it asked for. Never "fix" a hang by adding a timeout here: that is #170, where httpx's own 5s default silently killed every destructive Mail call over ~5s. A dead stream must ANSWER (fail_loud_on_dead_stream) — silence is what a model misreads as failure, then retries a destructive call that already succeeded.
• Three capability tiers, all gated at registration (a gated-off tool is absent, never registered-and-erroring): read → write (@_write_tool/@_additive_tool, skipped by MACOS_APPS_READ_ONLY) → outbound (@_send_tool("<adapter>"), registered only when MACOS_APPS_ALLOW_SEND names that adapter; READ_ONLY wins unconditionally). Outbound acts off this machine, so it carries openWorldHint and defaults dry_run=True — and its dry-run path must make no native call at all (building a Mail outgoing message can strand an autosaved draft). A new send tool goes through _send_tool or tests/test_tool_annotations.py fails.
• Off macOS the server loads and lists its tools; every tool that needs the Mac refuses. A macOS-only import at module load sits under if sys.platform == "darwin": (else the name is None), never a try/except, and a native door refuses through runtime.require_macos(). The linux-tools-list CI job fails on a load-time macOS import on the server's import path, and Glama lists the server only after a Linux build test reads tools/list.