@littlebearapps/outlook-assistant 3.5.1 → 3.6.0

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/llms.txt

@@ -11,12 +11,12 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 - **License**: MIT
 - **Node.js**: >= 18.0.0
 - **Authentication**: OAuth 2.0 with Microsoft Graph API (requires Azure app registration)
-- **Tools**: 21 tools across 9 modules (reduced from 55 for optimal AI performance)
+- **Tools**: 22 tools across 9 modules (reduced from 55 for optimal AI performance)
 
 ## Why Outlook Assistant?
 
 - Read, search, send, and export emails directly from Claude instead of switching apps
-- 7 email tools covering search, conversations, attachments, bulk export, and pre-send mail tips
+- 8 email tools covering search, conversations, attachments, bulk export, pre-send mail tips, and draft management
 - Manage calendar events, contacts, rules, categories, and mailbox settings in one place
 - Export to multiple formats: MIME/EML, MBOX, Markdown, JSON, HTML
 
@@ -31,9 +31,9 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 
 ## Safety & Token Efficiency
 
-- **MCP safety annotations** on all 21 tools — AI clients auto-approve reads and prompt for destructive operations
+- **MCP safety annotations** on all 22 tools — AI clients auto-approve reads and prompt for destructive operations
 - **Send-email protections**: pre-send mail tips, dry-run preview, session rate limiting, recipient allowlist
-- **Token-optimised**: 21 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
+- **Token-optimised**: 22 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
 - These safeguards reduce risk but are not foolproof — always review actions before approving
 
 ## Quick Start
@@ -58,7 +58,7 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 ## Tool Categories
 
 - **Authentication (1 tool)**: `auth` — OAuth flow, status, about
-- **Email (7 tools)**: `search-emails`, `read-email`, `send-email`, `update-email`, `attachments`, `export`, `get-mail-tips`
+- **Email (8 tools)**: `search-emails`, `read-email`, `send-email`, `draft`, `update-email`, `attachments`, `export`, `get-mail-tips`
 - **Calendar (3 tools)**: `list-events`, `create-event`, `manage-event`
 - **Contacts (2 tools)**: `manage-contact`, `search-people`
 - **Folders (1 tool)**: `folders` — list, create, move, stats
@@ -70,7 +70,7 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 ## Documentation
 
 - [README](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/README.md): Full documentation including setup, Azure configuration, and usage
-- [Tools Reference](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/quickrefs/tools-reference.md): All 21 tools with parameters and safety annotations
+- [Tools Reference](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/quickrefs/tools-reference.md): All 22 tools with parameters and safety annotations
 - [CLAUDE.md](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CLAUDE.md): Quick reference for development
 - [CONTRIBUTING](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CONTRIBUTING.md): Contribution guidelines
 - [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history

package/package.json

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

package/utils/field-presets.js

@@ -107,6 +107,26 @@ const FIELD_PRESETS = {
     'changeKey',
   ],
 
+  /**
+   * Draft fields for viewing/editing drafts
+   * Use case: Draft creation, update, listing
+   */
+  draft: [
+    'id',
+    'subject',
+    'from',
+    'toRecipients',
+    'ccRecipients',
+    'bccRecipients',
+    'body',
+    'bodyPreview',
+    'lastModifiedDateTime',
+    'isDraft',
+    'importance',
+    'hasAttachments',
+    'conversationId',
+  ],
+
   /**
    * Search result fields (optimized for relevance display)
    * Use case: Search results with context

package/utils/graph-api.js

@@ -7,6 +7,7 @@ const mockData = require('./mock-data');
 
 /**
  * Makes a request to the Microsoft Graph API
+ * In test mode (USE_TEST_MODE=true), routes to mock data instead of the real API.
  * @param {string} accessToken - The access token for authentication
  * @param {string} method - HTTP method (GET, POST, etc.)
  * @param {string} path - API endpoint path
@@ -14,6 +15,8 @@ const mockData = require('./mock-data');
  * @param {object} queryParams - Query parameters
  * @param {object} extraHeaders - Additional headers (e.g. Prefer for immutable IDs)
  * @returns {Promise<object>} - The API response
+ * @throws {Error} 'UNAUTHORIZED' if the server returns HTTP 401 (token expired or invalid)
+ * @throws {Error} If the HTTP status is outside 2xx, or if JSON parsing or network fails
  */
 async function callGraphAPI(
   accessToken,
@@ -153,6 +156,8 @@ async function callGraphAPI(
  * @param {object} queryParams - Initial query parameters
  * @param {number} maxCount - Maximum number of items to retrieve (0 = all)
  * @returns {Promise<object>} - Combined API response with all items
+ * @throws {Error} If method is not 'GET'
+ * @throws {Error} If any page request fails for any other reason
  */
 async function callGraphAPIPaginated(
   accessToken,
@@ -268,9 +273,12 @@ async function callGraphAPIBatch(accessToken, requests) {
 
 /**
  * Calls Graph API to get raw MIME content (for email export)
+ * In test mode (USE_TEST_MODE=true), returns mock MIME content instead of calling the real API.
  * @param {string} accessToken - The access token for authentication
  * @param {string} emailId - The email ID to export
  * @returns {Promise<string>} - Raw MIME content as string
+ * @throws {Error} 'UNAUTHORIZED' if the server returns HTTP 401 (token expired or invalid)
+ * @throws {Error} If the HTTP status is outside 2xx or a network error occurs
  */
 async function callGraphAPIRaw(accessToken, emailId) {
   // Test mode: return mock MIME content