@lengelhard/imap-email-mcp 1.8.0 → 1.8.1

package/.env.example

@@ -21,6 +21,7 @@ IMAP_HOST=imap.example.com
 # INDEX_FOLDERS=            (comma list; default: all folders except Trash and Junk)
 # INDEX_EXCLUDE_FOLDERS=    (comma list, added to the default exclusions)
 # INDEX_SYNC_INTERVAL_MINUTES=5
+# INDEX_SYNC_MAX_MINUTES=15     (wall-clock cap on one sync run; 0 disables)
 
 # Optional - SMTP Settings (defaults to IMAP values if not set)
 # SMTP_HOST=smtp.example.com

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.8.1
+
+### Fixed
+- A sync could still hang forever after a connection dropped. The folder LIST at the start of every run was the one IMAP command not under the 1.7.3 time limit, and node-imap never fails a command whose socket has died, so a run that started on a silent connection (a sleeping laptop, a dropped session) waited indefinitely with `sync_running: true`, blocking every later sync and every `sync_index` call. Seen on 18, 20 and 21 Sep 2026. The LIST now runs under the same limit as every other command.
+- As a backstop, every sync run has a wall-clock cap (`INDEX_SYNC_MAX_MINUTES`, default 15). A run that outlives it is aborted, its connection is dropped and its lease released, and the next scheduled sync starts clean. A run cut loose can no longer write to the index.
+- The next background sync is scheduled from the end of the previous run instead of a fixed timer, so a slow run cannot queue a pile-up behind itself.
+
+### Added
+- `index_status` reports `sync_running_since`, `sync_running_seconds` and `sync_max_minutes`, so a stuck sync is a visible number rather than a flag.
+- `sync_index` takes `force: true`, which aborts a running sync before starting a fresh one. The index is read-only against the server, so this is always safe.
+- `find_duplicates` takes `offset` and returns `has_more`, so more than 500 groups can be paged through instead of partitioned by date.
+
 ## 1.8.0
 
 ### Added

package/README.md

@@ -105,7 +105,8 @@ Add to your config file:
 | `INDEX_DB_PATH` | see below | Location of the index database |
 | `INDEX_FOLDERS` | all but Trash/Junk | Comma-separated folders to index |
 | `INDEX_EXCLUDE_FOLDERS` | none | Comma-separated folders to skip, on top of Trash/Junk |
-| `INDEX_SYNC_INTERVAL_MINUTES` | `5` | Background sync interval |
+| `INDEX_SYNC_INTERVAL_MINUTES` | `5` | Background sync interval, measured from the end of the previous run |
+| `INDEX_SYNC_MAX_MINUTES` | `15` | Wall-clock cap on one sync run; a run that outlives it is aborted and its connection dropped (`0` disables) |
 
 ### Local search index
 
