@lengelhard/imap-email-mcp 1.5.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 =
@@ -31,6 +43,48 @@ const ATTACHMENT_DIR =
 // 700KB raw ≈ 933KB base64, leaving headroom for the JSON envelope.
 const MAX_INLINE_BYTES = 700 * 1024;
 
+// Cap on text returned by extract_text, to stay well under tool-result limits
+const MAX_EXTRACT_CHARS = 500 * 1024;
+
+// Parse a binary attachment buffer into plain text, dispatching on content
+// type / filename extension. Parsers are imported lazily so the server starts
+// fast and a missing optional parser only affects extract_text itself.
+async function extractTextFromBuffer(buffer, contentType, filename) {
+  const ct = (contentType || '').toLowerCase();
+  const ext = (filename || '').toLowerCase().split('.').pop();
+
+  if (ct.includes('pdf') || ext === 'pdf') {
+    const { extractText } = await import('unpdf');
+    const { totalPages, text } = await extractText(new Uint8Array(buffer), { mergePages: true });
+    return { parser: 'unpdf', pages: totalPages, text };
+  }
+
+  if (
+    ct.includes('spreadsheetml') || ct.includes('ms-excel') ||
+    ext === 'xlsx' || ext === 'xlsm' || ext === 'xls'
+  ) {
+    const XLSX = await import('xlsx');
+    const wb = XLSX.read(buffer, { type: 'buffer' });
+    const parts = wb.SheetNames.map(name => {
+      const csv = XLSX.utils.sheet_to_csv(wb.Sheets[name], { blankrows: false });
+      return `=== Sheet: ${name} ===\n${csv}`;
+    });
+    return { parser: 'xlsx', sheets: wb.SheetNames, text: parts.join('\n\n') };
+  }
+
+  if (ct.includes('wordprocessingml') || ext === 'docx') {
+    const { default: mammoth } = await import('mammoth');
+    const result = await mammoth.extractRawText({ buffer });
+    return { parser: 'mammoth', text: result.value };
+  }
+
+  if (ct.startsWith('text/') || ['txt', 'csv', 'md', 'json', 'xml', 'html'].includes(ext)) {
+    return { parser: 'utf8', text: buffer.toString('utf8') };
+  }
+
+  return null; // unsupported type
+}
+
 function sanitizeFilename(name) {
   return (name || 'attachment').replace(/[/\\?%*:|"<>\x00-\x1f]/g, '_').slice(0, 200);
 }
@@ -150,7 +204,7 @@ function validateConfig() {
 const server = new Server(
   {
     name: 'imap-email-mcp',
-    version: '1.0.0',
+    version: PKG_VERSION,
   },
   {
     capabilities: {
@@ -174,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: {
@@ -185,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: []
@@ -215,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']
@@ -222,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'
@@ -245,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',
@@ -426,6 +626,33 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ['uid']
         }
       },
+      {
+        name: 'extract_text',
+        description: 'Extract readable plain text from an email attachment in one call, parsed server-side. Supports PDF (pdf-parse), Excel xlsx/xlsm/xls (sheet-by-sheet CSV), Word docx (mammoth), and plain-text types. Use this instead of download_attachment when the goal is to read or analyze attachment content. Returns text plus metadata (filename, contentType, size_bytes, parser). Output is capped at 500KB with a truncation note. Unsupported types return an error naming the supported set; use download_attachment for those.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            uid: {
+              type: 'number',
+              description: 'Email UID'
+            },
+            part_id: {
+              type: 'string',
+              description: 'MIME part ID of the attachment (from get_email response)'
+            },
+            filename: {
+              type: 'string',
+              description: 'Filename of the attachment (used as fallback to find part_id if not provided)'
+            },
+            folder: {
+              type: 'string',
+              description: 'Folder name the UID belongs to (default: INBOX). Always pass this explicitly for non-inbox messages.',
+              default: 'INBOX'
+            }
+          },
+          required: ['uid']
+        }
+      },
       {
         name: 'delete_email',
         description: 'Delete an email by UID',
@@ -551,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)
@@ -588,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': {
@@ -618,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();
         }
@@ -661,22 +938,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const connection = await connectIMAP();
 
         try {
-          await connection.openBox(folder);
+          await openBox(connection, folder, true);
 
-          const fetchOptions = {
-            bodies: [''],
-            struct: true
-          };
+          const uid = Number(args.uid);
+          const fetched = await fetchMessages(connection, [uid], { bodies: [''], struct: true });
+          const rec = fetched.get(uid);
 
-          const messages = await connection.search([['UID', args.uid]], fetchOptions);
-
-          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: [{
@@ -689,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).
@@ -728,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();
         }
@@ -1154,6 +1439,125 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
       }
 
+      case 'extract_text': {
+        const folder = args.folder || 'INBOX';
+        const connection = await connectIMAP();
+
+        try {
+          await connection.openBox(folder);
+
+          const structFetch = await connection.search([['UID', args.uid]], {
+            bodies: [],
+            struct: true
+          });
+
+          if (structFetch.length === 0) {
+            return { content: [{ type: 'text', text: 'Email not found' }] };
+          }
+
+          const msg = structFetch[0];
+          let partID = args.part_id;
+
+          if (!partID && args.filename) {
+            const attachmentParts = findAttachmentParts(msg.attributes.struct || []);
+            const match = attachmentParts.find(p =>
+              (p.filename || '').toLowerCase() === args.filename.toLowerCase()
+            );
+            if (match) partID = match.partID;
+          }
+
+          if (!partID) {
+            return {
+              content: [{ type: 'text', text: 'Could not determine part ID. Please provide part_id from get_email response.' }],
+              isError: true
+            };
+          }
+
+          const partFetch = await connection.search([['UID', args.uid]], {
+            bodies: [partID],
+            struct: true
+          });
+
+          if (partFetch.length === 0) {
+            return { content: [{ type: 'text', text: 'Attachment part not found' }] };
+          }
+
+          const partData = partFetch[0].parts.find(p => p.which === partID);
+
+          if (!partData) {
+            return { content: [{ type: 'text', text: `Part ${partID} not found in message` }] };
+          }
+
+          const attachmentParts = findAttachmentParts(msg.attributes.struct || []);
+          const attachmentInfo = attachmentParts.find(p => p.partID === partID);
+
+          const buffer = decodePartBody(partData.body, attachmentInfo?.encoding || 'base64');
+          const filename = sanitizeFilename(attachmentInfo?.filename || args.filename);
+          const contentType = attachmentInfo?.contentType || 'application/octet-stream';
+
+          let extracted;
+          try {
+            extracted = await extractTextFromBuffer(buffer, contentType, filename);
+          } catch (parseErr) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  error: `Parsing failed: ${parseErr.message}`,
+                  uid: args.uid,
+                  partID,
+                  filename,
+                  contentType,
+                  size_bytes: buffer.length,
+                  hint: 'The file may be corrupted, password-protected, or an unusual variant. Use download_attachment to get the raw file.'
+                }, null, 2)
+              }],
+              isError: true
+            };
+          }
+
+          if (!extracted) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  error: `Unsupported type for text extraction: ${contentType} (${filename}). Supported: PDF, xlsx/xlsm/xls, docx, and plain-text types.`,
+                  uid: args.uid,
+                  partID,
+                  hint: 'Use download_attachment to get the raw file.'
+                }, null, 2)
+              }],
+              isError: true
+            };
+          }
+
+          const truncated = extracted.text.length > MAX_EXTRACT_CHARS;
+          const text = truncated
+            ? extracted.text.slice(0, MAX_EXTRACT_CHARS)
+            : extracted.text;
+
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                uid: args.uid,
+                partID,
+                filename,
+                contentType,
+                size_bytes: buffer.length,
+                parser: extracted.parser,
+                ...(extracted.pages !== undefined ? { pages: extracted.pages } : {}),
+                ...(extracted.sheets !== undefined ? { sheets: extracted.sheets } : {}),
+                ...(truncated ? { note: `Text truncated to ${MAX_EXTRACT_CHARS} characters (full length ${extracted.text.length}).` } : {}),
+                text
+              }, null, 2)
+            }]
+          };
+        } finally {
+          connection.end();
+        }
+      }
+
       case 'delete_email': {
         const folder = args.folder || 'INBOX';
         const connection = await connectIMAP();
@@ -1367,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}` }] };
     }
@@ -1379,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');