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

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/imap-client.d.ts

@@ -0,0 +1,21 @@
+import { ImapFlow, type MailboxLockObject } from 'imapflow';
+import type { ImapClientConfig } from './types.js';
+/**
+ * Initialize IMAP client with the given configuration.
+ * If the config is the same as the current one, this is a no-op.
+ * Otherwise, cleans up the existing connection before applying new config.
+ */
+export declare function initImap(nextConfig: ImapClientConfig): Promise<void>;
+/**
+ * Get an active IMAP connection, reconnecting if necessary.
+ */
+export declare function getConnection(): Promise<ImapFlow>;
+/**
+ * Acquire a mailbox lock, validating UID validity hasn't changed.
+ */
+export declare function getMailboxLock(mailbox: string): Promise<MailboxLockObject>;
+/**
+ * Clean up the IMAP connection and reset state.
+ */
+export declare function cleanup(): Promise<void>;
+//# sourceMappingURL=imap-client.d.ts.map

package/dist/imap-client.js

@@ -0,0 +1,144 @@
+import { ImapFlow } from 'imapflow';
+let config = null;
+let client = null;
+let connectPromise = null;
+const uidValidityByMailbox = new Map();
+let signalHandlersRegistered = false;
+function normalizeMailboxName(mailbox) {
+    return mailbox.toUpperCase() === 'INBOX' ? 'INBOX' : mailbox;
+}
+function sameConfig(a, b) {
+    return (a.host === b.host &&
+        a.port === b.port &&
+        a.tls === b.tls &&
+        a.user === b.user &&
+        a.pass === b.pass);
+}
+function registerSignalHandlers() {
+    if (signalHandlersRegistered) {
+        return;
+    }
+    signalHandlersRegistered = true;
+    const handleShutdown = () => {
+        void cleanup();
+    };
+    process.once('SIGTERM', handleShutdown);
+    process.once('SIGINT', handleShutdown);
+}
+/**
+ * Initialize IMAP client with the given configuration.
+ * If the config is the same as the current one, this is a no-op.
+ * Otherwise, cleans up the existing connection before applying new config.
+ */
+export async function initImap(nextConfig) {
+    registerSignalHandlers();
+    if (config && sameConfig(config, nextConfig)) {
+        return;
+    }
+    await cleanup();
+    config = { ...nextConfig };
+}
+async function createConnection() {
+    if (!config) {
+        throw new Error('IMAP client is not initialized');
+    }
+    const nextClient = new ImapFlow({
+        host: config.host,
+        port: config.port,
+        secure: config.tls,
+        auth: {
+            user: config.user,
+            pass: config.pass,
+        },
+        logger: false,
+    });
+    await nextClient.connect();
+    nextClient.on('close', () => {
+        if (client === nextClient) {
+            client = null;
+        }
+    });
+    client = nextClient;
+    return nextClient;
+}
+/**
+ * Get an active IMAP connection, reconnecting if necessary.
+ */
+export async function getConnection() {
+    if (connectPromise) {
+        return connectPromise;
+    }
+    if (client && client.usable) {
+        try {
+            await client.noop();
+            return client;
+        }
+        catch {
+            try {
+                client.close();
+            }
+            catch {
+                // ignore close errors
+            }
+            client = null;
+        }
+    }
+    connectPromise = createConnection().finally(() => {
+        connectPromise = null;
+    });
+    return connectPromise;
+}
+/**
+ * Acquire a mailbox lock, validating UID validity hasn't changed.
+ */
+export async function getMailboxLock(mailbox) {
+    const connection = await getConnection();
+    const lock = await connection.getMailboxLock(mailbox);
+    try {
+        const openedMailbox = connection.mailbox;
+        if (openedMailbox) {
+            const mailboxName = normalizeMailboxName(openedMailbox.path);
+            const previousUidValidity = uidValidityByMailbox.get(mailboxName);
+            const currentUidValidity = openedMailbox.uidValidity;
+            if (previousUidValidity !== undefined &&
+                previousUidValidity !== currentUidValidity) {
+                throw new Error('Mailbox was reorganized, please re-search');
+            }
+            uidValidityByMailbox.set(mailboxName, currentUidValidity);
+        }
+        return lock;
+    }
+    catch (error) {
+        lock.release();
+        throw error;
+    }
+}
+/**
+ * Clean up the IMAP connection and reset state.
+ */
+export async function cleanup() {
+    const activeClient = client;
+    client = null;
+    connectPromise = null;
+    uidValidityByMailbox.clear();
+    if (!activeClient) {
+        return;
+    }
+    try {
+        if (activeClient.usable) {
+            await activeClient.logout();
+        }
+        else {
+            activeClient.close();
+        }
+    }
+    catch {
+        try {
+            activeClient.close();
+        }
+        catch {
+            // ignore close errors
+        }
+    }
+}
+//# sourceMappingURL=imap-client.js.map

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * Email IMAP MCP Server
+ *
+ * Provides IMAP/SMTP email integration via Model Context Protocol.
+ * Supports multiple email providers: iCloud Mail, Yahoo Mail, and custom IMAP.
+ *
+ * Environment variables:
+ * - EMAIL_IMAP_EMAIL: Email address
+ * - EMAIL_IMAP_PASSWORD: App-specific password
+ * - EMAIL_IMAP_PROVIDER: Provider preset (icloud, yahoo, custom)
+ * - EMAIL_IMAP_IMAP_HOST: Custom IMAP server host
+ * - EMAIL_IMAP_IMAP_PORT: Custom IMAP server port (default: 993)
+ * - EMAIL_IMAP_SMTP_HOST: Custom SMTP server host
+ * - EMAIL_IMAP_SMTP_PORT: Custom SMTP server port (default: 587)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Email IMAP MCP Server
+ *
+ * Provides IMAP/SMTP email integration via Model Context Protocol.
+ * Supports multiple email providers: iCloud Mail, Yahoo Mail, and custom IMAP.
+ *
+ * Environment variables:
+ * - EMAIL_IMAP_EMAIL: Email address
+ * - EMAIL_IMAP_PASSWORD: App-specific password
+ * - EMAIL_IMAP_PROVIDER: Provider preset (icloud, yahoo, custom)
+ * - EMAIL_IMAP_IMAP_HOST: Custom IMAP server host
+ * - EMAIL_IMAP_IMAP_PORT: Custom IMAP server port (default: 993)
+ * - EMAIL_IMAP_SMTP_HOST: Custom SMTP server host
+ * - EMAIL_IMAP_SMTP_PORT: Custom SMTP server port (default: 587)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+import { initClients, getCredentials } from './tools/index.js';
+async function main() {
+    const server = createServer();
+    // Attempt to initialize from env vars at startup
+    const creds = getCredentials();
+    const email = creds.email.trim();
+    const password = creds.password.trim();
+    if (email && password) {
+        const provider = creds.provider.trim().toLowerCase() || 'icloud';
+        try {
+            await initClients({ email, password, provider });
+        }
+        catch (error) {
+            console.error('Failed to initialize Email IMAP clients from environment:', error);
+        }
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Email IMAP MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/presets.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderPreset } from './types.js';
+/**
+ * Get provider preset by name. Returns undefined for custom/unknown providers.
+ */
+export declare function getPreset(provider: string): ProviderPreset | undefined;
+/**
+ * Check if the given domain is a Yahoo-family domain.
+ */
+export declare function isYahooDomain(domain: string): boolean;
+//# sourceMappingURL=presets.d.ts.map

package/dist/presets.js

@@ -0,0 +1,56 @@
+const PRESETS = {
+    icloud: {
+        name: 'iCloud Mail',
+        imapHost: 'imap.mail.me.com',
+        imapPort: 993,
+        imapTls: true,
+        smtpHost: 'smtp.mail.me.com',
+        smtpPort: 587,
+        smtpSecure: false,
+        authType: 'app-password',
+        folderFallbacks: {
+            sent: ['Sent Messages', 'Sent'],
+            trash: ['Deleted Messages', 'Trash'],
+            junk: ['Junk'],
+            drafts: ['Drafts'],
+            archive: ['Archive'],
+        },
+        emailDomains: ['icloud.com', 'me.com', 'mac.com'],
+    },
+    yahoo: {
+        name: 'Yahoo Mail',
+        imapHost: 'imap.mail.yahoo.com',
+        imapPort: 993,
+        imapTls: true,
+        smtpHost: 'smtp.mail.yahoo.com',
+        smtpPort: 465,
+        smtpSecure: true,
+        authType: 'app-password',
+        folderFallbacks: {
+            sent: ['Sent'],
+            trash: ['Trash'],
+            junk: ['Bulk Mail', 'Spam'],
+            drafts: ['Draft', 'Drafts'],
+            archive: ['Archive'],
+        },
+        quirks: ['5 simultaneous IMAP connections per IP'],
+        emailDomains: [],
+    },
+};
+/**
+ * Get provider preset by name. Returns undefined for custom/unknown providers.
+ */
+export function getPreset(provider) {
+    return PRESETS[provider.toLowerCase()];
+}
+/**
+ * Check if the given domain is a Yahoo-family domain.
+ */
+export function isYahooDomain(domain) {
+    const normalized = domain.trim().toLowerCase();
+    return (normalized === 'ymail.com' ||
+        normalized === 'rocketmail.com' ||
+        normalized === 'yahoo.com' ||
+        normalized.startsWith('yahoo.'));
+}
+//# sourceMappingURL=presets.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerMailboxTools, registerMessageTools, registerSendTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'email-imap-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerMailboxTools(server);
+    registerMessageTools(server);
+    registerSendTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/smtp-client.d.ts

@@ -0,0 +1,15 @@
+import type { SmtpClientConfig, MailTransporter } from './types.js';
+/**
+ * Initialize SMTP transport with the given configuration.
+ * If the config is the same as the current one, this is a no-op.
+ */
+export declare function initSmtp(nextConfig: SmtpClientConfig): Promise<void>;
+/**
+ * Get the SMTP transport, creating it lazily if needed.
+ */
+export declare function getTransport(): Promise<MailTransporter>;
+/**
+ * Clean up the SMTP transport.
+ */
+export declare function cleanup(): Promise<void>;
+//# sourceMappingURL=smtp-client.d.ts.map

package/dist/smtp-client.js

@@ -0,0 +1,61 @@
+import nodemailer from 'nodemailer';
+let config = null;
+let transport = null;
+function sameConfig(a, b) {
+    return (a.host === b.host &&
+        a.port === b.port &&
+        a.secure === b.secure &&
+        a.user === b.user &&
+        a.pass === b.pass);
+}
+/**
+ * Initialize SMTP transport with the given configuration.
+ * If the config is the same as the current one, this is a no-op.
+ */
+export async function initSmtp(nextConfig) {
+    if (config && sameConfig(config, nextConfig)) {
+        return;
+    }
+    await cleanup();
+    config = { ...nextConfig };
+}
+/**
+ * Get the SMTP transport, creating it lazily if needed.
+ */
+export async function getTransport() {
+    if (transport) {
+        return transport;
+    }
+    if (!config) {
+        throw new Error('SMTP client is not initialized');
+    }
+    const nextTransport = nodemailer.createTransport({
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        auth: {
+            user: config.user,
+            pass: config.pass,
+        },
+    });
+    if (typeof nextTransport.verify === 'function') {
+        await nextTransport.verify();
+    }
+    transport = nextTransport;
+    return nextTransport;
+}
+/**
+ * Clean up the SMTP transport.
+ */
+export async function cleanup() {
+    if (!transport) {
+        return;
+    }
+    try {
+        transport.close();
+    }
+    finally {
+        transport = null;
+    }
+}
+//# sourceMappingURL=smtp-client.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Configure tool — credentials management and provider selection.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function getCredentials(): {
+    email: string;
+    password: string;
+    provider: string;
+};
+export declare function setCredentials(email: string, password: string, provider: string): void;
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,104 @@
+/**
+ * Configure tool — credentials management and provider selection.
+ */
+import { z } from 'zod';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { getPreset } from '../presets.js';
+import { EmailImapError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+import { initClients } from './index.js';
+/**
+ * Mutable env-level credential state.
+ * Updated when the configure tool is called, so subsequent tool calls
+ * use the new credentials even if the original env vars were empty.
+ */
+let EMAIL_IMAP_EMAIL = process.env.EMAIL_IMAP_EMAIL ?? '';
+let EMAIL_IMAP_PASSWORD = process.env.EMAIL_IMAP_PASSWORD ?? '';
+let EMAIL_IMAP_PROVIDER = process.env.EMAIL_IMAP_PROVIDER ?? '';
+export function getCredentials() {
+    return {
+        email: EMAIL_IMAP_EMAIL,
+        password: EMAIL_IMAP_PASSWORD,
+        provider: EMAIL_IMAP_PROVIDER,
+    };
+}
+export function setCredentials(email, password, provider) {
+    EMAIL_IMAP_EMAIL = email;
+    EMAIL_IMAP_PASSWORD = password;
+    EMAIL_IMAP_PROVIDER = provider;
+}
+export function registerConfigureTools(server) {
+    server.registerTool('configure_email_imap', {
+        description: 'Configure email account. Call this when the user provides their email and app-specific password. ' +
+            'For iCloud: generate an app-specific password at account.apple.com → Sign-In and Security → App-Specific Passwords ' +
+            '(guide: support.apple.com/en-gb/102654). For Yahoo: generate an app password at login.yahoo.com/myaccount/security/app-password.',
+        inputSchema: z.object({
+            email: z.string().min(1).describe('Email address for the account'),
+            password: z.string().min(1).describe('App-specific password for the account'),
+            provider: z
+                .string()
+                .optional()
+                .describe('Email provider preset (icloud, yahoo, or custom)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const email = args.email.trim();
+        const password = args.password.trim();
+        const providerArg = args.provider?.trim().toLowerCase() ?? '';
+        const provider = providerArg || EMAIL_IMAP_PROVIDER?.trim().toLowerCase() || 'icloud';
+        // For known providers, validate the preset
+        if (provider !== 'custom') {
+            const preset = getPreset(provider);
+            if (!preset) {
+                throw new EmailImapError(`Unsupported provider "${provider}". Supported providers: icloud, yahoo, custom.`, 'INVALID_PROVIDER', 'Use one of the supported providers or "custom" with explicit IMAP/SMTP settings.');
+            }
+        }
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/email-imap/configure', {
+                    email,
+                    password,
+                    provider,
+                });
+                if (result.success) {
+                    setCredentials(email, password, provider);
+                    await initClients({
+                        email,
+                        password,
+                        provider,
+                    });
+                    const preset = getPreset(provider);
+                    const providerName = preset?.name ?? provider;
+                    const message = result.warning
+                        ? `Email IMAP configured successfully. Note: ${result.warning}`
+                        : `Email IMAP configured successfully for ${providerName}.`;
+                    return JSON.stringify({ ok: true, message, provider });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new EmailImapError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof EmailImapError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new EmailImapError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge — configure directly
+        setCredentials(email, password, provider);
+        await initClients({
+            email,
+            password,
+            provider,
+        });
+        const preset = getPreset(provider);
+        const providerName = preset?.name ?? provider;
+        return JSON.stringify({
+            ok: true,
+            message: `Email IMAP configured successfully for ${providerName}.`,
+            provider,
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Email IMAP tool registration — aggregates all tool modules.
+ */
+export { registerMailboxTools } from './mailbox.js';
+export { registerMessageTools } from './messages.js';
+export { registerSendTools } from './send.js';
+export { registerConfigureTools, getCredentials, setCredentials } from './configure.js';
+/**
+ * Options for initializing email clients.
+ * Can be passed a full ClientConfig or simplified provider-based options.
+ */
+interface InitClientsOptions {
+    email: string;
+    password: string;
+    provider: string;
+    /** Explicit IMAP/SMTP config overrides (for custom provider) */
+    imapHost?: string;
+    imapPort?: number;
+    imapTls?: boolean;
+    smtpHost?: string;
+    smtpPort?: number;
+    smtpSecure?: boolean;
+}
+/**
+ * Initialize IMAP and SMTP clients from provider settings or explicit config.
+ */
+export declare function initClients(options: InitClientsOptions): Promise<void>;
+/**
+ * Clean up all email clients.
+ */
+export declare function cleanupClients(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map