@lengelhard/imap-email-mcp 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.7.1
+
+### Fixed
+- Several server processes sharing one index (Claude Desktop can start more than one) no longer sync at the same time. A lock file next to the database lets one process sync while the others keep answering searches. Stale locks (process gone, or no heartbeat for 3 minutes) are taken over automatically.
+- SQLite waits up to 10 seconds for a busy database instead of failing with "database is locked".
+- A scheduled sync is skipped when another process completed a full sync in the last half interval.
+- Index refreshes requested after a move or delete are retried when another process holds the sync lock.
+- The server exits when the client disconnects or on SIGTERM/SIGINT/SIGHUP, instead of lingering while IMAP sockets are open. The sync lock is released on exit.
+
+### Changed
+- `index_status` reports `this_pid`, `sync_running_in_pid` (when another process syncs), `last_full_sync`, and a `last_run` shared by all processes.
+- `sync_index` and `search_index` say so when another process is already syncing.
+
 ## 1.7.0
 
 ### Added

package/README.md

@@ -112,6 +112,7 @@ Some IMAP servers return incomplete results for body searches without reporting
 - **What is indexed.** Subject, sender, recipients, attachment file names, and the text body (plain text, or HTML converted to text). Attachment contents are not indexed.
 - **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.
 - **Requirements.** Node 22.13 or later (uses the built-in `node:sqlite`, no native modules).
 
 ### Provider Settings

package/index.js

@@ -130,6 +130,20 @@ const SMTP_CONFIG = {
   }
 };
 
+// Optional display name for outgoing mail. When unset, behaviour is unchanged
+// and the From header is the bare address.
+const SENDER_NAME = process.env.SENDER_NAME || '';
+
+// Build an RFC 5322 From value. ASCII names are quoted; anything else is
+// encoded as an RFC 2047 encoded-word so accents survive transport.
+function formatFrom(address) {
+  if (!SENDER_NAME) return address;
+  const name = /^[\x20-\x7E]*$/.test(SENDER_NAME)
+    ? `"${SENDER_NAME.replace(/["\\]/g, '\\$&')}"`
+    : `=?UTF-8?B?${Buffer.from(SENDER_NAME, 'utf8').toString('base64')}?=`;
+  return `${name} <${address}>`;
+}
+
 // Traverse the raw IMAP MIME struct to find all attachment parts.
 //
 // Detection rules (in priority order):
