@littlebearapps/outlook-assistant 3.7.2 → 3.7.4

package/email/search.js

@@ -33,7 +33,12 @@ async function handleSearchEmails(args) {
     };
   }
 
-  const requestedCount = args.count ?? DEFAULT_LIMITS.searchEmails; // Default 10
+  // F-17: accept `maxResults` as an alias for `count` in non-delta mode.
+  // The schema declares both, but `maxResults` was only consumed by
+  // the delta path, so callers passing `maxResults=5` to a normal
+  // search saw their override silently ignored.
+  const requestedCount =
+    args.count ?? args.maxResults ?? DEFAULT_LIMITS.searchEmails;
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
   const query = args.query || '';
   const from = args.from || '';
@@ -122,16 +127,40 @@ async function progressiveSearch(
   // Track search strategies attempted
   const searchAttempts = [];
 
-  // 0. If raw KQL query provided, use it directly
+  // 0. If raw KQL query provided, use it directly. The kqlQuery branch
+  //    *terminates* — if Graph returns 0 (or throws), we surface that
+  //    explicitly rather than falling through to combined-search, which
+  //    would drop the user's filter and return unrelated recent emails
+  //    with a misleading "combined-search" strategy line. (#169)
   if (searchTerms.kqlQuery) {
     try {
-      console.error(`Attempting raw KQL search: "${searchTerms.kqlQuery}"`);
+      // Pass the user's KQL through as-is. The user is responsible for
+      // their own phrase quoting (e.g. `subject:"foo bar"`); we do NOT
+      // auto-wrap, which previously produced broken nested quotes like
+      // `"subject:"foo bar""` on Graph $search and silently returned
+      // recent unfiltered messages. (#169 V37-F-1)
+      const trimmedKql = searchTerms.kqlQuery.trim();
+      const alreadyQuoted =
+        trimmedKql.startsWith('"') && trimmedKql.endsWith('"');
+      const looksLikeExpression =
+        trimmedKql.includes(':') || /\s/.test(trimmedKql);
+      // Already-quoted phrases and KQL-looking expressions (field syntax
+      // or multi-word) are passed through as-is; only bare single tokens
+      // are wrapped so Graph treats them as phrase searches.
+      let kqlForSearch;
+      if (alreadyQuoted || looksLikeExpression) {
+        kqlForSearch = trimmedKql;
+      } else {
+        kqlForSearch = `"${trimmedKql}"`;
+      }
+
+      console.error(`Attempting raw KQL search: ${kqlForSearch}`);
       searchAttempts.push('raw-kql');
 
       const kqlParams = {
         $top: Math.min(50, maxCount),
         $select: selectFields,
-        $search: `"${searchTerms.kqlQuery}"`,
+        $search: kqlForSearch,
       };
 
       const response = await callGraphAPIPaginated(
@@ -141,20 +170,40 @@ async function progressiveSearch(
         kqlParams,
         maxCount
       );
-      if (response.value && response.value.length > 0) {
-        console.error(
-          `Raw KQL search successful: found ${response.value.length} results`
-        );
-        response._searchInfo = {
+      console.error(
+        `Raw KQL search complete: ${response.value?.length || 0} results`
+      );
+      const matched = response.value?.length || 0;
+      response._searchInfo = {
+        attemptsCount: searchAttempts.length,
+        strategies: searchAttempts,
+        originalTerms: searchTerms,
+        filterTerms: filterTerms,
+        kqlApplied: kqlForSearch,
+        // noResults flips on the helpful "Suggestions" block in the
+        // formatter — without it, an empty kqlQuery result would render
+        // the bare "No emails found matching your search criteria" line
+        // with no guidance.
+        noResults: matched === 0,
+      };
+      // Always return — never silently fall through to a path that
+      // would ignore kqlQuery and return unrelated emails.
+      return response;
+    } catch (error) {
+      console.error(`Raw KQL search failed: ${error.message}`);
+      // Surface the failure rather than masking it with unrelated results.
+      searchAttempts.push('raw-kql-error');
+      return {
+        value: [],
+        _searchInfo: {
           attemptsCount: searchAttempts.length,
           strategies: searchAttempts,
           originalTerms: searchTerms,
           filterTerms: filterTerms,
-        };
-        return response;
-      }
-    } catch (error) {
-      console.error(`Raw KQL search failed: ${error.message}`);
+          kqlError: error.message,
+          noResults: true,
+        },
+      };
     }
   }
 
@@ -566,18 +615,26 @@ function filterToClientSide(messages, toValue) {
  * @returns {Array} - Filtered messages matching the query
  */
 function filterQueryClientSide(messages, queryText) {
-  const queryLower = queryText.toLowerCase();
+  // F-12: split multi-word queries on whitespace and require ALL words
+  // to be present (AND search). Previous behaviour was substring match
+  // on the literal phrase, which missed the common case where the
+  // user types e.g. "github token" expecting it to find a subject
+  // like "[GitHub] Your fine-grained personal access token".
+  const queryLower = queryText.toLowerCase().trim();
+  if (!queryLower) return messages;
+  const words = queryLower.split(/\s+/).filter(Boolean);
+
   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)
-    );
+    const haystack = [
+      m.subject,
+      m.bodyPreview,
+      m.from?.emailAddress?.address,
+      m.from?.emailAddress?.name,
+    ]
+      .filter(Boolean)
+      .join(' ')
+      .toLowerCase();
+    return words.every((w) => haystack.includes(w));
   });
 }
 

