@littlebearapps/outlook-assistant 3.5.0 → 3.5.2

package/.env.example

@@ -23,3 +23,8 @@ USE_TEST_MODE=false
 
 # Optional: Enable immutable IDs (IDs persist through folder moves)
 # OUTLOOK_IMMUTABLE_IDS=true
+
+# Optional: Default authentication method (device-code or browser)
+# device-code: No auth server needed, works remotely/headless
+# browser: Traditional OAuth redirect via localhost:3333
+# OUTLOOK_AUTH_METHOD=device-code

package/README.md

@@ -149,9 +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)
+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
 
@@ -340,7 +342,21 @@ If installed from source, use `node` instead of `npx`:
 
 ## Authentication Flow
 
-### Step 1: Start the Auth Server
+### Device Code Flow (Default — Recommended)
+
+No auth server needed. Works everywhere, including remote/headless environments.
+
+1. Ask your AI assistant to authenticate (calls `auth` tool with `action=authenticate`)
+2. Visit the URL shown (`microsoft.com/devicelogin`) on **any** browser, **any** device
+3. Enter the code, sign in with your Microsoft account, and grant permissions
+4. Tell your AI assistant to complete authentication (calls `auth` with `action=device-code-complete`)
+5. Tokens are saved to `~/.outlook-assistant-tokens.json` and **refresh automatically**
+
+> **Prerequisite**: Enable "Allow public client flows" in Azure Portal > your app > Authentication > Advanced settings.
+
+### Browser Redirect Flow (Alternative)
+
+For localhost development or if you prefer the traditional OAuth flow:
 
 ```bash
 npm run auth-server
@@ -348,14 +364,11 @@ npm run auth-server
 
 This starts a local server on port 3333 to handle the OAuth callback.
 
-> **Note**: The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from environment variables (or `MS_CLIENT_ID`/`MS_CLIENT_SECRET`). When running the auth server separately, ensure your `.env` file is in the project root or export the variables in your shell. Your MCP client's `"env"` config only applies to the MCP server process, not a separately-started auth server.
-
-### Step 2: Authenticate
-
-1. In your AI assistant, use the `auth` tool with `action=authenticate`
+1. In your AI assistant, use the `auth` tool with `action=authenticate, method=browser`
 2. Open the provided URL in your browser
-3. Sign in with your Microsoft account and grant permissions
-4. Tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+3. Sign in and grant permissions — tokens are saved automatically
+
+> **Note**: The auth server reads `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` from environment variables. Your MCP client's `"env"` config only applies to the MCP server process, not a separately-started auth server.
 
 ## Directory Structure
 
@@ -409,7 +422,11 @@ You're using the Secret **ID** instead of the Secret **Value**. Go to Azure Port
 
 ### Authentication URL doesn't work
 
-Start the auth server first: `npm run auth-server`
+If using browser flow: start the auth server first with `npm run auth-server`. If using device code flow: visit `microsoft.com/devicelogin` instead.
+
+### Device code "invalid_client"
+
+Enable "Allow public client flows" in Azure Portal > App registrations > Authentication > Advanced settings.
 
 ### Empty API responses
 

package/auth/device-code.js

@@ -0,0 +1,139 @@
+/**
+ * Device Code Flow for Microsoft OAuth2
+ *
+ * Enables authentication without browser redirect — ideal for
+ * headless/remote environments (SSH, VPS, containers).
+ *
+ * The user gets a short code, visits https://microsoft.com/devicelogin
+ * on any device, and enters it. No auth server or port forwarding needed.
+ */
+const https = require('https');
+const querystring = require('querystring');
+const config = require('../config');
+
+/**
+ * POST helper for OAuth2 endpoints
+ * @param {string} url - Full URL to POST to
+ * @param {string} postData - URL-encoded form data
+ * @returns {Promise<{statusCode: number, body: object}>}
+ */
+function postRequest(url, postData) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      url,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(postData),
+        },
+      },
+      (res) => {
+        let data = '';
+        res.on('data', (chunk) => (data += chunk));
+        res.on('end', () => {
+          try {
+            resolve({ statusCode: res.statusCode, body: JSON.parse(data) });
+          } catch (_e) {
+            reject(new Error(`Failed to parse response: ${data}`));
+          }
+        });
+      }
+    );
+    req.on('error', reject);
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Initiates the device code flow by requesting a device code from Azure.
+ * @param {string} clientId - Azure app client ID
+ * @param {string[]} scopes - OAuth2 scopes to request
+ * @returns {Promise<{userCode: string, verificationUri: string, deviceCode: string, expiresIn: number, interval: number, message: string}>}
+ */
+async function initiateDeviceCodeFlow(clientId, scopes) {
+  const postData = querystring.stringify({
+    client_id: clientId,
+    scope: scopes.join(' '),
+  });
+
+  const endpoint = config.AUTH_CONFIG.deviceCodeEndpoint;
+  const { statusCode, body } = await postRequest(endpoint, postData);
+
+  if (statusCode < 200 || statusCode >= 300) {
+    throw new Error(
+      body.error_description ||
+        `Device code request failed with status ${statusCode}`
+    );
+  }
+
+  return {
+    userCode: body.user_code,
+    verificationUri: body.verification_uri,
+    deviceCode: body.device_code,
+    expiresIn: body.expires_in,
+    interval: body.interval || 5,
+    message: body.message,
+  };
+}
+
+/**
+ * Polls the token endpoint until the user completes authentication.
+ * @param {string} clientId - Azure app client ID
+ * @param {string} deviceCode - Device code from initiateDeviceCodeFlow
+ * @param {number} interval - Polling interval in seconds
+ * @param {number} expiresIn - Seconds until the device code expires
+ * @returns {Promise<{access_token: string, refresh_token: string, expires_in: number, scope: string, token_type: string}>}
+ */
+async function pollForToken(clientId, deviceCode, interval, expiresIn) {
+  const endpoint = config.AUTH_CONFIG.tokenEndpoint;
+  const deadline = Date.now() + expiresIn * 1000;
+  let pollInterval = interval;
+
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
+
+    const postData = querystring.stringify({
+      client_id: clientId,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      device_code: deviceCode,
+    });
+
+    const { statusCode, body } = await postRequest(endpoint, postData);
+
+    if (statusCode >= 200 && statusCode < 300) {
+      return body;
+    }
+
+    switch (body.error) {
+      case 'authorization_pending':
+        // User hasn't completed auth yet — keep polling
+        break;
+      case 'slow_down':
+        // Server asked us to slow down — increase interval by 5s
+        pollInterval += 5;
+        break;
+      case 'authorization_declined':
+        throw new Error('Authentication was declined by the user.');
+      case 'expired_token':
+        throw new Error(
+          'Device code expired. Please restart the authentication process.'
+        );
+      default:
+        throw new Error(
+          body.error_description ||
+            `Token polling failed: ${body.error || `status ${statusCode}`}`
+        );
+    }
+  }
+
+  throw new Error(
+    'Device code expired. Please restart the authentication process.'
+  );
+}
+
+module.exports = {
+  initiateDeviceCodeFlow,
+  pollForToken,
+};

package/auth/index.js

@@ -2,22 +2,32 @@
  * Authentication module for Outlook Assistant server
  */
 const tokenManager = require('./token-manager');
-const { authTools } = require('./tools');
+const TokenStorage = require('./token-storage');
+const config = require('../config');
+const { authTools, setToolCount } = require('./tools');
+
+// Singleton TokenStorage instance with auto-refresh support
+const tokenStorage = new TokenStorage({
+  clientId: config.AUTH_CONFIG.clientId,
+  clientSecret: config.AUTH_CONFIG.clientSecret,
+  tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+  scopes: config.AUTH_CONFIG.scopes,
+  tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+});
 
 /**
- * Ensures the user is authenticated and returns an access token
+ * Ensures the user is authenticated and returns an access token.
+ * Automatically refreshes expired tokens via tokenStorage.
  * @param {boolean} forceNew - Whether to force a new authentication
  * @returns {Promise<string>} - Access token
  * @throws {Error} - If authentication fails
  */
 async function ensureAuthenticated(forceNew = false) {
   if (forceNew) {
-    // Force re-authentication
     throw new Error('Authentication required');
   }
 
-  // Check for existing token
-  const accessToken = tokenManager.getAccessToken();
+  const accessToken = await tokenStorage.getValidAccessToken();
   if (!accessToken) {
     throw new Error('Authentication required');
   }
@@ -26,7 +36,9 @@ async function ensureAuthenticated(forceNew = false) {
 }
 
 module.exports = {
-  tokenManager,
+  tokenManager, // deprecated: use tokenStorage
+  tokenStorage,
   authTools,
+  setToolCount,
   ensureAuthenticated,
 };

package/auth/tools.js

@@ -3,6 +3,13 @@
  */
 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
@@ -24,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} |`,
@@ -46,18 +53,14 @@ async function handleAbout() {
 }
 
 /**
- * Authentication tool handler
+ * Authentication tool handler — supports browser redirect and device code flow.
  * @param {object} args - Tool arguments
  * @returns {object} - MCP response
  */
 async function handleAuthenticate(args) {
-  const _force = args && args.force === true;
-
   // For test mode, create a test token
   if (config.USE_TEST_MODE) {
-    // Create a test token with a 1-hour expiry
     tokenManager.createTestTokens();
-
     return {
       content: [
         {
@@ -68,43 +71,205 @@ async function handleAuthenticate(args) {
     };
   }
 
-  // For real authentication, generate an auth URL and instruct the user to visit it
+  const method = args?.method || config.AUTH_CONFIG.defaultAuthMethod;
+
+  if (method === 'device-code') {
+    return handleDeviceCodeAuth();
+  }
+
+  // Browser redirect flow (existing behaviour)
   const authUrl = `${config.AUTH_CONFIG.authServerUrl}/auth?client_id=${config.AUTH_CONFIG.clientId}`;
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `Authentication required. Please visit the following URL to authenticate with Microsoft: ${authUrl}\n\nAfter authentication, you will be redirected back to this application.\n\nNote: The auth server must be running on port 3333. If working remotely, consider using method=device-code instead.`,
+      },
+    ],
+  };
+}
+
+// Module-level state for pending device code flow
+let pendingDeviceCode = 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.
+ * @returns {object} - MCP response
+ */
+async function handleDeviceCodeAuth() {
+  const clientId = config.AUTH_CONFIG.clientId;
+  if (!clientId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Error: OUTLOOK_CLIENT_ID is not configured.',
+        },
+      ],
+    };
+  }
+
+  console.error('[AUTH] Starting device code flow...');
+  const response = await initiateDeviceCodeFlow(
+    clientId,
+    config.AUTH_CONFIG.scopes
+  );
+
+  // Store for the completion step
+  pendingDeviceCode = {
+    deviceCode: response.deviceCode,
+    interval: response.interval,
+    expiresIn: response.expiresIn,
+    expiresAt: Date.now() + response.expiresIn * 1000,
+  };
+
+  console.error(
+    `[AUTH] Device code: ${response.userCode}, expires in ${response.expiresIn}s`
+  );
 
   return {
     content: [
       {
         type: 'text',
-        text: `Authentication required. Please visit the following URL to authenticate with Microsoft: ${authUrl}\n\nAfter authentication, you will be redirected back to this application.`,
+        text: [
+          `## Device Code Authentication\n`,
+          `Visit: **${response.verificationUri}**`,
+          `Enter code: **${response.userCode}**\n`,
+          `The code expires in ${Math.floor(response.expiresIn / 60)} minutes.\n`,
+          `After entering the code and signing in, call this tool again with \`action=device-code-complete\` to finish authentication.`,
+        ].join('\n'),
       },
     ],
   };
 }
 
 /**
- * Check authentication status tool handler
+ * Device code flow step 2 — poll until the user completes authentication.
+ * @returns {object} - MCP response
+ */
+async function handleDeviceCodeComplete() {
+  if (!pendingDeviceCode) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'No pending device code flow. Call authenticate with method=device-code first.',
+        },
+      ],
+    };
+  }
+
+  if (Date.now() > pendingDeviceCode.expiresAt) {
+    pendingDeviceCode = null;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Device code has expired. Please start a new authentication with action=authenticate.',
+        },
+      ],
+    };
+  }
+
+  const clientId = config.AUTH_CONFIG.clientId;
+
+  try {
+    console.error('[AUTH] Polling for device code completion...');
+    const tokenResponse = await pollForToken(
+      clientId,
+      pendingDeviceCode.deviceCode,
+      pendingDeviceCode.interval,
+      Math.ceil((pendingDeviceCode.expiresAt - Date.now()) / 1000)
+    );
+
+    pendingDeviceCode = null;
+
+    // Save tokens using TokenStorage
+    const TokenStorage = require('./token-storage');
+    const tokenStorage = new TokenStorage({
+      clientId: config.AUTH_CONFIG.clientId,
+      clientSecret: config.AUTH_CONFIG.clientSecret,
+      tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+      scopes: config.AUTH_CONFIG.scopes,
+      tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+    });
+
+    tokenStorage.tokens = {
+      access_token: tokenResponse.access_token,
+      refresh_token: tokenResponse.refresh_token,
+      expires_in: tokenResponse.expires_in,
+      expires_at: Date.now() + tokenResponse.expires_in * 1000,
+      scope: tokenResponse.scope,
+      token_type: tokenResponse.token_type,
+    };
+    await tokenStorage._saveTokensToFile();
+
+    console.error('[AUTH] Device code flow completed successfully.');
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Authentication successful! Tokens saved. You can now use Outlook tools.',
+        },
+      ],
+    };
+  } catch (error) {
+    pendingDeviceCode = null;
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Authentication failed: ${error.message}`,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Check authentication status — attempts token refresh if expired.
  * @returns {object} - MCP response
  */
 async function handleCheckAuthStatus() {
   console.error('[CHECK-AUTH-STATUS] Starting authentication status check');
 
-  const tokens = tokenManager.loadTokenCache();
+  // Use TokenStorage for accurate status (includes refresh attempt)
+  const TokenStorage = require('./token-storage');
+  const tokenStorage = new TokenStorage({
+    clientId: config.AUTH_CONFIG.clientId,
+    clientSecret: config.AUTH_CONFIG.clientSecret,
+    tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
+    scopes: config.AUTH_CONFIG.scopes,
+    tokenEndpoint: config.AUTH_CONFIG.tokenEndpoint,
+  });
 
-  console.error(`[CHECK-AUTH-STATUS] Tokens loaded: ${tokens ? 'YES' : 'NO'}`);
+  const accessToken = await tokenStorage.getValidAccessToken();
 
-  if (!tokens || !tokens.access_token) {
-    console.error('[CHECK-AUTH-STATUS] No valid access token found');
+  if (!accessToken) {
+    console.error('[CHECK-AUTH-STATUS] No valid access token');
     return {
       content: [{ type: 'text', text: 'Not authenticated' }],
     };
   }
 
-  console.error('[CHECK-AUTH-STATUS] Access token present');
-  console.error(`[CHECK-AUTH-STATUS] Token expires at: ${tokens.expires_at}`);
-  console.error(`[CHECK-AUTH-STATUS] Current time: ${Date.now()}`);
+  const expiresAt = tokenStorage.getExpiryTime();
+  const expiresIn = expiresAt
+    ? Math.round((expiresAt - Date.now()) / 60000)
+    : 'unknown';
+
+  console.error(
+    `[CHECK-AUTH-STATUS] Authenticated, token expires in ~${expiresIn} min`
+  );
 
   return {
-    content: [{ type: 'text', text: 'Authenticated and ready' }],
+    content: [
+      {
+        type: 'text',
+        text: `Authenticated and ready (token expires in ~${expiresIn} minutes)`,
+      },
+    ],
   };
 }
 
@@ -113,7 +278,7 @@ const authTools = [
   {
     name: 'auth',
     description:
-      'Manage authentication with Microsoft Graph API. action=status (default) checks auth state, action=authenticate starts OAuth flow, action=about shows server info.',
+      'Manage authentication with Microsoft Graph API. action=status (default) checks auth state and refreshes tokens if needed, action=authenticate starts OAuth flow (device-code by default — no auth server needed), action=device-code-complete finishes device code auth after user enters code, action=about shows server info.',
     annotations: {
       title: 'Authentication',
       readOnlyHint: false,
@@ -125,9 +290,15 @@ const authTools = [
       properties: {
         action: {
           type: 'string',
-          enum: ['status', 'authenticate', 'about'],
+          enum: ['status', 'authenticate', 'device-code-complete', 'about'],
           description: 'Action to perform (default: status)',
         },
+        method: {
+          type: 'string',
+          enum: ['device-code', 'browser'],
+          description:
+            'Auth method for action=authenticate. device-code (default): no auth server needed, works remotely. browser: traditional OAuth redirect via port 3333.',
+        },
         force: {
           type: 'boolean',
           description:
@@ -141,6 +312,8 @@ const authTools = [
       switch (action) {
         case 'authenticate':
           return handleAuthenticate(args);
+        case 'device-code-complete':
+          return handleDeviceCodeComplete();
         case 'about':
           return handleAbout();
         case 'status':
@@ -153,7 +326,10 @@ const authTools = [
 
 module.exports = {
   authTools,
+  setToolCount,
   handleAbout,
   handleAuthenticate,
+  handleDeviceCodeAuth,
+  handleDeviceCodeComplete,
   handleCheckAuthStatus,
 };

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/config.js

@@ -54,6 +54,10 @@ module.exports = {
     ],
     tokenStorePath: path.join(homeDir, '.outlook-assistant-tokens.json'),
     authServerUrl: 'http://localhost:3333',
+    deviceCodeEndpoint:
+      'https://login.microsoftonline.com/common/oauth2/v2.0/devicecode',
+    tokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    defaultAuthMethod: process.env.OUTLOOK_AUTH_METHOD || 'device-code',
   },
 
   // Microsoft Graph API

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/llms-install.md

@@ -0,0 +1,90 @@
+# Installing Outlook Assistant
+
+## Quick Install (npx — no global install needed)
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": ["-y", "@littlebearapps/outlook-assistant"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "<user-must-provide>",
+        "OUTLOOK_CLIENT_SECRET": "<user-must-provide>"
+      }
+    }
+  }
+}
+```
+
+## Prerequisites
+
+1. **Node.js 18+** must be installed
+2. **Azure app registration** is required for authentication (free tier works)
+
+## Getting the Client ID and Secret
+
+Users must create an Azure app registration to get credentials:
+
+1. Go to https://portal.azure.com/ and sign in
+2. Search for "App registrations" → click "New registration"
+3. Name: "Outlook Assistant" (or any name)
+4. Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
+5. Redirect URI: platform "Web", URI `http://localhost:3333/auth/callback`
+6. Click "Register"
+7. Copy the **Application (client) ID** → this is `OUTLOOK_CLIENT_ID`
+
+### Create a client secret:
+1. Go to "Certificates & secrets" → "New client secret"
+2. Add a description, select expiration, click "Add"
+3. **Copy the Value immediately** (not the Secret ID) → this is `OUTLOOK_CLIENT_SECRET`
+
+### Add API permissions:
+1. Go to "API permissions" → "Add a permission" → "Microsoft Graph" → "Delegated permissions"
+2. Add: `offline_access`, `User.Read`, `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`, `People.Read`, `MailboxSettings.ReadWrite`
+3. Click "Add permissions"
+
+## First-Time Authentication
+
+After configuring the MCP server:
+
+1. Start the auth server: `npx @littlebearapps/outlook-assistant-auth` (or run `npm run auth-server` from source)
+2. Use the `auth` tool with `action=authenticate` to get an OAuth URL
+3. Open the URL in a browser, sign in with your Microsoft account
+4. Grant permissions — tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+
+**Note**: The auth server needs `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` as environment variables. If running it separately from the MCP server, export them in your shell or create a `.env` file.
+
+## Configuration Files by Client
+
+### Claude Desktop
+File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+### Claude Code
+```bash
+claude mcp add outlook -- npx @littlebearapps/outlook-assistant
+```
+
+### Cursor
+File: `.cursor/mcp.json` in your project root
+
+### Windsurf
+File: `~/.codeium/windsurf/mcp_config.json`
+
+## Verify Installation
+
+After authentication, test with:
+- `auth` tool with `action=status` — should show "authenticated"
+- `search-emails` with no parameters — should list recent inbox emails
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID |
+| Auth URL doesn't work | Start the auth server first |
+| "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
+| Empty API responses | Run `auth` tool with `action=status` to check token |
+| Search returns no results (personal account) | Use `from`, `subject`, `to` filters instead of `query` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.5.0",
+  "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",
@@ -70,7 +70,8 @@
     ".env.example",
     "README.md",
     "LICENSE",
-    "llms.txt"
+    "llms.txt",
+    "llms-install.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

package/utils/graph-api.js

@@ -325,9 +325,67 @@ async function callGraphAPIRaw(accessToken, emailId) {
   });
 }
 
