@littlebearapps/outlook-assistant 3.12.1 → 3.14.0

package/server.js

@@ -0,0 +1,37 @@
+/**
+ * MCP server factory: builds the SDK Server for the tool registry.
+ *
+ * Kept apart from index.js (CLI flags, startup warnings, stdio transport) so
+ * protocol behaviour can be tested over an in-memory transport.
+ */
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const config = require('./config');
+const { createRequestHandler } = require('./request-handler');
+const { TOOLS } = require('./tools');
+const { serverInstructions } = require('./utils/server-instructions');
+
+/**
+ * @param {Array<object>} [tools] - tool definitions (default: the registry)
+ * @returns {Server}
+ */
+function createServer(tools = TOOLS) {
+  const server = new Server(
+    { name: config.SERVER_NAME, version: config.SERVER_VERSION },
+    {
+      // Spec shape: the tool list never changes at runtime. Nothing else
+      // (resources, prompts, logging) is declared, so those methods return
+      // -32601 rather than empty stubs. (#276)
+      capabilities: { tools: { listChanged: false } },
+      // Model-facing safety rules and usage tips, sent in the initialize
+      // result (#271).
+      instructions: serverInstructions({ readOnly: config.READ_ONLY }),
+    }
+  );
+
+  // Handle all requests. Dispatch + error-shaping logic lives in
+  // request-handler.js so it is unit-testable without starting the transport.
+  server.fallbackRequestHandler = createRequestHandler(tools);
+  return server;
+}
+
+module.exports = { createServer };

package/settings/index.js

