@lengelhard/imap-email-mcp 1.7.4 → 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,30 @@
 # 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
+- `find_duplicates`: lists messages that exist more than once, matched on the Message-ID header. `scope: "same_folder"` reports a folder holding the same message twice, a filing error, and names the extra copies under `redundant_copies` (the lowest UID is kept). `scope: "cross_folder"` reports a message present in several folders, usually a split thread, and never marks anything redundant, because deleting one copy of those only relocates the problem. Messages with no Message-ID are counted in `coverage.without_message_id` instead of being silently skipped. Requires the local index.
+- `message_id` on the results of `list_emails`, `search_emails`, `search_index` and `get_email`, with the angle brackets stripped. It was already fetched and stored by the indexer but never exposed, which left callers matching on subject, sender and timestamp instead. That heuristic is unreliable: in a fast thread two genuinely different replies can share a subject, a sender and a minute, and on 19 Sep 2026 it produced five candidate pairs of which none were duplicates.
+- `messages.message_id` is now indexed in SQLite.
+
+### Changed
+- **`delete_email` moves to Trash instead of erasing.** It previously flagged `\Deleted` and expunged, so a wrong UID was unrecoverable and nothing appeared in Trash. It now moves the message to the folder the server flags as `\Trash` (falling back to the usual names), and the response says where it went. Pass `expunge: true` for the old behaviour, which is permanent. A message already in Trash is still erased. On an account with no Trash folder the call now fails and says so, rather than erasing a message when the recoverable path was the one asked for.
+
+### Fixed
+- `normalizeMessageId` returned the literal `<>` for an empty Message-ID header instead of treating it as absent, which would have grouped every such message together as duplicates of one another.
+
 ## 1.7.4
 
 ### Added

package/README.md

@@ -75,7 +75,8 @@ Add to your config file:
 - **Compose** - Create and save email drafts
 - **Send** - Send emails directly via SMTP
 - **Manage drafts** - List, read, update, and delete drafts
-- **Delete emails** - Remove unwanted messages
+- **Find duplicates** - Spot messages filed twice in one folder, or the same message sitting in several folders, matched on Message-ID
+- **Delete emails** - Move to Trash by default, with an explicit opt-in to erase permanently
 - **Multi-provider support** - Works with Gmail, Outlook, Yahoo, Fastmail, and any standard IMAP provider
 
 ## Configuration
@@ -104,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
 
@@ -118,6 +120,15 @@ Some IMAP servers return incomplete results for body searches without reporting
 - **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).
 
+### Finding duplicates
+
+Mail clients that file by tag sometimes append a fresh copy of a message instead of moving the one already on the server, which leaves the same message in a folder twice. `find_duplicates` reports those, using the Message-ID header as the identity of a message.
+
+- **Why Message-ID.** It is set by the sending server, it is unique, and it does not change when mail is moved. Matching on subject, sender and timestamp instead produces false pairs: in a fast thread two different replies can share a subject, a sender and a minute.
+- **Two shapes.** `scope: "same_folder"` finds a folder holding one message more than once. Those extra copies carry nothing unique, and the tool lists them under `redundant_copies` (lowest UID kept). `scope: "cross_folder"` finds a message present in several folders, usually a split thread. Do not resolve those by deleting: removing one copy only moves the problem.
+- **Honest coverage.** A message with no Message-ID header cannot be compared. It is counted in `coverage.without_message_id` rather than quietly skipped, and `index.complete` says whether the index had seen everything.
+- **Nothing is deleted.** The tool only reports. Acting on it means calling `delete_email`, which moves to Trash unless you pass `expunge: true`.
+
 ### Provider Settings
 
 | Provider | IMAP_HOST | SMTP_HOST | Notes |
