get_messages

Instructions

Implementation Reference

• src/index.ts:57-80 (registration)

  Registration of the 'get_messages' tool in the MCP server's listTools handler, including name, description, and input schema.

  {
    name: 'get_messages',
    description: 'Get email messages from specified mailbox',
    inputSchema: {
      type: 'object',
      properties: {
        mailbox: {
          type: 'string',
          description: 'Mailbox name (default: INBOX)',
          default: 'INBOX',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of messages to retrieve',
          default: 10,
        },
        unreadOnly: {
          type: 'boolean',
          description: 'Retrieve only unread messages',
          default: false,
        },
      },
    },
  },

• src/index.ts:391-417 (handler)

  MCP tool handler for 'get_messages': validates connection, extracts parameters (mailbox, limit, unreadOnly), calls iCloudMailClient.getMessages, and returns JSON stringified messages.

  case 'get_messages': {
    if (!mailClient) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        'iCloud Mail not configured. Please set ICLOUD_EMAIL and ICLOUD_APP_PASSWORD environment variables.'
      );
    }
  
    const mailbox = (args?.mailbox as string) || 'INBOX';
    const limit = (args?.limit as number) || 10;
    const unreadOnly = (args?.unreadOnly as boolean) || false;
  
    const messages = await mailClient.getMessages(
      mailbox,
      limit,
      unreadOnly
    );
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(messages, null, 2),
        },
      ],
    };
  }

• src/lib/icloud-mail-client.ts:240-353 (helper)

  Core helper method getMessages in iCloudMailClient class: opens IMAP mailbox, searches for recent messages (optionally unread), fetches bodies, parses with mailparser, extracts metadata/attachments/flags, returns EmailMessage array.

  async getMessages(
    mailbox: string = 'INBOX',
    limit: number = 10,
    unreadOnly: boolean = false
  ): Promise<EmailMessage[]> {
    return new Promise((resolve, reject) => {
      this.imap.openBox(mailbox, true, (err: Error) => {
        if (err) {
          reject(err);
          return;
        }
  
        const searchCriteria = unreadOnly ? ['UNSEEN'] : ['ALL'];
  
        this.imap.search(searchCriteria, (err: Error, results: number[]) => {
          if (err) {
            reject(err);
            return;
          }
  
          if (!results || results.length === 0) {
            resolve([]);
            return;
          }
  
          const messageIds = results.slice(-limit);
          const fetch = this.imap.fetch(messageIds, {
            bodies: '',
            struct: true,
          });
  
          const messages: EmailMessage[] = [];
  
          fetch.on('message', (msg: ImapMessage, seqno: number) => {
            let emailData = '';
  
            msg.on('body', (stream: NodeJS.ReadableStream) => {
              stream.on('data', (chunk: Buffer) => {
                emailData += chunk.toString('utf8');
              });
  
              stream.once('end', async () => {
                try {
                  const parsed: ParsedMail = await simpleParser(emailData);
  
                  const attachments: Attachment[] = [];
                  if (parsed.attachments) {
                    parsed.attachments.forEach((att: MailparserAttachment) => {
                      attachments.push({
                        filename: att.filename || 'unknown',
                        contentType:
                          att.contentType || 'application/octet-stream',
                        size: att.size || 0,
                        data: att.content,
                      });
                    });
                  }
  
                  const getEmailText = (
                    addr:
                      | MailparserAddressObject
                      | MailparserAddressObject[]
                      | undefined
                  ) => {
                    if (!addr) return '';
                    if (Array.isArray(addr))
                      return addr.map((a) => a.text).join(', ');
                    return addr.text;
                  };
  
                  const emailMessage: EmailMessage = {
                    id: parsed.messageId || `${seqno}`,
                    from: getEmailText(parsed.from),
                    to: parsed.to
                      ? Array.isArray(parsed.to)
                        ? parsed.to.map((t) => getEmailText(t))
                        : [getEmailText(parsed.to)]
                      : [],
                    subject: parsed.subject || '',
                    body: parsed.text || parsed.html || '',
                    date: parsed.date || new Date(),
                    flags: [],
                    attachments:
                      attachments.length > 0 ? attachments : undefined,
                  };
  
                  messages.push(emailMessage);
                } catch (parseError) {
                  console.error('Error parsing email:', parseError);
                }
              });
            });
  
            msg.once('attributes', (attrs: ImapMessageAttributes) => {
              if (attrs.flags) {
                const lastMessage = messages[messages.length - 1];
                if (lastMessage) {
                  lastMessage.flags = attrs.flags;
                }
              }
            });
          });
  
          fetch.once('error', (fetchErr: Error) => {
            reject(fetchErr);
          });
  
          fetch.once('end', () => {
            resolve(messages);
          });
        });
      });
    });
  }