@littlebearapps/outlook-assistant 3.7.2 → 3.7.4

package/contacts/index.js

@@ -76,13 +76,10 @@ function formatContact(contact, verbosity = 'standard') {
       lines.push(`**Phone**: ${phones.join(' | ')}`);
     }
 
-    // Company info
-    if (contact.companyName || contact.jobTitle) {
-      const company = [contact.jobTitle, contact.companyName]
-        .filter(Boolean)
-        .join(' at ');
-      lines.push(`**Company**: ${company}`);
-    }
+    // Job title and company info — F-40: previously squashed into a
+    // single 'Company' label which mislabeled jobTitle-only contacts.
+    if (contact.jobTitle) lines.push(`**Job Title**: ${contact.jobTitle}`);
+    if (contact.companyName) lines.push(`**Company**: ${contact.companyName}`);
   }
 
   // Full verbosity extras
@@ -130,6 +127,8 @@ async function handleListContacts(args) {
   const verbosity = args.outputVerbosity || 'standard';
   const folder = args.folder || null; // null = default contacts folder
 
+  const skip = args.skip || 0;
+
   try {
     const accessToken = await ensureAuthenticated();
 
@@ -142,7 +141,9 @@ async function handleListContacts(args) {
       $select: fields.join(','),
       $top: count,
       $orderby: 'displayName',
+      $count: 'true', // Surface true total so callers know if more pages exist
     };
+    if (skip > 0) queryParams.$skip = skip;
 
     const response = await callGraphAPI(
       accessToken,
@@ -152,10 +153,29 @@ async function handleListContacts(args) {
       queryParams
     );
     const contacts = response.value || [];
+    const totalAvailable = response['@odata.count'];
+    const hasMore = Boolean(response['@odata.nextLink']);
 
     const output = [];
     output.push(`# Contacts\n`);
-    output.push(`**Total**: ${contacts.length}`);
+    if (typeof totalAvailable === 'number') {
+      output.push(
+        `**Showing**: ${contacts.length} of ${totalAvailable}${skip > 0 ? ` (offset ${skip})` : ''}`
+      );
+    } else {
+      output.push(`**Showing**: ${contacts.length}`);
+    }
+    // F-22: surface pagination cue when more results exist so callers
+    // know to ask for the next page instead of assuming "Total: 50"
+    // is the entire address book.
+    if (
+      hasMore ||
+      (totalAvailable && contacts.length + skip < totalAvailable)
+    ) {
+      output.push(
+        `**More available**: pass \`skip: ${skip + contacts.length}\` to fetch the next page (or \`count\` to raise the page size up to 100).`
+      );
+    }
     output.push('');
 
     contacts.forEach((contact) => {
@@ -164,7 +184,13 @@ async function handleListContacts(args) {
 
     return {
       content: [{ type: 'text', text: output.join('\n') }],
-      _meta: { count: contacts.length },
+      _meta: {
+        count: contacts.length,
+        ...(typeof totalAvailable === 'number' && {
+          totalAvailable,
+        }),
+        hasMore,
+      },
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
@@ -340,13 +366,32 @@ async function handleGetContact(args) {
  * Create contact handler
  */
 async function handleCreateContact(args) {
-  const { displayName, email, mobilePhone, companyName, jobTitle, notes } =
-    args;
-
-  if (!displayName && !email) {
+  const {
+    displayName,
+    firstName,
+    lastName,
+    email,
+    emails,
+    mobilePhone,
+    companyName,
+    jobTitle,
+    notes,
+  } = args;
+
+  // F-39: derive displayName from firstName/lastName if not provided.
+  const resolvedDisplayName =
+    displayName ||
+    [firstName, lastName].filter(Boolean).join(' ') ||
+    email ||
+    (Array.isArray(emails) && emails[0]);
+
+  if (!resolvedDisplayName && !email && !(emails && emails.length > 0)) {
     return {
       content: [
-        { type: 'text', text: 'At least displayName or email is required.' },
+        {
+          type: 'text',
+          text: 'At least displayName, firstName/lastName, email, or emails is required.',
+        },
       ],
     };
   }
@@ -356,24 +401,39 @@ async function handleCreateContact(args) {
 
     const contactData = {};
 
-    if (displayName) contactData.displayName = displayName;
-    if (email) {
-      contactData.emailAddresses = [
-        { address: email, name: displayName || email },
-      ];
+    if (resolvedDisplayName) contactData.displayName = resolvedDisplayName;
+
+    // F-39: prefer explicit givenName/surname when supplied; otherwise
+    // derive from displayName if it's a multi-word string.
+    if (firstName) contactData.givenName = firstName;
+    if (lastName) contactData.surname = lastName;
+    if (
+      !contactData.givenName &&
+      !contactData.surname &&
+      displayName &&
+      displayName.includes(' ')
+    ) {
+      const parts = displayName.split(' ');
+      contactData.givenName = parts[0];
+      contactData.surname = parts.slice(1).join(' ');
+    }
+
+    // Email: accept either `email` (single) or `emails` (array).
+    const allEmails = [];
+    if (email) allEmails.push(email);
+    if (Array.isArray(emails)) allEmails.push(...emails);
+    if (allEmails.length > 0) {
+      contactData.emailAddresses = allEmails.map((addr) => ({
+        address: addr,
+        name: resolvedDisplayName || addr,
+      }));
     }
+
     if (mobilePhone) contactData.mobilePhone = mobilePhone;
     if (companyName) contactData.companyName = companyName;
     if (jobTitle) contactData.jobTitle = jobTitle;
     if (notes) contactData.personalNotes = notes;
 
-    // Parse name into given/surname if provided
-    if (displayName && displayName.includes(' ')) {
-      const parts = displayName.split(' ');
-      contactData.givenName = parts[0];
-      contactData.surname = parts.slice(1).join(' ');
-    }
-
     const contact = await callGraphAPI(
       accessToken,
       'POST',
@@ -640,6 +700,11 @@ const contactsTools = [
           description:
             'Number of results (action=list default: 50, action=search default: 25)',
         },
+        skip: {
+          type: 'integer',
+          description:
+            'Pagination offset for action=list (default: 0). Use the value suggested by the previous page response.',
+        },
         folder: {
           type: 'string',
           description: 'Contact folder ID (action=list)',
@@ -666,10 +731,26 @@ const contactsTools = [
           type: 'string',
           description: 'Full name (action=create/update)',
         },
+        firstName: {
+          type: 'string',
+          description:
+            'Given name (action=create/update). Maps to Graph `givenName`. If displayName not provided, will be combined with lastName.',
+        },
+        lastName: {
+          type: 'string',
+          description:
+            'Surname (action=create/update). Maps to Graph `surname`.',
+        },
         email: {
           type: 'string',
           description: 'Primary email address (action=create/update)',
         },
+        emails: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Multiple email addresses (action=create/update). First entry is primary.',
+        },
         mobilePhone: {
           type: 'string',
           description: 'Mobile phone number (action=create/update)',
@@ -687,6 +768,7 @@ const contactsTools = [
           description: 'Personal notes (action=create/update)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -703,8 +785,16 @@ const contactsTools = [
         case 'delete':
           return handleDeleteContact(args);
         case 'list':
-        default:
           return handleListContacts(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, search, get, create, update, delete.`,
+              },
+            ],
+          };
       }
     },
   },
@@ -729,6 +819,7 @@ const contactsTools = [
           description: 'Maximum results to return (default: 25, max: 50)',
         },
       },
+      additionalProperties: false,
       required: ['query'],
     },
     handler: handleSearchPeople,

package/email/attachments.js

@@ -4,6 +4,7 @@
  */
 const _https = require('https'); // Reserved for future use
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const _config = require('../config'); // Reserved for future use
 const { callGraphAPI } = require('../utils/graph-api');
@@ -110,7 +111,12 @@ async function handleListAttachments(args) {
  * @returns {object} - MCP response with download result
  */
 async function handleDownloadAttachment(args) {
-  const { messageId, attachmentId, savePath } = args;
+  // F-19: accept both `outputDir` (canonical) and `savePath` (legacy
+  // alias). Previously the silent-ignore-unknown-param behaviour
+  // dropped `outputDir` and fell through to cwd, polluting the source
+  // tree with downloaded files.
+  const { messageId, attachmentId } = args;
+  const savePath = args.outputDir || args.savePath;
 
   if (!messageId || !attachmentId) {
     return {
@@ -167,8 +173,12 @@ async function handleDownloadAttachment(args) {
         };
       }
 
-      // Determine save location
-      const outputDir = savePath || process.cwd();
+      // Determine save location. F-19: default to os.tmpdir() instead
+      // of cwd so attachments don't silently land in the source tree
+      // when the caller forgets to pass outputDir. Auto-create the
+      // target directory.
+      const outputDir = savePath || os.tmpdir();
+      fs.mkdirSync(outputDir, { recursive: true });
       const outputPath = path.join(outputDir, filename);
 
       // Decode base64 and save to file

package/email/conversations.js

@@ -372,7 +372,10 @@ async function handleGetConversation(args) {
 async function handleExportConversation(args) {
   const conversationId = args.conversationId;
   const format = (args.format || 'markdown').toLowerCase();
-  const outputDir = args.outputDir;
+  // F-29: default outputDir to os.tmpdir() to match target=message
+  // behaviour. Previously conversation export rejected calls without
+  // outputDir, inconsistent with the other export targets.
+  const outputDir = args.outputDir || require('os').tmpdir();
   const _includeAttachments = args.includeAttachments !== false;
   const order = args.order || 'chronological';
 
@@ -382,12 +385,6 @@ async function handleExportConversation(args) {
     };
   }
 
-  if (!outputDir) {
-    return {
-      content: [{ type: 'text', text: 'Output directory is required.' }],
-    };
-  }
-
   const validFormats = ['eml', 'mbox', 'markdown', 'json', 'html', 'csv'];
   if (!validFormats.includes(format)) {
     return {

package/email/delta.js

@@ -90,6 +90,11 @@ async function handleListEmailsDelta(args) {
     const isInitialSync = !deltaToken;
     const hasMoreChanges = Boolean(nextLink);
     const newDeltaToken = deltaLink || nextLink;
+    // F-15: nextLink is a continuation token (more pages of the same
+    // sync), not a delta token. The real delta token only emits once
+    // the initial sync finishes paging. Distinguish them in output so
+    // callers know what they're storing.
+    const tokenIsContinuation = !deltaLink && Boolean(nextLink);
 
     // Format output based on verbosity
     let resultText;
@@ -101,7 +106,10 @@ async function handleListEmailsDelta(args) {
       resultText += `| Type | ${isInitialSync ? 'Initial' : 'Incremental'} |\n`;
       resultText += `| More | ${hasMoreChanges ? 'Yes' : 'No'} |\n`;
       if (newDeltaToken) {
-        resultText += `\n**Delta Token** (save for next call):\n\`\`\`\n${newDeltaToken}\n\`\`\`\n`;
+        const label = tokenIsContinuation
+          ? 'Continuation Token (more pages — call again to keep paging)'
+          : 'Delta Token (save for next sync call)';
+        resultText += `\n**${label}**:\n\`\`\`\n${newDeltaToken}\n\`\`\`\n`;
       }
     } else {
       resultText = `## Delta Sync ${isInitialSync ? '(Initial)' : '(Incremental)'}\n\n`;
@@ -142,14 +150,19 @@ async function handleListEmailsDelta(args) {
 
       // Pagination info
       if (hasMoreChanges) {
-        resultText += `\n### More Changes Available\n`;
-        resultText += `Use the deltaToken below to fetch next page.\n`;
+        resultText += `\n### More Pages Available\n`;
+        resultText += `This page returned a continuation token. Call \`search-emails deltaMode=true deltaToken=<token>\` again to fetch the next page. The real delta token only emits once paging completes.\n`;
       }
 
-      // Delta token
+      // Token (delta or continuation)
       if (newDeltaToken) {
-        resultText += `\n### Delta Token\n`;
-        resultText += `**Save this token for next sync call:**\n\`\`\`\n${newDeltaToken}\n\`\`\`\n`;
+        if (tokenIsContinuation) {
+          resultText += `\n### Continuation Token\n`;
+          resultText += `**More pages remain. Pass this back to keep paging:**\n\`\`\`\n${newDeltaToken}\n\`\`\`\n`;
+        } else {
+          resultText += `\n### Delta Token\n`;
+          resultText += `**Save this token for next sync call:**\n\`\`\`\n${newDeltaToken}\n\`\`\`\n`;
+        }
       }
     }
 
@@ -167,6 +180,7 @@ async function handleListEmailsDelta(args) {
         hasMoreChanges: hasMoreChanges,
         changesSummary: changesSummary,
         deltaToken: newDeltaToken,
+        tokenType: tokenIsContinuation ? 'continuation' : 'delta',
       },
     };
   } catch (error) {

package/email/export.js

@@ -37,7 +37,10 @@ const EXPORT_FORMATS = {
 async function handleExportEmail(args) {
   const emailId = args.id;
   const format = (args.format || EXPORT_FORMATS.MARKDOWN).toLowerCase();
-  const savePath = args.savePath;
+  // F-27: accept `outputDir` (canonical) and `savePath` (legacy alias).
+  // Previously single-message exports ignored outputDir entirely and
+  // hardcoded os.tmpdir(), inconsistent with target=messages.
+  const savePath = args.outputDir || args.savePath;
   const includeAttachments = args.includeAttachments !== false;
 
   if (!emailId) {
@@ -116,17 +119,31 @@ async function handleExportEmail(args) {
     } else if (format === EXPORT_FORMATS.CSV) {
       // CSV export - email metadata
       content = formatEmailsAsCSV(email);
+    } else if (format === 'mbox' || format === 'html') {
+      // F-26: clarify that mbox/html are conversation-only formats so
+      // callers don't infer the format itself is unsupported.
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Format '${format}' is only supported for target=conversation. For target=message use one of: ${Object.values(EXPORT_FORMATS).join(', ')}.`,
+          },
+        ],
+      };
     } else {
       return {
         content: [
           {
             type: 'text',
-            text: `Unknown format: ${format}. Supported: ${Object.values(EXPORT_FORMATS).join(', ')}`,
+            text: `Unknown format: ${format}. Supported for target=message: ${Object.values(EXPORT_FORMATS).join(', ')}.`,
           },
         ],
       };
     }
 
+    // Auto-create the parent directory so callers don't have to pre-mkdir.
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+
     // Save main file
     fs.writeFileSync(finalPath, content, 'utf8');
 
@@ -207,7 +224,13 @@ async function handleExportEmail(args) {
  */
 async function handleBatchExportEmails(args) {
   const emailIds = args.emailIds || [];
-  const searchQuery = args.searchQuery || {};
+  // F-28: accept `query` as a top-level string alias for
+  // `searchQuery: { subject }`. Lets callers use the same `query`
+  // word they already know from search-emails.
+  const searchQuery = { ...(args.searchQuery || {}) };
+  if (args.query && !searchQuery.subject) {
+    searchQuery.subject = args.query;
+  }
   const format = (args.format || EXPORT_FORMATS.MARKDOWN).toLowerCase();
   const outputDir = args.outputDir;
   const includeAttachments = args.includeAttachments === true; // Default false for batch

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) {