@@ -147,8 +148,8 @@ Mail clients that file by tag sometimes append a fresh copy of a message instead
 | `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`); `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 |
+| `index_status` | Per-folder index coverage, last sync and errors; `sync_running_seconds` shows how long the current sync has run |
+| `sync_index` | Run an index sync now; `force: true` aborts a stuck sync first |
 | `find_duplicates` | Messages that exist more than once, matched on Message-ID: filed twice in one folder, or spread across folders |
 | `list_drafts` | List all draft emails |
 | `get_draft` | Get a specific draft by UID |

package/index.js

@@ -447,7 +447,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
           name: 'index_status',
-          description: 'Show the local index state: per-folder message counts on the server and in the index, whether backfill is complete, last sync time and errors.',
+          description: 'Show the local index state: per-folder message counts on the server and in the index, whether backfill is complete, last sync time and errors. sync_running_seconds says how long the current sync has been going; a value far beyond sync_max_minutes means it is stuck and sync_index with force: true will cut it loose.',
           inputSchema: { type: 'object', properties: {}, required: [] }
         },
         {
@@ -480,6 +480,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: 'Maximum groups to return (default: 50, max: 500). total_groups reports the full count.',
                 default: 50
               },
+              offset: {
+                type: 'number',
+                description: 'Skip this many groups, for paging (default: 0). has_more says whether another page exists.',
+                default: 0
+              },
               refresh: {
                 type: 'boolean',
                 description: 'Pick up new and moved mail before searching (default: true). Skipped while a background sync is running.',
@@ -491,7 +496,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         },
         {
           name: 'sync_index',
-          description: 'Run an index sync now and wait for it (up to wait_seconds). The index is read-only: syncing never changes anything on the mail server.',
+          description: 'Run an index sync now and wait for it (up to wait_seconds). The index is read-only: syncing never changes anything on the mail server. If a sync is already running the call waits on that one; pass force: true to abort it first and start fresh, which is the remedy for a sync that index_status shows as running far longer than sync_max_minutes.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -504,6 +509,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 type: 'number',
                 description: 'How long to wait before returning while the sync continues in the background (default: 60)',
                 default: 60
+              },
+              force: {
+                type: 'boolean',
+                description: 'Abort a sync that is already running before starting this one (default: false). Safe: the index is read-only against the server. Use when index_status shows sync_running_seconds far beyond sync_max_minutes.',
+                default: false
               }
             },
             required: []
@@ -1982,7 +1992,8 @@ async function handleTool(name, args) {
           scope: args.scope || 'all',
           since_date: args.since_date || null,
           before_date: args.before_date || null,
-          limit: args.limit
+          limit: args.limit,
+          offset: args.offset
         });
         if (refresh) found.index = { ...found.index, refresh };
         return { content: [{ type: 'text', text: JSON.stringify(found, null, 2) }] };
@@ -1991,7 +2002,16 @@ async function handleTool(name, args) {
       case 'sync_index': {
         if (!localIndex) throw new Error(localIndexError || 'Local index is not enabled (set INDEX_ENABLED=true)');
         const waitMs = Math.max(0, Number(args.wait_seconds ?? 60)) * 1000;
-        const alreadyRunning = !!localIndex.running;
+        let alreadyRunning = !!localIndex.running;
+        let forced = false;
+        if (alreadyRunning && args.force) {
+          const stuckFor = localIndex.runningSince ? Math.round((Date.now() - localIndex.runningSince) / 1000) : null;
+          forced = await Promise.race([
+            localIndex.abortSync(`forced by sync_index after ${stuckFor}s`),
+            new Promise((resolve) => setTimeout(() => resolve('timeout'), 15000))
+          ]);
+          alreadyRunning = !!localIndex.running;
+        }
         const run = localIndex.sync(args.folders?.length ? { folders: args.folders } : {});
         const outcome = await Promise.race([
           run.then((summary) => ({ finished: true, summary })),
@@ -2002,7 +2022,9 @@ async function handleTool(name, args) {
           content: [{
             type: 'text',
             text: JSON.stringify({
-              ...(alreadyRunning && { note: 'A sync was already running; waited on that one.' }),
+              ...(forced === true && { note: 'A running sync was aborted first (force: true) and a fresh one started.' }),
+              ...(forced === 'timeout' && { note: 'force: true was requested but the running sync did not release within 15s; waited on it instead.' }),
+              ...(alreadyRunning && !forced && { note: 'A sync was already running; waited on that one.' }),
               ...(skipped && { note: `Not started: ${outcome.summary.reason}. It keeps the index current; check index_status.` }),
               finished: skipped ? false : outcome.finished,
               ...(outcome.summary && !skipped && { summary: outcome.summary }),
@@ -2038,7 +2060,8 @@ async function main() {
         dbPath: process.env.INDEX_DB_PATH || undefined,
         folders: list(process.env.INDEX_FOLDERS),
         excludeFolders: list(process.env.INDEX_EXCLUDE_FOLDERS),
-        intervalMinutes: parseFloat(process.env.INDEX_SYNC_INTERVAL_MINUTES || '5')
+        intervalMinutes: parseFloat(process.env.INDEX_SYNC_INTERVAL_MINUTES || '5'),
+        maxRunMinutes: parseFloat(process.env.INDEX_SYNC_MAX_MINUTES || '15')
       }).open();
       localIndex.start();
       console.error(`Local index enabled: ${localIndex.dbPath}`);

package/lib/imap-session.js

@@ -89,6 +89,9 @@ export class SessionManager {
     this.lastUsedAt = 0;
     this.tail = Promise.resolve();
     this.idleTimer = null;
+    this.activeRelease = null;
+    this.generation = 0;
+    this.abortConnect = null;
   }
 
   _isUsable(conn) {
@@ -113,15 +116,34 @@ export class SessionManager {
   async _connect() {
     if (this._isUsable(this.conn)) return this.conn;
     if (!this.connecting) {
-      this.connecting = (async () => {
+      const generation = this.generation;
+      // dropCurrent() can reject this attempt at once, so a caller queued on a
+      // socket that will never answer does not wait out the connect timeout.
+      let abort;
+      const aborted = new Promise((_, reject) => { abort = reject; });
+      aborted.catch(() => {});
+      this.abortConnect = abort;
+      const dial = (async () => {
         const conn = await imaps.connect(this.config);
+        if (generation !== this.generation) {
+          // The caller that wanted this socket is gone; do not hand it to anyone.
+          try { conn.imap.destroy(); } catch { /* ignore */ }
+          throw new Error('connection attempt superseded');
+        }
         // Without an 'error' listener an idle socket error would crash the process.
         conn.on('error', (err) => this._drop(conn, `error: ${err && err.message}`));
         conn.imap.once('close', () => { if (this.conn === conn) this.conn = null; });
         conn.imap.once('end', () => { if (this.conn === conn) this.conn = null; });
         this.conn = conn;
         return conn;
-      })().finally(() => { this.connecting = null; });
+      })();
+      dial.catch(() => {});
+      const attempt = Promise.race([dial, aborted]);
+      attempt.then(() => {}, () => {}).then(() => {
+        if (this.connecting === attempt) this.connecting = null;
+        if (this.abortConnect === abort) this.abortConnect = null;
+      });
+      this.connecting = attempt;
     }
     return this.connecting;
   }
@@ -172,6 +194,7 @@ export class SessionManager {
       const release = () => {
         if (released) return;
         released = true;
+        if (this.activeRelease === release) this.activeRelease = null;
         this.lastUsedAt = Date.now();
         clearTimeout(watchdog);
         if (!this._isUsable(conn)) this._drop(conn, 'unusable after call');
@@ -185,6 +208,7 @@ export class SessionManager {
         release();
       }, this.leaseTimeoutMs);
       if (watchdog.unref) watchdog.unref();
+      this.activeRelease = release;
 
       return new Proxy(conn, {
         get(target, prop) {
@@ -196,12 +220,41 @@ export class SessionManager {
     });
   }
 
+  /**
+   * Drop the current connection (if any) so the next acquire() opens a fresh
+   * one. Used to cut a sync loose from a socket that has gone silent.
+   */
+  dropCurrent(reason) {
+    if (this.conn) this._drop(this.conn, reason);
+    // A connect attempt still pending belongs to the run being cut loose:
+    // fail it now and detach it, so the next acquire() starts its own.
+    this.generation++;
+    const abort = this.abortConnect;
+    this.abortConnect = null;
+    this.connecting = null;
+    if (abort) abort(new Error(`connection attempt aborted: ${reason}`));
+    // Release the lease the dropped connection was handed out under, so the
+    // next acquire() does not wait behind an owner that will never return.
+    if (this.activeRelease) this.activeRelease();
+  }
+
   close() {
     clearTimeout(this.idleTimer);
     if (this.conn) this._drop(this.conn, null);
   }
 }
 
+/** LIST all mailboxes, under the command time limit. */
+export function listBoxes(connection) {
+  return withTimeout(connection, 'list folders', new Promise((resolve, reject) => {
+    try {
+      connection.imap.getBoxes((err, boxes) => (err ? reject(err) : resolve(boxes)));
+    } catch (err) {
+      reject(err);
+    }
+  }));
+}
+
 /** Open a mailbox. readOnly uses EXAMINE, which never changes flags. */
 export function openBox(connection, name, readOnly = false) {
   return withTimeout(connection, `open ${name}`, new Promise((resolve, reject) => {

package/lib/local-index.js

@@ -19,7 +19,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
-import { SessionManager, openBox, fetchMessages, headerOf, localDate, uidSearchAll, getOpTimeout } from './imap-session.js';
+import { SessionManager, openBox, fetchMessages, headerOf, localDate, uidSearchAll, listBoxes, getOpTimeout } from './imap-session.js';
 import { planParts, partsToText } from './mime-text.js';
 
 const SCHEMA_VERSION = '1';
@@ -29,6 +29,7 @@ const REQUEST_RETRY_MS = 15 * 1000;
 const STALL_MS = 5 * 60 * 1000;
 const REQUEST_MAX_ATTEMPTS = 6;
 const STALE_AFTER_MS = 15 * 60 * 1000;
+const DEFAULT_MAX_RUN_MINUTES = 15;
 
 function describeAge(ms) {
   const minutes = Math.round(ms / 60000);
@@ -134,17 +135,23 @@ export function normalizeMessageId(value) {
 }
 
 export class LocalIndex {
-  constructor({ imapConfig, dbPath, folders = null, excludeFolders = [], intervalMinutes = 5, batchSize = 100, maxBodyChars = 100000, log = console.error }) {
+  constructor({ imapConfig, dbPath, folders = null, excludeFolders = [], intervalMinutes = 5, maxRunMinutes = DEFAULT_MAX_RUN_MINUTES, batchSize = 100, maxBodyChars = 100000, log = console.error }) {
     this.imapConfig = imapConfig;
     this.dbPath = dbPath || defaultDbPath(imapConfig.imap.user, imapConfig.imap.host);
     this.folders = folders && folders.length ? folders : null;
     this.excludeFolders = excludeFolders.map((f) => f.toLowerCase());
     this.intervalMs = Math.max(1, intervalMinutes) * 60 * 1000;
+    // Wall-clock cap on one sync run. 0 disables it. Fractions are allowed for tests.
+    const cap = Number(maxRunMinutes);
+    this.maxRunMs = Number.isFinite(cap) && cap >= 0 ? cap * 60 * 1000 : DEFAULT_MAX_RUN_MINUTES * 60 * 1000;
     this.batchSize = batchSize;
     this.maxBodyChars = maxBodyChars;
     this.log = log;
     this.db = null;
     this.running = null;
+    this.runningSince = 0;
+    this.abortRun = null;
+    this.stopped = false;
     this.timer = null;
     this.progressAt = 0;
     this.debounce = null;
@@ -206,19 +213,31 @@ export class LocalIndex {
   }
 
   start() {
-    const kick = () => {
-      const last = Number(this._meta('last_full_sync') || 0);
-      if (Date.now() - last < this.intervalMs / 2) return;
-      this.sync().catch((err) => this.log(`[index] sync failed: ${err.message}`));
+    // The next scheduled sync is armed when the previous one ends, so a slow
+    // or stuck run can never queue a pile-up behind itself.
+    const arm = (delay) => {
+      clearTimeout(this.timer);
+      if (this.stopped) return;
+      this.timer = setTimeout(kick, delay);
+      if (this.timer.unref) this.timer.unref();
     };
-    const first = setTimeout(kick, 5000);
-    if (first.unref) first.unref();
-    this.timer = setInterval(kick, this.intervalMs);
-    if (this.timer.unref) this.timer.unref();
+    const kick = async () => {
+      try {
+        const last = Number(this._meta('last_full_sync') || 0);
+        if (Date.now() - last >= this.intervalMs / 2) await this.sync();
+      } catch (err) {
+        this.log(`[index] sync failed: ${err.message}`);
+      } finally {
+        arm(this.intervalMs);
+      }
+    };
+    this.stopped = false;
+    arm(5000);
   }
 
   stop() {
-    clearInterval(this.timer);
+    this.stopped = true;
+    clearTimeout(this.timer);
     clearTimeout(this.debounce);
     this.releaseLock();
     this.session.close();
@@ -332,7 +351,7 @@ export class LocalIndex {
   }
 
   async _targetFolders(connection) {
-    const boxes = flattenBoxes(await connection.getBoxes());
+    const boxes = flattenBoxes(await listBoxes(connection));
     const selectable = boxes.filter((b) => !b.attribs.includes('\\noselect') && !b.attribs.includes('\\nonexistent'));
     if (this.folders) {
       const wanted = new Set(this.folders.map((f) => f.toLowerCase()));
@@ -353,6 +372,7 @@ export class LocalIndex {
    */
   sync({ folders = null, maxPerFolder = 1000, passes = Infinity } = {}) {
     if (this.running) return this.running;
+    this.runningSince = Date.now();
     this.running = (async () => {
       if (!this._acquireLock()) {
         return { skipped: true, reason: `another server process (pid ${this.lockHolder}) is syncing the index` };
@@ -373,7 +393,7 @@ export class LocalIndex {
       }, LOCK_HEARTBEAT_MS);
       if (heartbeat.unref) heartbeat.unref();
       try {
-        const summary = await this._sync({ folders, maxPerFolder, passes });
+        const summary = await this._runCapped(() => this._sync({ folders, maxPerFolder, passes }));
         if (this.db) {
           if (!folders && passes === Infinity && !summary.aborted) this._setMeta('last_full_sync', Date.now());
           this._setMeta('last_run', JSON.stringify({
@@ -391,15 +411,58 @@ export class LocalIndex {
         clearInterval(heartbeat);
         this.releaseLock();
       }
-    })().finally(() => { this.running = null; });
+    })().finally(() => { this.running = null; this.runningSince = 0; this.abortRun = null; });
     return this.running;
   }
 
+  /**
+   * Run one sync body under a wall-clock cap and an abort handle. A run that
+   * outlives the cap, or is aborted through abortSync(), is cut loose: its
+   * connection is dropped so any command it is waiting on fails, the caller
+   * releases the lock, and the orphaned body cannot touch the index again
+   * because _assertLock() throws once the lock is gone.
+   */
+  _runCapped(body) {
+    const started = Date.now();
+    let capTimer = null;
+    const cut = (reason) => ({ added: 0, removed: 0, folders: {}, aborted: reason, duration_ms: Date.now() - started, cut: true });
+    const stop = new Promise((resolve) => {
+      this.abortRun = (reason) => resolve(cut(reason));
+      if (this.maxRunMs > 0) {
+        const minutes = this.maxRunMs / 60000;
+        capTimer = setTimeout(() => this.abortRun(`sync exceeded ${minutes} minute${minutes === 1 ? '' : 's'}, aborted`), this.maxRunMs);
+        if (capTimer.unref) capTimer.unref();
+      }
+    });
+    const guarded = body().catch((err) => ({ error: err }));
+    return Promise.race([guarded, stop]).then((summary) => {
+      clearTimeout(capTimer);
+      if (summary.error) throw summary.error;
+      if (summary.cut) {
+        delete summary.cut;
+        this.session.dropCurrent(summary.aborted);
+        this.log(`[index] sync stopped: ${summary.aborted}`);
+      }
+      return summary;
+    });
+  }
+
+  /**
+   * Abort a running sync so a fresh one can start. Resolves once the run has
+   * been released. Returns false when nothing was running.
+   */
+  async abortSync(reason = 'aborted') {
+    if (!this.running) return false;
+    if (this.abortRun) this.abortRun(reason);
+    try { await this.running; } catch { /* the aborted run's own error is not interesting */ }
+    return true;
+  }
+
   async _sync({ folders, maxPerFolder, passes }) {
     const started = Date.now();
     const summary = { added: 0, removed: 0, folders: {} };
     let targets;
-    {
+    try {
       const conn = await this.session.acquire();
       try {
         const all = await this._targetFolders(conn);
@@ -408,6 +471,14 @@ export class LocalIndex {
       } finally {
         conn.end();
       }
+    } catch (err) {
+      if (err.code !== 'IMAP_TIMEOUT') throw err;
+      // The folder LIST on a dead connection: the run ends here, recorded like
+      // any other timed-out command, and the next scheduled sync reconnects.
+      summary.aborted = err.message;
+      summary.duration_ms = Date.now() - started;
+      this.log(`[index] sync stopped: ${err.message}`);
+      return summary;
     }
 
     let pass = 0;
@@ -538,6 +609,7 @@ export class LocalIndex {
 
   async _indexBatch(conn, folder, uidvalidity, uids) {
     const meta = await fetchMessages(conn, uids, { bodies: [HEADER_FIELDS], struct: true, size: true });
+    this._assertLock(); // a run cut loose by the cap must not write after the fact
     const parseHeader = conn.imap.constructor.parseHeader;
 
     // Group messages by the exact set of text parts they need, so each group
@@ -557,6 +629,7 @@ export class LocalIndex {
       const fetched = await fetchMessages(conn, groupUids, { bodies: key.split(',') });
       for (const [uid, rec] of fetched) bodies.set(uid, rec.parts);
     }
+    this._assertLock();
 
     const insMsg = this.db.prepare(`INSERT OR IGNORE INTO messages
       (folder, uid, uidvalidity, internal_date, sent_date, from_addr, to_addr, cc_addr, subject, message_id, size, attachments, body_chars)