@@ -137,14 +148,15 @@ Some IMAP servers return incomplete results for body searches without reporting
 | `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 |
 | `create_draft` | Create a new email draft |
 | `update_draft` | Update an existing draft |
 | `send_email` | Send an email directly |
-| `delete_email` | Delete an email by UID |
+| `delete_email` | Delete an email by UID. Moves to Trash unless `expunge: true` |
 | `download_attachment` | Download an attachment: ≤700KB returns inline base64, larger saves to disk (ATTACHMENT_DIR) |
 | `extract_text` | Extract plain text from a PDF, xlsx/xlsm/xls, docx, or text attachment in one call, parsed server-side |
 

package/index.js

@@ -31,7 +31,7 @@ import {
   buildCriteria
 } from './lib/imap-session.js';
 import { htmlToText, stripDataUris, leafParts } from './lib/mime-text.js';
-import { LocalIndex } from './lib/local-index.js';
+import { LocalIndex, normalizeMessageId } from './lib/local-index.js';
 
 const PKG_VERSION = createRequire(import.meta.url)('./package.json').version;
 
@@ -447,12 +447,56 @@ 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: [] }
         },
+        {
+          name: 'find_duplicates',
+          description: 'List messages that exist more than once, matched on their Message-ID header. Message-ID is assigned by the sending server and survives moves, so it identifies a message reliably; matching on subject, sender and timestamp instead pairs up genuinely different messages in fast threads. scope "same_folder" finds a folder holding the same message twice, which is a filing error and whose extra copies are listed under redundant_copies. scope "cross_folder" finds a message sitting in several folders, usually a split thread; never resolve those by deleting, since that only relocates the problem. Check index.complete and coverage.without_message_id before treating the result as exhaustive.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              scope: {
+                type: 'string',
+                enum: ['all', 'same_folder', 'cross_folder'],
+                description: 'same_folder: one folder holds the message more than once; cross_folder: the message is in several folders; all: either (default)',
+                default: 'all'
+              },
+              folders: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Only these folders (default: all indexed folders). A copy outside this list is not counted.'
+              },
+              since_date: {
+                type: 'string',
+                description: 'Only messages delivered on or after this date (YYYY-MM-DD)'
+              },
+              before_date: {
+                type: 'string',
+                description: 'Only messages delivered before this date (YYYY-MM-DD)'
+              },
+              limit: {
+                type: 'number',
+                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.',
+                default: true
+              }
+            },
+            required: []
+          }
+        },
         {
           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: {
@@ -465,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: []
@@ -670,7 +719,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'delete_email',
-        description: 'Delete an email by UID',
+        description: 'Delete an email by UID. By default the message is moved to the Trash folder, so it can still be recovered; the response says where it went. Pass expunge: true to erase it from the server instead, which cannot be undone. A message already in Trash is always erased.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -682,6 +731,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Folder name (default: INBOX)',
               default: 'INBOX'
+            },
+            expunge: {
+              type: 'boolean',
+              description: 'Erase the message from the server instead of moving it to Trash. Permanent and not recoverable (default: false).',
+              default: false
             }
           },
           required: ['uid']
@@ -812,7 +866,7 @@ async function connectIMAP() {
   return await sessions.acquire();
 }
 
-const LIST_HEADER_FIELDS = 'HEADER.FIELDS (FROM TO CC SUBJECT DATE)';
+const LIST_HEADER_FIELDS = 'HEADER.FIELDS (FROM TO CC SUBJECT DATE MESSAGE-ID)';
 const MAX_LIMIT = 200;
 
 function clampLimit(value, fallback = 20) {
@@ -839,6 +893,8 @@ async function summarize(connection, folder, uids, { withFlags = true } = {}) {
       subject: h.subject?.[0]
     };
     if (h.cc?.length) item.cc = h.cc.join(', ');
+    const messageId = normalizeMessageId(h['message-id']?.[0]);
+    if (messageId) item.message_id = messageId;
     if (withFlags) item.flags = rec.attributes.flags;
     out.push(item);
   }
@@ -850,6 +906,37 @@ function dateValue(item) {
   return Number.isNaN(t) ? 0 : t;
 }
 
+/**
+ * Find the mailbox that holds deleted mail.
+ *
+ * Prefers the folder the server itself flags as \Trash, since that is what the
+ * user's other mail clients will treat as the bin, and falls back to the usual
+ * names. Returns null when nothing plausible exists, which the caller reports
+ * rather than guessing and writing mail somewhere unexpected.
+ */
+async function findTrashFolder(connection) {
+  const boxes = await connection.getBoxes();
+  const walk = (node, prefix = '', out = []) => {
+    for (const [name, box] of Object.entries(node || {})) {
+      const full = prefix ? `${prefix}${box.delimiter || '/'}${name}` : name;
+      const attribs = (box.attribs || []).map((a) => String(a).toLowerCase());
+      if (box.special_use_attrib) attribs.push(String(box.special_use_attrib).toLowerCase());
+      out.push({ name: full, attribs, leaf: name });
+      if (box.children) walk(box.children, full, out);
+    }
+    return out;
+  };
+  const all = walk(boxes);
+  const selectable = all.filter((b) => !b.attribs.includes('\\noselect') && !b.attribs.includes('\\nonexistent'));
+
+  const flagged = selectable.find((b) => b.attribs.includes('\\trash'));
+  if (flagged) return flagged.name;
+
+  const known = ['trash', 'deleted items', 'deleted messages', 'bin', 'papierkorb', 'corbeille'];
+  const byName = selectable.find((b) => known.includes(b.leaf.toLowerCase()));
+  return byName ? byName.name : null;
+}
+
 // Helper to find drafts folder (handles different provider conventions)
 async function findDraftsFolder(connection) {
   const boxes = await connection.getBoxes();
@@ -986,6 +1073,7 @@ async function handleTool(name, args) {
                 cc: parsed.cc?.text,
                 subject: parsed.subject,
                 date: parsed.date,
+                ...(normalizeMessageId(parsed.messageId) && { message_id: normalizeMessageId(parsed.messageId) }),
                 text: (htmlOnly || !parsed.text) && parsed.html ? htmlToText(parsed.html) : (parsed.text || ''),
                 ...(htmlOnly && { text_source: 'converted from HTML' }),
                 ...(args.include_html && parsed.html && { html: stripDataUris(parsed.html) }),
@@ -1582,11 +1670,60 @@ async function handleTool(name, args) {
         const connection = await connectIMAP();
 
         try {
+          // Default to the recoverable path: move to Trash. Erasing is opt-in,
+          // because an expunge cannot be undone and a wrong uid is silent.
+          const trash = args.expunge ? null : await findTrashFolder(connection);
+          const alreadyInTrash = trash && trash.toLowerCase() === folder.toLowerCase();
+
           await connection.openBox(folder);
+
+          if (trash && !alreadyInTrash) {
+            await new Promise((resolve, reject) => {
+              connection.imap.move(args.uid, trash, (err) => (err ? reject(err) : resolve()));
+            });
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  success: true,
+                  uid: args.uid,
+                  folder,
+                  action: 'moved_to_trash',
+                  trash_folder: trash,
+                  recoverable: true,
+                  note: `Moved to ${trash}. Pass expunge: true to erase permanently instead.`
+                }, null, 2)
+              }]
+            };
+          }
+
+          if (!args.expunge && !trash) {
+            // The caller asked for the recoverable path and it is not available.
+            // Erasing anyway would be a permanent action nobody asked for.
+            return {
+              content: [{
+                type: 'text',
+                text: `No Trash folder found on this server, so the message was left where it is. Pass expunge: true to erase uid ${args.uid} from ${folder} permanently, or create a Trash folder first.`
+              }],
+              isError: true
+            };
+          }
+
           await connection.addFlags(args.uid, ['\\Deleted']);
           await connection.closeBox(true); // Expunge
-
-          return { content: [{ type: 'text', text: 'Email deleted successfully' }] };
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                success: true,
+                uid: args.uid,
+                folder,
+                action: 'expunged',
+                recoverable: false,
+                ...(alreadyInTrash && { reason: 'message was already in Trash' })
+              }, null, 2)
+            }]
+          };
         } finally {
           connection.end();
         }
@@ -1831,10 +1968,50 @@ async function handleTool(name, args) {
         return { content: [{ type: 'text', text: JSON.stringify(localIndex.status(), null, 2) }] };
       }
 
+      case 'find_duplicates': {
+        if (!localIndex) throw new Error(localIndexError || 'Local index is not enabled (set INDEX_ENABLED=true)');
+        let refresh = null;
+        if (args.refresh !== false) {
+          if (localIndex.running) {
+            refresh = 'skipped: background sync in progress';
+          } else {
+            const quick = localIndex.sync({ maxPerFolder: 300, passes: 1 });
+            const outcome = await Promise.race([
+              quick.then((r) => (r && r.skipped ? 'skipped' : 'done')),
+              new Promise((resolve) => setTimeout(() => resolve('timeout'), 20000))
+            ]);
+            refresh = {
+              done: 'done',
+              skipped: 'skipped: another server process is syncing the index',
+              timeout: 'partial: refresh still running in background'
+            }[outcome];
+          }
+        }
+        const found = localIndex.findDuplicates({
+          folders: args.folders || null,
+          scope: args.scope || 'all',
+          since_date: args.since_date || null,
+          before_date: args.before_date || null,
+          limit: args.limit,
+          offset: args.offset
+        });
+        if (refresh) found.index = { ...found.index, refresh };
+        return { content: [{ type: 'text', text: JSON.stringify(found, null, 2) }] };
+      }
+
       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 })),
@@ -1845,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 }),
@@ -1881,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);
@@ -116,18 +117,41 @@ function ftsQuery(query, { match = 'all', prefix = false, field = 'any' } = {})
   return expr;
 }
 
+/**
+ * Compare form for a Message-ID header.
+ *
+ * Strips the surrounding angle brackets and whitespace and nothing else.
+ * Case is preserved on purpose: the local part of a Message-ID is
+ * case-sensitive per RFC 5322, and this value decides whether two messages
+ * are reported as copies of each other. A missed duplicate is a nuisance; a
+ * wrongly matched pair could cost someone a message, so this errs strict.
+ */
+export function normalizeMessageId(value) {
+  const s = String(value ?? '').trim();
+  if (!s) return null;
+  const m = s.match(/<([^<>]+)>/);
+  const id = (m ? m[1] : s.replace(/^<+|>+$/g, '')).trim();
+  return id || null;
+}
+
 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;
@@ -177,6 +201,7 @@ export class LocalIndex {
       );
       CREATE INDEX IF NOT EXISTS messages_date ON messages (internal_date);
       CREATE INDEX IF NOT EXISTS messages_folder_date ON messages (folder, internal_date);
+      CREATE INDEX IF NOT EXISTS messages_message_id ON messages (message_id);
       CREATE VIRTUAL TABLE IF NOT EXISTS fts USING fts5 (
         subject, from_addr, to_addr, attachments, body,
         tokenize = 'unicode61 remove_diacritics 2'
@@ -188,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 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);
+      }
     };
-    const first = setTimeout(kick, 5000);
-    if (first.unref) first.unref();
-    this.timer = setInterval(kick, this.intervalMs);
-    if (this.timer.unref) this.timer.unref();
+    this.stopped = false;
+    arm(5000);
   }
 
   stop() {
-    clearInterval(this.timer);
+    this.stopped = true;
+    clearTimeout(this.timer);
     clearTimeout(this.debounce);
     this.releaseLock();
     this.session.close();
@@ -314,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()));
@@ -335,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` };
@@ -355,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({
@@ -373,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);
@@ -390,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;
@@ -520,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
@@ -539,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)
@@ -601,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,
@@ -611,6 +707,152 @@ export class LocalIndex {
     };
   }
 
