applescript-patterns

AppleScript Generation Patterns

Follow these patterns when writing or modifying AppleScript templates in apple_mail_mcp/tools/*.py.

Escaping User Input

NEVER interpolate user strings directly into AppleScript f-strings. Always use escape_applescript() from core.py:

from apple_mail_mcp.core import escape_applescript

safe_account = escape_applescript(account)
safe_keyword = escape_applescript(subject_keyword)

script = f'''
tell application "Mail"
    set targetAccount to account "{safe_account}"
    ...
end tell
'''

escape_applescript() handles: backslashes, double quotes, carriage returns, newlines, and tabs. This prevents AppleScript injection via user-controlled strings.

Mailbox Handling

Use get_mailbox_script() for any mailbox access. It handles the INBOX/Inbox inconsistency in macOS Mail:

from apple_mail_mcp.core import get_mailbox_script

# Generates try/catch with INBOX->Inbox fallback
mailbox_setup = get_mailbox_script(mailbox, "targetMailbox", "targetAccount")

script = f'''
tell application "Mail"
    set targetAccount to account "{safe_account}"
    {mailbox_setup}
    ...
end tell
'''

For inbox specifically, use inbox_mailbox_script():

from apple_mail_mcp.core import inbox_mailbox_script

script = f'''
    {inbox_mailbox_script("inboxMailbox", "targetAccount")}
'''

Recipients (TO/CC/BCC)

Use recipients_script() for adding recipients to outgoing messages:

from apple_mail_mcp.core import recipients_script

to_script = recipients_script(to, "to", "newMessage")
cc_script = recipients_script(cc, "cc", "newMessage")
bcc_script = recipients_script(bcc, "bcc", "newMessage")

This handles comma-separated addresses, escaping each one, and generating the correct make new ... recipient AppleScript.

Iteration Direction

When mutating a collection (moving or deleting messages), ALWAYS iterate in reverse to avoid index shifting:

-- CORRECT: reverse iteration during mutation
set msgCount to count of inboxMessages
repeat with i from msgCount to 1 by -1
    set aMessage to item i of inboxMessages
    move aMessage to targetMailbox
end repeat

-- WRONG: forward iteration skips items after mutation
repeat with aMessage in inboxMessages
    move aMessage to targetMailbox  -- shifts subsequent indices
end repeat