@littlebearapps/outlook-assistant 3.8.2 → 3.9.1

package/README.md

@@ -39,7 +39,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 - 📅 **Manage your calendar** — view upcoming events, schedule meetings with attendees, decline or cancel invitations
 - 📦 **Export emails** — save individual messages to Markdown, EML, JSON, or CSV; export full conversation threads to MBOX or HTML; bulk-export search results in one call
 - 🔍 **Investigate email headers** — full raw header access (DKIM, SPF, DMARC, delivery chain, X-Mailer, X-Originating-IP) for phishing investigation and compliance review
-- 🗂️ **Organise your inbox** — create folders, set up inbox rules, colour-code with categories, manage Focused Inbox — all work together for complete inbox automation
+- 🗂️ **Organise your inbox** — create nested folders (addressable by path), set up inbox rules, colour-code with categories, manage Focused Inbox — all work together for complete inbox automation
 - 🔄 **Track inbox changes** — delta sync detects new, modified, and deleted emails since your last check, with tokens for incremental polling
 - 👥 **Manage contacts** — search your contact book and organisational directory, create and update contact records
 - ⚙️ **Configure settings** — set out-of-office auto-replies, working hours, and time zone
@@ -67,7 +67,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 | **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) |
-| **Folder** | 1 | `folders` (list/create/move/stats/delete) |
+| **Folder** | 1 | `folders` (list/create/move/stats/delete) — nested folders addressable by path (`Parent/Child`) or ID |
 | **Rules** | 1 | `manage-rules` (list/create/update/reorder/delete) |
 | **Advanced** | 2 | `access-shared-mailbox`, `find-meeting-rooms` |
 | **Auth** | 1 | `auth` (status/authenticate/about) |
@@ -112,7 +112,7 @@ Outlook Assistant works with both personal and work/school Microsoft accounts, b
 ### What Makes This Different
 
 - **Progressive search** — on accounts where Microsoft's `$search` API is limited, Outlook Assistant automatically falls back through up to 4 search strategies to find your emails. Most Graph API wrappers fail silently; this one adapts.
-- **Email forensics** — raw header access for DKIM, SPF, DMARC, delivery chain, X-Mailer, X-Originating-IP, and spam scores. Returns the full data so you can investigate phishing, audit compliance, or trace delivery issues. (Auto-verdict is on the v3.8.0 roadmap; today the data is surfaced and analysed in-conversation.)
+- **Email forensics** — raw header access for DKIM, SPF, DMARC, delivery chain, X-Mailer, X-Originating-IP, and spam scores. Returns the full data so you can investigate phishing, audit compliance, or trace delivery issues. (Auto-verdict is on the roadmap; today the data is surfaced and analysed in-conversation.)
 - **Delta sync** — incremental inbox monitoring returns only what changed since your last check, with tokens for continuous polling. Designed for agent workflows that need to watch a mailbox.
 - **Batch operations** — flag, move, export, or categorise multiple emails in a single call. Search-driven export lets you batch-export results without collecting IDs manually.
 - **Pre-send intelligence** — check recipients for out-of-office, full mailbox, delivery restrictions, and moderation status before sending — no other Outlook MCP server offers this.