@@ -6,6 +6,9 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { dryRunResult, dryRunUnsupported } = require('../utils/safety');
 
 // Days of the week for working hours
 const DAYS_OF_WEEK = [
@@ -91,6 +94,88 @@ function formatAutomaticReplies(settings) {
   return lines.join('\n');
 }
 
+/** Who gets the external reply, for each externalAudience value. */
+const EXTERNAL_AUDIENCE_LABELS = {
+  none: 'nobody',
+  contactsOnly: 'only senders in your contacts',
+  all: 'all external senders',
+};
+
+/** Longest stretch of a reply message quoted in a preview. */
+const REPLY_PREVIEW_CHARS = 100;
+
+/** "get a 25-character reply: "…"" (or no message) for a preview. */
+function describeReply(message, unchanged) {
+  const tag = unchanged ? ' (unchanged)' : '';
+  if (!message) return `— no reply message is set${tag}`;
+  const quoted =
+    message.length > REPLY_PREVIEW_CHARS
+      ? `${message.substring(0, REPLY_PREVIEW_CHARS)}…`
+      : message;
+  return `get a ${message.length}-character reply${tag}: "${quoted}"`;
+}
+
+/** "scheduled, from A to B (UTC)" */
+function describeSchedule(start, end) {
+  if (!start?.dateTime || !end?.dateTime) return 'scheduled';
+  return start.timeZone === end.timeZone
+    ? `scheduled, from ${start.dateTime} to ${end.dateTime} (${start.timeZone})`
+    : `scheduled, from ${start.dateTime} (${start.timeZone}) to ${end.dateTime} (${end.timeZone})`;
+}
+
+/**
+ * dryRun preview for set-auto-replies (#274): who would get an automatic
+ * reply, when, and how long each message is. Fields the call doesn't set
+ * keep their current values, so those are read first and marked unchanged.
+ * @param {object} changes - The automaticRepliesSetting the call would PATCH
+ * @param {object} current - The current automaticRepliesSetting
+ */
+function previewAutomaticReplies(changes, current) {
+  const effective = { ...current, ...changes };
+  const unchanged = (field) => !(field in changes);
+  const lines = [];
+
+  const status = effective.status;
+  const statusTag = unchanged('status') ? ' (unchanged)' : '';
+  if (status === 'disabled') {
+    lines.push(
+      `Status: off (disabled)${statusTag}. Nobody gets an automatic reply.`
+    );
+    return dryRunResult(lines, { settings: effective });
+  }
+  if (status === 'alwaysEnabled') {
+    lines.push(`Status: on now, with no end date (alwaysEnabled)${statusTag}.`);
+  } else {
+    lines.push(
+      `Status: ${describeSchedule(effective.scheduledStartDateTime, effective.scheduledEndDateTime)}${statusTag}.`
+    );
+  }
+
+  lines.push(
+    `Internal senders (your organisation): ${describeReply(effective.internalReplyMessage, unchanged('internalReplyMessage'))}`
+  );
+
+  const audience = effective.externalAudience;
+  const audienceTag = `externalAudience=${audience || 'unknown'}${unchanged('externalAudience') ? '; unchanged' : ''}`;
+  if (audience === 'none') {
+    lines.push(`External senders: nobody (${audienceTag}).`);
+  } else {
+    const who = EXTERNAL_AUDIENCE_LABELS[audience] || 'unknown audience';
+    lines.push(
+      `External senders: ${who} (${audienceTag}) ${describeReply(effective.externalReplyMessage, unchanged('externalReplyMessage'))}`
+    );
+  }
+
+  if (changes.status === 'alwaysEnabled') {
+    lines.push(
+      '',
+      'Note: Personal Outlook.com accounts only support scheduled replies, and Graph may leave them off. Pass `startDateTime` + `endDateTime` there instead.'
+    );
+  }
+
+  return dryRunResult(lines, { settings: effective });
+}
+
 /**
  * Get mailbox settings handler
  */
@@ -189,23 +274,9 @@ async function handleGetMailboxSettings(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error getting mailbox settings: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error getting mailbox settings: ${error.message}`);
   }
 }
 
@@ -220,6 +291,7 @@ async function handleSetAutomaticReplies(args) {
     internalReplyMessage,
     externalReplyMessage,
     externalAudience,
+    dryRun = false,
   } = args;
 
   try {
@@ -273,14 +345,9 @@ async function handleSetAutomaticReplies(args) {
     // External audience
     if (externalAudience) {
       if (!['none', 'contactsOnly', 'all'].includes(externalAudience)) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: "externalAudience must be 'none', 'contactsOnly', or 'all'.",
-            },
-          ],
-        };
+        return toolError(
+          "externalAudience must be 'none', 'contactsOnly', or 'all'."
+        );
       }
       settings.externalAudience = externalAudience;
     }
@@ -290,14 +357,20 @@ async function handleSetAutomaticReplies(args) {
     // 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`.',
-          },
-        ],
-      };
+      return toolError(
+        '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`.'
+      );
+    }
+
+    // dryRun: read the current setting to fill in what this call leaves
+    // alone, and say who would get a reply; change nothing.
+    if (dryRun) {
+      const current = await callGraphAPI(
+        accessToken,
+        'GET',
+        'me/mailboxSettings/automaticRepliesSetting'
+      );
+      return previewAutomaticReplies(settings, current || {});
     }
 
     // Apply settings
@@ -377,23 +450,9 @@ async function handleSetAutomaticReplies(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error setting automatic replies: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error setting automatic replies: ${error.message}`);
   }
 }
 
@@ -405,37 +464,22 @@ async function handleSetWorkingHours(args) {
 
   // Validate inputs
   if (!startTime && !endTime && !daysOfWeek && !timeZone) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'At least one of startTime, endTime, daysOfWeek, or timeZone is required.',
-        },
-      ],
-    };
+    return toolError(
+      'At least one of startTime, endTime, daysOfWeek, or timeZone is required.'
+    );
   }
 
   // Validate time format (HH:MM or HH:MM:SS)
   const timeRegex = /^([01]?[0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$/;
   if (startTime && !timeRegex.test(startTime)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "startTime must be in HH:MM or HH:MM:SS format (e.g., '09:00' or '09:00:00').",
-        },
-      ],
-    };
+    return toolError(
+      "startTime must be in HH:MM or HH:MM:SS format (e.g., '09:00' or '09:00:00')."
+    );
   }
   if (endTime && !timeRegex.test(endTime)) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "endTime must be in HH:MM or HH:MM:SS format (e.g., '17:00' or '17:00:00').",
-        },
-      ],
-    };
+    return toolError(
+      "endTime must be in HH:MM or HH:MM:SS format (e.g., '17:00' or '17:00:00')."
+    );
   }
 
   // Validate days of week
@@ -444,14 +488,9 @@ async function handleSetWorkingHours(args) {
       (d) => !DAYS_OF_WEEK.includes(d.toLowerCase())
     );
     if (invalidDays.length > 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Invalid days: ${invalidDays.join(', ')}. Valid days: ${DAYS_OF_WEEK.join(', ')}`,
-          },
-        ],
-      };
+      return toolError(
+        `Invalid days: ${invalidDays.join(', ')}. Valid days: ${DAYS_OF_WEEK.join(', ')}`
+      );
     }
   }
 