package/folder/create.js

@@ -43,6 +43,9 @@ async function handleCreateFolder(args) {
           text: result.message,
         },
       ],
+      // F-31: surface the folder ID in _meta so callers can chain
+      // create→move→stats without an extra `folders list` round-trip.
+      ...(result.folderId && { _meta: { folderId: result.folderId } }),
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
@@ -118,7 +121,9 @@ async function createMailFolder(accessToken, folderName, parentFolderName) {
 
       return {
         success: true,
-        message: `Successfully created folder "${folderName}" ${locationInfo}.`,
+        // F-31: include the ID in the human-readable message too so it
+        // shows up for AI agents that don't read _meta.
+        message: `Successfully created folder "${folderName}" ${locationInfo}.\n\n**ID**: ${response.id}`,
         folderId: response.id,
       };
     } else {

package/folder/index.js

@@ -81,6 +81,7 @@ const folderTools = [
             'Folder name to delete — resolved to ID (action=delete). Cannot delete protected folders (Inbox, Drafts, Sent, etc.)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -95,8 +96,16 @@ const folderTools = [
         case 'delete':
           return handleDeleteFolder(args);
         case 'list':
-        default:
           return handleListFolders(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, create, move, stats, delete.`,
+              },
+            ],
+          };
       }
     },
   },

package/index.js

@@ -10,6 +10,7 @@ const {
   StdioServerTransport,
 } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const config = require('./config');
+const { coerceArgsAgainstSchema } = require('./utils/schema-coerce');
 
 // Import module tools
 const { authTools, setToolCount } = require('./auth');
@@ -26,6 +27,19 @@ const { advancedTools } = require('./advanced');
 console.error(`STARTING ${config.SERVER_NAME.toUpperCase()} MCP SERVER`);
 console.error(`Test mode is ${config.USE_TEST_MODE ? 'enabled' : 'disabled'}`);
 
+// F-1 / F-48: warn at startup when safety belts are unset. Mirrors the
+// warning surfaced by `auth action=about`. Visible to operators reading
+// stderr; AI clients reading the JSON-RPC stream are unaffected.
+if (
+  !process.env.OUTLOOK_MAX_EMAILS_PER_SESSION &&
+  !process.env.OUTLOOK_ALLOWED_RECIPIENTS &&
+  !config.USE_TEST_MODE
+) {
+  console.error(
+    '⚠ Safety belts not configured. Consider setting OUTLOOK_MAX_EMAILS_PER_SESSION and OUTLOOK_ALLOWED_RECIPIENTS in your .mcp.json env block for safer AI-assisted sending. See `auth action=about` for details.'
+  );
+}
+
 // Combine all tools
 const TOOLS = [
   ...authTools,
@@ -110,6 +124,25 @@ server.fallbackRequestHandler = async (request) => {
         const tool = TOOLS.find((t) => t.name === name);
 
         if (tool && tool.handler) {
+          // Coerce + validate args against the tool's inputSchema before
+          // dispatching. Catches array-as-string, boolean-as-string, unknown
+          // params, and out-of-enum action values at the MCP boundary so
+          // handlers receive properly-typed JS values. (#160, #162)
+          if (tool.inputSchema) {
+            const coerced = coerceArgsAgainstSchema(args, tool.inputSchema);
+            if (coerced.error) {
+              return {
+                content: [
+                  {
+                    type: 'text',
+                    text: `Invalid arguments for tool '${name}':\n${coerced.error}`,
+                  },
+                ],
+                isError: true,
+              };
+            }
+            return await tool.handler(coerced.args);
+          }
           return await tool.handler(args);
         }
 

package/llms.txt

@@ -22,7 +22,8 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 
 ## Key Differentiators
 
-- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently
+- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently. Explicit "no results" messaging instead of unfiltered fallback.
+- **Remote-friendly auth**: Device code flow (default) — no auth server, no port forwarding, no SSH tunnels. State persists across MCP server restarts. Works from Untether, mosh, SSH, and headless environments.
 - **Email forensics**: Built-in header analysis for DKIM, SPF, DMARC authentication, delivery chains, and spam scores — useful for phishing investigation and compliance
 - **Delta sync**: Incremental inbox monitoring — returns only new, modified, and deleted emails since last check, with tokens for continuous polling
 - **Batch operations**: Flag, move, export, or categorise multiple emails in a single tool call; search-driven export for batch archiving without collecting IDs
@@ -72,7 +73,12 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 
 - [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 22 tools with parameters and safety annotations
+- [Connect Outlook to Claude](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/connect-outlook-to-claude.md): Step-by-step setup guide for Claude Desktop / Claude Code
+- [Verify Your Connection](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/how-to/getting-started/verify-your-connection.md): Test and troubleshoot the connection after installation
+- [Azure Setup](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/guides/azure-setup.md): Azure app registration and API permissions walkthrough
+- [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/index.md): Frequently asked questions — install, accounts, permissions, tokens, send safety, updates, uninstall (also at <https://littlebearapps.com/help/outlook-assistant/faq/>)
 - [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
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.7.4 — patch release closing two regressions surfaced by an independent v3.7.3 E2E re-verification: F-24 chokepoint now catches JSON-stringified arrays from MCP transport (#168) and search-emails kqlQuery no longer silently drops on Step 0 fall-through (#169))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.7.5 polish, v3.8.0 task integration & auth, v3.9.0 new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.7.2",
+  "version": "3.7.4",
   "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",

package/rules/create.js

@@ -150,7 +150,10 @@ async function handleCreateRule(args) {
     );
 
     if (response && response.id) {
-      let text = `Successfully created rule "${name}" with sequence ${ruleSequence}.`;
+      // F-43: include the rule ID. update/delete accept ruleName so this
+      // is workable, but ID is more reliable when names contain unicode
+      // or duplicates exist.
+      let text = `Successfully created rule "${name}" with sequence ${ruleSequence}.\n\n**ID**: ${response.id}`;
       if (allWarnings.length > 0) {
         text += `\n\nNotes:\n${allWarnings.map((w) => `- ${w}`).join('\n')}`;
       }
@@ -160,6 +163,7 @@ async function handleCreateRule(args) {
       }
       return {
         content: [{ type: 'text', text }],
+        _meta: { ruleId: response.id },
       };
     }
 

package/rules/index.js

@@ -209,6 +209,11 @@ const rulesTools = [
           description:
             'Rule name (action=create required, action=update to rename)',
         },
+        displayName: {
+          type: 'string',
+          description:
+            "Alias for `name` (matches Graph's own `displayName` field).",
+        },
         dryRun: {
           type: 'boolean',
           description:
@@ -378,10 +383,15 @@ const rulesTools = [
           description: 'ID of existing rule (action=update/delete)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
       const action = args.action || 'list';
+      // F-41: accept Graph's own `displayName` as alias for `name`.
+      if (args.displayName && !args.name) {
+        args = { ...args, name: args.displayName };
+      }
       switch (action) {
         case 'create':
           return handleCreateRule(args);
@@ -392,8 +402,16 @@ const rulesTools = [
         case 'delete':
           return handleDeleteRule(args);
         case 'list':
-        default:
           return handleListRules(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, create, update, reorder, delete.`,
+              },
+            ],
+          };
       }
     },
   },

