@littlebearapps/outlook-assistant 3.7.1 → 3.7.4

package/email/index.js

@@ -137,6 +137,7 @@ const emailTools = [
             'Include email headers for each message (conversationId only)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -223,6 +224,7 @@ const emailTools = [
             'Return raw JSON instead of Markdown (headersMode only, default: false)',
         },
       },
+      additionalProperties: false,
       required: ['id'],
     },
     handler: async (args) => {
@@ -286,6 +288,7 @@ const emailTools = [
             'Check recipients for out-of-office, mailbox full, delivery restrictions before sending (default: false). Combine with dryRun=true for pre-send review.',
         },
       },
+      additionalProperties: false,
       required: ['to', 'subject', 'body'],
     },
     handler: handleSendEmail,
@@ -364,6 +367,7 @@ const emailTools = [
             'Check recipients for out-of-office, delivery restrictions before saving (action=create, default: false)',
         },
       },
+      additionalProperties: false,
       required: ['action'],
     },
     handler: handleDraft,
@@ -408,6 +412,7 @@ const emailTools = [
           description: 'Start date/time for follow-up, ISO 8601 (action=flag)',
         },
       },
+      additionalProperties: false,
       required: ['action'],
     },
     handler: async (args) => {
@@ -473,12 +478,18 @@ const emailTools = [
           type: 'string',
           description: 'Attachment ID (action=view/download, required)',
         },
+        outputDir: {
+          type: 'string',
+          description:
+            'Directory to save file (action=download, default: system tmpdir). Auto-created if missing.',
+        },
         savePath: {
           type: 'string',
           description:
-            'Directory to save file (action=download, default: current directory)',
+            'DEPRECATED alias for `outputDir`. Will be removed in v3.8.0.',
         },
       },
+      additionalProperties: false,
       required: ['messageId'],
     },
     handler: async (args) => {
@@ -489,8 +500,16 @@ const emailTools = [
         case 'download':
           return handleDownloadAttachment(args);
         case 'list':
-        default:
           return handleListAttachments(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, view, download.`,
+              },
+            ],
+          };
       }
     },
   },
@@ -521,7 +540,7 @@ const emailTools = [
           type: 'string',
           enum: ['mime', 'eml', 'markdown', 'json', 'mbox', 'html', 'csv'],
           description:
-            'Export format (target=message: mime/eml/markdown/json/csv, target=conversation: eml/mbox/markdown/json/html/csv)',
+            'Export format. Valid values vary by target: target=message accepts mime/eml/markdown/json/csv (mbox and html are conversation-only). target=conversation accepts eml/mbox/markdown/json/html/csv. target=messages (batch) accepts markdown/json/csv. mime is an alias for eml (same RFC822 bytes, .eml extension on disk).',
         },
         savePath: {
           type: 'string',
@@ -551,6 +570,11 @@ const emailTools = [
           description:
             'Search query to find emails (target=messages, alternative to emailIds)',
         },
+        query: {
+          type: 'string',
+          description:
+            'Free-text search shortcut (target=messages). Equivalent to passing searchQuery: { subject: <query> }. Convenience alias for callers used to search-emails.',
+        },
         outputDir: {
           type: 'string',
           description:
@@ -581,6 +605,7 @@ const emailTools = [
           description: 'Max content size in bytes (target=mime, default: 1MB)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -593,8 +618,16 @@ const emailTools = [
         case 'mime':
           return handleGetMimeContent(args);
         case 'message':
-        default:
           return handleExportEmail(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown export target '${target}'. Valid targets: message, messages, conversation, mime.`,
+              },
+            ],
+          };
       }
     },
   },
@@ -630,6 +663,7 @@ const emailTools = [
             'Comma-separated tip types to request (default: all). Options: automaticReplies, mailboxFullStatus, customMailTip, externalMemberCount, totalMemberCount, maxMessageSize, deliveryRestriction, moderationStatus, recipientScope, recipientSuggestions',
         },
       },
+      additionalProperties: false,
       required: ['recipients'],
     },
     handler: handleGetMailTips,

package/email/list.js

@@ -44,7 +44,12 @@ function getFieldPresetForVerbosity(verbosity) {
  */
 async function handleListEmails(args) {
   const folder = args.folder || 'inbox';
-  const requestedCount = args.count || DEFAULT_LIMITS.listEmails; // Default 25 (was 10)
+  // F-17: accept `maxResults` as an alias for `count` here too. The
+  // search-mode handler already does this; list-mode used `args.count`
+  // only, so callers passing `maxResults=5` to a non-search list call
+  // saw their override silently ignored.
+  const requestedCount =
+    args.count ?? args.maxResults ?? DEFAULT_LIMITS.listEmails;
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
 
   try {

package/email/mail-tips.js

@@ -203,7 +203,7 @@ async function handleGetMailTips(args) {
         content: [
           {
             type: 'text',
-            text: 'No mail tips returned for the specified recipients.',
+            text: 'No mail tips returned. Mail Tips is M365-only — personal Outlook.com accounts return empty responses, so recipient validation is unavailable on this account.',
           },
         ],
       };
@@ -211,15 +211,39 @@ async function handleGetMailTips(args) {
 
     const { formatted, warningCount } = formatMailTips(mailTips);
 
+    // F-23: Detect a "fully empty" tips response — every recipient
+    // returned with no actionable fields. Personal Outlook.com
+    // accounts surface this as a successful empty response rather
+    // than a feature-unsupported error, leading to false confidence
+    // when callers see "No issues detected".
+    const allEmpty = mailTips.every((tip) => {
+      const hasContent =
+        tip.recipientNotFound ||
+        tip.mailboxFull ||
+        tip.deliveryRestricted ||
+        tip.isModerated ||
+        tip.automaticReplies?.message ||
+        tip.maxMessageSize ||
+        tip.totalMemberCount ||
+        tip.customMailTip;
+      return !hasContent;
+    });
+
     let header = `# Mail Tips\n\n`;
     header += `**Recipients checked**: ${mailTips.length}\n`;
-    header += `**Warnings**: ${warningCount}\n\n`;
+    header += `**Warnings**: ${warningCount}\n`;
+    if (allEmpty && warningCount === 0) {
+      header +=
+        '\n**Note**: Graph returned no actionable mail tips for any recipient. This usually means Mail Tips is not supported on the connected account (M365-only feature) — "No issues detected" below means "no warnings flagged by Graph", NOT "validated as deliverable".\n';
+    }
+    header += '\n';
 
     return {
       content: [{ type: 'text', text: header + formatted }],
       _meta: {
         recipientCount: mailTips.length,
         warningCount,
+        allEmpty,
       },
     };
   } catch (error) {

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.1",
+  "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';