@@ -506,23 +545,9 @@ async function handleSetWorkingHours(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error setting working hours: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error setting working hours: ${error.message}`);
   }
 }
 
@@ -548,23 +573,9 @@ async function handleGetAutomaticReplies() {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error getting automatic replies: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error getting automatic replies: ${error.message}`);
   }
 }
 
@@ -590,23 +601,9 @@ async function handleGetWorkingHours() {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error getting working hours: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error getting working hours: ${error.message}`);
   }
 }
 
@@ -615,13 +612,8 @@ const settingsTools = [
   {
     name: 'mailbox-settings',
     description:
-      'Read or update mailbox-level settings (idempotent — safe to retry; sets are PATCH-style and merge with existing state). action=`get` (default) returns settings — use `section` to filter (`language`, `timeZone`, `workingHours`, `automaticRepliesSetting`, or `all`). action=`set-auto-replies` configures out-of-office: `enabled` true/false, optional `startDateTime`/`endDateTime` (ISO 8601) for scheduled mode, `internalReplyMessage` and (optionally) `externalReplyMessage`. action=`set-working-hours` updates the schedule: `startTime`/`endTime` (HH:MM) and `daysOfWeek` (array of `monday`..`sunday`). Returns the updated settings object on set actions.',
-    annotations: {
-      title: 'Mailbox Settings',
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-    },
+      'Read or update mailbox-level settings (idempotent — safe to retry; sets are PATCH-style and merge with existing state). action=`get` (default) returns settings — use `section` to filter (`language`, `timeZone`, `workingHours`, `automaticRepliesSetting`, or `all`). action=`set-auto-replies` configures out-of-office: `enabled` true/false, optional `startDateTime`/`endDateTime` (ISO 8601) for scheduled mode, `internalReplyMessage` and (optionally) `externalReplyMessage` and `externalAudience` (none/contactsOnly/all); pass `dryRun: true` to preview who would get replies without changing anything. action=`set-working-hours` updates the schedule: `startTime`/`endTime` (HH:MM) and `daysOfWeek` (array of `monday`..`sunday`). Returns the updated settings object on set actions.',
+    ...toolMetadata('mailbox-settings', 'Mailbox Settings'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -674,6 +666,11 @@ const settingsTools = [
           enum: ['none', 'contactsOnly', 'all'],
           description: 'Who receives external reply (action=set-auto-replies)',
         },
+        dryRun: {
+          type: 'boolean',
+          description:
+            'Preview only (action=set-auto-replies): nothing is changed. Shows who would get automatic replies, the schedule and each message length. Other actions refuse dryRun and change nothing. Default false.',
+        },
         // set-working-hours params
         startTime: {
           type: 'string',
@@ -705,6 +702,13 @@ const settingsTools = [
     },
     handler: async (args) => {
       const action = args.action || 'get';
+      if (args.dryRun && action !== 'set-auto-replies') {
+        return dryRunUnsupported(
+          'mailbox-settings',
+          action,
+          'set-auto-replies'
+        );
+      }
       switch (action) {
         case 'set-auto-replies':
           return handleSetAutomaticReplies(args);
@@ -713,14 +717,9 @@ const settingsTools = [
         case 'get':
           return handleGetMailboxSettings(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: get, set-auto-replies, set-working-hours.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: get, set-auto-replies, set-working-hours.`
+          );
       }
     },
   },