+/**
+ * Calls Graph API with automatic auth and 401 retry.
+ * Gets token via ensureAuthenticated(), and if a 401 occurs,
+ * refreshes the token and retries once.
+ * @param {string} method - HTTP method
+ * @param {string} path - API endpoint path
+ * @param {object} data - Request body
+ * @param {object} queryParams - Query parameters
+ * @param {object} extraHeaders - Additional headers
+ * @returns {Promise<object>} - API response
+ */
+async function callGraphAPIWithAuth(
+  method,
+  path,
+  data = null,
+  queryParams = {},
+  extraHeaders = {}
+) {
+  // Lazy require to avoid circular dependency
+  const { ensureAuthenticated, tokenStorage } = require('../auth');
+
+  const accessToken = await ensureAuthenticated();
+  try {
+    return await callGraphAPI(
+      accessToken,
+      method,
+      path,
+      data,
+      queryParams,
+      extraHeaders
+    );
+  } catch (error) {
+    if (error.message === 'UNAUTHORIZED' && tokenStorage) {
+      console.error('[GRAPH-API] 401 received, attempting token refresh...');
+      try {
+        const newToken = await tokenStorage.refreshAccessToken();
+        if (newToken) {
+          return await callGraphAPI(
+            newToken,
+            method,
+            path,
+            data,
+            queryParams,
+            extraHeaders
+          );
+        }
+      } catch (refreshError) {
+        console.error(
+          '[GRAPH-API] Token refresh failed:',
+          refreshError.message
+        );
+      }
+    }
+    throw error;
+  }
+}
+
 module.exports = {
   callGraphAPI,
   callGraphAPIPaginated,
   callGraphAPIBatch,
   callGraphAPIRaw,
+  callGraphAPIWithAuth,
 };