@mindstone-engineering/mcp-server-email-imap 0.1.0

package/dist/tools/index.js

@@ -0,0 +1,76 @@
+/**
+ * Email IMAP tool registration — aggregates all tool modules.
+ */
+import { getPreset } from '../presets.js';
+import { initImap, cleanup as cleanupImap } from '../imap-client.js';
+import { initSmtp, cleanup as cleanupSmtp } from '../smtp-client.js';
+import { setClientConfig } from './shared.js';
+export { registerMailboxTools } from './mailbox.js';
+export { registerMessageTools } from './messages.js';
+export { registerSendTools } from './send.js';
+export { registerConfigureTools, getCredentials, setCredentials } from './configure.js';
+/**
+ * Initialize IMAP and SMTP clients from provider settings or explicit config.
+ */
+export async function initClients(options) {
+    const normalizedProvider = options.provider.trim().toLowerCase();
+    let config;
+    if (normalizedProvider === 'custom') {
+        const imapHost = options.imapHost ?? process.env.EMAIL_IMAP_IMAP_HOST?.trim();
+        const smtpHost = options.smtpHost ?? process.env.EMAIL_IMAP_SMTP_HOST?.trim();
+        if (!imapHost || !smtpHost) {
+            throw new Error('Custom email requires IMAP and SMTP server addresses. Provide imapHost and smtpHost.');
+        }
+        const imapPort = options.imapPort ?? parseInt(process.env.EMAIL_IMAP_IMAP_PORT || '993', 10);
+        const smtpPort = options.smtpPort ?? parseInt(process.env.EMAIL_IMAP_SMTP_PORT || '587', 10);
+        config = {
+            imapHost,
+            imapPort,
+            imapTls: options.imapTls ?? imapPort === 993,
+            smtpHost,
+            smtpPort,
+            smtpSecure: options.smtpSecure ?? smtpPort === 465,
+            email: options.email.trim(),
+            password: options.password.trim(),
+        };
+    }
+    else {
+        const preset = getPreset(normalizedProvider);
+        if (!preset) {
+            throw new Error(`Unsupported provider "${normalizedProvider}". Supported providers: icloud, yahoo, custom.`);
+        }
+        config = {
+            imapHost: preset.imapHost,
+            imapPort: preset.imapPort,
+            imapTls: preset.imapTls,
+            smtpHost: preset.smtpHost,
+            smtpPort: preset.smtpPort,
+            smtpSecure: preset.smtpSecure,
+            email: options.email.trim(),
+            password: options.password.trim(),
+        };
+    }
+    setClientConfig(config);
+    await initImap({
+        host: config.imapHost,
+        port: config.imapPort,
+        tls: config.imapTls,
+        user: config.email,
+        pass: config.password,
+    });
+    await initSmtp({
+        host: config.smtpHost,
+        port: config.smtpPort,
+        secure: config.smtpSecure,
+        user: config.email,
+        pass: config.password,
+    });
+}
+/**
+ * Clean up all email clients.
+ */
+export async function cleanupClients() {
+    await Promise.allSettled([cleanupImap(), cleanupSmtp()]);
+    setClientConfig(null);
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/mailbox.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mailbox tools — listing mailboxes and getting mailbox status.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerMailboxTools(server: McpServer): void;
+//# sourceMappingURL=mailbox.d.ts.map

package/dist/tools/mailbox.js

@@ -0,0 +1,101 @@
+/**
+ * Mailbox tools — listing mailboxes and getting mailbox status.
+ */
+import { z } from 'zod';
+import { withErrorHandling } from '../utils.js';
+import { getConnection } from '../imap-client.js';
+import { getMailboxLock } from '../imap-client.js';
+import { ensureInitialized, formatAddresses, formatDate } from './shared.js';
+export function registerMailboxTools(server) {
+    // ── email_list_mailboxes ────────────────────────────────────────
+    server.registerTool('email_list_mailboxes', {
+        description: 'List all email folders/mailboxes with message counts.',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        ensureInitialized();
+        const client = await getConnection();
+        const listedMailboxes = await client.list({
+            statusQuery: {
+                messages: true,
+                unseen: true,
+            },
+        });
+        const mailboxes = await Promise.all(listedMailboxes.map(async (mailbox) => {
+            let messages = mailbox.status?.messages;
+            let unseen = mailbox.status?.unseen;
+            if (messages === undefined || unseen === undefined) {
+                const status = await client.status(mailbox.path, {
+                    messages: true,
+                    unseen: true,
+                });
+                messages = status.messages ?? 0;
+                unseen = status.unseen ?? 0;
+            }
+            return {
+                name: mailbox.path,
+                specialUse: mailbox.specialUse ??
+                    (mailbox.path.toUpperCase() === 'INBOX' ? '\\Inbox' : undefined),
+                messages,
+                unseen,
+            };
+        }));
+        return JSON.stringify({ ok: true, mailboxes });
+    }));
+    // ── email_get_mailbox_status ────────────────────────────────────
+    server.registerTool('email_get_mailbox_status', {
+        description: 'Get mailbox status: total count, unread count, and optionally the latest unread message subjects.',
+        inputSchema: z.object({
+            mailbox: z.string().optional().describe('Mailbox/folder name (defaults to INBOX)'),
+            includeLatest: z
+                .boolean()
+                .optional()
+                .describe('Include latest unread message summaries'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        ensureInitialized();
+        const mailbox = args.mailbox?.trim() || 'INBOX';
+        const includeLatest = args.includeLatest ?? false;
+        const client = await getConnection();
+        const status = await client.status(mailbox, {
+            messages: true,
+            unseen: true,
+        });
+        let latestUnread;
+        if (includeLatest) {
+            const lock = await getMailboxLock(mailbox);
+            try {
+                const unreadUidsResult = await client.search({ seen: false }, { uid: true });
+                const unreadUids = Array.isArray(unreadUidsResult) ? unreadUidsResult : [];
+                const latestUids = [...unreadUids].sort((a, b) => b - a).slice(0, 5);
+                latestUnread = [];
+                if (latestUids.length > 0) {
+                    for await (const message of client.fetch(latestUids, {
+                        uid: true,
+                        envelope: true,
+                    }, { uid: true })) {
+                        latestUnread.push({
+                            uid: message.uid,
+                            subject: message.envelope?.subject ?? '',
+                            from: formatAddresses(message.envelope?.from),
+                            date: formatDate(message.envelope?.date),
+                        });
+                    }
+                }
+                latestUnread.sort((a, b) => b.uid - a.uid);
+            }
+            finally {
+                lock.release();
+            }
+        }
+        return JSON.stringify({
+            ok: true,
+            mailbox,
+            total: status.messages ?? 0,
+            unread: status.unseen ?? 0,
+            ...(latestUnread ? { latestUnread } : {}),
+        });
+    }));
+}
+//# sourceMappingURL=mailbox.js.map

package/dist/tools/messages.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Message tools — search, get, move, and flag management.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerMessageTools(server: McpServer): void;
+//# sourceMappingURL=messages.d.ts.map

package/dist/tools/messages.js

@@ -0,0 +1,212 @@
+/**
+ * Message tools — search, get, move, and flag management.
+ */
+import { z } from 'zod';
+import { withErrorHandling } from '../utils.js';
+import { getConnection, getMailboxLock } from '../imap-client.js';
+import { ensureInitialized, formatAddresses, formatDate, downloadPartAsText, collectMessageParts, ensureMailboxExists, } from './shared.js';
+export function registerMessageTools(server) {
+    // ── email_search_messages ───────────────────────────────────────
+    server.registerTool('email_search_messages', {
+        description: 'Search for emails in a mailbox. Returns summaries with UIDs for use with email_get_message.',
+        inputSchema: z.object({
+            mailbox: z.string().min(1).describe('Mailbox/folder name to search (e.g. INBOX)'),
+            from: z.string().optional().describe('Filter by sender email or name'),
+            subject: z.string().optional().describe('Filter by subject text'),
+            unread: z.boolean().optional().describe('If true, return only unread messages'),
+            limit: z.number().positive().optional().describe('Maximum number of messages to return'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        ensureInitialized();
+        const mailbox = args.mailbox;
+        const from = args.from?.trim() || undefined;
+        const subject = args.subject?.trim() || undefined;
+        const unread = args.unread ?? false;
+        const limit = args.limit !== undefined ? Math.trunc(args.limit) : undefined;
+        const lock = await getMailboxLock(mailbox);
+        try {
+            const client = await getConnection();
+            const criteria = { all: true };
+            if (from) {
+                criteria.from = from;
+            }
+            if (subject) {
+                criteria.subject = subject;
+            }
+            if (unread) {
+                criteria.seen = false;
+            }
+            const uidSearchResult = await client.search(criteria, { uid: true });
+            const allUids = Array.isArray(uidSearchResult) ? uidSearchResult : [];
+            const sortedUids = [...allUids].sort((a, b) => b - a);
+            const targetUids = limit ? sortedUids.slice(0, limit) : sortedUids;
+            const messages = [];
+            if (targetUids.length > 0) {
+                for await (const message of client.fetch(targetUids, {
+                    uid: true,
+                    envelope: true,
+                    flags: true,
+                }, { uid: true })) {
+                    messages.push({
+                        uid: message.uid,
+                        subject: message.envelope?.subject ?? '',
+                        from: formatAddresses(message.envelope?.from),
+                        date: formatDate(message.envelope?.date),
+                        flags: message.flags ? [...message.flags] : [],
+                    });
+                }
+            }
+            messages.sort((a, b) => b.uid - a.uid);
+            return JSON.stringify({
+                ok: true,
+                messages,
+                ...(limit && sortedUids.length > limit ? { hasMore: true } : {}),
+            });
+        }
+        finally {
+            lock.release();
+        }
+    }));
+    // ── email_get_message ───────────────────────────────────────────
+    server.registerTool('email_get_message', {
+        description: 'Get full email content by UID. Returns headers, text/HTML body, and attachment metadata.',
+        inputSchema: z.object({
+            mailbox: z.string().min(1).describe('Mailbox/folder name that contains the message'),
+            uid: z.number().int().positive().describe('Message UID from email_search_messages'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        ensureInitialized();
+        const { mailbox, uid } = args;
+        const lock = await getMailboxLock(mailbox);
+        try {
+            const client = await getConnection();
+            const fetchedMessage = await client.fetchOne(uid, {
+                bodyStructure: true,
+                envelope: true,
+                flags: true,
+                uid: true,
+            }, { uid: true });
+            if (!fetchedMessage) {
+                throw new Error('Message not found for the specified UID');
+            }
+            const parts = { attachments: [] };
+            collectMessageParts(fetchedMessage.bodyStructure, parts);
+            const textBody = parts.textPart
+                ? await downloadPartAsText(uid, parts.textPart)
+                : '';
+            const htmlBody = parts.htmlPart
+                ? await downloadPartAsText(uid, parts.htmlPart)
+                : undefined;
+            const fallbackTextBody = !textBody && htmlBody
+                ? htmlBody.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim()
+                : textBody;
+            return JSON.stringify({
+                ok: true,
+                message: {
+                    uid: fetchedMessage.uid,
+                    subject: fetchedMessage.envelope?.subject ?? '',
+                    from: formatAddresses(fetchedMessage.envelope?.from),
+                    to: formatAddresses(fetchedMessage.envelope?.to),
+                    date: formatDate(fetchedMessage.envelope?.date),
+                    messageId: fetchedMessage.envelope?.messageId ?? null,
+                    textBody: fallbackTextBody,
+                    ...(htmlBody ? { htmlBody } : {}),
+                    attachments: parts.attachments,
+                },
+            });
+        }
+        finally {
+            lock.release();
+        }
+    }));
+    // ── email_move_messages ─────────────────────────────────────────
+    server.registerTool('email_move_messages', {
+        description: 'Move emails between folders by UID.',
+        inputSchema: z.object({
+            uids: z
+                .array(z.number().int().positive())
+                .min(1)
+                .describe('Array of message UIDs to move'),
+            mailbox: z.string().min(1).describe('Source mailbox/folder name'),
+            destination: z.string().min(1).describe('Destination mailbox/folder name'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        ensureInitialized();
+        const { uids, mailbox, destination } = args;
+        await ensureMailboxExists(destination);
+        const lock = await getMailboxLock(mailbox);
+        try {
+            const client = await getConnection();
+            try {
+                const moveResult = await client.messageMove(uids, destination, {
+                    uid: true,
+                });
+                if (!moveResult) {
+                    throw new Error('MOVE command failed');
+                }
+                return JSON.stringify({
+                    ok: true,
+                    moved: moveResult.uidMap ? moveResult.uidMap.size : uids.length,
+                });
+            }
+            catch {
+                const copyResult = await client.messageCopy(uids, destination, {
+                    uid: true,
+                });
+                if (!copyResult) {
+                    throw new Error('Unable to copy messages to destination mailbox');
+                }
+                await client.messageFlagsAdd(uids, ['\\Deleted'], { uid: true });
+                await client.messageDelete(uids, { uid: true });
+                return JSON.stringify({
+                    ok: true,
+                    moved: uids.length,
+                });
+            }
+        }
+        finally {
+            lock.release();
+        }
+    }));
+    // ── email_set_flags ─────────────────────────────────────────────
+    server.registerTool('email_set_flags', {
+        description: 'Set or remove flags on messages. Common flags: \\Seen (read), \\Flagged (starred).',
+        inputSchema: z.object({
+            uids: z
+                .array(z.number().int().positive())
+                .min(1)
+                .describe('Array of message UIDs to update'),
+            mailbox: z.string().min(1).describe('Mailbox/folder containing the messages'),
+            action: z.enum(['add', 'remove']).describe('Whether to add or remove flags'),
+            flags: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe('Flags to update (e.g. \\Seen, \\Flagged)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        ensureInitialized();
+        const { uids, mailbox, action, flags } = args;
+        const lock = await getMailboxLock(mailbox);
+        try {
+            const client = await getConnection();
+            const success = action === 'add'
+                ? await client.messageFlagsAdd(uids, flags, { uid: true })
+                : await client.messageFlagsRemove(uids, flags, { uid: true });
+            if (!success) {
+                throw new Error('Unable to update message flags');
+            }
+            return JSON.stringify({
+                ok: true,
+                updated: uids.length,
+            });
+        }
+        finally {
+            lock.release();
+        }
+    }));
+}
+//# sourceMappingURL=messages.js.map

package/dist/tools/send.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Send/draft tools — sending emails and saving drafts.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSendTools(server: McpServer): void;
+//# sourceMappingURL=send.d.ts.map

package/dist/tools/send.js

@@ -0,0 +1,131 @@
+/**
+ * Send/draft tools — sending emails and saving drafts.
+ */
+import { z } from 'zod';
+import nodemailer from 'nodemailer';
+import { withErrorHandling } from '../utils.js';
+import { getConnection } from '../imap-client.js';
+import { getTransport } from '../smtp-client.js';
+import { ensureInitialized, generateMessageId, resolveDraftsMailbox, } from './shared.js';
+export function registerSendTools(server) {
+    // ── email_send ──────────────────────────────────────────────────
+    server.registerTool('email_send', {
+        description: 'Send an email. For replies, provide reply_to_message_id from the original message.',
+        inputSchema: z.object({
+            to: z
+                .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+                .describe('Recipient email address or array of addresses'),
+            subject: z.string().optional().describe('Email subject line'),
+            text: z.string().optional().describe('Plain-text email body'),
+            html: z.string().optional().describe('HTML email body'),
+            cc: z
+                .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+                .optional()
+                .describe('CC recipient(s)'),
+            bcc: z
+                .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+                .optional()
+                .describe('BCC recipient(s)'),
+            reply_to_message_id: z
+                .string()
+                .optional()
+                .describe('Message-ID of the original email when replying'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const config = ensureInitialized();
+        const { to, subject, text, html, cc, bcc, reply_to_message_id } = args;
+        const messageId = generateMessageId(config.email);
+        const transport = await getTransport();
+        await transport.sendMail({
+            from: config.email,
+            to,
+            cc,
+            bcc,
+            subject,
+            text,
+            html,
+            messageId,
+            ...(reply_to_message_id
+                ? {
+                    inReplyTo: reply_to_message_id,
+                    references: reply_to_message_id,
+                }
+                : {}),
+        });
+        return JSON.stringify({ ok: true, messageId });
+    }));
+    // ── email_save_draft ────────────────────────────────────────────
+    server.registerTool('email_save_draft', {
+        description: 'Save a draft email to the Drafts folder.',
+        inputSchema: z.object({
+            to: z
+                .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+                .optional()
+                .describe('Recipient email address or array of addresses'),
+            subject: z.string().optional().describe('Draft subject line'),
+            text: z.string().optional().describe('Plain-text draft body'),
+            html: z.string().optional().describe('HTML draft body'),
+            reply_to_message_id: z
+                .string()
+                .optional()
+                .describe('Message-ID of the original email when drafting a reply'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const config = ensureInitialized();
+        const { to, subject, text, html, reply_to_message_id } = args;
+        const hasSubject = Boolean(subject && subject.trim().length > 0);
+        const hasBody = Boolean(text && text.trim().length > 0) ||
+            Boolean(html && html.trim().length > 0);
+        if (!hasSubject && !hasBody) {
+            throw new Error('Provide at least a subject or a text/html body');
+        }
+        const messageId = generateMessageId(config.email);
+        const draftTransport = nodemailer.createTransport({
+            streamTransport: true,
+            buffer: true,
+            newline: 'unix',
+        });
+        const draftResult = await draftTransport.sendMail({
+            from: config.email,
+            to,
+            subject,
+            text,
+            html,
+            messageId,
+            ...(reply_to_message_id
+                ? {
+                    inReplyTo: reply_to_message_id,
+                    references: reply_to_message_id,
+                }
+                : {}),
+        });
+        draftTransport.close();
+        const rawMessageValue = draftResult.message;
+        const rawMessage = Buffer.isBuffer(rawMessageValue)
+            ? rawMessageValue
+            : typeof rawMessageValue === 'string'
+                ? Buffer.from(rawMessageValue)
+                : null;
+        if (!rawMessage) {
+            throw new Error('Unable to construct raw draft message');
+        }
+        const draftsMailbox = await resolveDraftsMailbox();
+        const client = await getConnection();
+        const appendResult = await client.append(draftsMailbox, rawMessage, [
+            '\\Draft',
+            '\\Seen',
+        ]);
+        if (!appendResult) {
+            throw new Error('Unable to append draft message');
+        }
+        return JSON.stringify({
+            ok: true,
+            messageId,
+            mailbox: draftsMailbox,
+            ...(appendResult.uid !== undefined ? { uid: appendResult.uid } : {}),
+        });
+    }));
+}
+//# sourceMappingURL=send.js.map

package/dist/tools/shared.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared utilities for email-imap tool handlers.
+ */
+import type { Readable } from 'node:stream';
+import type { MessageAddressObject, MessageStructureObject } from 'imapflow';
+import type { ClientConfig } from '../types.js';
+export declare function setClientConfig(config: ClientConfig | null): void;
+export declare function getClientConfig(): ClientConfig | null;
+export declare function ensureInitialized(): ClientConfig;
+/**
+ * Attachment metadata from a parsed message.
+ */
+export interface AttachmentMetadata {
+    filename: string | null;
+    contentType: string;
+    size: number;
+}
+/**
+ * Parsed message parts (text, html, attachments).
+ */
+export interface MessageParts {
+    textPart?: string;
+    htmlPart?: string;
+    attachments: AttachmentMetadata[];
+}
+/**
+ * Format email addresses for display.
+ */
+export declare function formatAddresses(addresses?: MessageAddressObject[]): string;
+/**
+ * Format a date value to ISO string.
+ */
+export declare function formatDate(date: Date | string | undefined): string | null;
+/**
+ * Generate a unique Message-ID for an email.
+ */
+export declare function generateMessageId(email: string): string;
+/**
+ * Read a stream into a Buffer.
+ */
+export declare function streamToBuffer(stream: Readable): Promise<Buffer>;
+/**
+ * Download a message part as text by UID and part number.
+ */
+export declare function downloadPartAsText(uid: number, part: string): Promise<string>;
+/**
+ * Recursively collect text/html parts and attachments from a message structure.
+ */
+export declare function collectMessageParts(node: MessageStructureObject | undefined, parts: MessageParts): void;
+/**
+ * Remove duplicates from an array, preserving order (case-insensitive).
+ */
+export declare function uniquePreserveOrder(values: string[]): string[];
+/**
+ * Resolve the drafts mailbox name for the current account.
+ */
+export declare function resolveDraftsMailbox(): Promise<string>;
+/**
+ * Ensure a mailbox exists, creating it if necessary.
+ */
+export declare function ensureMailboxExists(mailbox: string): Promise<void>;
+//# sourceMappingURL=shared.d.ts.map