applescript-mcp

Instructions

Implementation Reference

• src/categories/mail.ts:385-605 (handler)

  Handler implementation for the 'get_email' tool (registered as 'mail_get_email'). Generates AppleScript to search Mail.app for emails matching criteria like subject, sender, date, mailbox, and optionally includes body.
  { name: "get_email", description: "Get a specific email by search criteria from Mail.app", schema: { type: "object", properties: { mailbox: { type: "string", description: "Name of the mailbox to search in (e.g., 'Inbox', 'Sent')", default: "Inbox" }, account: { type: "string", description: "Name of the account to search in (e.g., 'iCloud', 'Gmail', 'Exchange'). If not specified, searches all accounts with preference for iCloud.", default: "iCloud" }, subject: { type: "string", description: "Subject text to search for (partial match)" }, sender: { type: "string", description: "Sender email or name to search for (partial match)" }, dateReceived: { type: "string", description: "Date received to search for (format: YYYY-MM-DD)" }, unreadOnly: { type: "boolean", description: "Only search unread emails if true" }, includeBody: { type: "boolean", description: "Include email body in the result if true", default: false } }, required: [] }, script: (args) => ` set mailboxName to "${args.mailbox || 'Inbox'}" set accountName to "${args.account || 'iCloud'}" set searchSubject to "${args.subject || ''}" set searchSender to "${args.sender || ''}" set searchDate to "${args.dateReceived || ''}" set showUnreadOnly to ${args.unreadOnly ? 'true' : 'false'} set includeBody to ${args.includeBody ? 'true' : 'false'} set searchAllAccounts to ${!args.account ? 'true' : 'false'} tell application "Mail" -- Get all messages if no specific mailbox is found set foundMailbox to false set emailMessages to {} set targetAccount to missing value -- First try to find the specified account if not searchAllAccounts then try set allAccounts to every account repeat with acct in allAccounts if name of acct is accountName then set targetAccount to acct exit repeat end if end repeat end try -- If account not found, set to search all accounts if targetAccount is missing value then set searchAllAccounts to true end if end if -- If specific account is found, search in that account if not searchAllAccounts and targetAccount is not missing value then try set acctMailboxes to every mailbox of targetAccount repeat with m in acctMailboxes if name of m is mailboxName then set targetMailbox to m set foundMailbox to true -- Get messages from the found mailbox if showUnreadOnly then set emailMessages to (messages of targetMailbox whose read status is false) else set emailMessages to (messages of targetMailbox) end if exit repeat end if end repeat end try else -- Search all accounts, with preference for iCloud set iCloudAccount to missing value set allAccounts to every account -- First look for iCloud account repeat with acct in allAccounts if name of acct is "iCloud" then set iCloudAccount to acct exit repeat end if end repeat -- Try to find the mailbox directly try set allMailboxes to every mailbox repeat with m in allMailboxes if name of m is mailboxName then set targetMailbox to m set foundMailbox to true -- Get messages from the found mailbox if showUnreadOnly then set emailMessages to (messages of targetMailbox whose read status is false) else set emailMessages to (messages of targetMailbox) end if exit repeat end if end repeat end try end if -- Filter messages based on search criteria set filteredMessages to {} repeat with theMessage in emailMessages try set matchesSubject to true set matchesSender to true set matchesDate to true -- Check subject if specified if searchSubject is not "" then set msgSubject to subject of theMessage if msgSubject does not contain searchSubject then set matchesSubject to false end if end if -- Check sender if specified if searchSender is not "" then set msgSender to sender of theMessage if msgSender does not contain searchSender then set matchesSender to false end if end if -- Check date if specified if searchDate is not "" then set msgDate to date received of theMessage set msgDateString to (year of msgDate as string) & "-" & my padNumber(month of msgDate as integer) & "-" & my padNumber(day of msgDate as integer) if msgDateString is not searchDate then set matchesDate to false end if end if -- Add to filtered list if all criteria match if matchesSubject and matchesSender and matchesDate then set end of filteredMessages to theMessage end if end try end repeat -- Format the results set emailList to "Search results:" & return & return if (count of filteredMessages) is 0 then set emailList to emailList & "No matching emails found." else repeat with theMessage in filteredMessages try set msgSubject to subject of theMessage set msgSender to sender of theMessage set msgDate to date received of theMessage set msgRead to read status of theMessage -- Try to get account name for this message set msgAccount to "" try set msgMailbox to mailbox of theMessage set msgAcct to account of msgMailbox set msgAccount to " [" & name of msgAcct & "]" end try set emailList to emailList & "From: " & msgSender & return set emailList to emailList & "Subject: " & msgSubject & return set emailList to emailList & "Date: " & msgDate & msgAccount & return set emailList to emailList & "Read: " & msgRead & return -- Include body if requested if includeBody then set msgContent to content of theMessage set emailList to emailList & "Content: " & return & msgContent & return end if set emailList to emailList & return on error errMsg set emailList to emailList & "Error processing message: " & errMsg & return & return end try end repeat end if return emailList end tell -- Helper function to pad numbers with leading zero if needed on padNumber(num) if num < 10 then return "0" & num else return num as string end if end padNumber `, },
