@lengelhard/imap-email-mcp 1.4.0 → 1.5.0

package/index.js

@@ -203,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: {
@@ -239,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'
@@ -389,7 +393,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: {
@@ -416,8 +420,7 @@ 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']
@@ -680,6 +683,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,
@@ -691,9 +695,9 @@ 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 }
                     ])
                   );
 
@@ -734,6 +738,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) {
@@ -1075,23 +1080,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',
@@ -1101,6 +1102,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                   filename,
                   contentType,
                   size_bytes: buffer.length,
+                  mode: 'base64',
                   encoding: 'base64',
                   data: buffer.toString('base64')
                 }, null, 2)
@@ -1108,7 +1110,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)) {
@@ -1136,7 +1143,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 filename,
                 contentType,
                 size_bytes: buffer.length,
-                saved_to: filePath
+                mode: 'file',
+                saved_to: filePath,
+                ...(fallbackNote ? { note: fallbackNote } : {})
               }, null, 2)
             }]
           };

package/package.json

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