package/tools.js

@@ -0,0 +1,30 @@
+/**
+ * Tool registry: every tool the server exposes, in listing order.
+ *
+ * Kept separate from index.js so tests can load the real tool list without
+ * starting the stdio transport. Add a new module's tools here (and classify
+ * them in utils/risk-classes.js).
+ */
+const { authTools } = require('./auth');
+const { calendarTools } = require('./calendar');
+const { emailTools } = require('./email');
+const { folderTools } = require('./folder');
+const { rulesTools } = require('./rules');
+const { contactsTools } = require('./contacts');
+const { categoriesTools } = require('./categories');
+const { settingsTools } = require('./settings');
+const { advancedTools } = require('./advanced');
+
+const TOOLS = [
+  ...authTools,
+  ...calendarTools,
+  ...emailTools,
+  ...folderTools,
+  ...rulesTools,
+  ...contactsTools,
+  ...categoriesTools,
+  ...settingsTools,
+  ...advancedTools,
+];
+
+module.exports = { TOOLS };

package/utils/field-presets.js

@@ -5,6 +5,8 @@
  * and reduce response size/token usage.
  */
 
+const { log } = require('./logger');
+
 /**
  * Field presets for different use cases
  */
@@ -255,7 +257,7 @@ const FOLDER_FIELDS = {
 function getEmailFields(preset = 'list') {
   const fields = FIELD_PRESETS[preset];
   if (!fields) {
-    console.error(`Unknown preset: ${preset}, falling back to 'list'`);
+    log.debug(`Unknown preset: ${preset}, falling back to 'list'`);
     return FIELD_PRESETS.list.join(',');
   }
   return fields.join(',');
@@ -269,7 +271,7 @@ function getEmailFields(preset = 'list') {
 function getFolderFields(preset = 'basic') {
   const fields = FOLDER_FIELDS[preset];
   if (!fields) {
-    console.error(`Unknown folder preset: ${preset}, falling back to 'basic'`);
+    log.debug(`Unknown folder preset: ${preset}, falling back to 'basic'`);
     return FOLDER_FIELDS.basic.join(',');
   }
   return fields.join(',');

package/utils/graph-api.js

@@ -4,6 +4,7 @@
 const https = require('https');
 const config = require('../config');
 const mockData = require('./mock-data');
+const { log, graphPathShape } = require('./logger');
 
 /**
  * Guard for caller-supplied full URLs (nextLink/deltaLink continuations).
@@ -270,7 +271,7 @@ function sleep(ms) {
  *   final response (2xx, or the last non-retried error status)
  * @throws {Error} The network error of the final attempt
  */
-async function requestWithRetry(request) {
+async function sendWithRetry(request) {
   const method = String(request.method).toUpperCase();
   const timeoutMs = request.timeoutMs || config.REQUEST_TIMEOUT_MS;
   let networkRetryUsed = false;
@@ -316,7 +317,8 @@ async function requestWithRetry(request) {
       }
     }
 
-    console.error(
+    log.increment('graphRetries');
+    log.debug(
       `[GRAPH-API] ${method} ${networkError ? networkError.code : response.status}; ` +
         `retry ${retry + 1}/${MAX_RETRIES} in ${delayMs} ms`
     );
@@ -325,6 +327,36 @@ async function requestWithRetry(request) {
   }
 }
 
+/**
+ * sendWithRetry, noting a final failure on the current tool call's log line
+ * as status (or network error code), method and a PII-free path shape (#278).
+ * @param {object} request - See sendWithRetry
+ * @returns {Promise<{status: number, headers: object, text: string}>}
+ */
+async function requestWithRetry(request) {
+  const method = String(request.method).toUpperCase();
+  try {
+    const response = await sendWithRetry(request);
+    if (response.status >= 400) {
+      log.note(
+        'graph',
+        `${response.status} ${method} ${graphPathShape(request.url)}`
+      );
+      log.debug(
+        `[GRAPH-API] ${method} ${request.url} failed with ${response.status}: ${response.text}`
+      );
+    }
+    return response;
+  } catch (error) {
+    log.note(
+      'graph',
+      `${error.code || 'network-error'} ${method} ${graphPathShape(request.url)}`
+    );
+    log.debug(`[GRAPH-API] ${method} ${request.url} failed:`, error);
+    throw error;
+  }
+}
+
 /**
  * Makes a request to the Microsoft Graph API
  * In test mode (USE_TEST_MODE=true), routes to mock data instead of the real API.
@@ -357,7 +389,7 @@ async function callGraphAPI(
   try {
     finalUrl = buildGraphUrl(path, queryParams);
   } catch (error) {
-    console.error('Error calling Graph API:', error);
+    log.debug('Error calling Graph API:', error);
     throw error;
   }
 
@@ -422,12 +454,18 @@ async function callGraphAPI(
 
 /**
  * Calls Graph API with pagination support to retrieve all results up to maxCount
+ *
+ * Reports truncation (#279): `hasMore` is true when it stopped with more
+ * available (at maxCount with items trimmed or a further page, or because
+ * Graph repeated a nextLink). `@odata.count` is set only when every item was
+ * returned, so a page size is never presented as a total. `@odata.nextLink`
+ * is kept only when it continues exactly after the returned items.
  * @param {string} accessToken - The access token for authentication
  * @param {string} method - HTTP method (GET only for pagination)
  * @param {string} path - API endpoint path
  * @param {object} queryParams - Initial query parameters
  * @param {number} maxCount - Maximum number of items to retrieve (0 = all)
- * @returns {Promise<object>} - Combined API response with all items
+ * @returns {Promise<{value: Array<object>, hasMore: boolean, '@odata.count'?: number, '@odata.nextLink'?: string}>}
  * @throws {Error} If method is not 'GET'
  * @throws {Error} If any page request fails for any other reason
  */
@@ -443,13 +481,14 @@ async function callGraphAPIPaginated(
   }
 
   const allItems = [];
-  let nextLink;
+  const seenLinks = new Set();
   let currentUrl = path;
   let currentParams = { ...queryParams };
+  let nextLink;
+  let hasMore = false;
 
   try {
-    do {
-      // Make API call
+    for (;;) {
       const response = await callGraphAPI(
         accessToken,
         method,
@@ -458,35 +497,39 @@ async function callGraphAPIPaginated(
         currentParams
       );
 
-      // Add items from this page
       if (response.value && Array.isArray(response.value)) {
         allItems.push(...response.value);
       }
+      nextLink = response['@odata.nextLink'];
 
-      // Check if we've reached the desired count
+      // Stop at the desired count; more remain if items were trimmed or
+      // there is another page.
       if (maxCount > 0 && allItems.length >= maxCount) {
+        hasMore = allItems.length > maxCount || Boolean(nextLink);
+        if (allItems.length > maxCount) nextLink = undefined;
         break;
       }
-
-      // Get next page URL
-      nextLink = response['@odata.nextLink'];
-
-      if (nextLink) {
-        // Pass the full nextLink URL directly to callGraphAPI
-        currentUrl = nextLink;
-        currentParams = {}; // nextLink already contains all params
+      if (!nextLink) break;
+      // A repeated link would loop forever; stop and say there is more.
+      if (seenLinks.has(nextLink)) {
+        hasMore = true;
+        nextLink = undefined;
+        break;
       }
-    } while (nextLink);
+      seenLinks.add(nextLink);
+      currentUrl = nextLink; // the full nextLink URL carries every param
+      currentParams = {};
+    }
 
-    // Trim to exact count if needed
     const finalItems = maxCount > 0 ? allItems.slice(0, maxCount) : allItems;
-
     return {
       value: finalItems,
-      '@odata.count': finalItems.length,
+      hasMore,
+      ...(!hasMore && { '@odata.count': finalItems.length }),
+      ...(hasMore && nextLink && { '@odata.nextLink': nextLink }),
     };
   } catch (error) {
-    console.error('Error during pagination:', error);
+    log.debug('Error during pagination:', error);
     throw error;
   }
 }