package/rules/update.js

@@ -163,11 +163,19 @@ async function handleUpdateRule(args) {
 
     const changedFields = Object.keys(patch)
       .map((k) => {
-        if (k === 'displayName') return `name → "${patch.displayName}"`;
+        if (k === 'displayName') {
+          return `name: "${currentRule.displayName}" → "${patch.displayName}"`;
+        }
         if (k === 'isEnabled') {
-          return patch.isEnabled ? 'enabled' : 'disabled';
+          // Show explicit before/after to remove the F-45 ambiguity:
+          // previously rendered as bare "enabled"/"disabled" with no
+          // indication of direction, so callers couldn't tell whether
+          // the rule was enabled or whether the action just succeeded.
+          return `isEnabled: ${currentRule.isEnabled} → ${patch.isEnabled}`;
+        }
+        if (k === 'sequence') {
+          return `sequence: ${currentRule.sequence} → ${patch.sequence}`;
         }
-        if (k === 'sequence') return `sequence → ${patch.sequence}`;
         if (k === 'conditions') return 'conditions updated';
         if (k === 'actions') return 'actions updated';
         if (k === 'exceptions') return 'exceptions updated';

package/settings/index.js

@@ -227,12 +227,27 @@ async function handleSetAutomaticReplies(args) {
 
     // Build the settings object
     const settings = {};
+    let requestedStatus = null;
 
     // Determine status
     if (enabled === false) {
       settings.status = 'disabled';
+      requestedStatus = 'disabled';
+      // F-6: Graph keeps schedule timestamps when transitioning out of
+      // 'scheduled' mode unless they're explicitly cleared, which leaves
+      // status stuck at 'scheduled'. Reset both to the unix epoch so the
+      // disable actually applies. Graph rejects null here.
+      settings.scheduledStartDateTime = {
+        dateTime: '1970-01-01T00:00:00.000',
+        timeZone: 'UTC',
+      };
+      settings.scheduledEndDateTime = {
+        dateTime: '1970-01-01T00:00:00.000',
+        timeZone: 'UTC',
+      };
     } else if (startDateTime && endDateTime) {
       settings.status = 'scheduled';
+      requestedStatus = 'scheduled';
       settings.scheduledStartDateTime = {
         dateTime: new Date(startDateTime).toISOString(),
         timeZone: 'UTC',
@@ -243,6 +258,7 @@ async function handleSetAutomaticReplies(args) {
       };
     } else if (enabled === true) {
       settings.status = 'alwaysEnabled';
+      requestedStatus = 'alwaysEnabled';
     }
 
     // Reply messages
@@ -269,6 +285,21 @@ async function handleSetAutomaticReplies(args) {
       settings.externalAudience = externalAudience;
     }
 
+    // F-4: refuse to claim "updated" when nothing meaningful changed.
+    // Catches the misleading-success case where the caller passed only
+    // externalAudience without enabled/scheduled — previously the wrapper
+    // announced "Automatic replies updated!" with no actual state change.
+    if (Object.keys(settings).length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'No automatic-reply settings were provided. To change state, pass `enabled: true|false` or `startDateTime` + `endDateTime`. To update messages or audience, pass `internalReplyMessage`, `externalReplyMessage`, or `externalAudience`.',
+          },
+        ],
+      };
+    }
+
     // Apply settings
     await callGraphAPI(accessToken, 'PATCH', 'me/mailboxSettings', {
       automaticRepliesSetting: settings,
@@ -282,9 +313,37 @@ async function handleSetAutomaticReplies(args) {
     );
 
     const output = [];
-    output.push('Automatic replies updated!\n');
+    if (requestedStatus) {
+      output.push('Automatic replies updated!\n');
+    } else {
+      // F-4: no status-changing param was provided. Spell out exactly
+      // which fields the PATCH carried so the caller doesn't think
+      // the status flipped silently.
+      const otherFields = Object.keys(settings).join(', ');
+      output.push(
+        `Updated automatic-reply settings (${otherFields}). No status change applied — pass \`enabled\` or \`startDateTime\`+\`endDateTime\` to change state.\n`
+      );
+    }
     output.push(formatAutomaticReplies(updated));
 
+    // F-7: Graph silently coerces alwaysEnabled → disabled on personal
+    // Outlook.com accounts (no error returned). Detect divergence
+    // between requested and post-PATCH state and surface it to the
+    // caller so they can correct the call.
+    if (requestedStatus && updated.status !== requestedStatus) {
+      let hint = '';
+      if (
+        requestedStatus === 'alwaysEnabled' &&
+        updated.status === 'disabled'
+      ) {
+        hint =
+          ' Personal Outlook.com accounts only support `scheduled` mode — provide `startDateTime` + `endDateTime` instead of `enabled: true` alone.';
+      }
+      output.push(
+        `\n**⚠ Warning**: Requested status \`${requestedStatus}\` but Graph applied \`${updated.status}\`.${hint}`
+      );
+    }
+
     // Warn if enabling without messages
     if (
       updated.status !== 'disabled' &&
@@ -641,6 +700,7 @@ const settingsTools = [
             "Time zone name, e.g. 'Australia/Melbourne' (action=set-working-hours)",
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -651,8 +711,16 @@ const settingsTools = [
         case 'set-working-hours':
           return handleSetWorkingHours(args);
         case 'get':
-        default:
           return handleGetMailboxSettings(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: get, set-auto-replies, set-working-hours.`,
+              },
+            ],
+          };
       }
     },
   },

package/utils/response-formatter.js

@@ -261,6 +261,11 @@ function formatEmailContent(
     body = email.bodyPreview || 'No content';
   }
 
+  // F-16: strip tracking-pixel zero-width chars before returning. These
+  // serve no purpose for AI consumption and can run into the hundreds
+  // per message, bloating token usage.
+  body = stripZeroWidth(body);
+
   // Truncate if needed (unless full verbosity requested)
   if (verbosity !== VERBOSITY.FULL) {
     const truncated = truncateWithMeta(body, DEFAULT_LIMITS.maxBodyTruncation);
@@ -480,6 +485,27 @@ function stripHtml(html) {
     .trim();
 }
 
+/**
+ * Strip zero-width characters and their HTML entity equivalents
+ * (F-16). Mailers inject hundreds of these to defeat Gmail clipping
+ * and threading; they bloat token usage and confuse AI consumers
+ * without adding any signal. Removes:
+ *
+ *   - U+200B..U+200F (zero-width space, joiner, non-joiner, RTL/LTR
+ *     marks)
+ *   - U+FEFF (BOM)
+ *   - U+2060 (word joiner)
+ *   - HTML decimal entities: ​..‏, ⁠, 
+ *   - HTML named entities: ‍, ‌, ‎, ‏
+ */
+function stripZeroWidth(text) {
+  if (!text) return text;
+  return text
+    .replace(/[\u200B-\u200F\u2060\uFEFF]+/g, '')
+    .replace(/&#(8203|8204|8205|8206|8207|8288|65279);/g, '')
+    .replace(/&(zwj|zwnj|lrm|rlm);/g, '');
+}
+
 function escapeCSV(value) {
   if (value === null || value === undefined) return '';
   const str = String(value);
@@ -520,5 +546,6 @@ module.exports = {
   formatRecipients,
   truncateText,
   stripHtml,
+  stripZeroWidth,
   escapeCSV,
 };