@littlebearapps/outlook-assistant 3.7.4 → 3.8.1

package/.env.example

@@ -28,3 +28,22 @@ USE_TEST_MODE=false
 # device-code: No auth server needed, works remotely/headless
 # browser: Traditional OAuth redirect via localhost:3333
 # OUTLOOK_AUTH_METHOD=device-code
+
+# Optional: OAuth audience — controls which Microsoft Identity Platform
+# endpoint is used. Must match the Azure app registration's "Supported
+# account types" setting:
+#   common         — personal AND work/school accounts (default; multi-tenant + personal apps)
+#   consumers      — personal Microsoft accounts only
+#   organizations  — work/school accounts only
+#   <tenant-guid>  — single-tenant
+# Example: OUTLOOK_AUTH_AUDIENCE=consumers   (for personal-account-only apps)
+# OUTLOOK_AUTH_AUDIENCE=common
+
+# Optional: Default timezone for calendar events when not explicitly
+# specified by the caller. Use any IANA timezone identifier.
+# Default: Australia/Melbourne
+# Examples:
+#   OUTLOOK_DEFAULT_TIMEZONE=Europe/London
+#   OUTLOOK_DEFAULT_TIMEZONE=America/New_York
+#   OUTLOOK_DEFAULT_TIMEZONE=Asia/Tokyo
+# OUTLOOK_DEFAULT_TIMEZONE=Australia/Melbourne

package/README.md

@@ -23,8 +23,8 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 
 <div align="center">
   <br />
-  <a href="docs/demo/outlook-assistant-demo.mp4">
-    <img src="docs/demo/outlook-assistant-demo.gif" alt="Outlook Assistant Demo — searching emails, reading, and drafting a reply" width="720" style="border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.12);" />
+  <a href="https://github.com/littlebearapps/outlook-assistant/blob/main/docs/demo/outlook-assistant-demo.mp4">
+    <img src="https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/demo/outlook-assistant-demo.gif" alt="Outlook Assistant Demo — searching emails, reading, and drafting a reply" width="720" style="border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.12);" />
   </a>
   <br />
   <sub>Search inbox → read &amp; summarise → draft a reply — all from the conversation</sub>
@@ -63,7 +63,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 | Module | Tools | What You Can Do |
 |--------|------:|-----------------|
 | **Email** | 8 | `search-emails` (list/search/delta/conversations), `read-email` (content + forensic headers), `send-email` (with dry-run + mail tips), `draft` (create/update/send/delete/reply/forward), `update-email` (read status, flags), `attachments`, `export`, `get-mail-tips` |
-| **Calendar** | 3 | `list-events`, `create-event`, `manage-event` (decline/cancel/delete) |
+| **Calendar** | 3 | `list-events`, `create-event`, `manage-event` (update/decline/cancel/delete) |
 | **Contacts** | 2 | `manage-contact` (list/search/get/create/update/delete), `search-people` |
 | **Categories** | 3 | `manage-category` (CRUD), `apply-category`, `manage-focused-inbox` |
 | **Settings** | 1 | `mailbox-settings` (get/set auto-replies/set working hours) |
@@ -336,6 +336,15 @@ USE_TEST_MODE=false
 
 > **Note:** The server also accepts `MS_CLIENT_ID` and `MS_CLIENT_SECRET` for backwards compatibility.
 
