adapter: Apple Mail adapter — first native-applescript golden path

[mickdarling]

Summary

Build the Apple Mail adapter as the first real-world adapter using the native-applescript transport plugin. This adapter proves out the full MCPAQL pipeline (interrogation → schema → generation) for native macOS applications.

Context

Apple Mail exposes a rich AppleScript API for reading accounts, mailboxes, messages, and message properties. It is an ideal golden path because:

1. Read-heavy — Most useful operations are READ, making it safe for initial development
2. Well-documented — Apple Mail's scripting dictionary is mature and stable
3. Immediately useful — Email access is a high-value capability for LLM agents
4. Representative — The API surface covers all CRUDE categories (read messages, create/delete rules, flag/unflag messages, etc.)

Adapter Operations

READ Operations

Operation	Description	maps_to
list_accounts	List all configured mail accounts	TELL Mail GET name of every account
list_mailboxes	List mailboxes for an account	TELL Mail GET name of every mailbox of account {account}
get_unread_count	Get unread message count for a mailbox	TELL Mail GET unread count of mailbox {mailbox} of account {account}
list_messages	List messages with metadata (subject, sender, date, read status)	Parameterized with limit, offset, mailbox, account
get_message	Get full message content by ID	TELL Mail GET content of message id {id}
get_message_metadata	Get message metadata (headers, recipients, attachments)	Multiple property reads
search_messages	Search messages by subject, sender, or content	TELL Mail GET messages whose {field} contains {query}

UPDATE Operations

Operation	Description	Danger Level
mark_read	Mark message as read	safe
mark_unread	Mark message as unread	safe
flag_message	Set flagged status	safe
move_message	Move message to another mailbox	reversible

DELETE Operations

Operation	Description	Danger Level
delete_message	Move message to trash	destructive

EXECUTE Operations

Operation	Description	Danger Level
check_mail	Trigger new mail check	safe

CREATE Operations (future)

Operation	Description	Danger Level
create_outgoing_message	Compose a new outgoing message (draft)	reversible

Pipeline Validation

This adapter should validate the full pipeline:

1. Interrogation — Parse Mail.app's scripting dictionary (/Applications/Mail.app/Contents/Resources/Mail.sdef) and produce a discovery bundle
2. Schema Build — Build adapter schema from discovery bundle with overrides for CRUDE classification
3. Generation — Generate the adapter MCP server package
4. Conformance — Run conformance tests against the generated adapter

Acceptance Criteria

• Adapter schema authored (YAML front matter format per element-type spec)
• All READ operations implemented and tested
• UPDATE operations implemented with appropriate danger levels
• DELETE operations implemented with confirmation requirements
• Introspection working (operation discovery, parameter details)
• End-to-end test: interrogate Mail.sdef → build schema → generate → run
• README with usage examples

Dependencies

• spec: Define native-applescript transport plugin specification #227 — native-applescript transport plugin specification
• spec: Define scripting dictionary interrogation mode for native-applescript #228 — Scripting dictionary interrogation mode
• spec: Define AppleScript parameter sanitization and injection prevention #229 — Parameter sanitization
• spec: Define AppleScript type serialization contract (AppleScript types ↔ JSON) #230 — Type serialization contract

Non-Goals

• Sending email (intentionally omitted from v1 — high risk, low initial value)
• Rule management (complex, defer to v2)
• Attachment download/processing (binary handling, defer)