iMail-mcp

Instructions

Implementation Reference

• src/lib/icloud-mail-client.ts:756-808 (handler)

  Core implementation of setFlags method in iCloudMailClient class that adds or removes IMAP flags on all messages in the specified mailbox using imap.addFlags or imap.delFlags.
  async setFlags( _messageIds: string[], flags: string[], mailbox: string = 'INBOX', action: 'add' | 'remove' = 'add' ): Promise<{ status: string; message: string }> { return new Promise((resolve) => { this.imap.openBox(mailbox, false, (err: Error) => { if (err) { resolve({ status: 'error', message: `Failed to open mailbox '${mailbox}': ${err.message}`, }); return; } this.imap.search(['ALL'], (err: Error, results: number[]) => { if (err) { resolve({ status: 'error', message: `Failed to search messages: ${err.message}`, }); return; } if (!results || results.length === 0) { resolve({ status: 'error', message: 'No messages found in mailbox', }); return; } const flagOperation = action === 'add' ? 'addFlags' : 'delFlags'; this.imap[flagOperation](results, flags, (err: Error) => { if (err) { resolve({ status: 'error', message: `Failed to ${action} flags: ${err.message}`, }); return; } resolve({ status: 'success', message: `Successfully ${action === 'add' ? 'added' : 'removed'} flags [${flags.join(', ')}] ${action === 'add' ? 'to' : 'from'} ${results.length} messages in '${mailbox}'`, }); }); }); }); }); }
• src/index.ts:644-672 (handler)

  MCP tool dispatch handler for 'set_flags' that extracts parameters and delegates to mailClient.setFlags method.
  case 'set_flags': { if (!mailClient) { throw new McpError( ErrorCode.InvalidRequest, 'iCloud Mail not configured. Please set ICLOUD_EMAIL and ICLOUD_APP_PASSWORD environment variables.' ); } const messageIds = args?.messageIds as string[]; const flags = args?.flags as string[]; const mailbox = (args?.mailbox as string) || 'INBOX'; const action = (args?.action as string) || 'add'; const result = await mailClient.setFlags( messageIds, flags, mailbox, action as 'add' | 'remove' ); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }
• src/index.ts:258-289 (schema)

  JSON schema definition for the set_flags tool input parameters, including messageIds, flags, mailbox, and action.
  { name: 'set_flags', description: 'Set flags on messages (read, unread, flagged, etc.)', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to set flags on', }, flags: { type: 'array', items: { type: 'string' }, description: 'Array of flags to set (e.g., ["\\Seen", "\\Flagged"])', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, action: { type: 'string', enum: ['add', 'remove'], description: 'Whether to add or remove the flags (default: add)', default: 'add', }, }, required: ['messageIds', 'flags'], }, },
• src/index.ts:54-384 (registration)

  Registration of all tools including 'set_flags' in the ListToolsRequestSchema handler.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { 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, }, }, }, }, { name: 'send_email', description: 'Send an email through iCloud Mail', inputSchema: { type: 'object', properties: { to: { oneOf: [ { type: 'string' }, { type: 'array', items: { type: 'string' } }, ], description: 'Recipient email address(es)', }, subject: { type: 'string', description: 'Email subject', }, text: { type: 'string', description: 'Plain text email body', }, html: { type: 'string', description: 'HTML email body', }, }, required: ['to', 'subject'], }, }, { name: 'mark_as_read', description: 'Mark email messages as read', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to mark as read', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, }, required: ['messageIds'], }, }, { name: 'get_mailboxes', description: 'List all available mailboxes', inputSchema: { type: 'object', properties: {}, }, }, { name: 'test_connection', description: 'Test the email server connection (IMAP and SMTP)', inputSchema: { type: 'object', properties: {}, }, }, { name: 'create_mailbox', description: 'Create a new mailbox (folder)', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name of the mailbox to create', }, }, required: ['name'], }, }, { name: 'delete_mailbox', description: 'Delete an existing mailbox (folder)', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Name of the mailbox to delete', }, }, required: ['name'], }, }, { name: 'move_messages', description: 'Move messages between mailboxes', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to move', }, sourceMailbox: { type: 'string', description: 'Source mailbox name', }, destinationMailbox: { type: 'string', description: 'Destination mailbox name', }, }, required: ['messageIds', 'sourceMailbox', 'destinationMailbox'], }, }, { name: 'search_messages', description: 'Search for messages using various criteria', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query text (searches in subject, from, body)', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, limit: { type: 'number', description: 'Maximum number of messages to retrieve', default: 10, }, dateFrom: { type: 'string', description: 'Start date for search (YYYY-MM-DD format)', }, dateTo: { type: 'string', description: 'End date for search (YYYY-MM-DD format)', }, fromEmail: { type: 'string', description: 'Filter by sender email address', }, unreadOnly: { type: 'boolean', description: 'Search only unread messages', default: false, }, }, }, }, { name: 'delete_messages', description: 'Delete messages from a mailbox', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to delete', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, }, required: ['messageIds'], }, }, { name: 'set_flags', description: 'Set flags on messages (read, unread, flagged, etc.)', inputSchema: { type: 'object', properties: { messageIds: { type: 'array', items: { type: 'string' }, description: 'Array of message IDs to set flags on', }, flags: { type: 'array', items: { type: 'string' }, description: 'Array of flags to set (e.g., ["\\Seen", "\\Flagged"])', }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, action: { type: 'string', enum: ['add', 'remove'], description: 'Whether to add or remove the flags (default: add)', default: 'add', }, }, required: ['messageIds', 'flags'], }, }, { name: 'download_attachment', description: 'Download an attachment from a specific message', inputSchema: { type: 'object', properties: { messageId: { type: 'string', description: 'Message ID containing the attachment', }, attachmentIndex: { type: 'number', description: 'Index of the attachment to download (0-based)', default: 0, }, mailbox: { type: 'string', description: 'Mailbox name (default: INBOX)', default: 'INBOX', }, }, required: ['messageId'], }, }, { name: 'auto_organize', description: 'Automatically organize emails based on rules (sender, subject keywords, etc.)', inputSchema: { type: 'object', properties: { rules: { type: 'array', items: { type: 'object', properties: { name: { type: 'string', description: 'Rule name', }, condition: { type: 'object', properties: { fromContains: { type: 'string', description: 'Move emails if sender contains this text', }, subjectContains: { type: 'string', description: 'Move emails if subject contains this text', }, }, }, action: { type: 'object', properties: { moveToMailbox: { type: 'string', description: 'Mailbox to move matching emails to', }, }, required: ['moveToMailbox'], }, }, required: ['name', 'condition', 'action'], }, description: 'Array of organization rules', }, sourceMailbox: { type: 'string', description: 'Source mailbox to organize (default: INBOX)', default: 'INBOX', }, dryRun: { type: 'boolean', description: 'If true, only shows what would be organized without moving emails', default: false, }, }, required: ['rules'], }, }, { name: 'check_config', description: 'Check if environment variables are properly configured', inputSchema: { type: 'object', properties: {}, }, }, ], }; });