ms365-mcp-server 1.1.17 → 1.1.19

package/README.md

@@ -12,6 +12,12 @@ A powerful **Model Context Protocol (MCP) server** that enables seamless Microso
 - **📁 Smart Contact Management** - Search and retrieve your Microsoft 365 contacts
 - **🌐 Cross-Platform** - Works on macOS, Linux, and Windows
 
+## 📚 Documentation
+
+For detailed technical documentation, enhancement reports, and guides, see the **[docs/](./docs/)** directory:
+- **[Enhancement Reports](./docs/MS365-MCP-Server-Enhancement-Report.md)** - Recent fixes and improvements
+- **[Technical Guides](./docs/)** - Batch operations and Graph API implementation guides
+
 ## 🛠️ Available Tools (6 Total)
 
 ### **📧 Email Management**

package/dist/index.js

@@ -83,7 +83,7 @@ function parseArgs() {
 }
 const server = new Server({
     name: "ms365-mcp-server",
-    version: "1.1.17"
+    version: "1.1.19"
 }, {
     capabilities: {
         resources: {

package/dist/utils/ms365-operations.js

@@ -7,7 +7,7 @@ export class MS365Operations {
     constructor() {
         this.graphClient = null;
         this.searchCache = new Map();
-        this.CACHE_DURATION = 60 * 1000; // 1 minute cache
+        this.CACHE_DURATION = 300 * 1000; // 5 minute cache for better performance
         this.MAX_RETRIES = 3;
         this.BASE_DELAY = 1000; // 1 second
     }
@@ -101,6 +101,7 @@ export class MS365Operations {
     }
     /**
      * Utility method to validate and format date for OData filters
+     * Microsoft Graph expects DateTimeOffset without quotes in OData filters
      */
     formatDateForOData(dateString) {
         try {
@@ -108,7 +109,8 @@ export class MS365Operations {
             if (isNaN(date.getTime())) {
                 throw new Error(`Invalid date: ${dateString}`);
             }
-            return date.toISOString();
+            // Remove milliseconds and format for OData DateTimeOffset (no quotes needed)
+            return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
         }
         catch (error) {
             logger.error(`Error formatting date ${dateString}:`, error);
@@ -127,23 +129,20 @@ export class MS365Operations {
             const escapedFrom = this.escapeODataValue(criteria.from);
             filters.push(`from/emailAddress/address eq '${escapedFrom}'`);
         }
-        // ✅ SAFE: toRecipients/ccRecipients with proper any() syntax
-        if (criteria.to && criteria.to.includes('@')) {
-            const escapedTo = this.escapeODataValue(criteria.to);
-            filters.push(`toRecipients/any(r: r/emailAddress/address eq '${escapedTo}')`);
-        }
+        // NOTE: toRecipients filtering is not supported by Microsoft Graph OData API
+        // Manual filtering will be applied after retrieving results
         if (criteria.cc && criteria.cc.includes('@')) {
             const escapedCc = this.escapeODataValue(criteria.cc);
-            filters.push(`ccRecipients/any(r: r/emailAddress/address eq '${escapedCc}')`);
+            filters.push(`ccRecipients/any(c: c/emailAddress/address eq '${escapedCc}')`);
         }
-        // ✅ SAFE: Date filters with proper ISO 8601 format
+        // ✅ SAFE: Date filters with proper DateTimeOffset format (no quotes)
         if (criteria.after) {
             const afterDate = this.formatDateForOData(criteria.after);
-            filters.push(`receivedDateTime ge '${afterDate}'`);
+            filters.push(`receivedDateTime ge ${afterDate}`);
         }
         if (criteria.before) {
             const beforeDate = this.formatDateForOData(criteria.before);
-            filters.push(`receivedDateTime le '${beforeDate}'`);
+            filters.push(`receivedDateTime le ${beforeDate}`);
         }
         // ✅ SAFE: Boolean filters
         if (criteria.hasAttachment !== undefined) {
@@ -1007,8 +1006,13 @@ ${originalBodyContent}
                 (criteria.from && !criteria.from.includes('@')) // name searches
             );
             try {
+                // STRATEGY 0: FOLDER SEARCH - Handle folder searches with optimized methods
+                if (criteria.folder) {
+                    logger.log('🔍 Using OPTIMIZED FOLDER SEARCH strategy');
+                    allMessages = await this.performOptimizedFolderSearch(criteria, maxResults);
+                }
                 // STRATEGY A: Pure Filter Strategy (when no search fields present)
-                if (hasFilterableFields && !hasSearchableFields) {
+                else if (hasFilterableFields && !hasSearchableFields) {
                     logger.log('🔍 Using PURE FILTER strategy (structured queries only)');
                     allMessages = await this.performPureFilterSearch(criteria, maxResults);
                 }
@@ -1029,7 +1033,8 @@ ${originalBodyContent}
                     allMessages = basicResult.messages;
                 }
                 // Apply manual filtering for unsupported fields (to/cc names, complex logic)
-                const filteredMessages = this.applyManualFiltering(allMessages, criteria);
+                // Note: Skip manual filtering for folder searches as they handle it internally
+                const filteredMessages = criteria.folder ? allMessages : this.applyManualFiltering(allMessages, criteria);
                 // Sort by relevance and date
                 const sortedMessages = this.sortSearchResults(filteredMessages, criteria);
                 // Apply maxResults limit
@@ -1420,11 +1425,8 @@ ${originalBodyContent}
                     filters.push(`contains(from/emailAddress/name,'${escapedFrom}')`);
                 }
             }
-            if (criteria.to && criteria.to.includes('@')) {
-                // Properly escape single quotes in email addresses
-                const escapedTo = this.escapeODataValue(criteria.to);
-                filters.push(`toRecipients/any(r: r/emailAddress/address eq '${escapedTo}')`);
-            }
+            // NOTE: toRecipients filtering not supported by Microsoft Graph OData API
+            // Manual filtering will be applied later
             if (criteria.cc && criteria.cc.includes('@')) {
                 // Properly escape single quotes in email addresses
                 const escapedCc = this.escapeODataValue(criteria.cc);
@@ -1436,14 +1438,14 @@ ${originalBodyContent}
                 filters.push(`contains(subject,'${escapedSubject}')`);
             }
             if (criteria.after) {
-                // Fix date formatting - use proper ISO format with quotes
+                // Fix date formatting - use proper DateTimeOffset format without quotes
                 const afterDate = this.formatDateForOData(criteria.after);
-                filters.push(`receivedDateTime ge '${afterDate}'`);
+                filters.push(`receivedDateTime ge ${afterDate}`);
             }
             if (criteria.before) {
-                // Fix date formatting - use proper ISO format with quotes
+                // Fix date formatting - use proper DateTimeOffset format without quotes
                 const beforeDate = this.formatDateForOData(criteria.before);
-                filters.push(`receivedDateTime le '${beforeDate}'`);
+                filters.push(`receivedDateTime le ${beforeDate}`);
             }
             if (criteria.isUnread !== undefined) {
                 filters.push(`isRead eq ${!criteria.isUnread}`);
@@ -1622,7 +1624,18 @@ ${originalBodyContent}
             // Other filters remain the same but are more robust
             if (criteria.to && !message.toRecipients.some(r => r.address.toLowerCase().includes(criteria.to.toLowerCase())))
                 return false;
-            if (criteria.cc && (!message.ccRecipients || !message.ccRecipients.some(r => r.address.toLowerCase().includes(criteria.cc.toLowerCase()))))
+            if (criteria.cc && (!message.ccRecipients || !message.ccRecipients.some(r => {
+                const searchTerm = criteria.cc.toLowerCase().trim();
+                const recipientName = r.name.toLowerCase();
+                const recipientAddress = r.address.toLowerCase();
+                // Multiple matching strategies for robust CC filtering
+                return (recipientAddress === searchTerm ||
+                    recipientAddress.includes(searchTerm) ||
+                    recipientName === searchTerm ||
+                    recipientName.includes(searchTerm) ||
+                    searchTerm.split(/\s+/).every(part => recipientName.includes(part)) ||
+                    new RegExp(`\\b${searchTerm.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'i').test(recipientName));
+            })))
                 return false;
             if (criteria.subject && !message.subject.toLowerCase().includes(criteria.subject.toLowerCase()))
                 return false;
@@ -2080,11 +2093,11 @@ ${originalBodyContent}
                     const filters = [];
                     if (additionalCriteria.after) {
                         const afterDate = this.formatDateForOData(additionalCriteria.after);
-                        filters.push(`receivedDateTime ge '${afterDate}'`);
+                        filters.push(`receivedDateTime ge ${afterDate}`);
                     }
                     if (additionalCriteria.before) {
                         const beforeDate = this.formatDateForOData(additionalCriteria.before);
-                        filters.push(`receivedDateTime le '${beforeDate}'`);
+                        filters.push(`receivedDateTime le ${beforeDate}`);
                     }
                     if (additionalCriteria.isUnread !== undefined) {
                         filters.push(`isRead eq ${!additionalCriteria.isUnread}`);
@@ -2377,13 +2390,49 @@ ${originalBodyContent}
                     return false;
             }
             if (criteria.to) {
-                const toMatch = message.toRecipients.some(recipient => recipient.address.toLowerCase() === criteria.to.toLowerCase());
+                const searchTerm = criteria.to.toLowerCase().trim();
+                const toMatch = message.toRecipients.some(recipient => {
+                    const recipientName = recipient.name.toLowerCase();
+                    const recipientAddress = recipient.address.toLowerCase();
+                    // Multiple matching strategies for robust TO filtering
+                    return (
+                    // Exact email match
+                    recipientAddress === searchTerm ||
+                        // Email contains search term
+                        recipientAddress.includes(searchTerm) ||
+                        // Full name match
+                        recipientName === searchTerm ||
+                        // Name contains search term
+                        recipientName.includes(searchTerm) ||
+                        // Split name matching (for "first last" searches)
+                        searchTerm.split(/\s+/).every(part => recipientName.includes(part)) ||
+                        // Word boundary matching
+                        new RegExp(`\\b${searchTerm.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'i').test(recipientName));
+                });
                 if (!toMatch)
                     return false;
             }
             if (criteria.cc) {
+                const searchTerm = criteria.cc.toLowerCase().trim();
                 const ccMatch = message.ccRecipients && message.ccRecipients.length > 0 &&
-                    message.ccRecipients.some(recipient => recipient.address.toLowerCase() === criteria.cc.toLowerCase());
+                    message.ccRecipients.some(recipient => {
+                        const recipientName = recipient.name.toLowerCase();
+                        const recipientAddress = recipient.address.toLowerCase();
+                        // Multiple matching strategies for robust CC filtering (same as TO)
+                        return (
+                        // Exact email match
+                        recipientAddress === searchTerm ||
+                            // Email contains search term
+                            recipientAddress.includes(searchTerm) ||
+                            // Full name match
+                            recipientName === searchTerm ||
+                            // Name contains search term
+                            recipientName.includes(searchTerm) ||
+                            // Split name matching (for "first last" searches)
+                            searchTerm.split(/\s+/).every(part => recipientName.includes(part)) ||
+                            // Word boundary matching
+                            new RegExp(`\\b${searchTerm.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'i').test(recipientName));
+                    });
                 if (!ccMatch)
                     return false;
             }
@@ -2646,14 +2695,14 @@ ${originalBodyContent}
                     filters.push(`contains(subject,'${escapedSubject}')`);
                 }
                 if (criteria.after) {
-                    // Fix date formatting - use proper ISO format with quotes
+                    // Fix date formatting - use proper DateTimeOffset format without quotes
                     const afterDate = this.formatDateForOData(criteria.after);
-                    filters.push(`receivedDateTime ge '${afterDate}'`);
+                    filters.push(`receivedDateTime ge ${afterDate}`);
                 }
                 if (criteria.before) {
-                    // Fix date formatting - use proper ISO format with quotes
+                    // Fix date formatting - use proper DateTimeOffset format without quotes
                     const beforeDate = this.formatDateForOData(criteria.before);
-                    filters.push(`receivedDateTime le '${beforeDate}'`);
+                    filters.push(`receivedDateTime le ${beforeDate}`);
                 }
                 if (criteria.isUnread !== undefined) {
                     filters.push(`isRead eq ${!criteria.isUnread}`);
@@ -3000,10 +3049,8 @@ ${originalBodyContent}
                 const escapedFrom = this.escapeODataValue(criteria.from);
                 filters.push(`contains(from/emailAddress/address,'${escapedFrom}') or contains(from/emailAddress/name,'${escapedFrom}')`);
             }
-            if (criteria.to) {
-                const escapedTo = this.escapeODataValue(criteria.to);
-                filters.push(`toRecipients/any(r:contains(r/emailAddress/address,'${escapedTo}'))`);
-            }
+            // NOTE: toRecipients filtering not supported by Microsoft Graph OData API
+            // Manual filtering will be applied after retrieval
             if (criteria.cc) {
                 const escapedCc = this.escapeODataValue(criteria.cc);
                 filters.push(`ccRecipients/any(r:contains(r/emailAddress/address,'${escapedCc}'))`);
@@ -3014,11 +3061,11 @@ ${originalBodyContent}
             }
             if (criteria.after) {
                 const afterDate = this.formatDateForOData(criteria.after);
-                filters.push(`receivedDateTime ge '${afterDate}'`);
+                filters.push(`receivedDateTime ge ${afterDate}`);
             }
             if (criteria.before) {
                 const beforeDate = this.formatDateForOData(criteria.before);
-                filters.push(`receivedDateTime le '${beforeDate}'`);
+                filters.push(`receivedDateTime le ${beforeDate}`);
             }
             if (criteria.isUnread !== undefined) {
                 filters.push(`isRead eq ${!criteria.isUnread}`);
@@ -3418,9 +3465,9 @@ ${originalBodyContent}
             .api(`/me/mailFolders/${folder.id}/messages`)
             .select('id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,bodyPreview,isRead,hasAttachments,importance,conversationId,parentFolderId,webLink')
             .orderby('receivedDateTime desc')
-            .top(Math.min(maxResults * 2, 500)); // Get more for filtering
+            .top(Math.min(maxResults * 10, 1000)); // Increased limit for TO searches to find more recipients
         // Build filters for better performance
-        const filters = [`receivedDateTime ge '${recentDateStr}T00:00:00Z'`];
+        const filters = [`receivedDateTime ge ${recentDateStr}T00:00:00Z`];
         if (criteria.from) {
             const escapedFrom = this.escapeODataValue(criteria.from);
             if (criteria.from.includes('@')) {
@@ -3434,6 +3481,8 @@ ${originalBodyContent}
             const escapedSubject = this.escapeODataValue(criteria.subject);
             filters.push(`contains(subject,'${escapedSubject}')`);
         }
+        // NOTE: toRecipients filtering is not supported by Microsoft Graph OData API
+        // Manual filtering will be applied after retrieving results
         if (criteria.isUnread !== undefined) {
             filters.push(`isRead eq ${!criteria.isUnread}`);
         }
@@ -3453,6 +3502,14 @@ ${originalBodyContent}
                 return messageText.includes(searchText);
             });
         }
+        // Apply manual TO filtering for names that might not be caught by OData filter
+        if (criteria.to && !criteria.to.includes('@')) {
+            messages = messages.filter(message => {
+                const toSearchTerm = criteria.to.toLowerCase();
+                return message.toRecipients.some(recipient => recipient.name.toLowerCase().includes(toSearchTerm) ||
+                    recipient.address.toLowerCase().includes(toSearchTerm));
+            });
+        }
         logger.log(`📧 Large folder search Phase 1 result: ${messages.length} emails found`);
         // If we have enough results or found good matches, return
         if (messages.length >= maxResults || messages.length > 5) {
@@ -3470,8 +3527,8 @@ ${originalBodyContent}
             .top(300);
         // More restrictive filters for older search
         const olderFilters = [
-            `receivedDateTime ge '${olderDateStr}T00:00:00Z'`,
-            `receivedDateTime lt '${recentDateStr}T00:00:00Z'`
+            `receivedDateTime ge ${olderDateStr}T00:00:00Z`,
+            `receivedDateTime lt ${recentDateStr}T00:00:00Z`
         ];
         // Must have at least one specific criteria for older search
         if (criteria.from) {
@@ -3483,13 +3540,17 @@ ${originalBodyContent}
                 olderFilters.push(`contains(from/emailAddress/name,'${escapedFrom}')`);
             }
         }
+        else if (criteria.to) {
+            // NOTE: toRecipients filtering is not supported by Microsoft Graph OData API
+            // Skip OData filtering, manual filtering will be applied later
+        }
         else if (criteria.subject) {
             const escapedSubject = this.escapeODataValue(criteria.subject);
             olderFilters.push(`contains(subject,'${escapedSubject}')`);
         }
         else {
-            // If no specific sender/subject, skip older search to avoid timeout
-            logger.log(`⚠️ No specific sender/subject for older search. Returning recent results only.`);
+            // If no specific sender/subject/to, skip older search to avoid timeout
+            logger.log(`⚠️ No specific sender/subject/to for older search. Returning recent results only.`);
             return messages.slice(0, maxResults);
         }
         if (criteria.importance) {
@@ -3509,6 +3570,14 @@ ${originalBodyContent}
                 return messageText.includes(searchText);
             });
         }
+        // Apply manual TO filtering for names to older results
+        if (criteria.to && !criteria.to.includes('@')) {
+            filteredOlderMessages = filteredOlderMessages.filter(message => {
+                const toSearchTerm = criteria.to.toLowerCase();
+                return message.toRecipients.some(recipient => recipient.name.toLowerCase().includes(toSearchTerm) ||
+                    recipient.address.toLowerCase().includes(toSearchTerm));
+            });
+        }
         logger.log(`📧 Large folder search Phase 2 result: ${filteredOlderMessages.length} additional emails found`);
         // Combine results and avoid duplicates
         const allMessages = [...messages];
@@ -3528,7 +3597,7 @@ ${originalBodyContent}
             .api(`/me/mailFolders/${folder.id}/messages`)
             .select('id,subject,from,toRecipients,ccRecipients,receivedDateTime,sentDateTime,bodyPreview,isRead,hasAttachments,importance,conversationId,parentFolderId,webLink')
             .orderby('receivedDateTime desc')
-            .top(Math.min(maxResults * 2, 999));
+            .top(Math.min(maxResults * 10, 999)); // Increased limit for TO searches to find more recipients
         // Build filters
         const filters = [];
         if (criteria.from) {
@@ -3540,13 +3609,11 @@ ${originalBodyContent}
                 filters.push(`contains(from/emailAddress/name,'${escapedFrom}')`);
             }
         }
-        if (criteria.to && criteria.to.includes('@')) {
-            const escapedTo = this.escapeODataValue(criteria.to);
-            filters.push(`toRecipients/any(r: r/emailAddress/address eq '${escapedTo}')`);
-        }
+        // NOTE: toRecipients filtering not supported by Microsoft Graph OData API
+        // Manual filtering will be applied after retrieval
         if (criteria.cc && criteria.cc.includes('@')) {
             const escapedCc = this.escapeODataValue(criteria.cc);
-            filters.push(`ccRecipients/any(r: r/emailAddress/address eq '${escapedCc}')`);
+            filters.push(`ccRecipients/any(c: c/emailAddress/address eq '${escapedCc}')`);
         }
         if (criteria.subject) {
             const escapedSubject = this.escapeODataValue(criteria.subject);
@@ -3554,11 +3621,11 @@ ${originalBodyContent}
         }
         if (criteria.after) {
             const afterDate = this.formatDateForOData(criteria.after);
-            filters.push(`receivedDateTime ge '${afterDate}'`);
+            filters.push(`receivedDateTime ge ${afterDate}`);
         }
         if (criteria.before) {
             const beforeDate = this.formatDateForOData(criteria.before);
-            filters.push(`receivedDateTime le '${beforeDate}'`);
+            filters.push(`receivedDateTime le ${beforeDate}`);
         }
         if (criteria.isUnread !== undefined) {
             filters.push(`isRead eq ${!criteria.isUnread}`);
@@ -3584,6 +3651,14 @@ ${originalBodyContent}
                 return messageText.includes(searchText);
             });
         }
+        // Apply manual TO filtering for names that might not be caught by OData filter
+        if (criteria.to && !criteria.to.includes('@')) {
+            messages = messages.filter(message => {
+                const toSearchTerm = criteria.to.toLowerCase();
+                return message.toRecipients.some(recipient => recipient.name.toLowerCase().includes(toSearchTerm) ||
+                    recipient.address.toLowerCase().includes(toSearchTerm));
+            });
+        }
         logger.log(`📧 Standard folder search result: ${messages.length} emails found`);
         return messages.slice(0, maxResults);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ms365-mcp-server",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Microsoft 365 MCP Server for managing Microsoft 365 email through natural language interactions with full OAuth2 authentication support",
   "main": "dist/index.js",
   "type": "module",