@littlebearapps/outlook-assistant 3.7.1 → 3.7.4

package/categories/index.js

@@ -116,9 +116,9 @@ async function handleListCategories(args) {
       output.push('|----------|-------|-----|');
       categories.forEach((cat) => {
         const colorName = COLOR_NAMES[cat.color] || cat.color;
-        const idDisplay =
-          outputVerbosity === 'full' ? cat.id : `${cat.id.substring(0, 8)}...`;
-        output.push(`| ${cat.displayName} | ${colorName} | ${idDisplay} |`);
+        // F-9: emit full IDs at standard verbosity. Truncated IDs were
+        // unusable downstream (the ellipsis became part of the copy).
+        output.push(`| ${cat.displayName} | ${colorName} | ${cat.id} |`);
       });
     }
 
@@ -255,7 +255,9 @@ async function handleCreateCategory(args) {
  * Update category handler
  */
 async function handleUpdateCategory(args) {
-  const { id, displayName, color } = args;
+  // F-34: accept `categoryId` as a deprecated alias for `id`.
+  const id = args.id || args.categoryId;
+  const { displayName, color } = args;
 
   if (!id) {
     return {
@@ -298,34 +300,45 @@ async function handleUpdateCategory(args) {
     if (displayName) updateData.displayName = displayName;
     if (color) updateData.color = color;
 
-    const response = await callGraphAPI(
+    await callGraphAPI(
       accessToken,
       'PATCH',
       `me/outlook/masterCategories/${id}`,
       updateData
     );
 
-    // 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;
+    // F-35: Graph silently drops master-category color updates on
+    // some account types. Re-fetch the category and diff requested
+    // values against what Graph actually stored, so the caller
+    // doesn't get a misleading "Category updated!" when nothing
+    // changed.
+    const fresh = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/outlook/masterCategories/${id}`
+    );
 
-    const updatedCategory = {
-      ...response,
-      displayName: updatedName,
-      color: updatedColor,
-    };
+    const warnings = [];
+    if (color && fresh.color !== color) {
+      warnings.push(
+        `Requested color \`${color}\` but Graph stored \`${fresh.color}\` (master-category colors may be immutable on this account type).`
+      );
+    }
+    if (displayName && fresh.displayName !== displayName) {
+      warnings.push(
+        `Requested name \`${displayName}\` but Graph stored \`${fresh.displayName}\`.`
+      );
+    }
+
+    const colorName = COLOR_NAMES[fresh.color] || fresh.color;
+    let text = `Category updated!\n\n**Name**: ${fresh.displayName}\n**Color**: ${colorName} (${fresh.color})\n**ID**: ${fresh.id || id}`;
+    if (warnings.length > 0) {
+      text += `\n\n**⚠ Warning**:\n${warnings.map((w) => `- ${w}`).join('\n')}`;
+    }
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: `Category updated!\n\n**Name**: ${updatedName}\n**Color**: ${colorName} (${updatedColor})\n**ID**: ${response.id || id}`,
-        },
-      ],
-      _meta: {
-        category: formatCategory(updatedCategory),
-      },
+      content: [{ type: 'text', text }],
+      _meta: { category: formatCategory(fresh) },
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
@@ -353,7 +366,8 @@ async function handleUpdateCategory(args) {
  * Delete category handler
  */
 async function handleDeleteCategory(args) {
-  const { id } = args;
+  // F-34: accept `categoryId` as a deprecated alias for `id`.
+  const id = args.id || args.categoryId;
 
   if (!id) {
     return {
@@ -824,8 +838,9 @@ const categoriesTools = [
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'create', 'update', 'delete'],
-          description: 'Action to perform (default: list)',
+          enum: ['list', 'create', 'update', 'set', 'delete'],
+          description:
+            "Action to perform (default: list). 'set' is a deprecated alias for 'update'.",
         },
         // list params
         outputVerbosity: {
@@ -850,7 +865,12 @@ const categoriesTools = [
           type: 'string',
           description: 'Category ID (action=update/delete, required)',
         },
+        categoryId: {
+          type: 'string',
+          description: 'DEPRECATED: alias for `id`. Will be removed in v3.8.0.',
+        },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -858,13 +878,22 @@ const categoriesTools = [
       switch (action) {
         case 'create':
           return handleCreateCategory(args);
+        case 'set': // deprecated alias
         case 'update':
           return handleUpdateCategory(args);
         case 'delete':
           return handleDeleteCategory(args);
         case 'list':
-        default:
           return handleListCategories(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, create, update, delete.`,
+              },
+            ],
+          };
       }
     },
   },
@@ -901,6 +930,7 @@ const categoriesTools = [
             'set (replace all), add (append), remove (remove specific). Default: set',
         },
       },
+      additionalProperties: false,
       required: ['categories'],
     },
     handler: handleApplyCategory,
@@ -945,6 +975,7 @@ const categoriesTools = [
             'Where to put emails from this sender (action=set, default: focused)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -955,8 +986,16 @@ const categoriesTools = [
         case 'delete':
           return handleSetFocusedInboxOverride(args);
         case 'list':
-        default:
           return handleGetFocusedInboxOverrides(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, set, delete.`,
+              },
+            ],
+          };
       }
     },
   },

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