@lengelhard/imap-email-mcp 1.2.1 → 1.4.0

package/index.js

@@ -18,6 +18,38 @@ import {
 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';
+
+// Default directory where download_attachment saves files
+const ATTACHMENT_DIR =
+  process.env.ATTACHMENT_DIR ||
+  path.join(os.homedir(), 'Downloads', 'email-attachments');
+
+// Keep inline base64 well under the 1MB tool-result cap most MCP clients enforce.
+// 700KB raw ≈ 933KB base64, leaving headroom for the JSON envelope.
+const MAX_INLINE_BYTES = 700 * 1024;
+
+function sanitizeFilename(name) {
+  return (name || 'attachment').replace(/[/\\?%*:|"<>\x00-\x1f]/g, '_').slice(0, 200);
+}
+
+// Decode a fetched MIME part body according to its Content-Transfer-Encoding
+function decodePartBody(body, encoding) {
+  const enc = (encoding || '').toLowerCase();
+  if (enc === 'base64') {
+    return Buffer.from(String(body).replace(/\s+/g, ''), 'base64');
+  }
+  if (enc === 'quoted-printable') {
+    const text = String(body)
+      .replace(/=\r?\n/g, '')
+      .replace(/=([0-9A-Fa-f]{2})/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
+    return Buffer.from(text, 'latin1');
+  }
+  // 7bit / 8bit / binary — body is already raw
+  return Buffer.isBuffer(body) ? body : Buffer.from(String(body), 'latin1');
+}
 
 // Configuration from environment variables
 const IMAP_CONFIG = {
@@ -83,7 +115,15 @@ function findAttachmentParts(struct, parts = []) {
       );
 
     if (isAttachment) {
-      parts.push({ node, filename, contentType, disposition, partID: node.partID });
+      parts.push({
+        node,
+        filename,
+        contentType,
+        disposition,
+        partID: node.partID,
+        size: node.size ?? null,
+        encoding: node.encoding || null
+      });
     }
   }
 
@@ -349,7 +389,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'download_attachment',
-        description: 'Download a specific email attachment as base64-encoded content. Use the partID from get_email response.',
+        description: 'Download an email attachment. By default the file is decoded and saved to disk (ATTACHMENT_DIR, default ~/Downloads/email-attachments) and the local file path is returned. Set return_base64=true to get the content inline instead (only allowed for attachments under 700KB).',
         inputSchema: {
           type: 'object',
           properties: {
@@ -369,6 +409,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Folder name (default: INBOX)',
               default: 'INBOX'
+            },
+            save_path: {
+              type: 'string',
+              description: 'Optional destination. A directory (file keeps its original name) or a full file path. Defaults to ATTACHMENT_DIR.'
+            },
+            return_base64: {
+              type: 'boolean',
+              description: 'Return content inline as base64 instead of saving to disk. Fails for attachments over 700KB; prefer the default file mode.',
+              default: false
             }
           },
           required: ['uid']
@@ -461,11 +510,44 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
           required: ['uid', 'seen']
         }
+      },
+      {
+        name: 'move_thread',
+        description: 'Move an entire email thread (all messages matching a subject) from one folder to another in a single call. Strips Re:/Fwd: prefixes for matching. Use move_email for single-message precision moves.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            subject: {
+              type: 'string',
+              description: 'Subject line of the thread to move. Re:/Fwd: prefixes are stripped automatically for matching.'
+            },
+            from_folder: {
+              type: 'string',
+              description: 'Source folder to search for thread messages'
+            },
+            to_folder: {
+              type: 'string',
+              description: 'Destination folder to move messages into'
+            },
+            from_address: {
+              type: 'string',
+              description: 'Optional sender address to disambiguate threads with generic subjects'
+            }
+          },
+          required: ['subject', 'from_folder', 'to_folder']
+        }
       }
     ]
   };
 });
 
