hypermail-mcp 0.7.19 → 0.7.20

package/README.md

@@ -3,6 +3,14 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **v0.7.20** — Hardened long-running IMAP and new-email polling paths:
+> IMAP connections now use explicit connection/greeting/socket/operation
+> timeouts, reset stuck connections, and report post-TLS authentication
+> failures with account-specific remediation guidance. `get_new_emails` now
+> applies per-account timeouts during candidate collection and hydration so one
+> hanging account does not block all-account polling; partial timeout failures
+> are returned alongside successful accounts' emails.
+>
 > **v0.7.19** — Hardened Outlook ID handling when Microsoft Graph `$search`
 > returns IDs that `/me/messages/{id}` rejects as malformed: `search_emails`
 > now returns a translated readable immutable ID when available, and
@@ -344,7 +352,9 @@ tool on their own schedule, for example every 30–60 seconds.
 - `limit: 0` can initialize/check state without fetching message bodies.
 
 All-account calls return partial failures as `errors: [{ account, message }]`
-and still return successful accounts' emails.
+and still return successful accounts' emails. Pollers should continue processing
+returned emails when `errors` is non-empty, and use those entries to notify or
+log which accounts are failing.
 
 See [`examples/hermes/`](examples/hermes/) for a Hermes scheduler integration
 that polls this tool and hands new-email payloads to a Hermes agent.
@@ -373,6 +383,13 @@ that polls this tool and hands new-email payloads to a Hermes agent.
    it returns `{ "status": "ready", "account": {...} }`.
 5. From then on, any tool can be called with `account: "<that-email>"`.
 
+### IMAP
+
+IMAP accounts are added synchronously with host/user/password settings. If the
+server accepts TCP/TLS but closes during login, Hypermail reports an IMAP
+authentication failure. Check the mailbox password or app-password, confirm IMAP
+access is enabled by the provider, then re-add or update the account.
+
 ### Gmail
 
 Gmail uses Google OAuth 2.0, matching the official Gmail MCP model. Google's

package/dist/cli.js

@@ -8625,19 +8625,19 @@ var getRefs = (options) => {
 };
 
 // node_modules/.pnpm/zod-to-json-schema@3.25.2_zod@4.4.3/node_modules/zod-to-json-schema/dist/esm/errorMessages.js
