@lengelhard/imap-email-mcp 1.7.3 → 1.7.4

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.7.4
+
+### Added
+- `search_index` results carry `index.warning` when the index may be behind: the last full sync finished more than 15 minutes ago (for example "index last synced 3 hours ago, results may be missing recent mail"), the index has never completed a full sync, or a searched folder recorded an error. The existing `index` fields are unchanged. This makes a stalled background sync visible in every search instead of silent, following the overnight freeze of 18 Sep 2026.
+
 ## 1.7.3
 
 ### Fixed

package/README.md

@@ -136,7 +136,7 @@ Some IMAP servers return incomplete results for body searches without reporting
 | `list_emails` | List emails newest first, with unread, flagged and date filters and paging |
 | `get_email` | Get an email by UID. Text by default; HTML (without inline images) on request |
 | `search_emails` | Live IMAP search across one or more folders: subject, from, to, cc, body, text, dates, flags |
-| `search_index` | Full-text search of the local index (when `INDEX_ENABLED=true`) |
+| `search_index` | Full-text search of the local index (when `INDEX_ENABLED=true`); `index.warning` flags a stale index or folder errors |
 | `index_status` | Per-folder index coverage, last sync and errors |
 | `sync_index` | Run an index sync now |
 | `list_drafts` | List all draft emails |

package/index.js

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

package/lib/local-index.js

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

package/package.json

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