@littlebearapps/outlook-assistant 3.5.1 → 3.5.2

package/README.md

@@ -149,10 +149,11 @@ npx @littlebearapps/outlook-assistant
 You need a Microsoft Azure app registration to authenticate. See the **[Azure Setup Guide](docs/guides/azure-setup.md)** for a detailed walkthrough (including first-time Azure account creation), or if you've done this before:
 
 1. Create a new app registration at [portal.azure.com](https://portal.azure.com/)
-2. Set redirect URI to `http://localhost:3333/auth/callback`
-3. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
-4. Create a client secret and copy the **Value** (not the Secret ID)
-5. Enable **"Allow public client flows"** in Authentication > Advanced settings (for device code flow)
+2. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
+3. Create a client secret and copy the **Value** (not the Secret ID)
+4. Under Authentication > **Add a platform** > **Mobile and desktop applications** — check `nativeclient` URI
+5. Enable **"Allow public client flows"** in Authentication > Advanced settings
+6. _(Optional)_ Set redirect URI to `http://localhost:3333/auth/callback` — only needed for browser auth flow
 
 ### 3. Configure Your MCP Client
 

package/auth/index.js

@@ -4,7 +4,7 @@
 const tokenManager = require('./token-manager');
 const TokenStorage = require('./token-storage');
 const config = require('../config');
-const { authTools } = require('./tools');
+const { authTools, setToolCount } = require('./tools');
 
 // Singleton TokenStorage instance with auto-refresh support
 const tokenStorage = new TokenStorage({
@@ -39,5 +39,6 @@ module.exports = {
   tokenManager, // deprecated: use tokenStorage
   tokenStorage,
   authTools,
+  setToolCount,
   ensureAuthenticated,
 };

package/auth/tools.js

@@ -5,6 +5,12 @@ const config = require('../config');
 const tokenManager = require('./token-manager');
 const { initiateDeviceCodeFlow, pollForToken } = require('./device-code');
 
+// Dynamic tool count — set by index.js after TOOLS array is built
+let _toolCount = 0;
+function setToolCount(count) {
+  _toolCount = count;
+}
+
 /**
  * About tool handler
  * @returns {object} - MCP response
@@ -25,7 +31,7 @@ async function handleAbout() {
     `## Diagnostics\n`,
     `| Setting | Value |`,
     `|---------|-------|`,
-    `| Tools | 20 across 9 modules |`,
+    `| Tools | ${_toolCount} across 9 modules |`,
     `| Modules | auth, email, calendar, folder, rules, contacts, categories, settings, advanced |`,
     `| Timezone | ${config.DEFAULT_TIMEZONE} |`,
     `| Test Mode | ${testMode} |`,
@@ -320,6 +326,7 @@ const authTools = [
 
 module.exports = {
   authTools,
+  setToolCount,
   handleAbout,
   handleAuthenticate,
   handleDeviceCodeAuth,

package/categories/index.js

@@ -305,17 +305,26 @@ async function handleUpdateCategory(args) {
       updateData
     );
 
-    const colorName = COLOR_NAMES[response.color] || response.color;
+    // Prefer input values over response (PATCH may return partial data)
+    const updatedName = displayName || response.displayName;
+    const updatedColor = color || response.color;
+    const colorName = COLOR_NAMES[updatedColor] || updatedColor;
+
+    const updatedCategory = {
+      ...response,
+      displayName: updatedName,
+      color: updatedColor,
+    };
 
     return {
       content: [
         {
           type: 'text',
-          text: `Category updated!\n\n**Name**: ${response.displayName}\n**Color**: ${colorName} (${response.color})\n**ID**: ${response.id}`,
+          text: `Category updated!\n\n**Name**: ${updatedName}\n**Color**: ${colorName} (${updatedColor})\n**ID**: ${response.id || id}`,
         },
       ],
       _meta: {
-        category: formatCategory(response),
+        category: formatCategory(updatedCategory),
       },
     };
   } catch (error) {
@@ -428,7 +437,9 @@ async function handleApplyCategory(args) {
     };
   }
 
-  if (!categories || !Array.isArray(categories) || categories.length === 0) {
+  const applyAction = action || 'set'; // 'set', 'add', 'remove'
+
+  if (!categories || !Array.isArray(categories)) {
     return {
       content: [
         {
@@ -439,7 +450,17 @@ async function handleApplyCategory(args) {
     };
   }
 
-  const applyAction = action || 'set'; // 'set', 'add', 'remove'
+  // Empty array is only valid for action=set (clears all categories)
+  if (categories.length === 0 && applyAction !== 'set') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Categories array cannot be empty for add/remove. Use action=set with an empty array to clear all categories.',
+        },
+      ],
+    };
+  }
 
   try {
     const accessToken = await ensureAuthenticated();

package/email/conversations.js

@@ -17,6 +17,8 @@ const {
   formatEmailsAsCSV,
   VERBOSITY,
 } = require('../utils/response-formatter');
+// Note: buildFromFilter/buildToFilter from search.js use OData $filter which causes
+// InefficientFilter on personal accounts with $orderby. Client-side filtering used instead.
 
 /**
  * Format a date for filenames
@@ -65,10 +67,12 @@ async function handleListConversations(args) {
       'id',
       'subject',
       'from',
+      'toRecipients',
       'receivedDateTime',
       'conversationId',
       'conversationIndex',
       'isRead',
+      'hasAttachments',
       'bodyPreview',
     ].join(',');
 
@@ -79,6 +83,34 @@ async function handleListConversations(args) {
       $top: 200, // Get more to group
     };
 
+    // Apply simple $filter conditions that Graph API supports on personal accounts
+    // Complex filters (contains on subject, endswith on email) cause InefficientFilter
+    // errors, so those are handled client-side after fetching.
+    const serverFilterConditions = [];
+    if (args.hasAttachments === true) {
+      serverFilterConditions.push('hasAttachments eq true');
+    }
+    if (args.receivedAfter) {
+      try {
+        const afterDate = new Date(args.receivedAfter).toISOString();
+        serverFilterConditions.push(`receivedDateTime ge ${afterDate}`);
+      } catch (_e) {
+        /* ignore invalid date */
+      }
+    }
+    if (args.receivedBefore) {
+      try {
+        const beforeDate = new Date(args.receivedBefore).toISOString();
+        serverFilterConditions.push(`receivedDateTime le ${beforeDate}`);
+      } catch (_e) {
+        /* ignore invalid date */
+      }
+    }
+
+    if (serverFilterConditions.length > 0) {
+      queryParams.$filter = serverFilterConditions.join(' and ');
+    }
+
     const response = await callGraphAPI(
       accessToken,
       'GET',
@@ -86,7 +118,33 @@ async function handleListConversations(args) {
       null,
       queryParams
     );
-    const messages = response.value || [];
+    let messages = response.value || [];
+
+    // Client-side filtering for conditions that cause InefficientFilter on personal accounts
+    if (args.subject) {
+      const subjectLower = args.subject.toLowerCase();
+      messages = messages.filter((m) =>
+        (m.subject || '').toLowerCase().includes(subjectLower)
+      );
+    }
+    if (args.from) {
+      const fromLower = args.from.toLowerCase();
+      messages = messages.filter((m) => {
+        const addr = (m.from?.emailAddress?.address || '').toLowerCase();
+        const name = (m.from?.emailAddress?.name || '').toLowerCase();
+        return addr.includes(fromLower) || name.includes(fromLower);
+      });
+    }
+    if (args.to) {
+      const toLower = args.to.toLowerCase();
+      messages = messages.filter((m) =>
+        (m.toRecipients || []).some((r) => {
+          const addr = (r.emailAddress?.address || '').toLowerCase();
+          const name = (r.emailAddress?.name || '').toLowerCase();
+          return addr.includes(toLower) || name.includes(toLower);
+        })
+      );
+    }
 
     // Group by conversationId
     const conversations = new Map();

package/email/mail-tips.js

@@ -146,13 +146,46 @@ async function handleGetMailTips(args) {
     };
   }
 
+  // Normalise recipients to a clean array of email strings
+  let recipientList;
+  if (Array.isArray(recipients)) {
+    recipientList = recipients.map((e) => String(e).trim());
+  } else if (typeof recipients === 'string') {
+    // Handle JSON array strings like '["a@b.com","c@d.com"]' from MCP clients
+    const trimmed = recipients.trim();
+    if (trimmed.startsWith('[')) {
+      try {
+        recipientList = JSON.parse(trimmed).map((e) => String(e).trim());
+      } catch (_e) {
+        // Fall through to comma-split
+      }
+    }
+    if (!recipientList) {
+      recipientList = trimmed.split(',').map((e) => e.trim());
+    }
+  } else {
+    recipientList = [String(recipients).trim()];
+  }
+
+  // Filter out empty strings
+  recipientList = recipientList.filter((e) => e.length > 0);
+
+  if (recipientList.length === 0) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'At least one valid recipient email address is required.',
+        },
+      ],
+    };
+  }
+
   try {
     const accessToken = await ensureAuthenticated();
 
     const requestBody = {
-      EmailAddresses: Array.isArray(recipients)
-        ? recipients
-        : recipients.split(',').map((e) => e.trim()),
+      EmailAddresses: recipientList,
       MailTipsOptions: tipTypes || MAIL_TIP_TYPES.join(','),
     };
 

package/email/search.js

@@ -152,33 +152,47 @@ async function progressiveSearch(
     }
   }
 
