@lengelhard/imap-email-mcp 1.6.0 → 1.7.0

package/index.js

@@ -15,12 +15,24 @@ import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import imaps from 'imap-simple';
 import { simpleParser } from 'mailparser';
 import nodemailer from 'nodemailer';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
+import { createRequire } from 'module';
+import {
+  SessionManager,
+  openBox,
+  queryUids,
+  fetchMessages,
+  headerOf,
+  buildCriteria
+} from './lib/imap-session.js';
+import { htmlToText, stripDataUris, leafParts } from './lib/mime-text.js';
+import { LocalIndex } from './lib/local-index.js';
+
+const PKG_VERSION = createRequire(import.meta.url)('./package.json').version;
 
 // Default directory where download_attachment saves files
 const ATTACHMENT_DIR =
@@ -192,7 +204,7 @@ function validateConfig() {
 const server = new Server(
   {
     name: 'imap-email-mcp',
-    version: '1.0.0',
+    version: PKG_VERSION,
   },
   {
     capabilities: {
@@ -216,7 +228,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'list_emails',
-        description: 'List emails from a folder with optional filtering',
+        description: 'List emails from a folder, newest first (by delivery time). Filters can be combined. Returns total_matches so you can tell when results were capped.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -227,17 +239,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             limit: {
               type: 'number',
-              description: 'Maximum number of emails to return (default: 20)',
+              description: 'Maximum number of emails to return (default: 20, max: 200)',
               default: 20
             },
+            offset: {
+              type: 'number',
+              description: 'Skip this many of the newest matches, for paging (default: 0)',
+              default: 0
+            },
             unseen_only: {
               type: 'boolean',
               description: 'Only return unread emails',
               default: false
             },
+            flagged_only: {
+              type: 'boolean',
+              description: 'Only return flagged (starred) emails',
+              default: false
+            },
             since_date: {
               type: 'string',
-              description: 'Only return emails since this date (YYYY-MM-DD format)'
+              description: 'Only return emails on or after this date (YYYY-MM-DD)'
+            },
+            before_date: {
+              type: 'string',
+              description: 'Only return emails before this date (YYYY-MM-DD)'
             }
           },
           required: []
@@ -257,6 +283,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Folder name (default: INBOX)',
               default: 'INBOX'
+            },
+            include_html: {
+              type: 'boolean',
+              description: 'Also return the HTML body, with inline images removed (default: false). The text body is always returned; for HTML-only emails it is converted from the HTML.',
+              default: false
             }
           },
           required: ['uid']
@@ -264,15 +295,46 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'search_emails',
-        description: 'Search emails by subject, from, or body text',
+        description: 'Live IMAP search on the server. All given criteria must match. Results are newest first and include folder and uid. Sender, recipient, subject, date and flag criteria are reliable. Body and text criteria depend on the server and can silently miss messages on some providers; for content searches prefer search_index when it is available.',
         inputSchema: {
           type: 'object',
           properties: {
             folder: {
               type: 'string',
-              description: 'Folder to search (default: INBOX)',
+              description: 'Folder to search (default: INBOX). Ignored when folders is given.',
               default: 'INBOX'
             },
+            folders: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Search several folders in one call, e.g. ["INBOX", "Action", "Waiting", "Archive"]. Results are merged and sorted by date.'
+            },
+            cc: {
+              type: 'string',
+              description: 'Search by CC recipient'
+            },
+            text: {
+              type: 'string',
+              description: 'Search headers and body together (server-dependent, see description)'
+            },
+            since_date: {
+              type: 'string',
+              description: 'Only emails on or after this date (YYYY-MM-DD)'
+            },
+            before_date: {
+              type: 'string',
+              description: 'Only emails before this date (YYYY-MM-DD)'
+            },
+            unseen_only: {
+              type: 'boolean',
+              description: 'Only unread emails',
+              default: false
+            },
+            flagged_only: {
+              type: 'boolean',
+              description: 'Only flagged (starred) emails',
+              default: false
+            },
             subject: {
               type: 'string',
               description: 'Search in subject line'
@@ -287,17 +349,113 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             body: {
               type: 'string',
-              description: 'Search in body text'
+              description: 'Search in body text (server-dependent, see description)'
             },
             limit: {
               type: 'number',
-              description: 'Maximum results (default: 20)',
+              description: 'Maximum results (default: 20, max: 200)',
               default: 20
             }
           },
           required: []
         }
       },