+// Strip Re:/Fwd:/Fw: prefixes from a subject line for thread matching.
+// Handles nested prefixes like "Re: Re: Fwd: topic" → "topic"
+function normalizeSubject(subject) {
+  if (!subject) return '';
+  return subject.replace(/^(\s*(Re|Fwd|Fw)\s*:\s*)+/i, '').trim();
+}
+
 // Helper function to connect to IMAP
 async function connectIMAP() {
   if (!IMAP_CONFIG.imap.password) {
@@ -616,13 +698,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                   );
 
                   // Also walk the raw MIME struct so we catch parts that mailparser
-                  // may have skipped: inline parts with filenames and parts that have
-                  // no Content-Disposition at all but carry a Content-Type "name" param.
+                  // may have skipped, and enrich every entry with its part_id so
+                  // download_attachment can be called directly.
                   const fromStruct = findAttachmentParts(msg.attributes.struct || []);
-                  for (const { filename, contentType } of fromStruct) {
+                  for (const { filename, contentType, partID, size } of fromStruct) {
                     const key = (filename || '').toLowerCase();
                     if (filename && !fromParser.has(key)) {
-                      fromParser.set(key, { filename, contentType, size: null });
+                      fromParser.set(key, { filename, contentType, size: size ?? null });
+                    }
+                    if (filename && fromParser.has(key)) {
+                      const entry = fromParser.get(key);
+                      entry.part_id = partID;
+                      if (entry.size == null) entry.size = size ?? null;
                     }
                   }
 
@@ -979,23 +1066,77 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return { content: [{ type: 'text', text: `Part ${partID} not found in message` }] };
           }
 
-          // imap-simple returns the body already base64-encoded by the mail server.
-          // Re-encoding would corrupt the output — strip whitespace and return directly.
-          const base64Content = String(partData.body).replace(/\s+/g, '');
-
           const attachmentParts = findAttachmentParts(msg.attributes.struct || []);
           const attachmentInfo = attachmentParts.find(p => p.partID === partID);
 
+          // Decode according to the part's Content-Transfer-Encoding
+          // (base64 for nearly all attachments, but not guaranteed).
+          const buffer = decodePartBody(partData.body, attachmentInfo?.encoding || 'base64');
+          const filename = sanitizeFilename(attachmentInfo?.filename || args.filename);
+          const contentType = attachmentInfo?.contentType || 'application/octet-stream';
+
+          // Inline mode: opt-in only, and only when it safely fits in a tool result
+          if (args.return_base64) {
+            if (buffer.length > MAX_INLINE_BYTES) {
+              return {
+                content: [{
+                  type: 'text',
+                  text: JSON.stringify({
+                    error: `Attachment is ${buffer.length} bytes; inline base64 is limited to ${MAX_INLINE_BYTES} bytes because the encoded result would exceed the MCP tool-result size cap. Call again without return_base64 to save it to disk and get the file path.`,
+                    uid: args.uid,
+                    partID,
+                    filename,
+                    size_bytes: buffer.length
+                  }, null, 2)
+                }],
+                isError: true
+              };
+            }
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  uid: args.uid,
+                  partID,
+                  filename,
+                  contentType,
+                  size_bytes: buffer.length,
+                  encoding: 'base64',
+                  data: buffer.toString('base64')
+                }, null, 2)
+              }]
+            };
+          }
+
+          // Default mode: save to disk and return the path
+          let target = args.save_path || ATTACHMENT_DIR;
+          let filePath;
+          if (args.save_path && path.extname(args.save_path)) {
+            // Treat as a full file path
+            filePath = args.save_path;
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+          } else {
+            fs.mkdirSync(target, { recursive: true });
+            filePath = path.join(target, filename);
+            // Avoid silently overwriting an existing different file
+            if (fs.existsSync(filePath)) {
+              const ext = path.extname(filename);
+              const base = path.basename(filename, ext);
+              filePath = path.join(target, `${base}_uid${args.uid}_${partID}${ext}`);
+            }
+          }
+          fs.writeFileSync(filePath, buffer);
+
           return {
             content: [{
               type: 'text',
               text: JSON.stringify({
                 uid: args.uid,
                 partID,
-                filename: attachmentInfo?.filename || args.filename || 'attachment',
-                contentType: attachmentInfo?.contentType || 'application/octet-stream',
-                encoding: 'base64',
-                data: base64Content
+                filename,
+                contentType,
+                size_bytes: buffer.length,
+                saved_to: filePath
               }, null, 2)
             }]
           };
@@ -1108,6 +1249,115 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
       }
 
+      case 'move_thread': {
+        const { subject, from_folder, to_folder, from_address } = args;
+        const normalizedTarget = normalizeSubject(subject);
+
+        if (!normalizedTarget) {
+          return {
+            content: [{ type: 'text', text: 'Error: subject cannot be empty' }],
+            isError: true
+          };
+        }
+
+        const connection = await connectIMAP();
+
+        try {
+          await connection.openBox(from_folder);
+
+          // Build IMAP search criteria: match subject header (and optionally sender)
+          const searchCriteria = [['SUBJECT', normalizedTarget]];
+          if (from_address) {
+            searchCriteria.push(['FROM', from_address]);
+          }
+
+          const fetchOptions = {
+            bodies: ['HEADER.FIELDS (SUBJECT FROM)'],
+            struct: false
+          };
+
+          const messages = await connection.search(searchCriteria, fetchOptions);
+
+          if (messages.length === 0) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  success: false,
+                  moved: 0,
+                  failed: 0,
+                  from_folder,
+                  to_folder,
+                  message: `No messages found matching subject "${normalizedTarget}" in ${from_folder}`
+                }, null, 2)
+              }]
+            };
+          }
+
+          // IMAP SUBJECT search is a substring match, so post-filter to ensure
+          // each message's normalized subject matches the target exactly.
+          const matchingUIDs = [];
+          for (const msg of messages) {
+            const header = msg.parts.find(p => p.which.includes('HEADER'))?.body || {};
+            const msgSubject = normalizeSubject((header.subject || [])[0] || '');
+            if (msgSubject.toLowerCase() === normalizedTarget.toLowerCase()) {
+              matchingUIDs.push(msg.attributes.uid);
+            }
+          }
+
+          if (matchingUIDs.length === 0) {
+            return {
+              content: [{
+                type: 'text',
+                text: JSON.stringify({
+                  success: false,
+                  moved: 0,
+                  failed: 0,
+                  from_folder,
+                  to_folder,
+                  message: `IMAP returned results but none matched the exact subject "${normalizedTarget}" after normalization`
+                }, null, 2)
+              }]
+            };
+          }
+
+          // Move each matching UID using the same imap.move() pattern as move_email
+          let moved = 0;
+          const failures = [];
+          for (const uid of matchingUIDs) {
+            try {
+              await new Promise((resolve, reject) => {
+                connection.imap.move(uid, to_folder, (err) => {
+                  if (err) reject(err);
+                  else resolve();
+                });
+              });
+              moved++;
+            } catch (moveErr) {
+              failures.push({ uid, error: moveErr.message });
+            }
+          }
+
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                success: failures.length === 0,
+                moved,
+                failed: failures.length,
+                total_found: matchingUIDs.length,
+                from_folder,
+                to_folder,
+                subject: normalizedTarget,
+                ...(failures.length > 0 && { failures })
+              }, null, 2)
+            }]
+          };
+        } finally {
+          connection.end();
+        }
+      }
+
       default:
         return { content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
     }

package/package.json

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