@@ -497,7 +497,7 @@ USE_TEST_MODE=true npm start
 | [Getting Started](docs/how-to/getting-started/connect-outlook-to-claude.md) | Install, configure, and authenticate — start here |
 | [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |
 | [How-To Guides](docs/how-to/index.md) | 29 practical guides for email, calendar, contacts, and settings |
-| [Roadmap](ROADMAP.md) | Active milestones (v3.7.5, v3.8.0, v3.9.0) and recent releases |
+| [Roadmap](ROADMAP.md) | Active milestones (v3.7.5, v3.8.x, v3.10.0+) and recent releases |
 | [Troubleshooting & FAQ](docs/how-to/getting-started/verify-your-connection.md#common-connection-problems) | Common problems, re-authentication, and frequently asked questions |
 | [Tools Reference](docs/quickrefs/tools-reference.md) | All 22 tools with parameters |
 | [AI Agent Guide](docs/how-to/ai-agents/using-outlook-assistant-in-agents.md) | Tool selection and workflow patterns for AI agents |
@@ -506,7 +506,7 @@ Full documentation: [docs/](docs/README.md)
 
 ## Known Limitations
 
-- **Personal account search**: Free-text `query` and `kqlQuery` rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts. Outlook Assistant mitigates this with progressive search fallback (trying OData filters automatically), but for the most direct results, use structured filters (`from`, `subject`, `to`, `receivedAfter`).
+- **Personal account search**: Free-text `query` and the raw `searchExpression` (formerly `kqlQuery`) rely on Microsoft's `$search` API, which has limited support on personal Outlook.com accounts — field-scoped raw `$search` (e.g. `subject:"…"`) may return nothing there. `query` mitigates this with progressive fallback (OData filters, then client-side), so for reliable personal-account search prefer structured filters (`from`, `subject`, `to`, `receivedAfter`) or `query`. Cross-folder search (`searchAllFolders: true`) returns a superset of inbox-only results.
 - **Focused Inbox**: Only available on work/school Microsoft 365 accounts.
 - **Shared mailboxes**: Require `Mail.Read.Shared` permission and a work/school account.
 - **Meeting room search**: Requires `Place.Read.All` permission with admin consent (work/school accounts only).

package/advanced/index.js

@@ -611,7 +611,9 @@ const advancedTools = [
     annotations: {
       title: 'Shared Mailbox',
       readOnlyHint: true,
-      openWorldHint: false,
+      // openWorldHint: returns shared-mailbox messages authored by external
+      // senders. (#92)
+      openWorldHint: true,
     },
     inputSchema: {
       type: 'object',

package/calendar/index.js

@@ -13,7 +13,7 @@ const calendarTools = [
   {
     name: 'list-events',
     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`).',
+      '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. Each start/end is returned as a canonical UTC ISO-8601 instant (e.g. `2026-04-02T22:00:00.000Z`) followed by a labelled local rendering in the configured display timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`) — the UTC value is authoritative, so consumers never have to guess the zone.',
     annotations: {
       title: 'List Calendar Events',
       readOnlyHint: true,

package/calendar/list.js

@@ -5,6 +5,84 @@ const config = require('../config');
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 
+/**
+ * Normalise a Graph dateTimeTimeZone value to a canonical UTC ISO-8601 string
+ * (e.g. "2026-04-02T22:00:00.000Z"). This is the authoritative, unambiguous
+ * value returned to consumers so an AI client never has to guess the zone. (#118)
+ *
+ * We request events in UTC (Prefer: outlook.timezone="UTC"), so Graph returns
+ * zone-less dateTimes tagged timeZone:"UTC". We still validate defensively
+ * rather than blindly appending "Z":
+ *  - values already ending in "Z" or carrying an explicit numeric offset are
+ *    parsed as-is (never double-suffixed);
+ *  - zone-less values are treated as UTC ONLY when the accompanying timeZone is
+ *    UTC (or absent); any other zone throws rather than emit a wrong instant.
+ *
+ * @param {{dateTime: string, timeZone?: string}} dtz - Graph start/end value
+ * @returns {string} Canonical UTC ISO-8601 string
+ * @throws {Error} if missing/unparseable, or zone-less in a non-UTC zone
+ */
+function toUtcIso(dtz) {
+  if (!dtz || !dtz.dateTime) {
+    throw new Error('event time missing dateTime');
+  }
+  const raw = String(dtz.dateTime).trim();
+  const hasZ = /[zZ]$/.test(raw);
+  const hasOffset = /[+-]\d{2}:?\d{2}$/.test(raw);
+
+  let iso;
+  if (hasZ || hasOffset) {
+    // Already zone-aware — parse as-is, never double-suffix.
+    iso = raw;
+  } else {
+    // Zone-less. Safe to treat as UTC only when Graph says so.
+    const zone = (dtz.timeZone || 'UTC').toUpperCase();
+    if (zone !== 'UTC') {
+      throw new Error(
+        `cannot normalise zone-less time in non-UTC zone "${dtz.timeZone}"`
+      );
+    }
+    iso = `${raw}Z`;
+  }
+
+  const parsed = new Date(iso);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new Error(`invalid event dateTime "${dtz.dateTime}"`);
+  }
+  return parsed.toISOString();
+}
+
+/**
+ * Render a UTC ISO instant as a human-friendly local time explicitly labelled
+ * with its zone offset (e.g. "3 Apr 2026, 9:00 am GMT+11:00"), so it can never
+ * be mistaken for UTC or another zone. Returns '' if unrenderable.
+ *
+ * NB: explicit component options are used deliberately — combining
+ * `dateStyle`/`timeStyle` with `timeZoneName` throws `Invalid option` in Intl.
+ *
+ * @param {string} utcIso - Canonical UTC ISO-8601 instant
+ * @param {string} tz - IANA display timezone
+ * @returns {string}
+ */
+function formatLocal(utcIso, tz) {
+  const d = new Date(utcIso);
+  if (Number.isNaN(d.getTime())) return '';
+  try {
+    return d.toLocaleString('en-AU', {
+      timeZone: tz,
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: '2-digit',
+      hour12: true,
+      timeZoneName: 'longOffset',
+    });
+  } catch (_e) {
+    return '';
+  }
+}
+
 /**
  * List events handler
  * @param {object} args - Tool arguments
@@ -28,13 +106,16 @@ async function handleListEvents(args) {
       $select: config.CALENDAR_SELECT_FIELDS,
     };
 
-    // Make API call
+    // Make API call. Force UTC so Graph's returned instants are unambiguous
+    // regardless of mailbox/server timezone; we then emit canonical UTC ISO
+    // plus a labelled local rendering. (#118)
     const response = await callGraphAPI(
       accessToken,
       'GET',
       endpoint,
       null,
-      queryParams
+      queryParams,
+      { Prefer: 'outlook.timezone="UTC"' }
     );
 
     if (!response.value || response.value.length === 0) {
@@ -48,29 +129,35 @@ async function handleListEvents(args) {
       };
     }
 
-    // Format results
+    // Format results. Each Start/End is the canonical UTC ISO-8601 instant
+    // (unambiguous for machine consumers), followed by a labelled local
+    // rendering in the configured display timezone for human readers. (#118)
     const tz = config.DEFAULT_TIMEZONE;
     const eventList = response.value
       .map((event, index) => {
-        const startDt = event.start.dateTime.endsWith('Z')
-          ? event.start.dateTime
-          : `${event.start.dateTime}Z`;
-        const endDt = event.end.dateTime.endsWith('Z')
-          ? event.end.dateTime
-          : `${event.end.dateTime}Z`;
-        const startDate = new Date(startDt).toLocaleString('en-AU', {
-          timeZone: tz,
-          dateStyle: 'medium',
-          timeStyle: 'short',
-        });
-        const endDate = new Date(endDt).toLocaleString('en-AU', {
-          timeZone: tz,
-          dateStyle: 'medium',
-          timeStyle: 'short',
-        });
-        const location = event.location.displayName || 'No location';
-
-        return `${index + 1}. ${event.subject} - Location: ${location}\nStart: ${startDate}\nEnd: ${endDate}\nSummary: ${event.bodyPreview}\nID: ${event.id}\n`;
+        // Authoritative machine-readable instants. Fall back to the raw Graph
+        // value if normalisation fails so one odd event can't break the list.
+        let startUtc;
+        let endUtc;
+        try {
+          startUtc = toUtcIso(event.start);
+        } catch (_e) {
+          startUtc = event.start?.dateTime || 'unknown';
+        }
+        try {
+          endUtc = toUtcIso(event.end);
+        } catch (_e) {
+          endUtc = event.end?.dateTime || 'unknown';
+        }
+
+        const startLocal = formatLocal(startUtc, tz);
+        const endLocal = formatLocal(endUtc, tz);
+        const startStr = startLocal ? `${startUtc} (${startLocal})` : startUtc;
+        const endStr = endLocal ? `${endUtc} (${endLocal})` : endUtc;
+
+        const location = event.location?.displayName || 'No location';
+
+        return `${index + 1}. ${event.subject} - Location: ${location}\nStart: ${startStr}\nEnd: ${endStr}\nSummary: ${event.bodyPreview}\nID: ${event.id}\n`;
       })
       .join('\n');
 
@@ -105,4 +192,9 @@ async function handleListEvents(args) {
   }
 }
 
+// Primary export stays the handler (default import used by calendar/index.js
+// and tests). Helpers are attached for unit testing without changing callers.
+handleListEvents.toUtcIso = toUtcIso;
+handleListEvents.formatLocal = formatLocal;
+
 module.exports = handleListEvents;

package/categories/index.js

@@ -867,7 +867,8 @@ const categoriesTools = [
         },
         categoryId: {
           type: 'string',
-          description: 'DEPRECATED: alias for `id`. Will be removed in v3.8.0.',
+          description:
+            'DEPRECATED: alias for `id`. Will be removed in a future release.',
         },
       },
       additionalProperties: false,

package/contacts/index.js

@@ -805,7 +805,9 @@ const contactsTools = [
     annotations: {
       title: 'People Search',
       readOnlyHint: true,
-      openWorldHint: false,
+      // openWorldHint: returns directory/people data for external contacts
+      // (org directory + inferred from recent comms). (#92)
+      openWorldHint: true,
     },
     inputSchema: {
       type: 'object',

package/email/folder-utils.js

@@ -2,6 +2,7 @@
  * Email folder utilities
  */
 const { callGraphAPI } = require('../utils/graph-api');
+const { resolveFolder } = require('../folder/resolve');
 
 /**
  * Cache of folder information to reduce API calls
@@ -65,20 +66,19 @@ async function resolveFolderPath(accessToken, folderName) {
   }
 
   try {
-    // Try to find the folder by name
-    const folderId = await getFolderIdByName(accessToken, folderName);
-    if (folderId) {
-      const path = `me/mailFolders/${folderId}/messages`;
-      console.error(`Resolved folder "${folderName}" to path: ${path}`);
-      return path;
-    }
-
-    // If not found, throw error instead of silently falling back
-    throw new Error(
-      `Folder "${folderName}" not found. Use the folders tool (action=list) to see available folders.`
-    );
+    // Path-aware resolution: supports nested folders ("Parent/Child"),
+    // case-insensitive names, and reports ambiguity — the same shared resolver
+    // the `folders` tool uses, so search can now scope to nested folders. (#216)
+    const resolved = await resolveFolder(accessToken, { name: folderName });
+    const path = `me/mailFolders/${resolved.id}/messages`;
+    console.error(`Resolved folder "${folderName}" to path: ${path}`);
+    return path;
   } catch (error) {
-    if (error.message.includes('not found')) {
+    // Surface not-found / ambiguity messages verbatim; wrap anything else.
+    if (
+      error.message.includes('not found') ||
+      error.message.includes('ambiguous')
+    ) {
       throw error;
     }
     throw new Error(

package/email/index.js

@@ -33,11 +33,13 @@ const emailTools = [
   {
     name: 'search-emails',
     description:
-      '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.',
+      '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 `searchExpression` (deprecated alias `kqlQuery`): a raw Microsoft Graph `$search` expression 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,
-      openWorldHint: false,
+      // openWorldHint: output includes email content authored by external
+      // senders (bodies/previews/threads) — may contain prompt-injection. (#92)
+      openWorldHint: true,
     },
     inputSchema: {
       type: 'object',
@@ -68,10 +70,15 @@ const emailTools = [
           type: 'string',
           description: 'Search query text. Omit for list mode.',
         },
+        searchExpression: {
+          type: 'string',
+          description:
+            'Raw Microsoft Graph `$search` expression for advanced server-side search, e.g. `subject:"invoice"`, `from:github.com`, or `foo OR bar`. Quote your own phrases; a single bare token is auto-quoted. Pair with `searchAllFolders: true` for cross-folder search. Bypasses other search params. NOTE: on personal Outlook.com accounts field-scoped `$search` is best-effort and may return nothing — prefer `query` there (it has progressive fallback).',
+        },
         kqlQuery: {
           type: 'string',
           description:
-            'Raw KQL (Keyword Query Language) query for advanced search. Bypasses other search params.',
+            'DEPRECATED alias for `searchExpression` (this was never full KQL — it is a Graph `$search` expression). Prefer `searchExpression`.',
         },
         folder: {
           type: 'string',
@@ -160,6 +167,7 @@ const emailTools = [
       // If any search params provided, use search handler
       if (
         args.query ||
+        args.searchExpression ||
         args.kqlQuery ||
         args.from ||
         args.to ||
@@ -183,7 +191,8 @@ const emailTools = [
     annotations: {
       title: 'Read Email',
       readOnlyHint: true,
-      openWorldHint: false,
+      // openWorldHint: returns full message body from external senders. (#92)
+      openWorldHint: true,
     },
     inputSchema: {
       type: 'object',
@@ -460,7 +469,9 @@ const emailTools = [
       title: 'Attachments',
       readOnlyHint: false,
       destructiveHint: false,
-      openWorldHint: false,
+      // openWorldHint: action=view returns attachment content supplied by
+      // external senders. (#92)
+      openWorldHint: true,
     },
     inputSchema: {
       type: 'object',
@@ -486,7 +497,7 @@ const emailTools = [
         savePath: {
           type: 'string',
           description:
-            'DEPRECATED alias for `outputDir`. Will be removed in v3.8.0.',
+            'DEPRECATED alias for `outputDir`. Will be removed in a future release.',
         },
       },
       additionalProperties: false,
@@ -521,7 +532,9 @@ const emailTools = [
       title: 'Export Emails',
       readOnlyHint: false,
       destructiveHint: false,
-      openWorldHint: false,
+      // openWorldHint: exports full message/MIME/conversation content from
+      // external senders. (#92)
+      openWorldHint: true,
     },
     inputSchema: {
       type: 'object',