+**Optional overrides** (v3.8.0+) — see [`.env.example`](.env.example) for the full list with commented worked examples:
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `OUTLOOK_AUTH_AUDIENCE` | OAuth audience: `common`, `consumers` (personal-only Azure apps), `organizations`, or single-tenant GUID. Fixes `AADSTS9002331` for personal-only app registrations. | `common` |
+| `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone applied to calendar events when callers don't pass one (e.g. `Europe/London`, `America/New_York`). | `Australia/Melbourne` |
+| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on `send-email` + `draft send` per MCP server lifetime. | unlimited |
+| `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of domains/addresses for sends, drafts, and rule forwards. | unrestricted |
+
 ### MCP Client Configuration
 
 See [Quick Start — Configure Your MCP Client](#3-configure-your-mcp-client) above for Claude Desktop, Claude Code, Cursor, and Windsurf configs.

package/advanced/index.js

@@ -606,7 +606,8 @@ async function handleFindMeetingRooms(args) {
 const advancedTools = [
   {
     name: 'access-shared-mailbox',
-    description: 'Read emails from a shared mailbox you have access to',
+    description:
+      'List emails from a shared mailbox the signed-in user has been granted access to (read-only). Returns paged messages from the named `sharedMailbox` (or alias `email`) and `folder` (default `inbox`) with id/subject/from/receivedDateTime/preview — same shape as `search-emails` list mode. Requires that the shared mailbox has been delegated to the signed-in user in Exchange (admin-configured). Use `outputVerbosity` to control field count and `count` (default 25, max 50) for page size. For full search/filter capability over a shared mailbox, prefer `search-emails` with a folder path scoped to the shared mailbox.',
     annotations: {
       title: 'Shared Mailbox',
       readOnlyHint: true,
@@ -645,7 +646,8 @@ const advancedTools = [
   },
   {
     name: 'find-meeting-rooms',
-    description: 'Search for meeting rooms in your organisation',
+    description:
+      "Discover bookable meeting rooms in the user's organisation via the Graph rooms endpoint (read-only). Returns room resources with displayName, emailAddress, building, floor, capacity, and bookingType — suitable for piping into `create-event` as attendees. Filter by `query` (matches name/email), `building`, `floor`, or minimum `capacity`. Returns empty list on personal accounts (the rooms endpoint is M365-only). Use `outputVerbosity` to control field count.",
     annotations: {
       title: 'Meeting Rooms',
       readOnlyHint: true,

package/auth/tools.js

@@ -386,7 +386,7 @@ const authTools = [
   {
     name: 'auth',
     description:
-      'Manage authentication with Microsoft Graph API. action=status (default) checks auth state and refreshes tokens if needed, action=authenticate starts OAuth flow (device-code by default — no auth server needed), action=device-code-complete finishes device code auth after user enters code, action=about shows server info.',
+      'Manage authentication with the Microsoft Graph API. action=`status` (default) returns the current auth state and auto-refreshes the access token if it\'s expired but the refresh token is still valid (~90-day window) — call this first to check before other tools. action=`authenticate` starts the OAuth flow: with `method: "device-code"` (default, works headlessly) it returns a code + URL for the user to visit; with `method: "browser"` it opens the local auth server on :3333 (run `npm run auth-server` first). Pass `force: true` to re-authenticate over an existing valid session. action=`device-code-complete` finishes device-code auth after the user enters the code in their browser — call this once authentication shows as successful in the browser. action=`about` returns server version, configured audience, scope list, and other diagnostic info. Tokens persist to `~/.outlook-assistant-tokens.json` and survive server restarts.',
     annotations: {
       title: 'Authentication',
       readOnlyHint: false,

package/calendar/index.js

@@ -6,12 +6,14 @@ const handleDeclineEvent = require('./decline');
 const handleCreateEvent = require('./create');
 const handleCancelEvent = require('./cancel');
 const handleDeleteEvent = require('./delete');
+const handleUpdateEvent = require('./update');
 
 // Calendar tool definitions (consolidated: 5 → 3)
 const calendarTools = [
   {
     name: 'list-events',
-    description: 'Lists upcoming events from your calendar',
+    description:
+      'List upcoming calendar events for the signed-in user (read-only). Returns an array of events with id, subject, start/end, attendees, location, organiser, and webLink. Use `count` (default 10, max 50) to control page size; this tool does not filter — use the Outlook UI or specific date ranges via Graph for filtered queries. Times are returned in the configured timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`).',
     annotations: {
       title: 'List Calendar Events',
       readOnlyHint: true,
@@ -32,7 +34,8 @@ const calendarTools = [
   },
   {
     name: 'create-event',
-    description: 'Creates a new calendar event',
+    description:
+      "Create a new calendar event on the signed-in user's default calendar. Returns the created event with its `id`, `webLink`, and (if attendees are present) an auto-generated online-meeting URL — attendees receive invitations on save. Times use the configured timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`); omit the `Z` suffix to send local time. Use `manage-event` action=`update` to modify an event after creation, or `manage-event` action=`cancel`/`delete` to remove it.",
     annotations: {
       title: 'Create Calendar Event',
       readOnlyHint: false,
@@ -74,7 +77,7 @@ const calendarTools = [
   {
     name: 'manage-event',
     description:
-      'Manage an existing calendar event. action=decline declines an invitation. action=cancel cancels an event you organised. action=delete permanently removes an event.',
+      "Manage an existing calendar event (destructive: covers update/decline/cancel/delete — use dryRun where supported to preview). action=`update` edits fields in place via PATCH (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart) — only fields you pass are changed; pass `dryRun: true` to preview the PATCH payload. action=`decline` declines an invitation (optional `comment`). action=`cancel` cancels an event you organised and notifies attendees. action=`delete` permanently removes the event. Returns the updated event on update; status confirmation otherwise. Note: there is no `accept` action — accept invitations in the Outlook UI (Graph's accept verb is unreliable across personal/M365).",
     annotations: {
       title: 'Manage Calendar Event',
       readOnlyHint: false,
@@ -86,7 +89,7 @@ const calendarTools = [
       properties: {
         action: {
           type: 'string',
-          enum: ['decline', 'cancel', 'delete'],
+          enum: ['update', 'decline', 'cancel', 'delete'],
           description: 'Action to perform (required)',
         },
         eventId: {
@@ -102,6 +105,98 @@ const calendarTools = [
           type: 'string',
           description: 'Optional comment for declining or cancelling the event',
         },
+        subject: {
+          type: 'string',
+          description: 'New subject (action=update only)',
+        },
+        start: {
+          oneOf: [
+            { type: 'string' },
+            {
+              type: 'object',
+              properties: {
+                dateTime: { type: 'string' },
+                timeZone: { type: 'string' },
+              },
+              required: ['dateTime'],
+              additionalProperties: false,
+            },
+          ],
+          description:
+            'New start time as ISO 8601 string or {dateTime, timeZone} object (action=update only)',
+        },
+        end: {
+          oneOf: [
+            { type: 'string' },
+            {
+              type: 'object',
+              properties: {
+                dateTime: { type: 'string' },
+                timeZone: { type: 'string' },
+              },
+              required: ['dateTime'],
+              additionalProperties: false,
+            },
+          ],
+          description:
+            'New end time as ISO 8601 string or {dateTime, timeZone} object (action=update only)',
+        },
+        attendees: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Full replacement attendee list — pass complete desired list, or [] to clear (action=update only)',
+        },
+        body: {
+          type: 'string',
+          description: 'New body content (action=update only)',
+        },
+        location: {
+          type: 'string',
+          description: 'New location display name (action=update only)',
+        },
+        isOnlineMeeting: {
+          type: 'boolean',
+          description: 'Toggle online meeting flag (action=update only)',
+        },
+        sensitivity: {
+          type: 'string',
+          enum: ['normal', 'personal', 'private', 'confidential'],
+          description: 'Event sensitivity classification (action=update only)',
+        },
+        showAs: {
+          type: 'string',
+          enum: [
+            'free',
+            'tentative',
+            'busy',
+            'oof',
+            'workingElsewhere',
+            'unknown',
+          ],
+          description: 'Free/busy status shown to others (action=update only)',
+        },
+        importance: {
+          type: 'string',
+          enum: ['low', 'normal', 'high'],
+          description: 'Event importance flag (action=update only)',
+        },
+        categories: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Full replacement category list — pass [] to clear (action=update only)',
+        },
+        reminderMinutesBeforeStart: {
+          type: 'number',
+          description:
+            'Minutes before start to fire the reminder (action=update only)',
+        },
+        dryRun: {
+          type: 'boolean',
+          description:
+            'Preview the PATCH without applying it (action=update only). Returns the body that would be sent to Graph.',
+        },
       },
       additionalProperties: false,
       required: ['action'],
@@ -126,6 +221,8 @@ const calendarTools = [
       }
       args = normalised;
       switch (args.action) {
+        case 'update':
+          return handleUpdateEvent(args);
         case 'decline':
           return handleDeclineEvent(args);
         case 'cancel':
@@ -137,7 +234,7 @@ const calendarTools = [
             content: [
               {
                 type: 'text',
-                text: "Invalid action. Use 'decline', 'cancel', or 'delete'.",
+                text: "Invalid action. Use 'update', 'decline', 'cancel', or 'delete'.",
               },
             ],
           };
@@ -153,4 +250,5 @@ module.exports = {
   handleCreateEvent,
   handleCancelEvent,
   handleDeleteEvent,
+  handleUpdateEvent,
 };

package/calendar/update.js

@@ -0,0 +1,287 @@
+/**
+ * Update event functionality.
+ *
+ * Wraps the Microsoft Graph PATCH /me/events/{id} endpoint. Sends only
+ * the fields the caller provides — anything left out is preserved
+ * server-side. Useful for re-scheduling, adding/removing attendees,
+ * editing the body, or tweaking metadata without rebuilding the event
+ * from scratch (which loses RSVP state).
+ *
+ * Supports the following Graph event properties:
+ *   - subject
+ *   - start          (ISO string or {dateTime, timeZone} object)
+ *   - end            (same shape as start)
+ *   - attendees      (full replacement list of emails)
+ *   - body           (sent as HTML)
+ *   - location       (displayName)
+ *   - isOnlineMeeting
+ *   - sensitivity    (normal | personal | private | confidential)
+ *   - showAs         (free | tentative | busy | oof | workingElsewhere | unknown)
+ *   - importance     (low | normal | high)
+ *   - categories     (full replacement array of category names)
+ *   - reminderMinutesBeforeStart
+ *
+ * `dryRun: true` returns a preview of the PATCH payload without calling
+ * Graph — useful for confirming behaviour before mutating real data.
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+const { DEFAULT_TIMEZONE } = require('../config');
+
+const SENSITIVITY_VALUES = new Set([
+  'normal',
+  'personal',
+  'private',
+  'confidential',
+]);
+const SHOW_AS_VALUES = new Set([
+  'free',
+  'tentative',
+  'busy',
+  'oof',
+  'workingElsewhere',
+  'unknown',
+]);
+const IMPORTANCE_VALUES = new Set(['low', 'normal', 'high']);
+
+/**
+ * Update event handler
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleUpdateEvent(args) {
+  const {
+    eventId,
+    subject,
+    start,
+    end,
+    attendees,
+    body,
+    location,
+    isOnlineMeeting,
+    sensitivity,
+    showAs,
+    importance,
+    categories,
+    reminderMinutesBeforeStart,
+    dryRun = false,
+  } = args;
+
+  if (!eventId) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Event ID is required to update an event.',
+        },
+      ],
+    };
+  }
+
+  // Build the patch body from only the fields the caller actually provided.
+  // Graph treats absent properties as "no change", so we never overwrite
+  // something the user didn't intend to touch.
+  const patch = {};
+
+  if (subject !== undefined) patch.subject = subject;
+
+  if (start !== undefined) {
+    patch.start = {
+      dateTime: start.dateTime || start,
+      timeZone: start.timeZone || DEFAULT_TIMEZONE,
+    };
+  }
+
+  if (end !== undefined) {
+    patch.end = {
+      dateTime: end.dateTime || end,
+      timeZone: end.timeZone || DEFAULT_TIMEZONE,
+    };
+  }
+
+  if (attendees !== undefined) {
+    // Replaces the full attendee list — Graph PATCH on this property is
+    // not additive. Caller must pass the desired complete list.
+    patch.attendees = (attendees || []).map((email) => ({
+      emailAddress: { address: email },
+      type: 'required',
+    }));
+  }
+
+  if (body !== undefined) {
+    patch.body = { contentType: 'HTML', content: body };
+  }
+
+  if (location !== undefined) {
+    patch.location = { displayName: location };
+  }
+
+  if (isOnlineMeeting !== undefined) {
+    patch.isOnlineMeeting = Boolean(isOnlineMeeting);
+  }
+
+  if (sensitivity !== undefined) {
+    if (!SENSITIVITY_VALUES.has(sensitivity)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid sensitivity: '${sensitivity}'. Must be one of: ${[...SENSITIVITY_VALUES].join(', ')}.`,
+          },
+        ],
+      };
+    }
+    patch.sensitivity = sensitivity;
+  }
+
+  if (showAs !== undefined) {
+    if (!SHOW_AS_VALUES.has(showAs)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid showAs: '${showAs}'. Must be one of: ${[...SHOW_AS_VALUES].join(', ')}.`,
+          },
+        ],
+      };
+    }
+    patch.showAs = showAs;
+  }
+
+  if (importance !== undefined) {
+    if (!IMPORTANCE_VALUES.has(importance)) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid importance: '${importance}'. Must be one of: ${[...IMPORTANCE_VALUES].join(', ')}.`,
+          },
+        ],
+      };
+    }
+    patch.importance = importance;
+  }
+
+  if (categories !== undefined) {
+    // Full replacement, like attendees. Pass [] to clear all categories.
+    patch.categories = Array.isArray(categories) ? categories : [];
+  }
+
+  if (reminderMinutesBeforeStart !== undefined) {
+    const reminder = Number(reminderMinutesBeforeStart);
+    if (!Number.isFinite(reminder) || reminder < 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Invalid reminderMinutesBeforeStart: '${reminderMinutesBeforeStart}'. Must be a non-negative number.`,
+          },
+        ],
+      };
+    }
+    patch.reminderMinutesBeforeStart = reminder;
+  }
+
+  if (Object.keys(patch).length === 0) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'No fields to update — provide at least one updatable field (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart).',
+        },
+      ],
+    };
+  }
+
+  // dryRun: don't touch Graph; just show the caller what would be sent.
+  if (dryRun) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: [
+            `**Dry run** — would PATCH \`me/events/${eventId}\` with:`,
+            '',
+            '```json',
+            JSON.stringify(patch, null, 2),
+            '```',
+            '',
+            `Fields that would change: ${Object.keys(patch).join(', ')}`,
+          ].join('\n'),
+        },
+      ],
+      _meta: {
+        eventId,
+        dryRun: true,
+        patch,
+        fieldsChanged: Object.keys(patch),
+      },
+    };
+  }
+
+  try {
+    const accessToken = await ensureAuthenticated();
+    const endpoint = `me/events/${eventId}`;
+
+    const response = await callGraphAPI(accessToken, 'PATCH', endpoint, patch);
+
+    const output = [
+      `Event '${response.subject || eventId}' updated successfully.`,
+    ];
+    if (response.id) {
+      output.push(`**ID**: \`${response.id}\``);
+    }
+    if (response.start) {
+      output.push(
+        `**Start**: ${response.start.dateTime} (${response.start.timeZone})`
+      );
+    }
+    if (response.end) {
+      output.push(
+        `**End**: ${response.end.dateTime} (${response.end.timeZone})`
+      );
+    }
+    if (response.webLink) {
+      output.push(`**Link**: ${response.webLink}`);
+    }
+    output.push(`\nFields changed: ${Object.keys(patch).join(', ')}`);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: output.join('\n'),
+        },
+      ],
+      _meta: {
+        eventId: response.id,
+        subject: response.subject,
+        start: response.start,
+        end: response.end,
+        fieldsChanged: Object.keys(patch),
+      },
+    };
+  } catch (error) {
+    if (error.message === 'Authentication required') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: "Authentication required. Please use the 'authenticate' tool first.",
+          },
+        ],
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error updating event: ${error.message}`,
+        },
+      ],
+    };
+  }
+}
+
+module.exports = handleUpdateEvent;

package/categories/index.js

@@ -826,7 +826,7 @@ const categoriesTools = [
   {
     name: 'manage-category',
     description:
-      'Manage master categories. action=list (default) lists categories. action=create creates a category. action=update changes name/color. action=delete removes a category.',
+      "Manage the user's master category list (the colour-coded labels available across mail/calendar/contacts). action=`list` (default) returns categories with id/displayName/color. action=`create` adds a new category — `displayName` required, `color` optional (preset0-preset24, e.g. preset0=Red, preset7=Blue). action=`update` (alias `set` — deprecated) changes name/colour by `id`. action=`delete` removes a category — this does NOT untag messages already labelled with it; existing messages retain the orphaned label until manually cleaned. Use `apply-category` to tag/untag specific messages.",
     annotations: {
       title: 'Master Categories',
       readOnlyHint: false,
@@ -899,7 +899,8 @@ const categoriesTools = [
   },
   {
     name: 'apply-category',
-    description: 'Apply, add, or remove categories on email message(s)',
+    description:
+      "Tag or untag email messages with master categories (those created via `manage-category`). action=`set` (default) replaces the message's category set with the supplied `categories` array. action=`add` appends categories to whatever's already on the message. action=`remove` removes only the named categories, leaving the rest. Accepts either `messageId` (single) or `messageIds` (batch via Graph `$batch`). `categories` are matched by display name — names must already exist in the master list (create via `manage-category` first). Returns per-message confirmation.",
     annotations: {
       title: 'Apply Categories',
       readOnlyHint: false,
@@ -938,7 +939,7 @@ const categoriesTools = [
   {
     name: 'manage-focused-inbox',
     description:
-      'Manage Focused Inbox overrides. action=list (default) shows overrides. action=set creates/updates an override. action=delete removes an override.',
+      'Manage Focused Inbox sender overrides — explicit rules that force messages from a given sender into Focused or Other regardless of the ML classifier. action=`list` (default) returns existing overrides with id/sender/classifyAs. action=`set` creates or updates an override for `emailAddress` (optional `name`), routing future mail to `focused` (default) or `other`. action=`delete` removes the override for `emailAddress`. Note: this only works on accounts that have Focused Inbox enabled — personal Outlook.com accounts without it return an empty list.',
     annotations: {
       title: 'Focused Inbox',
       readOnlyHint: false,

package/config.js

@@ -23,6 +23,48 @@ if (!homeDir) {
   );
 }
 
+/**
+ * Resolve the OAuth audience segment used in Microsoft Graph endpoints.
+ *
+ * Microsoft's identity platform v2.0 routes by audience:
+ *   - `common`         — personal AND work/school accounts (multi-tenant + personal)
+ *   - `consumers`      — personal Microsoft accounts only
+ *   - `organizations`  — work/school accounts only
+ *   - `<tenant-guid>`  — single-tenant
+ *
+ * The right value depends on the Azure app registration's "Supported account
+ * types" setting. An app registered as "Personal Microsoft accounts only" is
+ * rejected by `/common/` with `AADSTS9002331` and must use `/consumers/`;
+ * a single-tenant app must use its tenant GUID; etc.
+ *
+ * Defaulting to `common` preserves existing behaviour. Set
+ * `OUTLOOK_AUTH_AUDIENCE` to override.
+ */
+const AUTH_AUDIENCE = process.env.OUTLOOK_AUTH_AUDIENCE || 'common';
+
+// Surface obvious misconfigurations at startup rather than failing later with a
+// cryptic AADSTS error from Microsoft. Warn rather than throw so we never break
+// an existing deployment on upgrade — Graph itself remains the source of truth
+// for what audiences it accepts.
+const VALID_AUDIENCE_LITERALS = new Set([
+  'common',
+  'consumers',
+  'organizations',
+]);
+const TENANT_GUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+if (
+  !VALID_AUDIENCE_LITERALS.has(AUTH_AUDIENCE) &&
+  !TENANT_GUID_RE.test(AUTH_AUDIENCE)
+) {
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[outlook-assistant] OUTLOOK_AUTH_AUDIENCE="${AUTH_AUDIENCE}" is not a recognised value. ` +
+      `Expected one of: common, consumers, organizations, or a tenant GUID. ` +
+      `Proceeding anyway — Microsoft's identity platform will reject it at runtime if invalid.`
+  );
+}
+
 module.exports = {
   // Server information
   SERVER_NAME: 'outlook-assistant',
@@ -54,9 +96,10 @@ module.exports = {
     ],
     tokenStorePath: path.join(homeDir, '.outlook-assistant-tokens.json'),
     authServerUrl: 'http://localhost:3333',
-    deviceCodeEndpoint:
-      'https://login.microsoftonline.com/common/oauth2/v2.0/devicecode',
-    tokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    audience: AUTH_AUDIENCE,
+    deviceCodeEndpoint: `https://login.microsoftonline.com/${AUTH_AUDIENCE}/oauth2/v2.0/devicecode`,
+    tokenEndpoint: `https://login.microsoftonline.com/${AUTH_AUDIENCE}/oauth2/v2.0/token`,
+    authorizeEndpoint: `https://login.microsoftonline.com/${AUTH_AUDIENCE}/oauth2/v2.0/authorize`,
     defaultAuthMethod: process.env.OUTLOOK_AUTH_METHOD || 'device-code',
   },
 
@@ -97,6 +140,9 @@ module.exports = {
   // Immutable IDs (opt-in: IDs persist through folder moves)
   USE_IMMUTABLE_IDS: process.env.OUTLOOK_IMMUTABLE_IDS === 'true',
 
-  // Timezone
-  DEFAULT_TIMEZONE: 'Australia/Melbourne', // Updated for Nathan's timezone
+  // Timezone — IANA zone (e.g. "Australia/Melbourne", "Europe/London",
+  // "America/New_York"). Override per-deployment via OUTLOOK_DEFAULT_TIMEZONE.
+  // Default preserves the historic value for backwards compatibility.
+  DEFAULT_TIMEZONE:
+    process.env.OUTLOOK_DEFAULT_TIMEZONE || 'Australia/Melbourne',
 };

package/contacts/index.js

@@ -679,11 +679,11 @@ const contactsTools = [
   {
     name: 'manage-contact',
     description:
-      'Manage personal contacts. action=list (default) lists contacts. action=search searches by name/email. action=get retrieves full details. action=create adds a contact. action=update modifies a contact. action=delete removes a contact.',
+      "Full CRUD over the signed-in user's personal Outlook contacts (destructive: covers `delete` action). action=`list` (default) returns contacts with pagination via `skip`/`count` (default 50). action=`search` returns contacts matching `query` against name/email (default 25). action=`get` returns full contact detail by `id`. action=`create` adds a new contact and returns its `id`. action=`update` patches the given fields by `id` (only fields passed are changed). action=`delete` permanently removes the contact by `id`. Use `outputVerbosity` (minimal/standard/full) on list/search to control field count. Prefer `search-people` for cross-source relevance ranking (contacts + directory + recent comms) — this tool only searches your personal contact store.",
     annotations: {
       title: 'Contacts',
       readOnlyHint: false,
-      destructiveHint: false,
+      destructiveHint: true,
       openWorldHint: false,
     },
     inputSchema: {
@@ -801,7 +801,7 @@ const contactsTools = [
   {
     name: 'search-people',
     description:
-      'Search for people by relevance (includes contacts, directory, and recent communications). Uses a different API from manage-contact search.',
+      'Relevance-ranked search across personal contacts, organisation directory, and recent communications via the Microsoft Graph People API (read-only). Returns people objects with `displayName`, `emailAddresses`, `companyName`, `jobTitle`, and relevance metadata — ideal for "who is X?" or "who do I email about Y?" lookups. Use `manage-contact` action=`search` instead when you specifically need entries from your personal contact store only.',
     annotations: {
       title: 'People Search',
       readOnlyHint: true,

package/email/index.js

@@ -33,7 +33,7 @@ const emailTools = [
   {
     name: 'search-emails',
     description:
-      'Search and list emails. With no query, lists recent emails (like list-emails). Supports search queries, KQL, delta sync, message-id lookup, and conversation listing.',
+      'Search, list, delta-sync, or thread-group emails — six modes selected by parameters (read-only). With no params: lists recent emails in `folder` (default `inbox`). With `query`/`from`/`to`/`subject`/date filters: full search (combines via OData filter). With `kqlQuery`: raw Keyword Query Language for advanced server-side search. With `deltaMode: true`: returns current state plus a `deltaToken`; pass the token back on the next call for incremental changes only — ideal for inbox monitoring. With `groupByConversation: true`: returns conversation threads. With `conversationId`: returns all messages in a single thread. With `internetMessageId`: looks up a message by its RFC Message-ID header. Personal Outlook.com accounts have limited `$search` support — this tool falls back through OData filters / boolean filters / recent listing automatically, but structured filters (`from`/`subject`/`receivedAfter`/`hasAttachments`/`unreadOnly`) return cleaner results. Returns paged messages with id/subject/from/receivedDateTime/preview by default; use `outputVerbosity` to expand.',
     annotations: {
       title: 'Search Emails',
       readOnlyHint: true,
@@ -179,7 +179,7 @@ const emailTools = [
   {
     name: 'read-email',
     description:
-      'Read email content. Set headersMode=true for forensic headers (DKIM, SPF, Received, Message-ID).',
+      'Read a single email by id (read-only). Default: returns the full message body (HTML stripped to text by default), subject, from/to/cc, receivedDateTime, conversationId, attachments metadata, and webLink as Markdown. With `headersMode: true`: returns RFC-822 forensic headers instead (DKIM, SPF, DMARC, Received chain, Message-ID, Authentication-Results) — pair with `importantOnly: true` for the security-relevant subset, `groupByType: true` for category-bucketed view, or `raw: true` for JSON instead of Markdown. With `includeHeaders: true` (non-headers-mode): adds basic headers alongside body. Use `outputVerbosity` (minimal/standard/full) to control field count.',
     annotations: {
       title: 'Read Email',
       readOnlyHint: true,
@@ -237,7 +237,7 @@ const emailTools = [
   {
     name: 'send-email',
     description:
-      'Compose and send an email. Use dryRun=true to preview without sending. Subject to rate limits and recipient allowlist when configured.',
+      'Compose and send an email immediately (destructive: sends external comms). Returns a confirmation with the saved-message id. Safety controls: `dryRun: true` returns the composed message for review without sending; `checkRecipients: true` runs `get-mail-tips` first to flag out-of-office / mailbox-full / delivery-restricted / external recipients; combine both for a full pre-send review. Subject to session rate limits (`OUTLOOK_MAX_EMAILS_PER_SESSION` env) and recipient allowlist (`OUTLOOK_ALLOWED_RECIPIENTS` env) when configured — calls outside the allowlist fail before any Graph request. For multi-step compose/review workflows prefer `draft` (action=`create` → `update` → `send`) since drafts can be inspected in Outlook before sending. Comma-separated recipient strings or arrays both accepted.',
     annotations: {
       title: 'Send Email',
       readOnlyHint: false,
@@ -296,7 +296,7 @@ const emailTools = [
   {
     name: 'draft',
     description:
-      'Manage email drafts. action=create saves a new draft. action=update edits an existing draft. action=send sends a draft. action=delete removes a draft. action=reply/reply-all/forward creates a reply or forward draft from an existing message.',
+      'Full draft lifecycle for review-before-send workflows (destructive: covers `send` and `delete`). action=`create` saves a new draft in the Drafts folder and returns its id (use `dryRun: true` to preview without saving; `checkRecipients: true` runs mail-tips first). action=`update` patches an existing draft by `id` (only fields passed are changed). action=`send` dispatches an existing draft — shares the rate limit with `send-email`. action=`delete` removes a draft permanently. action=`reply`/`reply-all` creates a reply draft from a message `id` (use `comment` to prepend text — mutually exclusive with `body`). action=`forward` creates a forward draft (requires `id` and `to`). Recipient allowlist applies to create/update/forward. Returns the draft object on create/update/reply/forward; status confirmation on send/delete.',
     annotations: {
       title: 'Draft Operations',
       readOnlyHint: false,
@@ -375,7 +375,7 @@ const emailTools = [
   {
     name: 'update-email',
     description:
-      'Update email state. action=mark-read/mark-unread changes read status. action=flag sets follow-up flag. action=unflag clears flag. action=complete marks flag as done.',
+      'Update message state without modifying content (idempotent — safe to retry). action=`mark-read`/`mark-unread` toggles the `isRead` flag on a single message by `id`. action=`flag` sets a follow-up flag with optional `dueDateTime`/`startDateTime` (ISO 8601). action=`unflag` clears the flag. action=`complete` marks the flag as done. Flag/unflag/complete accept either `id` (single) or `ids` (batch array) — batch operations use Graph `$batch` for efficiency. Returns status confirmation per message.',
     annotations: {
       title: 'Update Email',
       readOnlyHint: false,
@@ -455,7 +455,7 @@ const emailTools = [
   {
     name: 'attachments',
     description:
-      'Manage email attachments. action=list shows attachments for a message. action=view shows content/metadata. action=download saves to disk.',
+      'Inspect or retrieve email attachments. action=`list` (default) returns metadata for all attachments on `messageId` (id, name, contentType, size, isInline) — read-only. action=`view` returns inline content for text/JSON/XML attachments via `attachmentId`; binary types require download. action=`download` saves the attachment to disk at `outputDir` (default system tmpdir, auto-created) and returns the saved file path. `messageId` is required for all actions; `attachmentId` is required for view/download. Use `outputVerbosity` to control list field count.',
     annotations: {
       title: 'Attachments',
       readOnlyHint: false,
@@ -516,7 +516,7 @@ const emailTools = [
   {
     name: 'export',
     description:
-      'Export emails. target=message exports one email. target=messages batch-exports. target=conversation exports a thread. target=mime gets raw MIME/EML content.',
+      'Export emails to file formats for archival, forensics, or programmatic processing. target=`message` (default) exports a single email by `id` to `savePath` — accepts `mime`/`eml`/`markdown`/`json`/`csv`. target=`messages` batch-exports either an explicit `emailIds` array or messages matching `searchQuery` (or `query` shortcut) into `outputDir` — accepts `markdown`/`json`/`csv`. target=`conversation` exports a full thread by `conversationId` into `outputDir` (chronological by default; pass `order: "reverse"` for newest-first) — accepts `eml`/`mbox`/`markdown`/`json`/`html`/`csv`. target=`mime` returns raw RFC-822 MIME bytes for `id` (use `headersOnly` for just headers, `base64` for encoded transport, `maxSize` to cap at default 1MB). `includeAttachments` defaults to true for single-message exports and false for batch. Format support varies by target — see the format param enum.',
     annotations: {
       title: 'Export Emails',
       readOnlyHint: false,
@@ -634,7 +634,7 @@ const emailTools = [
   {
     name: 'get-mail-tips',
     description:
-      'Check recipients before sending: out-of-office status, mailbox full, external recipients, delivery restrictions, moderation, group member counts, and max message size. No competitor offers this.',
+      'Pre-send recipient validation via Graph `POST /me/getMailTips` (read-only; uses the existing `Mail.Read` scope — no extra permissions). Returns per-recipient tips covering automatic replies (out-of-office), mailbox full status, custom admin mail tips, delivery restrictions, moderation requirements, external-vs-internal scope, max message size, and group member counts (total + external). Use ahead of `send-email` or `draft` action=`create` to catch issues like OOO replies or external-recipient warnings before the message goes out; `send-email`/`draft` accept `checkRecipients: true` to invoke this automatically. Accepts either a comma-separated string or an array of addresses; `tipTypes` filters which tips are requested (defaults to all).',
     annotations: {
       title: 'Mail Tips',
       readOnlyHint: true,

package/folder/index.js

@@ -12,7 +12,7 @@ const folderTools = [
   {
     name: 'folders',
     description:
-      'Manage mail folders. action=list (default) lists folders. action=create creates a folder. action=move moves emails between folders. action=stats gets folder counts for pagination planning. action=delete removes a folder.',
+      'Manage mail folders (tool-level destructiveHint=true because `delete` permanently removes a folder; `list` and `stats` are read-only sub-actions despite the annotation). action=`list` (default) returns the folder tree with id/displayName/parentFolderId (toggle `includeItemCounts` for unread/total, `includeChildren` for hierarchy). action=`create` makes a new folder under the inbox (or under `folder`/`folderId`/`folderName`) and returns its id. action=`move` relocates emails (`emailIds` array) into `targetFolder`. action=`stats` returns counts (totalItemCount/unreadItemCount) suitable for pagination planning — pair with `outputVerbosity` to limit noise. action=`delete` permanently removes a folder and its contents — there is no recycle-bin recovery.',
     annotations: {
       title: 'Mail Folders',
       readOnlyHint: false,

package/llms.txt

@@ -76,9 +76,9 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [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/>)
+- [FAQ](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/faq/faq.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 (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)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.8.0 — `manage-event` gains an `update` action covering 12 fields with `dryRun` (#173, closes #124); new `OUTLOOK_AUTH_AUDIENCE` env var fixes AADSTS9002331 for personal-only Azure apps (#174); new `OUTLOOK_DEFAULT_TIMEZONE` env var overrides the hardcoded Australia/Melbourne default (#175))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.8.x polish, 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/outlook-auth-server.js

@@ -39,7 +39,8 @@ const { AUTH_CONFIG: centralAuth } = require('./config');
 // Log to console
 console.log('Starting Outlook Authentication Server');
 
-// Authentication configuration — scopes and tokenStorePath from config.js (single source of truth)
+// Authentication configuration — scopes, tokenStorePath, and audience-driven
+// endpoints sourced from config.js (single source of truth).
 const AUTH_CONFIG = {
   clientId: process.env.OUTLOOK_CLIENT_ID || process.env.MS_CLIENT_ID || '',
   clientSecret:
@@ -47,6 +48,8 @@ const AUTH_CONFIG = {
   redirectUri: centralAuth.redirectUri,
   scopes: centralAuth.scopes,
   tokenStorePath: centralAuth.tokenStorePath,
+  authorizeEndpoint: centralAuth.authorizeEndpoint,
+  tokenEndpoint: centralAuth.tokenEndpoint,
 };
 
 // Create HTTP server
@@ -247,7 +250,9 @@ const server = http.createServer((req, res) => {
       state,
     };
 
-    const authUrl = `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?${querystring.stringify(authParams)}`;
+    // Use the audience from config (defaults to "common"; configurable via
+    // OUTLOOK_AUTH_AUDIENCE for personal-only / single-tenant Azure apps).
+    const authUrl = `${AUTH_CONFIG.authorizeEndpoint}?${querystring.stringify(authParams)}`;
     console.log(`Redirecting to: ${authUrl}`);
 
     // Redirect to Microsoft's login page
@@ -296,9 +301,13 @@ function exchangeCodeForTokens(code) {
       scope: AUTH_CONFIG.scopes.join(' '),
     });
 
+    // Same audience-driven path as the authorize URL above.
+    const tokenUrl = new URL(AUTH_CONFIG.tokenEndpoint);
     const options = {
-      hostname: 'login.microsoftonline.com',
-      path: '/common/oauth2/v2.0/token',
+      hostname: tokenUrl.hostname,
+      // Preserve any query string on the endpoint (none today, but future-safe
+      // if Microsoft ever adds hint params to the token URL).
+      path: tokenUrl.pathname + tokenUrl.search,
       method: 'POST',
       headers: {
         'Content-Type': 'application/x-www-form-urlencoded',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.7.4",
+  "version": "3.8.1",
   "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",
@@ -74,7 +74,7 @@
     "llms-install.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.3.1"
   },
   "devDependencies": {

package/rules/index.js

@@ -180,7 +180,7 @@ const rulesTools = [
   {
     name: 'manage-rules',
     description:
-      'Manage inbox rules. action=list (default) lists rules. action=create creates a new rule with conditions, actions, and optional exceptions. action=update modifies an existing rule. action=reorder changes rule execution priority. action=delete removes a rule.',
+      'Server-side inbox rule CRUD (destructive: covers `delete`; supports `dryRun` on create/update for preview). Rules run on the Exchange server regardless of which client is open. action=`list` (default) returns rules with id/name/sequence — pass `includeDetails: true` to expand conditions/actions/exceptions. action=`create` builds a new rule from condition params (12 supported: fromAddresses, containsSubject, bodyContains, hasAttachments, importance, sentTo, sensitivity, etc.), action params (9 supported: moveToFolder, forwardTo, redirectTo, assignCategories, markAsRead, delete, etc.), and optional `except*` exceptions. action=`update` patches the named fields by `ruleId`. action=`reorder` changes execution priority via `sequence` (lower = earlier). action=`delete` removes a rule. Recipient allowlist applies to forwardTo/redirectTo. `permanentDelete` action is intentionally omitted (too dangerous for AI use — use the Outlook UI). Subject to session rate limits (`OUTLOOK_MAX_MANAGE_RULES_PER_SESSION`).',
     annotations: {
       title: 'Inbox Rules',
       readOnlyHint: false,

package/settings/index.js

@@ -615,7 +615,7 @@ const settingsTools = [
   {
     name: 'mailbox-settings',
     description:
-      'Manage mailbox settings. action=get (default) retrieves settings (language, timezone, working hours, auto-replies). action=set-auto-replies configures out-of-office. action=set-working-hours configures work schedule.',
+      '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,