-  // 1. Try combined search (most specific)
-  try {
-    const params = buildSearchParams(
-      searchTerms,
-      filterTerms,
-      Math.min(50, maxCount),
-      selectFields
-    );
-    console.error('Attempting combined search with params:', params);
-    searchAttempts.push('combined-search');
+  // Check if we have any actual search terms (not just boolean filters)
+  const hasSearchTerms =
+    searchTerms.query ||
+    searchTerms.from ||
+    searchTerms.to ||
+    searchTerms.subject;
+
+  // 1. Try combined search (most specific) — skip if only boolean filters
+  if (
+    !hasSearchTerms &&
+    (filterTerms.hasAttachments === true || filterTerms.unreadOnly === true)
+  ) {
+    // Skip directly to boolean-only filter (step 3) — combined search is redundant
+    console.error('Only boolean filters provided, skipping combined search');
+  } else
+    try {
+      const params = buildSearchParams(
+        searchTerms,
+        filterTerms,
+        Math.min(50, maxCount),
+        selectFields
+      );
+      console.error('Attempting combined search with params:', params);
+      searchAttempts.push('combined-search');
 
-    const response = await callGraphAPIPaginated(
-      accessToken,
-      'GET',
-      endpoint,
-      params,
-      maxCount
-    );
-    if (response.value && response.value.length > 0) {
-      console.error(
-        `Combined search successful: found ${response.value.length} results`
+      const response = await callGraphAPIPaginated(
+        accessToken,
+        'GET',
+        endpoint,
+        params,
+        maxCount
       );
-      return response;
+      if (response.value && response.value.length > 0) {
+        console.error(
+          `Combined search successful: found ${response.value.length} results`
+        );
+        return response;
+      }
+    } catch (error) {
+      console.error(`Combined search failed: ${error.message}`);
     }
-  } catch (error) {
-    console.error(`Combined search failed: ${error.message}`);
-  }
 
   // 2. Try each search term individually, starting with most specific
   const searchPriority = ['from', 'to', 'subject', 'query'];
@@ -200,23 +214,16 @@ async function progressiveSearch(
         // $search for free-text query only.
         // NOTE: $filter and $orderby cannot be used together on mailbox - Graph API limitation
         if (term === 'from') {
-          if (searchTerms[term].includes('@')) {
-            simplifiedParams.$filter = `from/emailAddress/address eq '${searchTerms[term]}'`;
-          } else {
-            simplifiedParams.$filter = `contains(from/emailAddress/name, '${searchTerms[term]}')`;
-          }
+          simplifiedParams.$filter = buildFromFilter(searchTerms[term]);
         } else if (term === 'to') {
-          if (searchTerms[term].includes('@')) {
-            simplifiedParams.$filter = `toRecipients/any(r: r/emailAddress/address eq '${searchTerms[term]}')`;
-          } else {
-            simplifiedParams.$filter = `toRecipients/any(r: contains(r/emailAddress/name, '${searchTerms[term]}'))`;
-          }
+          simplifiedParams.$filter = buildToFilter(searchTerms[term]);
         } else if (term === 'subject') {
           // Use $filter with contains() — $search silently fails on personal MS accounts
           simplifiedParams.$filter = `contains(subject, '${searchTerms[term].replace(/'/g, "''")}')`;
         } else if (term === 'query') {
-          simplifiedParams.$orderby = 'receivedDateTime desc';
-          simplifiedParams.$search = `"${searchTerms[term]}"`;
+          // On personal accounts, $search fails with 503. Use $filter with
+          // contains(subject) as a best-effort fallback for free-text queries.
+          simplifiedParams.$filter = `contains(subject, '${searchTerms[term].replace(/'/g, "''")}')`;
         }
 
         // Add boolean filters if applicable
@@ -241,21 +248,29 @@ async function progressiveSearch(
     }
   }
 
-  // 3. Try with only boolean filters
-  if (filterTerms.hasAttachments === true || filterTerms.unreadOnly === true) {
+  // 3. Try with only boolean filters (also date range filters)
+  const hasBooleanFilters =
+    filterTerms.hasAttachments === true || filterTerms.unreadOnly === true;
+  const hasDateFilters =
+    filterTerms.receivedAfter || filterTerms.receivedBefore;
+  if (hasBooleanFilters || hasDateFilters) {
     try {
-      console.error('Attempting search with only boolean filters');
+      console.error('Attempting search with only boolean/date filters');
       searchAttempts.push('boolean-filters-only');
 
       const filterOnlyParams = {
         $top: Math.min(50, maxCount),
         $select: selectFields,
-        $orderby: 'receivedDateTime desc',
       };
 
-      // Add the boolean filters
+      // Add the boolean + date filters
       addBooleanFilters(filterOnlyParams, filterTerms);
 
+      // Only add $orderby if no $filter (they can conflict on personal accounts)
+      if (!filterOnlyParams.$filter) {
+        filterOnlyParams.$orderby = 'receivedDateTime desc';
+      }
+
       const response = await callGraphAPIPaginated(
         accessToken,
         'GET',
@@ -269,6 +284,29 @@ async function progressiveSearch(
       return response;
     } catch (error) {
       console.error(`Boolean filter search failed: ${error.message}`);
+      // Retry without $orderby if it was the issue
+      if (error.message && error.message.includes('InefficientFilter')) {
+        try {
+          console.error('Retrying boolean filters without $orderby');
+          const retryParams = {
+            $top: Math.min(50, maxCount),
+            $select: selectFields,
+          };
+          addBooleanFilters(retryParams, filterTerms);
+          const response = await callGraphAPIPaginated(
+            accessToken,
+            'GET',
+            endpoint,
+            retryParams,
+            maxCount
+          );
+          return response;
+        } catch (retryError) {
+          console.error(
+            `Boolean filter retry also failed: ${retryError.message}`
+          );
+        }
+      }
     }
   }
 
@@ -304,6 +342,54 @@ async function progressiveSearch(
   return response;
 }
 
+/**
+ * Detect if a value is a domain-only filter (e.g. "@souliv.com.au" or "souliv.com.au")
+ * vs a full email address (e.g. "user@souliv.com.au") vs a display name (e.g. "Billie")
+ * @param {string} val - The from/to filter value
+ * @returns {'domain'|'email'|'name'} - The type of filter
+ */
+function classifyEmailFilter(val) {
+  if (val.startsWith('@')) return 'domain';
+  // Has dots but no @ — likely a domain like "souliv.com.au"
+  if (!val.includes('@') && val.includes('.')) return 'domain';
+  if (val.includes('@')) return 'email';
+  return 'name';
+}
+
+/**
+ * Build a $filter condition for a from field value
+ * @param {string} val - The from filter value
+ * @returns {string} - OData $filter condition
+ */
+function buildFromFilter(val) {
+  const type = classifyEmailFilter(val);
+  if (type === 'domain') {
+    // Use contains() — endswith() not supported on personal accounts
+    const domain = val.startsWith('@') ? val : `@${val}`;
+    return `contains(from/emailAddress/address, '${domain.substring(1)}')`;
+  } else if (type === 'email') {
+    return `from/emailAddress/address eq '${val}'`;
+  }
+  return `contains(from/emailAddress/name, '${val}')`;
+}
+
+/**
+ * Build a $filter condition for a to field value
+ * @param {string} val - The to filter value
+ * @returns {string} - OData $filter condition
+ */
+function buildToFilter(val) {
+  const type = classifyEmailFilter(val);
+  if (type === 'domain') {
+    const domain = val.startsWith('@') ? val : `@${val}`;
+    // Use contains() — endswith() not supported on personal accounts
+    return `toRecipients/any(r: contains(r/emailAddress/address, '${domain.substring(1)}'))`;
+  } else if (type === 'email') {
+    return `toRecipients/any(r: r/emailAddress/address eq '${val}')`;
+  }
+  return `toRecipients/any(r: contains(r/emailAddress/name, '${val}'))`;
+}
+
 /**
  * Build search parameters from search terms and filter terms
  * Uses $filter for email addresses (more reliable than $search)
@@ -342,28 +428,12 @@ function buildSearchParams(searchTerms, filterTerms, count, selectFields) {
   // NOTE: $filter on email addresses is incompatible with $orderby - Graph API limitation
   if (searchTerms.from) {
     usesEmailFilter = true;
-    if (searchTerms.from.includes('@')) {
-      filterConditions.push(
-        `from/emailAddress/address eq '${searchTerms.from}'`
-      );
-    } else {
-      filterConditions.push(
-        `contains(from/emailAddress/name, '${searchTerms.from}')`
-      );
-    }
+    filterConditions.push(buildFromFilter(searchTerms.from));
   }
 
   if (searchTerms.to) {
     usesEmailFilter = true;
-    if (searchTerms.to.includes('@')) {
-      filterConditions.push(
-        `toRecipients/any(r: r/emailAddress/address eq '${searchTerms.to}')`
-      );
-    } else {
-      filterConditions.push(
-        `toRecipients/any(r: contains(r/emailAddress/name, '${searchTerms.to}'))`
-      );
-    }
+    filterConditions.push(buildToFilter(searchTerms.to));
   }
 
   // Add boolean filters (these ARE compatible with $orderby)
@@ -625,4 +695,7 @@ async function handleSearchByMessageId(args) {
 module.exports = {
   handleSearchEmails,
   handleSearchByMessageId,
+  buildFromFilter,
+  buildToFilter,
+  classifyEmailFilter,
 };

package/email/send.js

@@ -101,49 +101,7 @@ async function handleSendEmail(args) {
     const allowlistError = checkRecipientAllowlist(allRecipients);
     if (allowlistError) return allowlistError;
 
-    // Pre-send mail tips check
-    if (checkRecipients) {
-      const allAddresses = allRecipients.map((r) => r.emailAddress.address);
-      const tipsResult = await handleGetMailTips({
-        recipients: allAddresses,
-      });
-
-      // If there are warnings, prepend them to the response
-      if (tipsResult._meta?.warningCount > 0 && dryRun) {
-        // In dry-run mode, include mail tips in the preview
-        const tipsText = tipsResult.content[0]?.text || '';
-        const preview = formatDryRunPreview({
-          message: {
-            subject,
-            body: {
-              contentType:
-                /<(html|div|p|h[1-6]|br|table|ul|ol|li|span|a\s|img|strong|em|b|i)\b/i.test(
-                  body
-                )
-                  ? 'html'
-                  : 'text',
-              content: body,
-            },
-            toRecipients,
-            ccRecipients: ccRecipients.length > 0 ? ccRecipients : undefined,
-            bccRecipients: bccRecipients.length > 0 ? bccRecipients : undefined,
-            importance,
-          },
-          saveToSentItems,
-        });
-        return {
-          content: [
-            {
-              type: 'text',
-              text: tipsText + '\n\n---\n\n' + preview.content[0].text,
-            },
-          ],
-          _meta: { mailTips: tipsResult._meta },
-        };
-      }
-    }
-
-    // Prepare email object
+    // Prepare email object (needed by both dryRun and actual send)
     const emailObject = {
       message: {
         subject,
@@ -164,6 +122,37 @@ async function handleSendEmail(args) {
       saveToSentItems,
     };
 
+    // Pre-send mail tips check
+    if (checkRecipients) {
+      const allAddresses = allRecipients.map((r) => r.emailAddress.address);
+      const tipsResult = await handleGetMailTips({
+        recipients: allAddresses,
+      });
+
+      const tipsText = tipsResult.content[0]?.text || '';
+
+      // In dry-run mode, always include mail tips in the preview
+      if (dryRun) {
+        const preview = formatDryRunPreview(emailObject);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: tipsText + '\n\n---\n\n' + preview.content[0].text,
+            },
+          ],
+          _meta: { mailTips: tipsResult._meta },
+        };
+      }
+
+      // In send mode, warn if there are issues but proceed
+      if (tipsResult._meta?.warningCount > 0) {
+        // Store tips to prepend to send response
+        emailObject._mailTipsText = tipsText;
+        emailObject._mailTipsMeta = tipsResult._meta;
+      }
+    }
+
     // Dry-run mode: return preview without sending
     if (dryRun) {
       return formatDryRunPreview(emailObject);

package/index.js

@@ -12,7 +12,7 @@ const {
 const config = require('./config');
 
 // Import module tools
-const { authTools } = require('./auth');
+const { authTools, setToolCount } = require('./auth');
 const { calendarTools } = require('./calendar');
 const { emailTools } = require('./email');
 const { folderTools } = require('./folder');
@@ -39,6 +39,9 @@ const TOOLS = [
   ...advancedTools,
 ];
 
+// Set dynamic tool count for auth about handler
+setToolCount(TOOLS.length);
+
 // Create server with tools capabilities
 const server = new Server(
   { name: config.SERVER_NAME, version: config.SERVER_VERSION },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.5.1",
+  "version": "3.5.2",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
   "description": "Outlook Assistant — MCP server with 21 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",