Apple MCP

Instructions

Implementation Reference

• index.ts:673-774 (handler)

  Main handler logic for the 'reminders' tool. Validates input, loads the reminders utils module, and dispatches to specific helper functions based on the 'operation' parameter (list, search, open, create, listById). Returns structured content with results or errors.
  case "reminders": { if (!isRemindersArgs(args)) { throw new Error("Invalid arguments for reminders tool"); } try { const remindersModule = await loadModule('reminders'); const { operation } = args; if (operation === "list") { // List all reminders const lists = await remindersModule.getAllLists(); const allReminders = await remindersModule.getAllReminders(); return { content: [{ type: "text", text: `Found ${lists.length} lists and ${allReminders.length} reminders.` }], lists, reminders: allReminders, isError: false }; } else if (operation === "search") { // Search for reminders const { searchText } = args; const results = await remindersModule.searchReminders(searchText!); return { content: [{ type: "text", text: results.length > 0 ? `Found ${results.length} reminders matching "${searchText}".` : `No reminders found matching "${searchText}".` }], reminders: results, isError: false }; } else if (operation === "open") { // Open a reminder const { searchText } = args; const result = await remindersModule.openReminder(searchText!); return { content: [{ type: "text", text: result.success ? `Opened Reminders app. Found reminder: ${result.reminder?.name}` : result.message }], ...result, isError: !result.success }; } else if (operation === "create") { // Create a reminder const { name, listName, notes, dueDate } = args; const result = await remindersModule.createReminder(name!, listName, notes, dueDate); return { content: [{ type: "text", text: `Created reminder "${result.name}" ${listName ? `in list "${listName}"` : ''}.` }], success: true, reminder: result, isError: false }; } else if (operation === "listById") { // Get reminders from a specific list by ID const { listId, props } = args; const results = await remindersModule.getRemindersFromListById(listId!, props); return { content: [{ type: "text", text: results.length > 0 ? `Found ${results.length} reminders in list with ID "${listId}".` : `No reminders found in list with ID "${listId}".` }], reminders: results, isError: false }; } return { content: [{ type: "text", text: "Unknown operation" }], isError: true }; } catch (error) { console.error("Error in reminders tool:", error); return { content: [{ type: "text", text: `Error in reminders tool: ${error}` }], isError: true }; } }
• tools.ts:133-178 (schema)

  Tool schema definition including name, description, and detailed inputSchema with properties and requirements for the 'reminders' tool.
  const REMINDERS_TOOL: Tool = { name: "reminders", description: "Search, create, and open reminders in Apple Reminders app", inputSchema: { type: "object", properties: { operation: { type: "string", description: "Operation to perform: 'list', 'search', 'open', 'create', or 'listById'", enum: ["list", "search", "open", "create", "listById"] }, searchText: { type: "string", description: "Text to search for in reminders (required for search and open operations)" }, name: { type: "string", description: "Name of the reminder to create (required for create operation)" }, listName: { type: "string", description: "Name of the list to create the reminder in (optional for create operation)" }, listId: { type: "string", description: "ID of the list to get reminders from (required for listById operation)" }, props: { type: "array", items: { type: "string" }, description: "Properties to include in the reminders (optional for listById operation)" }, notes: { type: "string", description: "Additional notes for the reminder (optional for create operation)" }, dueDate: { type: "string", description: "Due date for the reminder in ISO format (optional for create operation)" } }, required: ["operation"] } };
• utils/reminders.ts:257-257 (helper)

  Export of all helper functions used by the reminders handler: getAllLists(), getAllReminders(), searchReminders(), createReminder(), openReminder(), getRemindersFromListById() which implement the core Apple Reminders app interactions via AppleScript/JXA.
  export default { getAllLists, getAllReminders, searchReminders, createReminder, openReminder, getRemindersFromListById };
• tools.ts:308-310 (registration)

  Registration of the reminders tool schema in the main tools array, exported for listing via ListToolsRequest.
  const tools = [CONTACTS_TOOL, NOTES_TOOL, MESSAGES_TOOL, MAIL_TOOL, REMINDERS_TOOL, WEB_SEARCH_TOOL, CALENDAR_TOOL, MAPS_TOOL]; export default tools;
• index.ts:1225-1267 (schema)

  Runtime Type Guard / validator for reminders tool input arguments, matching the inputSchema.
  function isRemindersArgs(args: unknown): args is { operation: "list" | "search" | "open" | "create" | "listById"; searchText?: string; name?: string; listName?: string; listId?: string; props?: string[]; notes?: string; dueDate?: string; } { if (typeof args !== "object" || args === null) { return false; } const { operation } = args as any; if (typeof operation !== "string") { return false; } if (!["list", "search", "open", "create", "listById"].includes(operation)) { return false; } // For search and open operations, searchText is required if ((operation === "search" || operation === "open") && (typeof (args as any).searchText !== "string" || (args as any).searchText === "")) { return false; } // For create operation, name is required if (operation === "create" && (typeof (args as any).name !== "string" || (args as any).name === "")) { return false; } // For listById operation, listId is required if (operation === "listById" && (typeof (args as any).listId !== "string" || (args as any).listId === "")) { return false; } return true; }