@littlebearapps/outlook-assistant 3.7.0 → 3.7.2

package/auth/token-storage.js

@@ -49,11 +49,13 @@ class TokenStorage {
       }
     }
 
-    if (!this.config.clientId || !this.config.clientSecret) {
+    if (!this.config.clientId) {
       console.warn(
-        'TokenStorage: OUTLOOK_CLIENT_ID or OUTLOOK_CLIENT_SECRET is not configured. Token operations might fail.'
+        'TokenStorage: OUTLOOK_CLIENT_ID is not configured. Token operations will fail.'
       );
     }
+    // client_secret is only required for browser flow (confidential client).
+    // Device code flow (public client) does not use client_secret.
   }
 
   async _loadTokensFromFile() {
@@ -158,14 +160,24 @@ class TokenStorage {
       return this._refreshPromise.then((tokens) => tokens.access_token);
     }
 
-    console.log('Attempting to refresh access token...');
-    const postData = querystring.stringify({
+    // Device code flow is a public client flow — Microsoft rejects client_secret
+    // in refresh requests for tokens obtained via device code.
+    // Browser flow (confidential client) requires client_secret.
+    const isDeviceCode = this.tokens.auth_method === 'device-code';
+    console.log(
+      `Attempting to refresh access token (auth_method: ${this.tokens.auth_method || 'browser'})...`
+    );
+
+    const refreshParams = {
       client_id: this.config.clientId,
-      client_secret: this.config.clientSecret,
       grant_type: 'refresh_token',
       refresh_token: this.tokens.refresh_token,
       scope: this.config.scopes.join(' '),
-    });
+    };
+    if (!isDeviceCode) {
+      refreshParams.client_secret = this.config.clientSecret;
+    }
+    const postData = querystring.stringify(refreshParams);
 
     const requestOptions = {
       method: 'POST',

package/auth/tools.js

@@ -2,9 +2,17 @@
  * Authentication-related tools for the Outlook Assistant server
  */
 const config = require('../config');
+const fs = require('fs');
+const path = require('path');
 const tokenManager = require('./token-manager');
 const { initiateDeviceCodeFlow, pollForToken } = require('./device-code');
 
+// Path for persisting device code state across MCP server restarts
+const DEVICE_CODE_STATE_PATH = path.join(
+  process.env.HOME || process.env.USERPROFILE,
+  '.outlook-assistant-pending-auth.json'
+);
+
 // Dynamic tool count — set by index.js after TOOLS array is built
 let _toolCount = 0;
 function setToolCount(count) {
@@ -89,12 +97,57 @@ async function handleAuthenticate(args) {
   };
 }
 
-// Module-level state for pending device code flow
+// In-memory state for pending device code flow (also persisted to disk)
 let pendingDeviceCode = null;
 
+/**
+ * Save device code state to disk so it survives MCP server restarts.
+ * Uses mode 0o600 (owner-only) — same as token file.
+ * @param {object|null} state - Device code state or null to delete
+ */
+function saveDeviceCodeState(state) {
+  try {
+    if (state) {
+      fs.writeFileSync(DEVICE_CODE_STATE_PATH, JSON.stringify(state), {
+        mode: 0o600,
+      });
+    } else if (fs.existsSync(DEVICE_CODE_STATE_PATH)) {
+      fs.unlinkSync(DEVICE_CODE_STATE_PATH);
+    }
+  } catch (error) {
+    console.error(
+      `[AUTH] Failed to ${state ? 'save' : 'clean up'} device code state: ${error.message}`
+    );
+  }
+}
+
+/**
+ * Load device code state from disk (fallback when in-memory state is lost).
+ * Returns null if no state exists or if the state has expired.
+ * @returns {object|null}
+ */
+function loadDeviceCodeState() {
+  try {
+    if (!fs.existsSync(DEVICE_CODE_STATE_PATH)) {
+      return null;
+    }
+    const state = JSON.parse(fs.readFileSync(DEVICE_CODE_STATE_PATH, 'utf8'));
+    if (Date.now() > state.expiresAt) {
+      console.error('[AUTH] Persisted device code has expired, cleaning up');
+      saveDeviceCodeState(null);
+      return null;
+    }
+    return state;
+  } catch (error) {
+    console.error(`[AUTH] Failed to load device code state: ${error.message}`);
+    return null;
+  }
+}
+
 /**
  * Device code flow step 1 — request a code for the user to enter.
  * Returns the code + URL immediately. Call device-code-complete to finish.
+ * State is persisted to disk so it survives MCP server restarts.
  * @returns {object} - MCP response
  */
 async function handleDeviceCodeAuth() {
@@ -116,13 +169,14 @@ async function handleDeviceCodeAuth() {
     config.AUTH_CONFIG.scopes
   );
 
-  // Store for the completion step
+  // Store in memory and persist to disk
   pendingDeviceCode = {
     deviceCode: response.deviceCode,
     interval: response.interval,
     expiresIn: response.expiresIn,
     expiresAt: Date.now() + response.expiresIn * 1000,
   };
+  saveDeviceCodeState(pendingDeviceCode);
 
   console.error(
     `[AUTH] Device code: ${response.userCode}, expires in ${response.expiresIn}s`
@@ -146,9 +200,15 @@ async function handleDeviceCodeAuth() {
 
 /**
  * Device code flow step 2 — poll until the user completes authentication.
+ * Checks in-memory state first, falls back to disk-persisted state.
  * @returns {object} - MCP response
  */
 async function handleDeviceCodeComplete() {
+  // Try in-memory first, fall back to disk (survives server restarts)
+  if (!pendingDeviceCode) {
+    pendingDeviceCode = loadDeviceCodeState();
+  }
+
   if (!pendingDeviceCode) {
     return {
       content: [
@@ -162,6 +222,7 @@ async function handleDeviceCodeComplete() {
 
   if (Date.now() > pendingDeviceCode.expiresAt) {
     pendingDeviceCode = null;
+    saveDeviceCodeState(null);
     return {
       content: [
         {
@@ -184,8 +245,9 @@ async function handleDeviceCodeComplete() {
     );
 
     pendingDeviceCode = null;
+    saveDeviceCodeState(null);
 
-    // Save tokens using TokenStorage
+    // Save tokens using TokenStorage — mark as device-code auth
     const TokenStorage = require('./token-storage');
     const tokenStorage = new TokenStorage({
       clientId: config.AUTH_CONFIG.clientId,
@@ -202,6 +264,7 @@ async function handleDeviceCodeComplete() {
       expires_at: Date.now() + tokenResponse.expires_in * 1000,
       scope: tokenResponse.scope,
       token_type: tokenResponse.token_type,
+      auth_method: 'device-code',
     };
     await tokenStorage._saveTokensToFile();
 
@@ -217,6 +280,7 @@ async function handleDeviceCodeComplete() {
     };
   } catch (error) {
     pendingDeviceCode = null;
+    saveDeviceCodeState(null);
     return {
       content: [
         {

package/email/search.js

@@ -145,6 +145,12 @@ async function progressiveSearch(
         console.error(
           `Raw KQL search successful: found ${response.value.length} results`
         );
+        response._searchInfo = {
+          attemptsCount: searchAttempts.length,
+          strategies: searchAttempts,
+          originalTerms: searchTerms,
+          filterTerms: filterTerms,
+        };
         return response;
       }
     } catch (error) {
@@ -188,6 +194,12 @@ async function progressiveSearch(
         console.error(
           `Combined search successful: found ${response.value.length} results`
         );
+        response._searchInfo = {
+          attemptsCount: searchAttempts.length,
+          strategies: searchAttempts,
+          originalTerms: searchTerms,
+          filterTerms: filterTerms,
+        };
         return response;
       }
     } catch (error) {
@@ -241,10 +253,109 @@ async function progressiveSearch(
           console.error(
             `Search with ${term} successful: found ${response.value.length} results`
           );
+          response._searchInfo = {
+            attemptsCount: searchAttempts.length,
+            strategies: searchAttempts,
+            originalTerms: searchTerms,
+            filterTerms: filterTerms,
+          };
           return response;
         }
+
+        // Client-side fallback for 'to' filter — toRecipients/any() lambda
+        // returns 0 results on personal accounts even when emails exist
+        if (term === 'to') {
+          console.error(
+            'to filter returned 0 results, trying client-side filtering'
+          );
+          searchAttempts.push('client-side-to');
+          const messages = await fetchForClientSideFilter(
+            accessToken,
+            endpoint,
+            maxCount
+          );
+          const matched = filterToClientSide(messages, searchTerms[term]);
+          if (matched.length > 0) {
+            console.error(
+              `Client-side to filter matched ${matched.length} of ${messages.length} messages`
+            );
+            return { value: matched.slice(0, maxCount) };
+          }
+        }
+
+        // Client-side fallback for 'query' — search bodyPreview, subject, from
+        if (term === 'query') {
+          console.error(
+            'query contains(subject) returned 0 results, trying client-side body search'
+          );
+          searchAttempts.push('client-side-query');
+          const messages = await fetchForClientSideFilter(
+            accessToken,
+            endpoint,
+            maxCount
+          );
+          const matched = filterQueryClientSide(messages, searchTerms[term]);
+          if (matched.length > 0) {
+            console.error(
+              `Client-side query matched ${matched.length} of ${messages.length} messages`
+            );
+            return { value: matched.slice(0, maxCount) };
+          }
+        }
       } catch (error) {
         console.error(`Search with ${term} failed: ${error.message}`);
+
+        // Client-side fallback for 'to' when API throws (e.g. InefficientFilter)
+        if (term === 'to') {
+          try {
+            console.error(
+              'to filter threw error, trying client-side filtering'
+            );
+            searchAttempts.push('client-side-to');
+            const messages = await fetchForClientSideFilter(
+              accessToken,
+              endpoint,
+              maxCount
+            );
+            const matched = filterToClientSide(messages, searchTerms[term]);
+            if (matched.length > 0) {
+              console.error(
+                `Client-side to filter matched ${matched.length} of ${messages.length} messages`
+              );
+              return { value: matched.slice(0, maxCount) };
+            }
+          } catch (fallbackError) {
+            console.error(
+              `Client-side to fallback also failed: ${fallbackError.message}`
+            );
+          }
+        }
+
+        // Client-side fallback for 'query' when API throws
+        if (term === 'query') {
+          try {
+            console.error(
+              'query filter threw error, trying client-side body search'
+            );
+            searchAttempts.push('client-side-query');
+            const messages = await fetchForClientSideFilter(
+              accessToken,
+              endpoint,
+              maxCount
+            );
+            const matched = filterQueryClientSide(messages, searchTerms[term]);
+            if (matched.length > 0) {
+              console.error(
+                `Client-side query matched ${matched.length} of ${messages.length} messages`
+              );
+              return { value: matched.slice(0, maxCount) };
+            }
+          } catch (fallbackError) {
+            console.error(
+              `Client-side query fallback also failed: ${fallbackError.message}`
+            );
+          }
+        }
       }
     }
   }
@@ -282,6 +393,12 @@ async function progressiveSearch(
       console.error(
         `Boolean filter search found ${response.value?.length || 0} results`
       );
+      response._searchInfo = {
+        attemptsCount: searchAttempts.length,
+        strategies: searchAttempts,
+        originalTerms: searchTerms,
+        filterTerms: filterTerms,
+      };
       return response;
     } catch (error) {
       console.error(`Boolean filter search failed: ${error.message}`);
@@ -301,6 +418,12 @@ async function progressiveSearch(
             retryParams,
             maxCount
           );
+          response._searchInfo = {
+            attemptsCount: searchAttempts.length,
+            strategies: searchAttempts,
+            originalTerms: searchTerms,
+            filterTerms: filterTerms,
+          };
           return response;
         } catch (retryError) {
           console.error(
@@ -311,8 +434,35 @@ async function progressiveSearch(
     }
   }
 
-  // 4. Final fallback: just get recent emails with pagination
-  console.error('All search strategies failed, falling back to recent emails');
+  // 4. Final fallback
+  // If the user specified search filters, return 0 results with guidance
+  // instead of silently returning unfiltered recent emails.
+  const hasAnyFilters =
+    searchTerms.query ||
+    searchTerms.from ||
+    searchTerms.to ||
+    searchTerms.subject ||
+    searchTerms.kqlQuery;
+
+  if (hasAnyFilters) {
+    console.error(
+      'All search strategies exhausted with filters active — returning 0 results'
+    );
+    searchAttempts.push('no-results');
+    return {
+      value: [],
+      _searchInfo: {
+        attemptsCount: searchAttempts.length,
+        strategies: searchAttempts,
+        originalTerms: searchTerms,
+        filterTerms: filterTerms,
+        noResults: true,
+      },
+    };
+  }
+
+  // No search filters specified — return recent emails (list mode)
+  console.error('No search filters specified, returning recent emails');
   searchAttempts.push('recent-emails');
 
   const basicParams = {
@@ -328,11 +478,8 @@ async function progressiveSearch(
     basicParams,
     maxCount
   );
-  console.error(
-    `Fallback to recent emails found ${response.value?.length || 0} results`
-  );
+  console.error(`Recent emails: found ${response.value?.length || 0} results`);
 
-  // Add a note to the response about the search attempts
   response._searchInfo = {
     attemptsCount: searchAttempts.length,
     strategies: searchAttempts,
@@ -391,6 +538,74 @@ function buildToFilter(val) {
   return `toRecipients/any(r: contains(r/emailAddress/name, '${val}'))`;
 }
 
+/**
+ * Client-side filter for toRecipients — used when the OData toRecipients/any()
+ * lambda expression fails on personal accounts (InefficientFilter).
+ * Mirrors the pattern from conversations.js lines 138-147.
+ * @param {Array} messages - Array of message objects with toRecipients
+ * @param {string} toValue - The to filter value (email, domain, or name)
+ * @returns {Array} - Filtered messages where at least one recipient matches
+ */
+function filterToClientSide(messages, toValue) {
+  const toLower = toValue.toLowerCase();
+  return 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);
+    })
+  );
+}
+
+/**
+ * Client-side filter for free-text query — used when $search and
+ * contains(subject) both fail on personal accounts.
+ * Searches subject, bodyPreview, from address, and from name.
+ * @param {Array} messages - Array of message objects
+ * @param {string} queryText - The query text to search for
+ * @returns {Array} - Filtered messages matching the query
+ */
+function filterQueryClientSide(messages, queryText) {
+  const queryLower = queryText.toLowerCase();
+  return messages.filter((m) => {
+    const subject = (m.subject || '').toLowerCase();
+    const body = (m.bodyPreview || '').toLowerCase();
+    const fromAddr = (m.from?.emailAddress?.address || '').toLowerCase();
+    const fromName = (m.from?.emailAddress?.name || '').toLowerCase();
+    return (
+      subject.includes(queryLower) ||
+      body.includes(queryLower) ||
+      fromAddr.includes(queryLower) ||
+      fromName.includes(queryLower)
+    );
+  });
+}
+
+/**
+ * Fetch recent messages for client-side filtering fallback.
+ * Uses the 'search' field preset which includes toRecipients and bodyPreview.
+ * @param {string} accessToken - Access token
+ * @param {string} endpoint - API endpoint
+ * @param {number} maxCount - Maximum results to fetch
+ * @returns {Promise<Array>} - Array of message objects
+ */
+async function fetchForClientSideFilter(accessToken, endpoint, maxCount) {
+  const searchFields = getEmailFields('search');
+  const params = {
+    $top: Math.min(200, maxCount * 5),
+    $select: searchFields,
+    $orderby: 'receivedDateTime desc',
+  };
+  const response = await callGraphAPIPaginated(
+    accessToken,
+    'GET',
+    endpoint,
+    params,
+    Math.min(200, maxCount * 5)
+  );
+  return response.value || [];
+}
+
 /**
  * Build search parameters from search terms and filter terms
  * Uses $filter for email addresses (more reliable than $search)
@@ -531,37 +746,75 @@ function addBooleanFilters(params, filterTerms) {
  * @returns {object} - MCP response object
  */
 function formatSearchResults(response, folder, verbosity) {
+  // Build metadata
+  const meta = {
+    returned: (response.value || []).length,
+    totalAvailable: response['@odata.count'] || null,
+    hasMore: Boolean(response['@odata.nextLink']),
+    verbosity: verbosity,
+  };
+
+  // Add searchMetadata to _meta when available (for programmatic fallback detection)
+  if (response._searchInfo) {
+    const finalStrategy =
+      response._searchInfo.strategies[
+        response._searchInfo.strategies.length - 1
+      ];
+    meta.searchMetadata = {
+      strategiesAttempted: response._searchInfo.strategies,
+      finalStrategy: finalStrategy,
+      filterApplied: !response._searchInfo.noResults,
+      originalFilters: response._searchInfo.originalTerms,
+    };
+  }
+
+  // Handle 0 results
   if (!response.value || response.value.length === 0) {
+    // Actionable guidance when filters were specified but matched nothing
+    if (response._searchInfo?.noResults) {
+      const filters = response._searchInfo.originalTerms || {};
+      const activeFilters = Object.entries(filters)
+        .filter(([, v]) => v)
+        .map(([k]) => k);
+      const filterDesc =
+        activeFilters.length > 0
+          ? ` (filters: ${activeFilters.join(', ')})`
+          : '';
+
+      const text =
+        `No emails found matching your filters in "${folder}"${filterDesc}.\n\n` +
+        '**Suggestions:**\n' +
+        '- Try `searchAllFolders: true` to search across all folders including Archive\n' +
+        '- Specify the correct folder if emails have been moved (use `folders` tool to list folders)\n' +
+        '- Use `from` filter instead of `to` (more reliable on personal accounts)\n' +
+        '- Use `kqlQuery` with `searchAllFolders: true` for cross-folder search';
+
+      return {
+        content: [{ type: 'text', text }],
+        _meta: meta,
+      };
+    }
+
     return {
       content: [
         {
           type: 'text',
-          text: `No emails found matching your search criteria.`,
+          text: 'No emails found matching your search criteria.',
         },
       ],
+      _meta: meta,
     };
   }
 
-  // Build metadata
-  const meta = {
-    returned: response.value.length,
-    totalAvailable: response['@odata.count'] || null,
-    hasMore: Boolean(response['@odata.nextLink']),
-    verbosity: verbosity,
-  };
-
-  // Add search strategy info if available (for debugging)
+  // Add search strategy note for transparency
   let searchNote = '';
   if (response._searchInfo) {
-    const strategy =
-      response._searchInfo.strategies[
-        response._searchInfo.strategies.length - 1
-      ];
+    const strategy = meta.searchMetadata.finalStrategy;
     if (strategy === 'recent-emails') {
       searchNote =
-        '\n\n**Note**: Your search query could not be applied — showing recent emails instead. ' +
-        'On personal Microsoft accounts, free-text `query` search may not work. ' +
-        'Try using `subject`, `from`, `to`, or `kqlQuery` parameters for more reliable filtering.';
+        '\n\n**Note**: No search filters were applied — showing recent emails.';
+    } else if (strategy.startsWith('client-side-')) {
+      searchNote = `\n\n_Search strategy: ${strategy} (filtered locally due to personal account API limitations)_`;
     } else {
       searchNote = `\n\n_Search strategy: ${strategy}_`;
     }
@@ -699,4 +952,6 @@ module.exports = {
   buildFromFilter,
   buildToFilter,
   classifyEmailFilter,
+  filterToClientSide,
+  filterQueryClientSide,
 };

package/package.json

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