@@ -1134,7 +1148,7 @@ async function handleTool(name, args) {
           // Build RFC 2822 compliant email message
           const boundary = `----=_Part_${Date.now()}`;
           let message = '';
-          message += `From: ${IMAP_CONFIG.imap.user}\r\n`;
+          message += `From: ${formatFrom(IMAP_CONFIG.imap.user)}\r\n`;
           message += `To: ${args.to}\r\n`;
           if (args.cc) message += `Cc: ${args.cc}\r\n`;
           if (args.bcc) message += `Bcc: ${args.bcc}\r\n`;
@@ -1180,7 +1194,7 @@ async function handleTool(name, args) {
 
           const boundary = `----=_Part_${Date.now()}`;
           let message = '';
-          message += `From: ${IMAP_CONFIG.imap.user}\r\n`;
+          message += `From: ${formatFrom(IMAP_CONFIG.imap.user)}\r\n`;
           message += `To: ${args.to}\r\n`;
           if (args.cc) message += `Cc: ${args.cc}\r\n`;
           if (args.bcc) message += `Bcc: ${args.bcc}\r\n`;
@@ -1221,7 +1235,9 @@ async function handleTool(name, args) {
         const transporter = nodemailer.createTransport(SMTP_CONFIG);
 
         const mailOptions = {
-          from: SMTP_CONFIG.auth.user,
+          from: SENDER_NAME
+            ? { name: SENDER_NAME, address: SMTP_CONFIG.auth.user }
+            : SMTP_CONFIG.auth.user,
           to: args.to,
           subject: args.subject,
           text: args.body,
@@ -1238,7 +1254,7 @@ async function handleTool(name, args) {
         const sentDate = new Date();
         const boundary = `----=_Part_${Date.now()}`;
         let rawMessage = '';
-        rawMessage += `From: ${SMTP_CONFIG.auth.user}\r\n`;
+        rawMessage += `From: ${formatFrom(SMTP_CONFIG.auth.user)}\r\n`;
         rawMessage += `To: ${args.to}\r\n`;
         if (args.cc) rawMessage += `Cc: ${args.cc}\r\n`;
         if (args.bcc) rawMessage += `Bcc: ${args.bcc}\r\n`;
@@ -1779,11 +1795,15 @@ async function handleTool(name, args) {
             refresh = 'skipped: background sync in progress';
           } else {
             const quick = localIndex.sync({ maxPerFolder: 300, passes: 1 });
-            const timedOut = await Promise.race([
-              quick.then(() => false),
-              new Promise((resolve) => setTimeout(() => resolve(true), 20000))
+            const outcome = await Promise.race([
+              quick.then((r) => (r && r.skipped ? 'skipped' : 'done')),
+              new Promise((resolve) => setTimeout(() => resolve('timeout'), 20000))
             ]);
-            refresh = timedOut ? 'partial: refresh still running in background' : 'done';
+            refresh = {
+              done: 'done',
+              skipped: 'skipped: another server process is syncing the index',
+              timeout: 'partial: refresh still running in background'
+            }[outcome];
           }
         }
         const found = localIndex.search({
@@ -1817,13 +1837,15 @@ async function handleTool(name, args) {
           run.then((summary) => ({ finished: true, summary })),
           new Promise((resolve) => setTimeout(() => resolve({ finished: false }), waitMs))
         ]);
+        const skipped = outcome.summary && outcome.summary.skipped;
         return {
           content: [{
             type: 'text',
             text: JSON.stringify({
               ...(alreadyRunning && { note: 'A sync was already running; waited on that one.' }),
-              finished: outcome.finished,
-              ...(outcome.summary && { summary: outcome.summary }),
+              ...(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 }),
               status: localIndex.status()
             }, null, 2)
           }]
@@ -1867,6 +1889,21 @@ async function main() {
     }
   }
 
+  // Exit promptly when the client goes away. Without this, open IMAP sockets
+  // would keep an orphaned process alive after Claude Desktop quits.
+  let shuttingDown = false;
+  const shutdown = () => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    try { localIndex?.stop(); } catch { /* ignore */ }
+    try { sessions.close(); } catch { /* ignore */ }
+    setTimeout(() => process.exit(0), 500);
+  };
+  process.stdin.on('end', shutdown);
+  process.stdin.on('close', shutdown);
+  for (const sig of ['SIGTERM', 'SIGINT', 'SIGHUP']) process.on(sig, shutdown);
+  process.on('exit', () => { try { localIndex?.releaseLock(); } catch { /* ignore */ } });
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error('IMAP Email MCP Server running on stdio');

package/lib/local-index.js

@@ -23,6 +23,27 @@ import { SessionManager, openBox, fetchMessages, headerOf, localDate } from './i
 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 REQUEST_MAX_ATTEMPTS = 6;
+
+class LockLostError extends Error {
+  constructor() {
+    super('sync lock taken over by another process');
+    this.code = 'LOCK_LOST';
+  }
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
 const HEADER_FIELDS = 'HEADER.FIELDS (FROM TO CC SUBJECT DATE MESSAGE-ID)';
 const DEFAULT_EXCLUDE = ['trash', 'junk', 'spam', 'deleted items', 'deleted messages', 'bin'];
 const SPECIAL_EXCLUDE = ['\\trash', '\\junk'];
@@ -99,7 +120,6 @@ export class LocalIndex {
     this.timer = null;
     this.debounce = null;
     this.pendingFolders = new Set();
-    this.lastRun = null;
     this.session = new SessionManager(imapConfig, { label: 'index', idleCloseMs: 60 * 1000, leaseTimeoutMs: 10 * 60 * 1000, log });
   }
 
@@ -110,6 +130,9 @@ export class LocalIndex {
     for (const suffix of ['', '-wal', '-shm']) {
       try { fs.chmodSync(this.dbPath + suffix, 0o600); } catch { /* may not exist yet */ }
     }
+    // Several server processes can share this file (Claude Desktop may start
+    // more than one). Wait for locks instead of failing immediately.
+    this.db.exec('PRAGMA busy_timeout = 10000;');
     this.db.exec(`
       PRAGMA journal_mode = WAL;
       PRAGMA synchronous = NORMAL;
@@ -153,7 +176,11 @@ export class LocalIndex {
   }
 
   start() {
-    const kick = () => this.sync().catch((err) => this.log(`[index] sync failed: ${err.message}`));
+    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}`));
+    };
     const first = setTimeout(kick, 5000);
     if (first.unref) first.unref();
     this.timer = setInterval(kick, this.intervalMs);
@@ -163,20 +190,114 @@ export class LocalIndex {
   stop() {
     clearInterval(this.timer);
     clearTimeout(this.debounce);
+    this.releaseLock();
     this.session.close();
     try { this.db?.close(); } catch { /* ignore */ }
+    this.db = null;
+  }
+
+  _meta(key) {
+    try {
+      return this.db.prepare('SELECT value FROM meta WHERE key = ?').get(key)?.value ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  _setMeta(key, value) {
+    this.db.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
+      .run(key, String(value));
+  }
+
+  // Cross-process sync lock: a small file next to the database holding the
+  // owner's pid, with its mtime refreshed while a sync runs. A lock is stale
+  // when its pid is gone or its heartbeat is older than LOCK_STALE_MS.
+  get lockPath() {
+    return `${this.dbPath}.lock`;
+  }
+
+  _readLock() {
+    try {
+      const pid = parseInt(fs.readFileSync(this.lockPath, 'utf8'), 10);
+      const mtime = fs.statSync(this.lockPath).mtimeMs;
+      return { pid, mtime };
+    } catch {
+      return null;
+    }
+  }
+
+  _lockIsLive(lock) {
+    return !!lock && pidAlive(lock.pid) && Date.now() - lock.mtime < LOCK_STALE_MS;
+  }
+
+  _acquireLock() {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        fs.writeFileSync(this.lockPath, `${process.pid}\n`, { flag: 'wx', mode: 0o600 });
+        return true;
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err;
+        const lock = this._readLock();
+        if (!lock) continue;
+        if (lock.pid === process.pid) {
+          this._touchLock();
+          return true;
+        }
+        if (this._lockIsLive(lock)) {
+          this.lockHolder = lock.pid;
+          return false;
+        }
+        this.log(`[index] removing stale sync lock from pid ${lock.pid}`);
+        try { fs.unlinkSync(this.lockPath); } catch { /* another process got there first */ }
+      }
+    }
+    return false;
+  }
+
+  _holdsLock() {
+    const lock = this._readLock();
+    return !!lock && lock.pid === process.pid;
+  }
+
+  _touchLock() {
+    if (!this._holdsLock()) return;
+    const now = new Date();
+    try { fs.utimesSync(this.lockPath, now, now); } catch { /* ignore */ }
+  }
+
+  releaseLock() {
+    if (this._holdsLock()) {
+      try { fs.unlinkSync(this.lockPath); } catch { /* ignore */ }
+    }
+  }
+
+  _assertLock() {
+    if (!this._holdsLock()) throw new LockLostError();
   }
 
   /** Ask for a near-term incremental sync of specific folders (after moves or deletes). */
-  requestSync(folders = []) {
+  requestSync(folders = [], attempt = 1, delay = 3000) {
     for (const f of folders) if (f) this.pendingFolders.add(f);
     clearTimeout(this.debounce);
-    this.debounce = setTimeout(() => {
+    this.debounce = setTimeout(async () => {
       const list = [...this.pendingFolders];
-      this.pendingFolders.clear();
-      if (this.running) return; // the running sync or the next scheduled one will catch up
-      this.sync({ folders: list, maxPerFolder: 500, passes: 1 }).catch((err) => this.log(`[index] sync failed: ${err.message}`));
-    }, 3000);
+      if (!list.length) return;
+      if (this.running) {
+        // A local sync may have listed these folders before the move. Try again after it.
+        this.running.catch(() => {}).then(() => this.requestSync([], attempt, REQUEST_RETRY_MS));
+        return;
+      }
+      try {
+        const result = await this.sync({ folders: list, maxPerFolder: 500, passes: 1 });
+        if (result && result.skipped) {
+          if (attempt < REQUEST_MAX_ATTEMPTS) this.requestSync([], attempt + 1, REQUEST_RETRY_MS);
+          return;
+        }
+        for (const f of list) this.pendingFolders.delete(f);
+      } catch (err) {
+        this.log(`[index] sync failed: ${err.message}`);
+      }
+    }, delay);
     if (this.debounce.unref) this.debounce.unref();
   }
 
@@ -202,7 +323,32 @@ export class LocalIndex {
    */
   sync({ folders = null, maxPerFolder = 1000, passes = Infinity } = {}) {
     if (this.running) return this.running;
-    this.running = this._sync({ folders, maxPerFolder, passes }).finally(() => { this.running = null; });
+    this.running = (async () => {
+      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);
+      if (heartbeat.unref) heartbeat.unref();
+      try {
+        const summary = await 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({
+            finished: new Date().toISOString(),
+            pid: process.pid,
+            scope: folders ? folders.join(', ') : 'all folders',
+            added: summary.added,
+            removed: summary.removed,
+            duration_ms: summary.duration_ms,
+            ...(summary.aborted && { aborted: summary.aborted })
+          }));
+        }
+        return summary;
+      } finally {
+        clearInterval(heartbeat);
+        this.releaseLock();
+      }
+    })().finally(() => { this.running = null; });
     return this.running;
   }
 
@@ -223,6 +369,7 @@ export class LocalIndex {
 
     let pass = 0;
     let remaining = new Set(targets);
+    outer:
     while (remaining.size && pass < passes) {
       pass++;
       for (const folder of [...remaining]) {
@@ -244,6 +391,11 @@ export class LocalIndex {
             this.log(`[index] ${folder}: ${r.attempted} messages could not be fetched, will retry next sync`);
           }
         } catch (err) {
+          if (err.code === 'LOCK_LOST' || !this.db) {
+            summary.aborted = err.code === 'LOCK_LOST' ? err.message : 'index closed';
+            this.log(`[index] sync stopped: ${summary.aborted}`);
+            break outer;
+          }
           remaining.delete(folder);
           this.log(`[index] ${folder}: ${err.message}`);
           this.db.prepare(`INSERT INTO folders (name, last_error, last_sync) VALUES (?, ?, ?)
@@ -254,7 +406,6 @@ export class LocalIndex {
       }
     }
     summary.duration_ms = Date.now() - started;
-    this.lastRun = { finished: Date.now(), ...summary };
     return summary;
   }
 
@@ -280,6 +431,7 @@ export class LocalIndex {
   }
 
   async _syncFolder(folder, maxPerFolder) {
+    this._assertLock();
     const conn = await this.session.acquire();
     try {
       const box = await openBox(conn, folder, true);
@@ -317,6 +469,7 @@ export class LocalIndex {
       const todo = missing.slice(0, maxPerFolder);
       let added = 0;
       for (let i = 0; i < todo.length; i += this.batchSize) {
+        this._assertLock();
         added += await this._indexBatch(conn, folder, uidvalidity, todo.slice(i, i + this.batchSize));
       }
 
@@ -407,18 +560,21 @@ export class LocalIndex {
     for (const suffix of ['', '-wal']) {
       try { sizeBytes += fs.statSync(this.dbPath + suffix).size; } catch { /* ignore */ }
     }
+    const lock = this._readLock();
+    const lockLive = this._lockIsLive(lock);
+    let lastRun = null;
+    try { lastRun = JSON.parse(this._meta('last_run') || 'null'); } catch { /* ignore */ }
+    const lastFull = Number(this._meta('last_full_sync') || 0);
     return {
       db_path: this.dbPath,
       db_size_mb: Math.round(sizeBytes / 1024 / 102.4) / 10,
-      sync_running: !!this.running,
+      this_pid: process.pid,
+      sync_running: !!this.running || lockLive,
+      ...(lockLive && lock.pid !== process.pid && { sync_running_in_pid: lock.pid }),
       sync_interval_minutes: this.intervalMs / 60000,
       complete: folders.length > 0 && folders.every((f) => f.complete && !f.last_error),
-      last_run: this.lastRun ? {
-        finished: new Date(this.lastRun.finished).toISOString(),
-        added: this.lastRun.added,
-        removed: this.lastRun.removed,
-        duration_ms: this.lastRun.duration_ms
-      } : null,
+      last_full_sync: lastFull ? new Date(lastFull).toISOString() : null,
+      last_run: lastRun,
       folders
     };
   }

package/package.json

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