@lengelhard/imap-email-mcp 1.3.0 → 1.4.1

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
+      });
     }
   }
 
@@ -163,7 +203,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'get_email',
-        description: 'Get full email content by UID',
+        description: 'Get full email content by UID. IMPORTANT: UIDs are folder-scoped. Always pass the same folder the UID came from (list_emails or search_emails). Omitting folder opens INBOX and may silently return a different message.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -199,6 +239,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
               type: 'string',
               description: 'Search by sender'
             },
+            to: {
+              type: 'string',
+              description: 'Search by recipient (use with folder: "Sent" to find outgoing mail)'
+            },
             body: {
               type: 'string',
               description: 'Search in body text'
@@ -349,7 +393,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 +413,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']
@@ -631,6 +684,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               type: 'text',
               text: JSON.stringify({
                 uid: msg.attributes.uid,
+                folder,
                 from: parsed.from?.text,
                 to: parsed.to?.text,
                 cc: parsed.cc?.text,
@@ -642,20 +696,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                   // Start with what mailparser found (covers Content-Disposition: attachment
                   // and inline+filename cases for content it fully parsed).
                   const fromParser = new Map(
-                    (parsed.attachments || []).map(a => [
-                      (a.filename || '').toLowerCase(),
-                      { filename: a.filename, contentType: a.contentType, size: a.size }
+                    (parsed.attachments || []).map((a, i) => [
+                      a.filename ? a.filename.toLowerCase() : `__unnamed_${i}`,
+                      { filename: a.filename || null, contentType: a.contentType, size: a.size }
                     ])
                   );
 
                   // 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;
                     }
                   }
 
@@ -680,6 +739,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           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) {
@@ -1012,23 +1072,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)
             }]
           };

package/package.json

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