@lengelhard/imap-email-mcp 1.7.1 → 1.7.3

package/.env.example

@@ -12,6 +12,8 @@ IMAP_HOST=imap.example.com
 # IMAP_AUTH_TIMEOUT=10000
 # IMAP_TLS_REJECT_UNAUTHORIZED=true
 # IMAP_IDLE_CLOSE_SECONDS=300
+# IMAP_OP_TIMEOUT_SECONDS=120
+# SENDER_NAME=
 
 # Optional - Local read-only search index (requires Node 22.13+)
 # INDEX_ENABLED=false

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.7.3
+
+### Fixed
+- A sync could hang forever and never release its lock, which silently froze the index until the server was restarted. This happened when the IMAP connection went silent without closing, for example after the machine slept: the underlying library never fails a command whose connection died, so the sync waited indefinitely. Every IMAP command now runs under a time limit (`IMAP_OP_TIMEOUT_SECONDS`, default 120). A command that expires drops the socket, the sync stops with the folder's error recorded, the lock is released, and the next scheduled sync reconnects.
+- The sync lock's heartbeat now stops when a run makes no progress for 5 minutes, so another server process can take over even if a run is stuck for some other reason.
+- Tool calls on a dead connection now fail with a clear timeout message instead of waiting out the 5-minute lease.
+- A connection idle for over a minute is checked with a cheap command before reuse, so the first call after a sleep reconnects in seconds instead of waiting for a timeout.
+- A socket-level inactivity timeout was added as a second line of defence.
+
+### Changed
+- `index_status` reports `command_timeout_seconds`.
+
+## 1.7.2
+
+### Added
+- `SENDER_NAME`: optional display name for outgoing mail. The From header becomes `Name <address>`, with non-ASCII names encoded. Unset means the bare address, as before.
+
 ## 1.7.1
 
 ### Fixed

package/README.md

@@ -98,6 +98,8 @@ Add to your config file:
 | `SMTP_PORT` | `465` | SMTP port |
 | `SMTP_SECURE` | `true` | Use secure SMTP |
 | `IMAP_IDLE_CLOSE_SECONDS` | `300` | Close the shared IMAP connection after this much inactivity |
+| `IMAP_OP_TIMEOUT_SECONDS` | `120` | Time limit for a single IMAP command. Set `0` to disable |
+| `SENDER_NAME` | none | Display name for outgoing mail (From becomes `Name <address>`) |
 | `INDEX_ENABLED` | `false` | Enable the local read-only search index |
 | `INDEX_DB_PATH` | see below | Location of the index database |
 | `INDEX_FOLDERS` | all but Trash/Junk | Comma-separated folders to index |
@@ -113,6 +115,7 @@ Some IMAP servers return incomplete results for body searches without reporting
 - **Sync.** Newest mail first, in the background, every few minutes. Moves and deletes are picked up on the next sync; moves made through this server trigger a sync of the affected folders within seconds.
 - **Storage.** A single SQLite file, created with owner-only permissions. Default location on macOS: `~/Library/Application Support/imap-email-mcp/index-<account>.sqlite`; elsewhere `~/.local/share/imap-email-mcp/`. It contains the text of your mail, so keep the disk encrypted. Deleting the file is safe; it is rebuilt on the next start.
 - **Several processes.** Some clients start more than one copy of the server. They share the index file: one process syncs at a time (a lock file next to the database), and all of them answer searches. A lock left by a process that died is taken over after at most 3 minutes.
+- **Recovery.** If the connection dies silently, the running sync gives up at the command time limit, records the error and releases its lock. The next sync reconnects on its own.
 - **Requirements.** Node 22.13 or later (uses the built-in `node:sqlite`, no native modules).
 
 ### Provider Settings

package/index.js

@@ -22,6 +22,7 @@ import path from 'path';
 import os from 'os';
 import { createRequire } from 'module';
 import {
+  setOpTimeout,
   SessionManager,
   openBox,
   queryUids,
@@ -130,6 +131,20 @@ const SMTP_CONFIG = {
   }
 };
 
+// Optional display name for outgoing mail. When unset, behaviour is unchanged
+// and the From header is the bare address.
+const SENDER_NAME = process.env.SENDER_NAME || '';
+
+// Build an RFC 5322 From value. ASCII names are quoted; anything else is
+// encoded as an RFC 2047 encoded-word so accents survive transport.
+function formatFrom(address) {
+  if (!SENDER_NAME) return address;
+  const name = /^[\x20-\x7E]*$/.test(SENDER_NAME)
+    ? `"${SENDER_NAME.replace(/["\\]/g, '\\$&')}"`
+    : `=?UTF-8?B?${Buffer.from(SENDER_NAME, 'utf8').toString('base64')}?=`;
+  return `${name} <${address}>`;
+}
+
 // Traverse the raw IMAP MIME struct to find all attachment parts.
 //
 // Detection rules (in priority order):