@@ -619,8 +692,13 @@ export class LocalIndex {
       db_size_mb: Math.round(sizeBytes / 1024 / 102.4) / 10,
       this_pid: process.pid,
       sync_running: !!this.running || lockLive,
+      ...(this.running && this.runningSince && {
+        sync_running_since: new Date(this.runningSince).toISOString(),
+        sync_running_seconds: Math.round((Date.now() - this.runningSince) / 1000)
+      }),
       ...(lockLive && lock.pid !== process.pid && { sync_running_in_pid: lock.pid }),
       sync_interval_minutes: this.intervalMs / 60000,
+      sync_max_minutes: this.maxRunMs / 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,
@@ -673,7 +751,7 @@ export class LocalIndex {
    * Messages with no Message-ID header cannot be compared and are reported
    * under coverage rather than silently ignored.
    */
-  findDuplicates({ folders = null, scope = 'all', since_date = null, before_date = null, limit = 50 } = {}) {
+  findDuplicates({ folders = null, scope = 'all', since_date = null, before_date = null, limit = 50, offset = 0 } = {}) {
     if (!['all', 'same_folder', 'cross_folder'].includes(scope)) {
       throw new Error(`Unknown scope: ${scope}. Use all, same_folder or cross_folder.`);
     }
@@ -755,6 +833,8 @@ export class LocalIndex {
     }
     out.sort((a, b) => (b.copies - a.copies) || String(b.date || '').localeCompare(String(a.date || '')));
     const cap = Math.min(Math.max(1, Number(limit) || 50), 500);
+    const skip = Math.max(0, Number(offset) || 0);
+    const page = out.slice(skip, skip + cap);
     return {
       scope,
       folders_searched: folderList.length ? folderList : 'all indexed folders',
@@ -765,8 +845,10 @@ export class LocalIndex {
         ...(inScope > withId && { note: 'messages without a Message-ID header cannot be compared and are not included' })
       },
       total_groups: out.length,
-      returned: Math.min(out.length, cap),
-      groups: out.slice(0, cap),
+      returned: page.length,
+      offset: skip,
+      has_more: skip + page.length < out.length,
+      groups: page,
       index: this._indexHealth(folderList)
     };
   }

package/package.json

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