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

package/dist/tools/shared.js

@@ -0,0 +1,187 @@
+/**
+ * Shared utilities for email-imap tool handlers.
+ */
+import { randomUUID } from 'node:crypto';
+import { getConnection } from '../imap-client.js';
+import { getPreset } from '../presets.js';
+/**
+ * In-memory client config. Set by initClients(), read by tool handlers.
+ */
+let clientConfig = null;
+export function setClientConfig(config) {
+    clientConfig = config ? { ...config } : null;
+}
+export function getClientConfig() {
+    return clientConfig;
+}
+export function ensureInitialized() {
+    if (!clientConfig) {
+        throw new Error('Email clients are not initialized');
+    }
+    return clientConfig;
+}
+/**
+ * Format email addresses for display.
+ */
+export function formatAddresses(addresses) {
+    if (!addresses || addresses.length === 0) {
+        return '';
+    }
+    return addresses
+        .map((address) => {
+        if (!address.address) {
+            return '';
+        }
+        if (address.name) {
+            return `${address.name} <${address.address}>`;
+        }
+        return address.address;
+    })
+        .filter((entry) => entry.length > 0)
+        .join(', ');
+}
+/**
+ * Format a date value to ISO string.
+ */
+export function formatDate(date) {
+    if (!date) {
+        return null;
+    }
+    if (date instanceof Date) {
+        return date.toISOString();
+    }
+    const parsed = new Date(date);
+    return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+/**
+ * Generate a unique Message-ID for an email.
+ */
+export function generateMessageId(email) {
+    const [, domain = 'localhost'] = email.split('@');
+    return `<${randomUUID()}@${domain}>`;
+}
+/**
+ * Read a stream into a Buffer.
+ */
+export async function streamToBuffer(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        if (typeof chunk === 'string') {
+            chunks.push(Buffer.from(chunk));
+        }
+        else {
+            chunks.push(chunk);
+        }
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Download a message part as text by UID and part number.
+ */
+export async function downloadPartAsText(uid, part) {
+    const client = await getConnection();
+    const partData = await client.download(uid, part, { uid: true });
+    const content = await streamToBuffer(partData.content);
+    return content.toString('utf8');
+}
+/**
+ * Recursively collect text/html parts and attachments from a message structure.
+ */
+export function collectMessageParts(node, parts) {
+    if (!node) {
+        return;
+    }
+    if (Array.isArray(node.childNodes) && node.childNodes.length > 0) {
+        for (const childNode of node.childNodes) {
+            collectMessageParts(childNode, parts);
+        }
+        return;
+    }
+    const contentType = node.type.toLowerCase();
+    const partIdentifier = node.part ?? '1';
+    if (contentType === 'text/plain' && !parts.textPart) {
+        parts.textPart = partIdentifier;
+        return;
+    }
+    if (contentType === 'text/html' && !parts.htmlPart) {
+        parts.htmlPart = partIdentifier;
+        return;
+    }
+    const disposition = node.disposition?.toLowerCase();
+    const filename = node.dispositionParameters?.filename ?? node.parameters?.name ?? null;
+    const isAttachment = disposition === 'attachment' ||
+        (disposition === 'inline' && Boolean(filename)) ||
+        (Boolean(filename) && !contentType.startsWith('text/'));
+    if (!isAttachment) {
+        return;
+    }
+    parts.attachments.push({
+        filename,
+        contentType,
+        size: typeof node.size === 'number' ? node.size : 0,
+    });
+}
+/**
+ * Remove duplicates from an array, preserving order (case-insensitive).
+ */
+export function uniquePreserveOrder(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const key = value.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(value);
+    }
+    return result;
+}
+/**
+ * Resolve the drafts mailbox name for the current account.
+ */
+export async function resolveDraftsMailbox() {
+    const client = await getConnection();
+    const listedMailboxes = await client.list();
+    const mailboxByLowerName = new Map();
+    for (const mailbox of listedMailboxes) {
+        mailboxByLowerName.set(mailbox.path.toLowerCase(), mailbox.path);
+    }
+    const exactDrafts = mailboxByLowerName.get('drafts');
+    if (exactDrafts) {
+        return exactDrafts;
+    }
+    const specialUseDrafts = listedMailboxes.find((mailbox) => mailbox.specialUse === '\\Drafts');
+    if (specialUseDrafts) {
+        return specialUseDrafts.path;
+    }
+    const iCloudPreset = getPreset('icloud');
+    const yahooPreset = getPreset('yahoo');
+    const fallbackCandidates = uniquePreserveOrder([
+        'Drafts',
+        'Draft',
+        ...(iCloudPreset?.folderFallbacks.drafts ?? []),
+        ...(yahooPreset?.folderFallbacks.drafts ?? []),
+    ]);
+    for (const candidate of fallbackCandidates) {
+        const existing = mailboxByLowerName.get(candidate.toLowerCase());
+        if (existing) {
+            return existing;
+        }
+    }
+    const defaultMailbox = fallbackCandidates[0] ?? 'Drafts';
+    await client.mailboxCreate(defaultMailbox);
+    return defaultMailbox;
+}
+/**
+ * Ensure a mailbox exists, creating it if necessary.
+ */
+export async function ensureMailboxExists(mailbox) {
+    const client = await getConnection();
+    const listedMailboxes = await client.list();
+    const exists = listedMailboxes.some((entry) => entry.path.toLowerCase() === mailbox.toLowerCase());
+    if (!exists) {
+        await client.mailboxCreate(mailbox);
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/types.d.ts

@@ -0,0 +1,70 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class EmailImapError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+/**
+ * Provider preset configuration for well-known email providers.
+ */
+export interface ProviderPreset {
+    name: string;
+    imapHost: string;
+    imapPort: number;
+    imapTls: boolean;
+    smtpHost: string;
+    smtpPort: number;
+    smtpSecure: boolean;
+    authType: 'app-password';
+    folderFallbacks: Record<string, string[]>;
+    quirks?: string[];
+    emailDomains: string[];
+}
+/**
+ * Full client configuration for initializing IMAP and SMTP connections.
+ */
+export interface ClientConfig {
+    imapHost: string;
+    imapPort: number;
+    imapTls: boolean;
+    smtpHost: string;
+    smtpPort: number;
+    smtpSecure: boolean;
+    email: string;
+    password: string;
+}
+/**
+ * IMAP client configuration subset.
+ */
+export interface ImapClientConfig {
+    host: string;
+    port: number;
+    tls: boolean;
+    user: string;
+    pass: string;
+}
+/**
+ * SMTP client configuration subset.
+ */
+export interface SmtpClientConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    pass: string;
+}
+/**
+ * Interface for a mail transporter (abstracted for testing).
+ */
+export interface MailTransporter {
+    sendMail(mailOptions: Record<string, unknown>): Promise<{
+        messageId?: string;
+    }>;
+    close(): void;
+    verify?: () => Promise<boolean>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,12 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export class EmailImapError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'EmailImapError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On EmailImapError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { EmailImapError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On EmailImapError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof EmailImapError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mindstone-engineering/mcp-server-email-imap",
+  "version": "0.1.0",
+  "description": "Email IMAP/SMTP MCP server for Model Context Protocol hosts — supports iCloud Mail, Yahoo Mail, and custom IMAP providers",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-email-imap": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/email-imap"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/email-imap",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "imapflow": "^1.2.0",
+    "nodemailer": "^6.9.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@types/nodemailer": "^6.4.0",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}