messages

Instructions

Implementation Reference

• src/handlers/messagesHandler.ts:15-110 (handler)

  The handleMessages function that executes the tool logic for send, read, schedule, and unread operations using the loaded message module and contacts module for name resolution.

  export async function handleMessages(
    args: MessagesArgs,
    loadModule: LoadModuleFunction
  ): Promise<ToolResult> {
    try {
      const messageModule = await loadModule('message');
  
      switch (args.operation) {
        case "send": {
          await messageModule.sendMessage(args.phoneNumber, args.message);
          return {
            content: [{ type: "text", text: `Message sent to ${args.phoneNumber}` }],
            isError: false
          };
        }
  
        case "read": {
          const messages = await messageModule.readMessages(args.phoneNumber, args.limit);
          return {
            content: [{ 
              type: "text", 
              text: messages.length > 0 ? 
                messages.map(msg => 
                  `[${new Date(msg.date).toLocaleString()}] ${msg.is_from_me ? 'Me' : msg.sender}: ${msg.content}`
                ).join("\n") :
                "No messages found"
            }],
            isError: false
          };
        }
  
        case "schedule": {
          const scheduledMsg = await messageModule.scheduleMessage(
            args.phoneNumber,
            args.message,
            new Date(args.scheduledTime)
          );
          return {
            content: [{ 
              type: "text", 
              text: `Message scheduled to be sent to ${args.phoneNumber} at ${scheduledMsg.scheduledTime}` 
            }],
            isError: false
          };
        }
  
        case "unread": {
          const messages = await messageModule.getUnreadMessages(args.limit);
          
          // Look up contact names for all messages
          const contactsModule = await loadModule('contacts'); // Need contacts module here
          const messagesWithNames = await Promise.all(
            messages.map(async msg => {
              // Only look up names for messages not from me
              if (!msg.is_from_me) {
                const contactName = await contactsModule.findContactByPhone(msg.sender);
                return {
                  ...msg,
                  displayName: contactName || msg.sender // Use contact name if found, otherwise use phone/email
                };
              }
              return {
                ...msg,
                displayName: 'Me'
              };
            })
          );
  
          return {
            content: [{ 
              type: "text", 
              text: messagesWithNames.length > 0 ? 
                `Found ${messagesWithNames.length} unread message(s):\n` +
                messagesWithNames.map(msg => 
                  `[${new Date(msg.date).toLocaleString()}] From ${msg.displayName}:\n${msg.content}`
                ).join("\n\n") :
                "No unread messages found"
            }],
            isError: false
          };
        }
  
        default:
          // This should be unreachable due to Zod validation
          throw new Error(`Unknown messages operation: ${(args as any).operation}`);
      }
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error with messages operation: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  }

• src/handlers/messagesHandler.ts:5-10 (schema)

  Zod schema used for input validation of the messages tool arguments in the server handler.

  export const MessagesArgsSchema = z.discriminatedUnion("operation", [
    z.object({ operation: z.literal("send"), phoneNumber: z.string(), message: z.string() }),
    z.object({ operation: z.literal("read"), phoneNumber: z.string(), limit: z.number().optional() }),
    z.object({ operation: z.literal("schedule"), phoneNumber: z.string(), message: z.string(), scheduledTime: z.string().datetime() }), // Assuming ISO 8601 format
    z.object({ operation: z.literal("unread"), limit: z.number().optional() }),
  ]);

• index.ts:124-127 (registration)

  Registration of the messages tool handler in the MCP server's CallToolRequest handler switch statement.

  case "messages": {
    const validatedArgs = MessagesArgsSchema.parse(args);
    return await handleMessages(validatedArgs, loadModule);
  }

• tools.ts:49-79 (schema)

  JSON inputSchema definition for the messages tool, used in tool discovery (ListTools).

  const MESSAGES_TOOL: Tool = {
    name: "messages",
    description: "Interact with Apple Messages app - send, read, schedule messages and check unread messages",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          description: "Operation to perform: 'send', 'read', 'schedule', or 'unread'",
          enum: ["send", "read", "schedule", "unread"]
        },
        phoneNumber: {
          type: "string",
          description: "Phone number to send message to (required for send, read, and schedule operations)"
        },
        message: {
          type: "string",
          description: "Message to send (required for send and schedule operations)"
        },
        limit: {
          type: "number",
          description: "Number of messages to read (optional, for read and unread operations)"
        },
        scheduledTime: {
          type: "string",
          description: "ISO string of when to send the message (required for schedule operation)"
        }
      },
      required: ["operation"]
    }
  };

• tools.ts:317-317 (registration)

  Includes MESSAGES_TOOL in the exported tools array returned by ListToolsRequest.

  const tools = [CONTACTS_TOOL, NOTES_TOOL, MESSAGES_TOOL, MAIL_TOOL, REMINDERS_TOOL, WEB_SEARCH_TOOL, CALENDAR_TOOL, MAPS_TOOL];