@lengelhard/imap-email-mcp 1.4.1 → 1.6.0

package/README.md

@@ -121,6 +121,8 @@ Add to your config file:
 | `update_draft` | Update an existing draft |
 | `send_email` | Send an email directly |
 | `delete_email` | Delete an email by UID |
+| `download_attachment` | Download an attachment: ≤700KB returns inline base64, larger saves to disk (ATTACHMENT_DIR) |
+| `extract_text` | Extract plain text from a PDF, xlsx/xlsm/xls, docx, or text attachment in one call, parsed server-side |
 
 ## Usage Examples
 

package/index.js

@@ -31,6 +31,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);
 }
@@ -393,7 +435,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: 'download_attachment',
-        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).',
+        description: 'Download an email attachment. Mode is automatic: attachments up to 700KB are returned inline as base64; larger ones are decoded and saved to disk (ATTACHMENT_DIR, default ~/Downloads/email-attachments) with the file path returned. Every response includes a "mode" field ("base64" or "file"). Set return_base64 explicitly to force a mode; forcing base64 on an oversized attachment falls back to disk with a note instead of erroring.',
         inputSchema: {
           type: 'object',
           properties: {
@@ -420,8 +462,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             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
+              description: 'Optional. Omit for automatic mode: attachments up to 700KB return inline base64, larger ones are saved to disk. Set true/false to force a mode; true on an oversized attachment falls back to disk with a note.'
+            }
+          },
+          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']
@@ -1081,23 +1149,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           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
-              };
-            }
+          // Resolve mode:
+          // - return_base64 omitted -> auto: inline when it fits, disk otherwise
+          // - return_base64: true   -> inline, but fall back to disk (with a note)
+          //                            if oversized instead of erroring
+          // - return_base64: false  -> disk
+          const fitsInline = buffer.length <= MAX_INLINE_BYTES;
+          const wantInline = args.return_base64 === true
+            ? true
+            : args.return_base64 === false
+              ? false
+              : fitsInline;
+
+          if (wantInline && fitsInline) {
             return {
               content: [{
                 type: 'text',
@@ -1107,6 +1171,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                   filename,
                   contentType,
                   size_bytes: buffer.length,
+                  mode: 'base64',
                   encoding: 'base64',
                   data: buffer.toString('base64')
                 }, null, 2)
@@ -1114,7 +1179,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
           }
 
-          // Default mode: save to disk and return the path
+          // Note attached to the result when inline was requested but not possible
+          const fallbackNote = (wantInline && !fitsInline)
+            ? `Attachment is ${buffer.length} bytes, over the ${MAX_INLINE_BYTES}-byte inline limit; saved to disk instead.`
+            : undefined;
+
+          // Disk mode: save and return the path
           let target = args.save_path || ATTACHMENT_DIR;
           let filePath;
           if (args.save_path && path.extname(args.save_path)) {
@@ -1142,7 +1212,128 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 filename,
                 contentType,
                 size_bytes: buffer.length,
-                saved_to: filePath
+                mode: 'file',
+                saved_to: filePath,
+                ...(fallbackNote ? { note: fallbackNote } : {})
+              }, null, 2)
+            }]
+          };
+        } finally {
+          connection.end();
+        }
+      }
+
+      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)
             }]
           };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lengelhard/imap-email-mcp",
-  "version": "1.4.1",
+  "version": "1.6.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",
@@ -45,6 +45,9 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "imap-simple": "^5.1.0",
     "mailparser": "^3.7.2",
-    "nodemailer": "^6.9.16"
+    "mammoth": "^1.8.0",
+    "nodemailer": "^6.9.16",
+    "unpdf": "^1.8.1",
+    "xlsx": "^0.18.5"
   }
 }