+      ...(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.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              query: {
+                type: 'string',
+                description: 'Words to find. By default every word must appear (match: all).'
+              },
+              match: {
+                type: 'string',
+                enum: ['all', 'any', 'phrase'],
+                description: 'all: every word; any: at least one word; phrase: the exact phrase (default: all)',
+                default: 'all'
+              },
+              prefix: {
+                type: 'boolean',
+                description: 'Treat each word as a prefix, e.g. "valuat" matches "valuation" (default: false)',
+                default: false
+              },
+              field: {
+                type: 'string',
+                enum: ['any', 'subject', 'body', 'from', 'to', 'attachments'],
+                description: 'Restrict the match to one field (default: any)',
+                default: 'any'
+              },
+              folders: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Only these folders (default: all indexed folders)'
+              },
+              from: {
+                type: 'string',
+                description: 'Only messages whose sender contains this text'
+              },
+              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)'
+              },
+              sort: {
+                type: 'string',
+                enum: ['date', 'relevance'],
+                description: 'date: newest first; relevance: best match first (default: date)',
+                default: 'date'
+              },
+              limit: {
+                type: 'number',
+                description: 'Maximum results (default: 20, max: 200)',
+                default: 20
+              },
+              offset: {
+                type: 'number',
+                description: 'Skip this many results, for paging (default: 0)',
+                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: ['query']
+          }
+        },
+        {
+          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.',
+          inputSchema: { type: 'object', properties: {}, 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.',
+          inputSchema: {
+            type: 'object',
+            properties: {
+              folders: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Only sync these folders (default: all indexed folders)'
+              },
+              wait_seconds: {
+                type: 'number',
+                description: 'How long to wait before returning while the sync continues in the background (default: 60)',
+                default: 60
+              }
+            },
+            required: []
+          }
+        }
+      ] : []),
       {
         name: 'list_drafts',
         description: 'List all draft emails',
@@ -620,12 +778,59 @@ function normalizeSubject(subject) {
   return subject.replace(/^(\s*(Re|Fwd|Fw)\s*:\s*)+/i, '').trim();
 }
 
-// Helper function to connect to IMAP
+// Shared IMAP session. connectIMAP() returns a lease on one persistent
+// connection; connection.end() releases the lease instead of logging out.
+const sessions = new SessionManager(IMAP_CONFIG, {
+  idleCloseMs: parseInt(process.env.IMAP_IDLE_CLOSE_SECONDS || '300') * 1000
+});
+
+// Optional local read-only index (INDEX_ENABLED=true)
+let localIndex = null;
+let localIndexError = null;
+
 async function connectIMAP() {
   if (!IMAP_CONFIG.imap.password) {
     throw new Error('IMAP_PASSWORD environment variable is not set');
   }
-  return await imaps.connect(IMAP_CONFIG);
+  return await sessions.acquire();
+}
+
+const LIST_HEADER_FIELDS = 'HEADER.FIELDS (FROM TO CC SUBJECT DATE)';
+const MAX_LIMIT = 200;
+
+function clampLimit(value, fallback = 20) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return Math.min(Math.floor(n), MAX_LIMIT);
+}
+
+// Fetch compact header summaries for an ordered UID list, keeping that order.
+async function summarize(connection, folder, uids, { withFlags = true } = {}) {
+  const fetched = await fetchMessages(connection, uids, { bodies: [LIST_HEADER_FIELDS] });
+  const parseHeader = connection.imap.constructor.parseHeader;
+  const out = [];
+  for (const uid of uids) {
+    const rec = fetched.get(uid);
+    if (!rec) continue;
+    const h = headerOf(rec, parseHeader);
+    const item = {
+      folder,
+      uid,
+      date: h.date?.[0],
+      from: h.from?.[0],
+      to: h.to?.join(', '),
+      subject: h.subject?.[0]
+    };
+    if (h.cc?.length) item.cc = h.cc.join(', ');
+    if (withFlags) item.flags = rec.attributes.flags;
+    out.push(item);
+  }
+  return out;
+}
+
+function dateValue(item) {
+  const t = Date.parse(item.date || '');
+  return Number.isNaN(t) ? 0 : t;
 }
 
 // Helper to find drafts folder (handles different provider conventions)
@@ -657,9 +862,23 @@ async function findDraftsFolder(connection) {
 }
 
 // Tool handlers