-function addErrorMessage(res, key, errorMessage, refs) {
+function addErrorMessage(res, key, errorMessage2, refs) {
   if (!refs?.errorMessages)
     return;
-  if (errorMessage) {
+  if (errorMessage2) {
     res.errorMessage = {
       ...res.errorMessage,
-      [key]: errorMessage
+      [key]: errorMessage2
     };
   }
 }
-function setResponseValueAndErrors(res, key, value, errorMessage, refs) {
+function setResponseValueAndErrors(res, key, value, errorMessage2, refs) {
   res[key] = value;
-  addErrorMessage(res, key, errorMessage, refs);
+  addErrorMessage(res, key, errorMessage2, refs);
 }
 
 // node_modules/.pnpm/zod-to-json-schema@3.25.2_zod@4.4.3/node_modules/zod-to-json-schema/dist/esm/getRelativePath.js
@@ -9955,8 +9955,8 @@ var Protocol = class {
                   if (queuedMessage.type === "response") {
                     resolver(message);
                   } else {
-                    const errorMessage = message;
-                    const error = new McpError(errorMessage.error.code, errorMessage.error.message, errorMessage.error.data);
+                    const errorMessage2 = message;
+                    const error = new McpError(errorMessage2.error.code, errorMessage2.error.message, errorMessage2.error.data);
                     resolver(error);
                   }
                 } else {
@@ -11256,23 +11256,23 @@ var Server = class extends Protocol {
       const wrappedHandler = async (request, extra) => {
         const validatedRequest = safeParse2(CallToolRequestSchema, request);
         if (!validatedRequest.success) {
-          const errorMessage = validatedRequest.error instanceof Error ? validatedRequest.error.message : String(validatedRequest.error);
-          throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call request: ${errorMessage}`);
+          const errorMessage2 = validatedRequest.error instanceof Error ? validatedRequest.error.message : String(validatedRequest.error);
+          throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call request: ${errorMessage2}`);
         }
         const { params } = validatedRequest.data;
         const result = await Promise.resolve(handler(request, extra));
         if (params.task) {
           const taskValidationResult = safeParse2(CreateTaskResultSchema, result);
           if (!taskValidationResult.success) {
-            const errorMessage = taskValidationResult.error instanceof Error ? taskValidationResult.error.message : String(taskValidationResult.error);
-            throw new McpError(ErrorCode.InvalidParams, `Invalid task creation result: ${errorMessage}`);
+            const errorMessage2 = taskValidationResult.error instanceof Error ? taskValidationResult.error.message : String(taskValidationResult.error);
+            throw new McpError(ErrorCode.InvalidParams, `Invalid task creation result: ${errorMessage2}`);
           }
           return taskValidationResult.data;
         }
         const validationResult = safeParse2(CallToolResultSchema, result);
         if (!validationResult.success) {
-          const errorMessage = validationResult.error instanceof Error ? validationResult.error.message : String(validationResult.error);
-          throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call result: ${errorMessage}`);
+          const errorMessage2 = validationResult.error instanceof Error ? validationResult.error.message : String(validationResult.error);
+          throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call result: ${errorMessage2}`);
         }
         return validationResult.data;
       };
@@ -11767,12 +11767,12 @@ var McpServer = class {
    * @param errorMessage - The error message.
    * @returns The tool error result.
    */
-  createToolError(errorMessage) {
+  createToolError(errorMessage2) {
     return {
       content: [
         {
           type: "text",
-          text: errorMessage
+          text: errorMessage2
         }
       ],
       isError: true
@@ -11790,8 +11790,8 @@ var McpServer = class {
     const parseResult = await safeParseAsync2(schemaToParse, args);
     if (!parseResult.success) {
       const error = "error" in parseResult ? parseResult.error : "Unknown error";
-      const errorMessage = getParseErrorMessage(error);
-      throw new McpError(ErrorCode.InvalidParams, `Input validation error: Invalid arguments for tool ${toolName}: ${errorMessage}`);
+      const errorMessage2 = getParseErrorMessage(error);
+      throw new McpError(ErrorCode.InvalidParams, `Input validation error: Invalid arguments for tool ${toolName}: ${errorMessage2}`);
     }
     return parseResult.data;
   }
@@ -11815,8 +11815,8 @@ var McpServer = class {
     const parseResult = await safeParseAsync2(outputObj, result.structuredContent);
     if (!parseResult.success) {
       const error = "error" in parseResult ? parseResult.error : "Unknown error";
-      const errorMessage = getParseErrorMessage(error);
-      throw new McpError(ErrorCode.InvalidParams, `Output validation error: Invalid structured content for tool ${toolName}: ${errorMessage}`);
+      const errorMessage2 = getParseErrorMessage(error);
+      throw new McpError(ErrorCode.InvalidParams, `Output validation error: Invalid structured content for tool ${toolName}: ${errorMessage2}`);
     }
   }
   /**
@@ -12028,8 +12028,8 @@ var McpServer = class {
         const parseResult = await safeParseAsync2(argsObj, request.params.arguments);
         if (!parseResult.success) {
           const error = "error" in parseResult ? parseResult.error : "Unknown error";
-          const errorMessage = getParseErrorMessage(error);
-          throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for prompt ${request.params.name}: ${errorMessage}`);
+          const errorMessage2 = getParseErrorMessage(error);
+          throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for prompt ${request.params.name}: ${errorMessage2}`);
         }
         const args = parseResult.data;
         const cb = prompt.callback;
@@ -15276,6 +15276,10 @@ var OutlookProvider = class {
 // src/providers/imap/client.ts
 import { ImapFlow } from "imapflow";
 import nodemailer from "nodemailer";
+var IMAP_CONNECTION_TIMEOUT_MS = 15e3;
+var IMAP_GREETING_TIMEOUT_MS = 15e3;
+var IMAP_SOCKET_TIMEOUT_MS = 45e3;
+var IMAP_OPERATION_TIMEOUT_MS = 45e3;
 function isImapTokens(obj) {
   if (typeof obj !== "object" || obj === null) return false;
   const o = obj;
@@ -15290,10 +15294,12 @@ function extractTokens(account) {
   return account.tokens;
 }
 var ImapClient = class {
-  constructor(tokens) {
+  constructor(tokens, opts = {}) {
     this.tokens = tokens;
+    this.opts = opts;
   }
   tokens;
+  opts;
   imap = null;
   transporter = null;
   connecting = null;
@@ -15309,16 +15315,28 @@ var ImapClient = class {
         user: this.tokens.user,
         pass: this.tokens.password
       },
-      logger: false
+      logger: false,
+      connectionTimeout: IMAP_CONNECTION_TIMEOUT_MS,
+      greetingTimeout: IMAP_GREETING_TIMEOUT_MS,
+      socketTimeout: IMAP_SOCKET_TIMEOUT_MS
     });
     if (!this.connecting) {
-      this.connecting = this.imap.connect().catch((err) => {
-        this.imap = null;
-        this.connecting = null;
-        throw err;
+      this.log("connectStart");
+      this.connecting = this.withOperationTimeout("connect", this.imap.connect()).then(() => {
+        this.log("connectEnd");
+      }).catch((err) => {
+        const normalized = this.normalizeConnectError(err);
+        this.log("connectError", {
+          message: normalized.message,
+          code: imapErrorCode(err) ?? null,
+          authenticationFailed: hasAuthenticationFailedFlag(err)
+        });
+        this.resetImap();
+        throw normalized;
       });
     }
     await this.connecting;
+    if (!this.imap) throw new Error("IMAP connection unavailable after connect");
     return this.imap;
   }
   /** Get (or create) a nodemailer SMTP transporter. */
@@ -15345,7 +15363,17 @@ var ImapClient = class {
       () => void 0,
       () => void 0
     );
-    return run;
+    try {
+      return await this.withOperationTimeout("operation", run, () => {
+        this.imapQueue = Promise.resolve();
+        this.resetImap();
+      });
+    } catch (err) {
+      if (err instanceof ImapTimeoutError) {
+        this.log("operationTimeout", { message: err.message });
+      }
+      throw err;
+    }
   }
   /**
    * Acquire a mailbox lock and run `fn` with the mailbox selected.
@@ -15376,15 +15404,101 @@ var ImapClient = class {
       this.transporter = null;
     }
   }
+  resetImap() {
+    const imap = this.imap;
+    this.imap = null;
+    this.connecting = null;
+    if (imap) {
+      imap.logout().catch(() => {
+      });
+    }
+  }
+  async withOperationTimeout(operation, promise, onTimeout) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        onTimeout?.();
+        reject(new ImapTimeoutError(this.timeoutMessage(operation)));
+      }, IMAP_OPERATION_TIMEOUT_MS);
+    });
+    try {
+      return await Promise.race([promise, timeout]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  timeoutMessage(operation) {
+    return `IMAP ${operation} timed out after ${IMAP_OPERATION_TIMEOUT_MS}ms for account ${this.accountLabel()} (${this.tokens.host}:${this.tokens.port})`;
+  }
+  accountLabel() {
+    return this.opts.account ?? this.tokens.user;
+  }
+  normalizeConnectError(err) {
+    if (!isImapAuthenticationError(err)) {
+      return err instanceof Error ? err : new Error(String(err));
+    }
+    const code = imapErrorCode(err);
+    const codeSuffix = code ? ` Provider error code: ${code}.` : "";
+    return new Error(
+      `IMAP authentication failed for account ${this.accountLabel()} (${this.tokens.host}:${this.tokens.port}). Verify the password/app-password and IMAP access policy, then re-add or update the account.` + codeSuffix,
+      { cause: err }
+    );
+  }
+  log(event, fields = {}) {
+    (this.opts.logger ?? noopLogger).debug("imap", event, {
+      account: this.accountLabel(),
+      host: this.tokens.host,
+      port: this.tokens.port,
+      ...fields
+    });
+  }
 };
+var ImapTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ImapTimeoutError";
+  }
+};
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function isImapAuthenticationError(err) {
+  if (hasAuthenticationFailedFlag(err)) return true;
+  const code = imapErrorCode(err);
+  if (code === "ClosedAfterConnectTLS") return true;
+  const message = errorMessage(err).toLowerCase();
+  return message.includes("authentication failed") || message.includes("invalid credentials") || message.includes("login failed");
+}
+function hasAuthenticationFailedFlag(err) {
+  return readErrorField(err, "authenticationFailed") === true;
+}
+function imapErrorCode(err) {
+  const direct = readErrorField(err, "code");
+  if (typeof direct === "string" && direct !== "NoConnection") return direct;
+  const nested = readErrorField(readErrorField(err, "error"), "code");
+  if (typeof nested === "string") return nested;
+  if (typeof direct === "string") return direct;
+  return void 0;
+}
+function readErrorField(err, field) {
+  if (typeof err !== "object" || err === null) return void 0;
+  return err[field];
+}
 var ImapClientFactory = class {
+  constructor(logger = noopLogger) {
+    this.logger = logger;
+  }
+  logger;
   cache = /* @__PURE__ */ new Map();
   get(account) {
     const key = account.email.toLowerCase();
     const existing = this.cache.get(key);
     if (existing) return existing;
     const tokens = extractTokens(account);
-    const client = new ImapClient(tokens);
+    const client = new ImapClient(tokens, {
+      account: account.email,
+      logger: this.logger
+    });
     this.cache.set(key, client);
     return client;
   }
@@ -16155,12 +16269,13 @@ async function deleteFolder2(clients, account, folderId) {
 
 // src/providers/imap/index.ts
 var ImapProvider = class {
-  constructor(store) {
+  constructor(store, logger = noopLogger) {
     this.store = store;
+    this.clients = new ImapClientFactory(logger);
   }
   store;
   id = "imap";
-  clients = new ImapClientFactory();
+  clients;
   // ---------- account lifecycle ----------
   async addAccount(input) {
     if (!this.store) throw new Error("IMAP provider requires an AccountStore");
@@ -17345,7 +17460,7 @@ function buildRegistry(opts) {
     clientId: outlookCfg?.clientId,
     tenantId: outlookCfg?.tenantId
   }));
-  providers.set("imap", new ImapProvider(opts.store));
+  providers.set("imap", new ImapProvider(opts.store, opts.logger));
   const gmailCfg = opts.providers?.gmail;
   providers.set("gmail", new GmailProvider({
     store: opts.store,
@@ -17820,10 +17935,46 @@ function selectBody(msg, format) {
 
 // src/tools/new-emails.ts
 import { z as z4 } from "zod";
+
+// src/tools/new-emails-timeout.ts
+var ACCOUNT_POLL_TIMEOUT_MS = 45e3;
+var MISSING_RECEIVED_AT = "1970-01-01T00:00:00.000Z";
+function effectiveReceivedAt(receivedAt) {
+  return normalizeTimestamp2(receivedAt) ?? MISSING_RECEIVED_AT;
+}
+function normalizeTimestamp2(value) {
+  if (!value) return null;
+  const ms = Date.parse(value);
+  if (!Number.isFinite(ms)) return null;
+  return new Date(ms).toISOString();
+}
+function compareTimestamp2(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+async function withAccountPollTimeout(account, operation, promise) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      reject(
+        new Error(
+          `${operation} timed out after ${ACCOUNT_POLL_TIMEOUT_MS}ms for account ${account}`
+        )
+      );
+    }, ACCOUNT_POLL_TIMEOUT_MS);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// src/tools/new-emails.ts
 var DEFAULT_LIMIT = 10;
 var BODY_LIMIT = 2e4;
 var PAGE_SIZE = 100;
-var MISSING_RECEIVED_AT = "1970-01-01T00:00:00.000Z";
 function registerNewEmailTool(server, ctx) {
   const { store, registry, tools, logger = noopLogger } = ctx;
   if (!shouldRegister("get_new_emails", tools)) return;
@@ -17874,7 +18025,11 @@ function registerNewEmailTool(server, ctx) {
       if (args.account) {
         try {
           const { provider, account } = registry.resolveByEmail(args.account);
-          const result = await collectCandidatesForAccount(store, provider, account, logger);
+          const result = await withAccountPollTimeout(
+            account.email,
+            "collect new-email candidates",
+            collectCandidatesForAccount(store, provider, account, logger)
+          );
           const selected2 = oldestCandidatesFirst(result.candidates).slice(0, limit);
           logger.debug("get-new-emails", "selected", {
             account: result.account.email,
@@ -17884,7 +18039,11 @@ function registerNewEmailTool(server, ctx) {
             selectedReceivedAt: selected2.map((candidate) => candidate.timestamp),
             limit
           });
-          const emails2 = limit === 0 ? [] : await hydrateAndAdvance(store, provider, result.account, selected2, logger);
+          const emails2 = limit === 0 ? [] : await withAccountPollTimeout(
+            result.account.email,
+            "hydrate new emails",
+            hydrateAndAdvance(store, provider, result.account, selected2, logger)
+          );
           const data2 = { count: emails2.length, emails: emails2, errors: [] };
           logger.debug("get-new-emails", "end", {
             account: result.account.email,
@@ -17917,7 +18076,11 @@ function registerNewEmailTool(server, ctx) {
         accounts.map(async (stored) => {
           try {
             const { provider, account } = registry.resolveByEmail(stored.email);
-            const result = await collectCandidatesForAccount(store, provider, account, logger);
+            const result = await withAccountPollTimeout(
+              account.email,
+              "collect new-email candidates",
+              collectCandidatesForAccount(store, provider, account, logger)
+            );
             return {
               status: "ok",
               account: result.account,
@@ -17969,7 +18132,11 @@ function registerNewEmailTool(server, ctx) {
             try {
               return {
                 status: "ok",
-                emails: await hydrateAndAdvance(store, provider, account, accountCandidates, logger)
+                emails: await withAccountPollTimeout(
+                  email,
+                  "hydrate new emails",
+                  hydrateAndAdvance(store, provider, account, accountCandidates, logger)
+                )
               };
             } catch (err) {
               const message = errMsg(err);
@@ -18138,15 +18305,6 @@ function normalizeCheckpoint2(checkpoint) {
     deliveredIdsAtReceivedAt: checkpoint?.deliveredIdsAtReceivedAt ?? []
   };
 }
-function effectiveReceivedAt(receivedAt) {
-  return normalizeTimestamp2(receivedAt) ?? MISSING_RECEIVED_AT;
-}
-function normalizeTimestamp2(value) {
-  if (!value) return null;
-  const ms = Date.parse(value);
-  if (!Number.isFinite(ms)) return null;
-  return new Date(ms).toISOString();
-}
 function oldestCandidatesFirst(items) {
   return [...items].sort((a, b) => {
     const byTimestamp = compareTimestamp2(a.timestamp, b.timestamp);
@@ -18162,11 +18320,6 @@ function compareNewEmailOutputOldestFirst(a, b) {
   if (byTimestamp !== 0) return byTimestamp;
   return a.id.localeCompare(b.id);
 }
-function compareTimestamp2(a, b) {
-  if (a < b) return -1;
-  if (a > b) return 1;
-  return 0;
-}
 
 // src/tools/browse.ts
 function registerBrowseTools(server, ctx) {
@@ -19138,7 +19291,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.19",
+  version: "0.7.20",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {
@@ -19419,7 +19572,7 @@ async function startServer(opts) {
     toolsDisabled: config.tools?.disabled ?? null
   });
   const store = await AccountStore.open({ dataDir, logger });
-  const registry = buildRegistry({ store, providers: config.providers });
+  const registry = buildRegistry({ store, providers: config.providers, logger });
   const tools = resolveTools(config);
   const createServer = () => {
     const s = new McpServer(