@@ -778,6 +793,8 @@ function normalizeSubject(subject) {
   return subject.replace(/^(\s*(Re|Fwd|Fw)\s*:\s*)+/i, '').trim();
 }
 
+setOpTimeout(parseFloat(process.env.IMAP_OP_TIMEOUT_SECONDS || '120') * 1000);
+
 // Shared IMAP session. connectIMAP() returns a lease on one persistent
 // connection; connection.end() releases the lease instead of logging out.
 const sessions = new SessionManager(IMAP_CONFIG, {
@@ -1134,7 +1151,7 @@ async function handleTool(name, args) {
           // Build RFC 2822 compliant email message
           const boundary = `----=_Part_${Date.now()}`;
           let message = '';
-          message += `From: ${IMAP_CONFIG.imap.user}\r\n`;
+          message += `From: ${formatFrom(IMAP_CONFIG.imap.user)}\r\n`;
           message += `To: ${args.to}\r\n`;
           if (args.cc) message += `Cc: ${args.cc}\r\n`;
           if (args.bcc) message += `Bcc: ${args.bcc}\r\n`;
@@ -1180,7 +1197,7 @@ async function handleTool(name, args) {
 
           const boundary = `----=_Part_${Date.now()}`;
           let message = '';
-          message += `From: ${IMAP_CONFIG.imap.user}\r\n`;
+          message += `From: ${formatFrom(IMAP_CONFIG.imap.user)}\r\n`;
           message += `To: ${args.to}\r\n`;
           if (args.cc) message += `Cc: ${args.cc}\r\n`;
           if (args.bcc) message += `Bcc: ${args.bcc}\r\n`;
@@ -1221,7 +1238,9 @@ async function handleTool(name, args) {
         const transporter = nodemailer.createTransport(SMTP_CONFIG);
 
         const mailOptions = {
-          from: SMTP_CONFIG.auth.user,
+          from: SENDER_NAME
+            ? { name: SENDER_NAME, address: SMTP_CONFIG.auth.user }
+            : SMTP_CONFIG.auth.user,
           to: args.to,
           subject: args.subject,
           text: args.body,
@@ -1238,7 +1257,7 @@ async function handleTool(name, args) {
         const sentDate = new Date();
         const boundary = `----=_Part_${Date.now()}`;
         let rawMessage = '';
-        rawMessage += `From: ${SMTP_CONFIG.auth.user}\r\n`;
+        rawMessage += `From: ${formatFrom(SMTP_CONFIG.auth.user)}\r\n`;
         rawMessage += `To: ${args.to}\r\n`;
         if (args.cc) rawMessage += `Cc: ${args.cc}\r\n`;
         if (args.bcc) rawMessage += `Bcc: ${args.bcc}\r\n`;

package/lib/imap-session.js

@@ -17,13 +17,61 @@ import imaps from 'imap-simple';
 
 const DEFAULT_IDLE_CLOSE_MS = 5 * 60 * 1000;
 const DEFAULT_LEASE_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_OP_TIMEOUT_MS = 120 * 1000;
+const VALIDATE_AFTER_IDLE_MS = 60 * 1000;
+const VALIDATE_TIMEOUT_MS = 10 * 1000;
+
+/**
+ * A command that never comes back.
+ *
+ * node-imap does not fail pending commands when the socket dies, so a
+ * connection that goes silent (a sleeping laptop, a server that drops the
+ * connection without a FIN) leaves the caller waiting forever. Every IMAP
+ * command therefore runs under its own time limit.
+ */
+export class ImapTimeoutError extends Error {
+  constructor(label, ms) {
+    super(`IMAP ${label} timed out after ${Math.round(ms / 1000)}s (connection dropped, will reconnect)`);
+    this.code = 'IMAP_TIMEOUT';
+  }
+}
+
+let opTimeoutMs = DEFAULT_OP_TIMEOUT_MS;
+
+/** Set the per-command time limit. 0 disables it. */
+export function setOpTimeout(ms) {
+  opTimeoutMs = Number(ms) >= 0 ? Number(ms) : DEFAULT_OP_TIMEOUT_MS;
+}
+
+export function getOpTimeout() {
+  return opTimeoutMs;
+}
+
+/** Run one IMAP command under a time limit, destroying the socket if it expires. */
+export function withTimeout(connection, label, promise, ms = opTimeoutMs) {
+  if (!ms) return promise;
+  let timer;
+  const guard = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      // Kill the socket so the session opens a fresh one next time.
+      try { connection.imap.destroy(); } catch { /* ignore */ }
+      reject(new ImapTimeoutError(label, ms));
+    }, ms);
+  });
+  return Promise.race([promise, guard]).finally(() => clearTimeout(timer));
+}
 
 function withKeepalive(config) {
   // NOOP-based keepalive is more predictable than IDLE behind proxies.
+  // socketTimeout is a second line of defence: it kills a socket that goes
+  // quiet even when no command is pending.
   return {
     ...config,
     imap: {
       keepalive: { interval: 60000, idleInterval: 300000, forceNoop: true },
+      connTimeout: 20000,
+      authTimeout: 10000,
+      socketTimeout: opTimeoutMs ? opTimeoutMs + 60000 : 0,
       ...config.imap
     }
   };
@@ -38,6 +86,7 @@ export class SessionManager {
     this.log = log;
     this.conn = null;
     this.connecting = null;
+    this.lastUsedAt = 0;
     this.tail = Promise.resolve();
     this.idleTimer = null;
   }
@@ -100,6 +149,19 @@ export class SessionManager {
       let conn;
       try {
         conn = await this._connect();
+        // A connection that has been idle may be dead without knowing it
+        // (laptop sleep, silent server drop). Check it cheaply first so the
+        // caller does not wait out the full command timeout.
+        if (this.lastUsedAt && Date.now() - this.lastUsedAt > VALIDATE_AFTER_IDLE_MS) {
+          try {
+            await withTimeout(conn, 'STATUS (health check)', new Promise((resolve, reject) => {
+              conn.imap.status('INBOX', (err) => (err ? reject(err) : resolve()));
+            }), VALIDATE_TIMEOUT_MS);
+          } catch (err) {
+            this._drop(conn, `health check failed: ${err.message}`);
+            conn = await this._connect();
+          }
+        }
       } catch (err) {
         releaseLock();
         this._armIdleTimer();
@@ -110,6 +172,7 @@ export class SessionManager {
       const release = () => {
         if (released) return;
         released = true;
+        this.lastUsedAt = Date.now();
         clearTimeout(watchdog);
         if (!this._isUsable(conn)) this._drop(conn, 'unusable after call');
         this._armIdleTimer();
@@ -141,13 +204,24 @@ export class SessionManager {
 
 /** Open a mailbox. readOnly uses EXAMINE, which never changes flags. */
 export function openBox(connection, name, readOnly = false) {
-  return new Promise((resolve, reject) => {
+  return withTimeout(connection, `open ${name}`, new Promise((resolve, reject) => {
     try {
       connection.imap.openBox(name, readOnly, (err, box) => (err ? reject(err) : resolve(box)));
     } catch (err) {
       reject(err);
     }
-  });
+  }));
+}
+
+/** UID SEARCH ALL for the open mailbox. */
+export function uidSearchAll(connection) {
+  return withTimeout(connection, 'search', new Promise((resolve, reject) => {
+    try {
+      connection.imap.search(['ALL'], (err, uids) => (err ? reject(err) : resolve((uids || []).map(Number))));
+    } catch (err) {
+      reject(err);
+    }
+  }));
 }
 
 export function serverSupports(connection, cap) {
@@ -163,7 +237,7 @@ export function queryUids(connection, criteria, { order = 'arrival' } = {}) {
   const imap = connection.imap;
   const crit = criteria && criteria.length ? criteria : ['ALL'];
   const key = order === 'date' ? '-DATE' : '-ARRIVAL';
-  return new Promise((resolve, reject) => {
+  return withTimeout(connection, 'search', new Promise((resolve, reject) => {
     const done = (err, uids) => (err ? reject(err) : resolve((uids || []).map(Number)));
     try {
       if (serverSupports(connection, 'SORT')) {
@@ -177,7 +251,7 @@ export function queryUids(connection, criteria, { order = 'arrival' } = {}) {
     } catch (err) {
       reject(err);
     }
-  });
+  }));
 }
 
 /**
@@ -186,9 +260,9 @@ export function queryUids(connection, criteria, { order = 'arrival' } = {}) {
  * exist are simply absent from the result.
  */
 export function fetchMessages(connection, uids, options) {
-  return new Promise((resolve, reject) => {
+  if (!uids || !uids.length) return Promise.resolve(new Map());
+  return withTimeout(connection, `fetch ${uids.length} message(s)`, new Promise((resolve, reject) => {
     const out = new Map();
-    if (!uids || !uids.length) return resolve(out);
     let f;
     try {
       f = connection.imap.fetch(uids, options);
@@ -209,7 +283,7 @@ export function fetchMessages(connection, uids, options) {
     });
     f.once('error', reject);
     f.once('end', () => resolve(out));
-  });
+  }));
 }
 
 /** Find the header buffer in a fetched record and parse it into { name: [values] }. */

package/lib/local-index.js

@@ -19,13 +19,14 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
-import { SessionManager, openBox, fetchMessages, headerOf, localDate } from './imap-session.js';
+import { SessionManager, openBox, fetchMessages, headerOf, localDate, uidSearchAll, getOpTimeout } from './imap-session.js';
 import { planParts, partsToText } from './mime-text.js';
 
 const SCHEMA_VERSION = '1';
 const LOCK_STALE_MS = 3 * 60 * 1000;
 const LOCK_HEARTBEAT_MS = 30 * 1000;
 const REQUEST_RETRY_MS = 15 * 1000;
+const STALL_MS = 5 * 60 * 1000;
 const REQUEST_MAX_ATTEMPTS = 6;
 
 class LockLostError extends Error {
@@ -118,6 +119,7 @@ export class LocalIndex {
     this.db = null;
     this.running = null;
     this.timer = null;
+    this.progressAt = 0;
     this.debounce = null;
     this.pendingFolders = new Set();
     this.session = new SessionManager(imapConfig, { label: 'index', idleCloseMs: 60 * 1000, leaseTimeoutMs: 10 * 60 * 1000, log });
@@ -327,7 +329,20 @@ export class LocalIndex {
       if (!this._acquireLock()) {
         return { skipped: true, reason: `another server process (pid ${this.lockHolder}) is syncing the index` };
       }
-      const heartbeat = setInterval(() => this._touchLock(), LOCK_HEARTBEAT_MS);
+      this.progressAt = Date.now();
+      let stallLogged = false;
+      const heartbeat = setInterval(() => {
+        // Do not keep the lock alive for a run that is no longer moving:
+        // another process should be able to take over.
+        if (Date.now() - this.progressAt > STALL_MS) {
+          if (!stallLogged) {
+            stallLogged = true;
+            this.log('[index] sync has made no progress for 5 minutes, releasing the lock to another process');
+          }
+          return;
+        }
+        this._touchLock();
+      }, LOCK_HEARTBEAT_MS);
       if (heartbeat.unref) heartbeat.unref();
       try {
         const summary = await this._sync({ folders, maxPerFolder, passes });
@@ -391,6 +406,14 @@ export class LocalIndex {
             this.log(`[index] ${folder}: ${r.attempted} messages could not be fetched, will retry next sync`);
           }
         } catch (err) {
+          if (err.code === 'IMAP_TIMEOUT') {
+            summary.aborted = err.message;
+            this.db?.prepare(`INSERT INTO folders (name, last_error, last_sync) VALUES (?, ?, ?)
+              ON CONFLICT(name) DO UPDATE SET last_error = excluded.last_error`)
+              .run(folder, String(err.message).slice(0, 500), Date.now());
+            this.log(`[index] sync stopped: ${err.message}`);
+            break outer;
+          }
           if (err.code === 'LOCK_LOST' || !this.db) {
             summary.aborted = err.code === 'LOCK_LOST' ? err.message : 'index closed';
             this.log(`[index] sync stopped: ${summary.aborted}`);
@@ -432,6 +455,7 @@ export class LocalIndex {
 
   async _syncFolder(folder, maxPerFolder) {
     this._assertLock();
+    this.progressAt = Date.now();
     const conn = await this.session.acquire();
     try {
       const box = await openBox(conn, folder, true);
@@ -442,11 +466,7 @@ export class LocalIndex {
         this._wipeFolder(folder);
       }
 
-      const serverUids = box.messages.total
-        ? await new Promise((resolve, reject) => {
-          try { conn.imap.search(['ALL'], (e, u) => (e ? reject(e) : resolve((u || []).map(Number)))); } catch (e) { reject(e); }
-        })
-        : [];
+      const serverUids = box.messages.total ? await uidSearchAll(conn) : [];
       const serverSet = new Set(serverUids);
       const local = this.db.prepare('SELECT id, uid FROM messages WHERE folder = ?').all(folder);
       const localSet = new Set(local.map((r) => Number(r.uid)));
@@ -470,6 +490,7 @@ export class LocalIndex {
       let added = 0;
       for (let i = 0; i < todo.length; i += this.batchSize) {
         this._assertLock();
+        this.progressAt = Date.now();
         added += await this._indexBatch(conn, folder, uidvalidity, todo.slice(i, i + this.batchSize));
       }
 
@@ -572,6 +593,7 @@ export class LocalIndex {
       sync_running: !!this.running || lockLive,
       ...(lockLive && lock.pid !== process.pid && { sync_running_in_pid: lock.pid }),
       sync_interval_minutes: this.intervalMs / 60000,
+      command_timeout_seconds: getOpTimeout() / 1000,
       complete: folders.length > 0 && folders.every((f) => f.complete && !f.last_error),
       last_full_sync: lastFull ? new Date(lastFull).toISOString() : null,
       last_run: lastRun,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lengelhard/imap-email-mcp",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "MCP server for Claude Code that provides email capabilities through IMAP/SMTP. Read, search, compose, and manage emails from any IMAP provider.",
   "type": "module",
   "main": "index.js",