+const INDEX_AFFECTING_TOOLS = {
+  move_email: (a) => [a.from_folder || 'INBOX', a.to_folder],
+  move_thread: (a) => [a.from_folder, a.to_folder],
+  delete_email: (a) => [a.folder || 'INBOX']
+};
+
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args } = request.params;
+  const { name, arguments: rawArgs } = request.params;
+  const args = rawArgs || {};
+  const result = await handleTool(name, args);
+  if (localIndex && INDEX_AFFECTING_TOOLS[name] && !result.isError) {
+    localIndex.requestSync(INDEX_AFFECTING_TOOLS[name](args));
+  }
+  return result;
+});
 
+async function handleTool(name, args) {
   try {
     switch (name) {
       case 'list_folders': {
@@ -687,39 +906,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
       case 'list_emails': {
         const folder = args.folder || 'INBOX';
-        const limit = args.limit || 20;
+        const limit = clampLimit(args.limit);
+        const offset = Math.max(0, Number(args.offset) || 0);
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(folder);
-
-          let searchCriteria = ['ALL'];
-          if (args.unseen_only) {
-            searchCriteria = ['UNSEEN'];
-          }
-          if (args.since_date) {
-            searchCriteria = [['SINCE', args.since_date]];
-          }
-
-          const fetchOptions = {
-            bodies: ['HEADER.FIELDS (FROM TO SUBJECT DATE)'],
-            struct: true
-          };
-
-          const messages = await connection.search(searchCriteria, fetchOptions);
-          const results = messages.slice(-limit).reverse().map(msg => {
-            const header = msg.parts.find(p => p.which.includes('HEADER'))?.body || {};
-            return {
-              uid: msg.attributes.uid,
-              date: header.date?.[0],
-              from: header.from?.[0],
-              to: header.to?.[0],
-              subject: header.subject?.[0],
-              flags: msg.attributes.flags
-            };
+          await openBox(connection, folder, true);
+          const criteria = buildCriteria({
+            unseen_only: args.unseen_only,
+            flagged_only: args.flagged_only,
+            since_date: args.since_date,
+            before_date: args.before_date
           });
+          const uids = await queryUids(connection, criteria, { order: 'arrival' });
+          const page = uids.slice(offset, offset + limit);
+          const results = await summarize(connection, folder, page);
 
-          return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({ folder, total_matches: uids.length, returned: results.length, offset, results }, null, 2)
+            }]
+          };
         } finally {
           connection.end();
         }
@@ -730,22 +938,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(folder);
-
-          const fetchOptions = {
-            bodies: [''],
-            struct: true
-          };
+          await openBox(connection, folder, true);
 
-          const messages = await connection.search([['UID', args.uid]], fetchOptions);
+          const uid = Number(args.uid);
+          const fetched = await fetchMessages(connection, [uid], { bodies: [''], struct: true });
+          const rec = fetched.get(uid);
 
-          if (messages.length === 0) {
-            return { content: [{ type: 'text', text: 'Email not found' }] };
+          if (!rec) {
+            return {
+              content: [{ type: 'text', text: `Email not found: uid ${uid} in ${folder}. UIDs change when a message is moved; search again to get the current uid.` }],
+              isError: true
+            };
           }
 
-          const msg = messages[0];
-          const rawBody = msg.parts.find(p => p.which === '')?.body;
+          const msg = { attributes: rec.attributes };
+          const rawBody = rec.parts[''] ?? rec.parts[Object.keys(rec.parts)[0]];
           const parsed = await simpleParser(rawBody);
+          const hasPlainPart = leafParts(rec.attributes.struct || [])
+            .some((n) => `${n.type}/${n.subtype}`.toLowerCase() === 'text/plain' && (n.disposition?.type || '').toLowerCase() !== 'attachment');
+          const htmlOnly = !!parsed.html && !hasPlainPart;
 
           return {
             content: [{
@@ -758,8 +969,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 cc: parsed.cc?.text,
                 subject: parsed.subject,
                 date: parsed.date,
-                text: parsed.text,
-                html: parsed.html,
+                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) }),
                 attachments: (() => {
                   // Start with what mailparser found (covers Content-Disposition: attachment
                   // and inline+filename cases for content it fully parsed).
@@ -797,41 +1009,45 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       }
 
       case 'search_emails': {
-        const folder = args.folder || 'INBOX';
-        const limit = args.limit || 20;
+        const folders = Array.isArray(args.folders) && args.folders.length
+          ? args.folders
+          : [args.folder || 'INBOX'];
+        const limit = clampLimit(args.limit);
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(folder);
-
-          let searchCriteria = [];
-          if (args.subject) searchCriteria.push(['SUBJECT', args.subject]);
-          if (args.from) searchCriteria.push(['FROM', args.from]);
-          if (args.to) searchCriteria.push(['TO', args.to]);
-          if (args.body) searchCriteria.push(['BODY', args.body]);
-
-          if (searchCriteria.length === 0) {
-            searchCriteria = ['ALL'];
+          const merged = [];
+          const perFolder = {};
+          const errors = {};
+          for (const folder of folders) {
+            try {
+              await openBox(connection, folder, true);
+              // Fresh criteria per folder: node-imap rewrites date arguments in place.
+              const uids = await queryUids(connection, buildCriteria(args), { order: 'arrival' });
+              perFolder[folder] = uids.length;
+              merged.push(...await summarize(connection, folder, uids.slice(0, limit), { withFlags: true }));
+            } catch (err) {
+              errors[folder] = err.message;
+            }
           }
 
-          const fetchOptions = {
-            bodies: ['HEADER.FIELDS (FROM TO SUBJECT DATE)'],
-            struct: true
-          };
-
-          const messages = await connection.search(searchCriteria, fetchOptions);
-          const results = messages.slice(-limit).reverse().map(msg => {
-            const header = msg.parts.find(p => p.which.includes('HEADER'))?.body || {};
-            return {
-              uid: msg.attributes.uid,
-              date: header.date?.[0],
-              from: header.from?.[0],
-              to: header.to?.[0],
-              subject: header.subject?.[0]
-            };
-          });
+          merged.sort((a, b) => dateValue(b) - dateValue(a));
+          const results = merged.slice(0, limit);
+          const total = Object.values(perFolder).reduce((a, b) => a + b, 0);
 
-          return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                total_matches: total,
+                returned: results.length,
+                ...(folders.length > 1 && { matches_per_folder: perFolder }),
+                ...(Object.keys(errors).length && { errors }),
+                results
+              }, null, 2)
+            }],
+            ...(Object.keys(errors).length === folders.length && { isError: true })
+          };
         } finally {
           connection.end();
         }
@@ -1555,6 +1771,65 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
       }
 
