@lengelhard/imap-email-mcp 1.7.2 → 1.7.4

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,27 @@
 # Changelog
 
+## 1.7.4
+
+### Added
+- `search_index` results carry `index.warning` when the index may be behind: the last full sync finished more than 15 minutes ago (for example "index last synced 3 hours ago, results may be missing recent mail"), the index has never completed a full sync, or a searched folder recorded an error. The existing `index` fields are unchanged. This makes a stalled background sync visible in every search instead of silent, following the overnight freeze of 18 Sep 2026.
+
+## 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
@@ -133,7 +136,7 @@ Some IMAP servers return incomplete results for body searches without reporting
 | `list_emails` | List emails newest first, with unread, flagged and date filters and paging |
 | `get_email` | Get an email by UID. Text by default; HTML (without inline images) on request |
 | `search_emails` | Live IMAP search across one or more folders: subject, from, to, cc, body, text, dates, flags |
-| `search_index` | Full-text search of the local index (when `INDEX_ENABLED=true`) |
+| `search_index` | Full-text search of the local index (when `INDEX_ENABLED=true`); `index.warning` flags a stale index or folder errors |
 | `index_status` | Per-folder index coverage, last sync and errors |
 | `sync_index` | Run an index sync now |
 | `list_drafts` | List all draft emails |

package/index.js

@@ -22,6 +22,7 @@ import path from 'path';
 import os from 'os';
 import { createRequire } from 'module';
 import {
+  setOpTimeout,
   SessionManager,
   openBox,
   queryUids,
@@ -377,7 +378,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       ...(localIndex ? [
         {
           name: 'search_index',
-          description: 'Full-text search of the local read-only mail index (subject, sender, recipients, attachment names and body text). Accent-insensitive: "Loic" matches "Loïc". Use this for content searches. Results carry folder and uid for get_email; a uid can be stale if the message was moved since the last sync, in which case get_email reports it as not found. Check index.complete in the response before treating zero results as proof that nothing exists.',
+          description: 'Full-text search of the local read-only mail index (subject, sender, recipients, attachment names and body text). Accent-insensitive: "Loic" matches "Loïc". Use this for content searches. Results carry folder and uid for get_email; a uid can be stale if the message was moved since the last sync, in which case get_email reports it as not found. Check index.complete in the response before treating zero results as proof that nothing exists. index.warning is present when the last full sync is older than 15 minutes or a searched folder has an error; pass it on to the user.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -792,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, {

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,14 +19,25 @@ 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;
+const STALE_AFTER_MS = 15 * 60 * 1000;
+
+function describeAge(ms) {
+  const minutes = Math.round(ms / 60000);
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? '' : 's'}`;
+  const hours = Math.round(ms / 3600000);
+  if (hours < 48) return `${hours} hour${hours === 1 ? '' : 's'}`;
+  const days = Math.round(ms / 86400000);
+  return `${days} day${days === 1 ? '' : 's'}`;
+}
 
 class LockLostError extends Error {
   constructor() {
@@ -118,6 +129,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 +339,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 +416,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 +465,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 +476,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 +500,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 +603,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,
@@ -615,6 +647,17 @@ export class LocalIndex {
 
     const st = this.status();
     const scope = folderList.length ? st.folders.filter((f) => folderList.includes(f.folder)) : st.folders;
+    const warnings = [];
+    const lastFullMs = Number(this._meta('last_full_sync') || 0);
+    if (!lastFullMs) {
+      warnings.push('index has never completed a full sync, results may be missing mail');
+    } else if (Date.now() - lastFullMs > STALE_AFTER_MS) {
+      warnings.push(`index last synced ${describeAge(Date.now() - lastFullMs)} ago, results may be missing recent mail`);
+    }
+    const errored = scope.filter((f) => f.last_error);
+    if (errored.length) {
+      warnings.push(`folder error${errored.length === 1 ? '' : 's'}: ${errored.map((f) => `${f.folder} (${f.last_error})`).join(', ')}; results from ${errored.length === 1 ? 'that folder' : 'those folders'} may be incomplete`);
+    }
     return {
       total_matches: total,
       returned: rows.length,
@@ -623,7 +666,8 @@ export class LocalIndex {
         complete: scope.length > 0 && scope.every((f) => f.complete && !f.last_error),
         sync_running: st.sync_running,
         oldest_folder_sync: scope.reduce((min, f) => (f.last_sync && (!min || f.last_sync < min) ? f.last_sync : min), null),
-        incomplete_folders: scope.filter((f) => !f.complete || f.last_error).map((f) => f.folder)
+        incomplete_folders: scope.filter((f) => !f.complete || f.last_error).map((f) => f.folder),
+        ...(warnings.length && { warning: warnings.join('; ') })
       },
       results: rows.map((r) => ({
         folder: r.folder,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lengelhard/imap-email-mcp",
-  "version": "1.7.2",
+  "version": "1.7.4",
   "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",