• src/categories/mail.ts:388-424 (schema)

  Input schema for the mail_get_email tool, defining parameters for searching emails by mailbox, account, subject, sender, date, unread status, and body inclusion.
  schema: { type: "object", properties: { mailbox: { type: "string", description: "Name of the mailbox to search in (e.g., 'Inbox', 'Sent')", default: "Inbox" }, account: { type: "string", description: "Name of the account to search in (e.g., 'iCloud', 'Gmail', 'Exchange'). If not specified, searches all accounts with preference for iCloud.", default: "iCloud" }, subject: { type: "string", description: "Subject text to search for (partial match)" }, sender: { type: "string", description: "Sender email or name to search for (partial match)" }, dateReceived: { type: "string", description: "Date received to search for (format: YYYY-MM-DD)" }, unreadOnly: { type: "boolean", description: "Only search unread emails if true" }, includeBody: { type: "boolean", description: "Include email body in the result if true", default: false } }, required: [] },
• src/framework.ts:219-232 (registration)

  Registers all tools for listing, constructing names like 'mail_get_email' from category 'mail' and script 'get_email', including description and input schema.
  private setupHandlers(): void { // List available tools this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this.categories.flatMap((category) => category.scripts.map((script) => ({ name: `${category.name}_${script.name}`, // Changed from dot to underscore description: `[${category.description}] ${script.description}`, inputSchema: script.schema || { type: "object", properties: {}, }, })), ), }));
• src/framework.ts:242-258 (registration)

  Tool execution handler parses tool name 'mail_get_email' by splitting on '_', finds 'mail' category and 'get_email' script, generates and executes the AppleScript.
  try { // Split on underscore instead of dot const [categoryName, ...scriptNameParts] = toolName.split("_"); const scriptName = scriptNameParts.join("_"); // Rejoin in case script name has underscores const category = this.categories.find((c) => c.name === categoryName); if (!category) { this.log("warning", "Category not found", { categoryName }); throw new McpError( ErrorCode.MethodNotFound, `Category not found: ${categoryName}`, ); } const script = category.scripts.find((s) => s.name === scriptName); if (!script) {
• src/index.ts:8-31 (registration)

  Imports and registers the mail category containing the get_email script, making 'mail_get_email' available as a tool.
  import { mailCategory } from "./categories/mail.js"; import { pagesCategory } from "./categories/pages.js"; import { shortcutsCategory } from "./categories/shortcuts.js"; import { messagesCategory } from "./categories/messages.js"; import { notesCategory } from "./categories/notes.js"; const server = new AppleScriptFramework({ name: "applescript-server", version: "1.0.4", debug: false, }); // Log startup information using stderr (server isn't connected yet) console.error(`[INFO] Starting AppleScript MCP server - PID: ${process.pid}`); // Add all categories console.error("[INFO] Registering categories..."); server.addCategory(systemCategory); server.addCategory(calendarCategory); server.addCategory(finderCategory); server.addCategory(clipboardCategory); server.addCategory(notificationsCategory); server.addCategory(itermCategory); server.addCategory(mailCategory);