+      case 'search_index': {
+        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 timedOut = await Promise.race([
+              quick.then(() => false),
+              new Promise((resolve) => setTimeout(() => resolve(true), 20000))
+            ]);
+            refresh = timedOut ? 'partial: refresh still running in background' : 'done';
+          }
+        }
+        const found = localIndex.search({
+          query: args.query,
+          match: args.match,
+          prefix: args.prefix,
+          field: args.field,
+          folders: args.folders,
+          from: args.from,
+          since_date: args.since_date,
+          before_date: args.before_date,
+          sort: args.sort,
+          limit: args.limit,
+          offset: args.offset
+        });
+        if (refresh) found.index.refresh = refresh;
+        return { content: [{ type: 'text', text: JSON.stringify(found, null, 2) }] };
+      }
+
+      case 'index_status': {
+        if (!localIndex) throw new Error(localIndexError || 'Local index is not enabled (set INDEX_ENABLED=true)');
+        return { content: [{ type: 'text', text: JSON.stringify(localIndex.status(), 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;
+        const run = localIndex.sync(args.folders?.length ? { folders: args.folders } : {});
+        const outcome = await Promise.race([
+          run.then((summary) => ({ finished: true, summary })),
+          new Promise((resolve) => setTimeout(() => resolve({ finished: false }), waitMs))
+        ]);
+        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 }),
+              status: localIndex.status()
+            }, null, 2)
+          }]
+        };
+      }
+
       default:
         return { content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
     }
@@ -1567,11 +1842,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       isError: true
     };
   }
-});
+}
 
 // Start server
 async function main() {
   validateConfig();
+
+  if (/^(1|true|yes)$/i.test(process.env.INDEX_ENABLED || '')) {
+    const list = (v) => (v || '').split(',').map((x) => x.trim()).filter(Boolean);
+    try {
+      localIndex = await new LocalIndex({
+        imapConfig: IMAP_CONFIG,
+        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')
+      }).open();
+      localIndex.start();
+      console.error(`Local index enabled: ${localIndex.dbPath}`);
+    } catch (err) {
+      localIndex = null;
+      localIndexError = `Local index failed to start: ${err.message}`;
+      console.error(localIndexError);
+    }
+  }
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error('IMAP Email MCP Server running on stdio');