@lengelhard/imap-email-mcp 1.0.1 → 1.0.3

package/index.js

@@ -83,7 +83,7 @@ function findAttachmentParts(struct, parts = []) {
       );
 
     if (isAttachment) {
-      parts.push({ node, filename, contentType, disposition });
+      parts.push({ node, filename, contentType, disposition, partID: node.partID });
     }
   }
 
@@ -347,6 +347,33 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           required: ['to', 'subject']
         }
       },
+      {
+        name: 'download_attachment',
+        description: 'Download a specific email attachment as base64-encoded content. Use the partID from get_email response.',
+        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 (default: INBOX)',
+              default: 'INBOX'
+            }
+          },
+          required: ['uid']
+        }
+      },
       {
         name: 'delete_email',
         description: 'Delete an email by UID',
@@ -515,7 +542,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                   const fromParser = new Map(
                     (parsed.attachments || []).map(a => [
                       (a.filename || '').toLowerCase(),
-                      { filename: a.filename, contentType: a.contentType, size: a.size }
+                      { filename: a.filename, contentType: a.contentType, size: a.size, partID: null }
                     ])
                   );
 
@@ -523,10 +550,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                   // may have skipped: inline parts with filenames and parts that have
                   // no Content-Disposition at all but carry a Content-Type "name" param.
                   const fromStruct = findAttachmentParts(msg.attributes.struct || []);
-                  for (const { filename, contentType } of fromStruct) {
+                  for (const { filename, contentType, partID } of fromStruct) {
                     const key = (filename || '').toLowerCase();
-                    if (filename && !fromParser.has(key)) {
-                      fromParser.set(key, { filename, contentType, size: null });
+                    if (filename) {
+                      if (!fromParser.has(key)) {
+                        fromParser.set(key, { filename, contentType, size: null, partID });
+                      } else {
+                        // Enrich existing entry with partID from struct
+                        fromParser.get(key).partID = partID;
+                      }
                     }
                   }
 
@@ -771,6 +803,88 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case 'download_attachment': {
+        const folder = args.folder || 'INBOX';
+        const connection = await connectIMAP();
+
+        try {
+          await connection.openBox(folder);
+
+          // First fetch the struct to find the part if part_id not provided
+          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 no partID given, find it by filename
+          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
+            };
+          }
+
+          // Fetch the specific MIME part
+          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 partMsg = partFetch[0];
+          const partData = partMsg.parts.find(p => p.which === partID);
+
+          if (!partData) {
+            return { content: [{ type: 'text', text: `Part ${partID} not found in message` }] };
+          }
+
+          // IMAP attachment parts are already base64-encoded by the mail server.
+          // Return the raw content as-is — do NOT re-encode, which would double-encode.
+          const rawContent = partData.body;
+          const base64Content = Buffer.isBuffer(rawContent)
+            ? rawContent.toString('ascii').replace(/\s/g, '')   // buffer → clean base64 string
+            : rawContent.replace(/\s/g, '');                    // string → strip whitespace/newlines
+
+          // Get filename from struct for reference
+          const attachmentParts = findAttachmentParts(msg.attributes.struct || []);
+          const attachmentInfo = attachmentParts.find(p => p.partID === partID);
+
+          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
+              }, null, 2)
+            }]
+          };
+        } finally {
+          connection.end();
+        }
+      }
+
       case 'delete_email': {
         const folder = args.folder || 'INBOX';
         const connection = await connectIMAP();

package/package.json

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