+  /** Sync health for a set of folders, shared by search() and findDuplicates(). */
+  _indexHealth(folderList = []) {
+    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 {
+      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),
+      ...(warnings.length && { warning: warnings.join('; ') })
+    };
+  }
+
+  /**
+   * Find messages that exist more than once, keyed on Message-ID.
+   *
+   * Message-ID is assigned by the sending server and does not change when mail
+   * is moved, so it is the only dependable identity for a message across
+   * folders. Matching on subject, sender and timestamp instead produces false
+   * pairs on fast back-and-forth threads, where two genuinely different
+   * messages can share everything but the second.
+   *
+   * scope:
+   *   same_folder  one folder holds the message more than once. A filing
+   *                error: the extra copies carry nothing unique.
+   *   cross_folder the message sits in more than one folder. Usually a split
+   *                thread or a stray archive copy. Never resolve these by
+   *                deleting; deleting one copy only relocates the problem.
+   *   all          either of the above (default).
+   *
+   * 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, offset = 0 } = {}) {
+    if (!['all', 'same_folder', 'cross_folder'].includes(scope)) {
+      throw new Error(`Unknown scope: ${scope}. Use all, same_folder or cross_folder.`);
+    }
+    const folderList = Array.isArray(folders) ? folders.filter(Boolean) : (folders ? [folders] : []);
+    const where = [];
+    const params = [];
+    if (folderList.length) {
+      where.push(`folder IN (${folderList.map(() => '?').join(', ')})`);
+      params.push(...folderList);
+    }
+    if (since_date) {
+      where.push('internal_date >= ?');
+      params.push(localDate(since_date).getTime());
+    }
+    if (before_date) {
+      where.push('internal_date < ?');
+      params.push(localDate(before_date).getTime());
+    }
+    const scopeSql = where.length ? `WHERE ${where.join(' AND ')}` : '';
+    const hasId = "message_id IS NOT NULL AND trim(message_id) <> ''";
+    const andHasId = where.length ? `${scopeSql} AND ${hasId}` : `WHERE ${hasId}`;
+
+    const inScope = this.db.prepare(`SELECT count(*) AS n FROM messages ${scopeSql}`).get(...params).n;
+    const withId = this.db.prepare(`SELECT count(*) AS n FROM messages ${andHasId}`).get(...params).n;
+
+    // Pre-filter in SQL to the ids that occur more than once, then regroup in
+    // JS on the normalized id so bracket differences cannot split a group.
+    const key = "trim(replace(replace(message_id, '<', ''), '>', ''))";
+    const rows = this.db.prepare(`
+      SELECT folder, uid, message_id, subject, from_addr, internal_date, sent_date
+      FROM messages
+      ${andHasId} AND ${key} IN (
+        SELECT ${key} FROM messages ${andHasId} GROUP BY ${key} HAVING count(*) > 1
+      )
+      ORDER BY internal_date DESC, folder, uid`).all(...params, ...params);
+
+    const groups = new Map();
+    for (const r of rows) {
+      const id = normalizeMessageId(r.message_id);
+      if (!id) continue;
+      if (!groups.has(id)) groups.set(id, []);
+      groups.get(id).push(r);
+    }
+
+    const out = [];
+    for (const [message_id, copies] of groups) {
+      if (copies.length < 2) continue;
+      const byFolder = {};
+      for (const c of copies) byFolder[c.folder] = (byFolder[c.folder] || 0) + 1;
+      const sameFolder = Object.values(byFolder).some((n) => n > 1);
+      const crossFolder = Object.keys(byFolder).length > 1;
+      if (scope === 'same_folder' && !sameFolder) continue;
+      if (scope === 'cross_folder' && !crossFolder) continue;
+      const first = copies[0];
+      // Redundant copies only ever come from a folder holding the message more
+      // than once: within that folder keep the lowest uid and list the rest.
+      const redundant = [];
+      for (const [folder, n] of Object.entries(byFolder)) {
+        if (n < 2) continue;
+        const inFolder = copies.filter((c) => c.folder === folder).sort((a, b) => Number(a.uid) - Number(b.uid));
+        for (const c of inFolder.slice(1)) redundant.push({ folder, uid: Number(c.uid) });
+      }
+      out.push({
+        message_id,
+        subject: first.subject,
+        from: first.from_addr,
+        date: first.sent_date || (first.internal_date ? new Date(Number(first.internal_date)).toISOString() : null),
+        copies: copies.length,
+        same_folder_duplicates: sameFolder,
+        cross_folder: crossFolder,
+        by_folder: byFolder,
+        ...(redundant.length && { redundant_copies: redundant }),
+        messages: copies.map((c) => ({
+          folder: c.folder,
+          uid: Number(c.uid),
+          date: c.sent_date || (c.internal_date ? new Date(Number(c.internal_date)).toISOString() : null)
+        }))
+      });
+    }
+    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',
+      coverage: {
+        messages_in_scope: inScope,
+        with_message_id: withId,
+        without_message_id: inScope - withId,
+        ...(inScope > withId && { note: 'messages without a Message-ID header cannot be compared and are not included' })
+      },
+      total_groups: out.length,
+      returned: page.length,
+      offset: skip,
+      has_more: skip + page.length < out.length,
+      groups: page,
+      index: this._indexHealth(folderList)
+    };
+  }
+
   search({ query, folders = null, from = null, since_date = null, before_date = null, field = 'any', match = 'all', prefix = false, sort = 'date', limit = 20, offset = 0 }) {
     const where = ['fts MATCH ?'];
     const params = [ftsQuery(query, { match, prefix, field })];
@@ -638,37 +880,18 @@ export class LocalIndex {
 
     const total = this.db.prepare(`SELECT count(*) AS n FROM fts JOIN messages m ON m.id = fts.rowid WHERE ${whereSql}`).get(...params).n;
     const rows = this.db.prepare(`
-      SELECT m.folder, m.uid, m.internal_date, m.sent_date, m.from_addr, m.to_addr, m.subject, m.attachments,
+      SELECT m.folder, m.uid, m.internal_date, m.sent_date, m.from_addr, m.to_addr, m.subject, m.attachments, m.message_id,
              snippet(fts, -1, '[', ']', '...', 16) AS snippet
       FROM fts JOIN messages m ON m.id = fts.rowid
       WHERE ${whereSql}
       ORDER BY ${order}
       LIMIT ? OFFSET ?`).all(...params, cap, skip);
 
-    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,
       offset: skip,
-      index: {
-        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),
-        ...(warnings.length && { warning: warnings.join('; ') })
-      },
+      index: this._indexHealth(folderList),
       results: rows.map((r) => ({
         folder: r.folder,
         uid: Number(r.uid),
@@ -676,6 +899,7 @@ export class LocalIndex {
         from: r.from_addr,
         to: r.to_addr,
         subject: r.subject,
+        message_id: normalizeMessageId(r.message_id) || undefined,
         attachments: r.attachments || undefined,
         snippet: r.snippet
       }))

package/package.json

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