@littlebearapps/outlook-assistant 3.11.2 → 3.12.1

package/llms.txt

@@ -9,7 +9,7 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 - **Package**: `@littlebearapps/outlook-assistant` on npm
 - **Install**: `npm install -g @littlebearapps/outlook-assistant` or `npx @littlebearapps/outlook-assistant`
 - **License**: MIT
-- **Node.js**: >= 18.0.0
+- **Node.js**: >= 18.18.0 (development tooling: >= 22.22.1)
 - **Authentication**: OAuth 2.0 with Microsoft Graph API (requires Azure app registration)
 - **Tools**: 22 tools across 9 modules (reduced from 55 for optimal AI performance)
 
@@ -17,8 +17,9 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 
 - Read, search, send, and export emails directly from Claude instead of switching apps
 - 8 email tools covering search, conversations, attachments, bulk export, pre-send mail tips, and draft management
-- Manage calendar events, contacts, rules, categories, and mailbox settings in one place
-- Export to multiple formats: MIME/EML, MBOX, Markdown, JSON, HTML
+- Manage calendar events (upcoming by default, or past and named events via `startAfter`/`startBefore`/`subject`), contacts, rules, categories, and mailbox settings in one place
+- Export to multiple formats: MIME/EML, MBOX, Markdown, JSON, HTML, CSV
+- Opt-in shared-mailbox read and organise support (`sharedMailbox`, work/school accounts, `OUTLOOK_SHARED_MAILBOX`); sending from a shared mailbox is not supported
 
 ## Key Differentiators
 
@@ -35,6 +36,8 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 - **MCP safety annotations** on all 22 tools — AI clients auto-approve reads and prompt for destructive operations
 - **Send-email protections**: pre-send mail tips, dry-run preview, session rate limiting, recipient allowlist
 - **Rule protections**: dry-run preview on create/update, rate limiting, recipient allowlist on forward/redirect, no permanent-delete action
+- **Input and file hardening**: IDs with `.`/`..` path segments refused, the access token only ever sent to `graph.microsoft.com`, attachment downloads and exports confined to the output directory without overwriting
+- **Shared mailboxes off by default**: `.Shared` scopes are requested only when `OUTLOOK_SHARED_MAILBOX` is set (`read` keeps shared access read-only)
 - **Token-optimised**: 22 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
 - These safeguards reduce risk but are not foolproof — always review actions before approving
 
@@ -59,15 +62,15 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 
 ## Tool Categories
 
-- **Authentication (1 tool)**: `auth` — OAuth flow, status, about
+- **Authentication (1 tool)**: `auth` — status, authenticate (device code by default), device-code-complete, about (version, granted scopes, shared-mailbox status)
 - **Email (8 tools)**: `search-emails`, `read-email`, `send-email`, `draft`, `update-email`, `attachments`, `export`, `get-mail-tips`
-- **Calendar (3 tools)**: `list-events`, `create-event`, `manage-event`
+- **Calendar (3 tools)**: `list-events` (`startAfter`, `startBefore`, `subject` filters), `create-event`, `manage-event` (update, decline, cancel, delete)
 - **Contacts (2 tools)**: `manage-contact`, `search-people`
 - **Folders (1 tool)**: `folders` — list, create, move, stats, delete; folders addressable by nested path (`Parent/Child`) or ID
 - **Rules (1 tool)**: `manage-rules` — list, create, update, reorder, delete
 - **Categories (3 tools)**: `manage-category`, `apply-category`, `manage-focused-inbox`
 - **Settings (1 tool)**: `mailbox-settings` — get, set auto-replies, set working hours
-- **Advanced (2 tools)**: `access-shared-mailbox`, `find-meeting-rooms`
+- **Advanced (2 tools)**: `access-shared-mailbox` (messages, `listFolders`, `folderId`, nested folder paths), `find-meeting-rooms`
 
 ## Documentation
 
@@ -76,9 +79,10 @@ 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
+- [Troubleshooting](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/troubleshooting.md): Known errors and fixes — auth, search, export, shared mailboxes
 - [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.11.2 — security release: attachment downloads confined to `outputDir` (GHSA-755c-c45g-69rv) and the access token only ever sent to Microsoft Graph (GHSA-mqfm-wfjq-jxq2), HTML-to-text entity double-decoding fixed, `npm audit` at 0. Preceded by v3.11.1 — search and export correctness: a search term combined with a date or boolean filter was silently overwritten, so the request carried only the date window and the whole window came back reported as a filtered result; batch export named files `<date>_<subject>`, so a same-day reply chain overwrote itself on disk while the summary reported `Failed 0` — filenames now carry the time, collisions get a numeric suffix instead of clobbering, and a manifest maps each requested ID to the file actually written; a truncated local scan is now disclosed when it matched, not only when it returned nothing; `query` versus `searchExpression` and the 500-message `to` scan cap documented. Preceded by v3.11.0 — fixes & polish: `--version`/`--help` CLI flags (#68), `AADSTS7000215` explaining the Secret ID vs Secret Value mistake via one shared AADSTS hint table (#69), token-refresh round trip covered end to end (#72), and all 17 development-dependency advisories cleared; and v3.10.0 — search correctness: field-scoped `searchExpression` translated to OData filters and retried on personal accounts (#217), two-filter searches no longer returning the single-filter superset (#229), `from`/`to` filter values OData-escaped (#230), no-results guidance derived from what was actually attempted (#231))
-- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.11.2 tool description audit, v3.8.x carry-over, v3.12.0+ new Graph APIs)
-- [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.12.1 — Graph reliability and correctness fixes: throttling retries, a request inactivity timeout and a 4-request concurrency cap (#244), complete delta paging (#254), a draft-only guard on `draft` update/send/delete (#246), nested folder paths in `manage-rules` (#248), flag dates honouring `Z` and offsets (#247), attendee types kept on `manage-event update` (#249), no "via API" text on decline/cancel (#242), escaped `$search` phrases (#251), and conversation read/export working on personal accounts. Preceded by v3.12.0 — opt-in shared-mailbox read and organise support via `sharedMailbox` and `OUTLOOK_SHARED_MAILBOX` (#228), `list-events` `startAfter`/`startBefore`/`subject` filters (#193), token refresh requesting the granted scopes plus `offline_access` (#241), and two security fixes: dot segments in resource paths rejected, `export` writes confined to the output directory. Preceded by v3.11.2 — security release: attachment downloads confined to `outputDir` (GHSA-755c-c45g-69rv) and the access token only ever sent to Microsoft Graph (GHSA-mqfm-wfjq-jxq2); v3.11.1 — search and export correctness (filters combined with dates no longer silently dropped, batch export no longer overwrites same-day reply chains); v3.11.0 — `--version`/`--help` CLI flags (#68) and the `AADSTS7000215` Secret ID vs Value explanation (#69); v3.10.0 — search correctness (#217, #229, #230, #231))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.12.x tool description audit, v3.8.x carry-over, v3.13.0+ new Graph APIs)
+- [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy (report vulnerabilities privately via GitHub private vulnerability reporting; acknowledged within 7 days), token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.11.2",
+  "version": "3.12.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",
@@ -84,12 +84,12 @@
     "@commitlint/cli": "^20.4.3",
     "@commitlint/config-conventional": "^20.4.3",
     "@eslint/js": "^10.0.1",
-    "@modelcontextprotocol/inspector": "^0.21.1",
+    "@modelcontextprotocol/inspector": "^2.8.0",
     "eslint": "^10.0.2",
     "globals": "^17.4.0",
     "husky": "^9.1.7",
     "jest": "^30.2.0",
-    "lint-staged": "^16.3.2",
+    "lint-staged": "^17.6.0",
     "prettier": "^3.8.1",
     "supertest": "^7.2.2"
   },

package/rules/index.js

@@ -180,7 +180,7 @@ const rulesTools = [
   {
     name: 'manage-rules',
     description:
-      '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`).',
+      '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/copyToFolder — folder name, nested path like `Triage/Delete`, or ID — 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,
@@ -304,12 +304,12 @@ const rulesTools = [
         moveToFolder: {
           type: 'string',
           description:
-            'Folder name to move matching emails to (action=create/update)',
+            'Folder to move matching emails to: a name, a nested path like `Triage/Delete`, a well-known name (e.g. `archive`), or a folder ID (action=create/update)',
         },
         copyToFolder: {
           type: 'string',
           description:
-            'Folder name to copy matching emails to (action=create/update)',
+            'Folder to copy matching emails to: a name, a nested path like `Projects/Backup`, a well-known name, or a folder ID (action=create/update)',
         },
         markAsRead: {
           type: 'boolean',

package/rules/rule-builder.js

@@ -2,7 +2,7 @@
  * Shared rule builder utilities for creating and updating mail rules.
  * Converts flat MCP tool parameters into Microsoft Graph API rule objects.
  */
-const { getFolderIdByName } = require('../email/folder-utils');
+const { resolveFolder, looksLikeFolderId } = require('../folder/resolve');
 const { checkRecipientAllowlist } = require('../utils/safety');
 
 const VALID_IMPORTANCE = ['low', 'normal', 'high'];
@@ -104,6 +104,49 @@ function buildConditions(args) {
   return { conditions, warnings };
 }
 
+/**
+ * Resolve a rule's target folder (ID, well-known alias, nested path such as
+ * "Triage/Delete", or bare name) to a folder ID with the shared resolver. (#248)
+ * Not-found and ambiguous folders become a warning containing "not found", which
+ * create/update treat as fatal when no other action is left; any other failure
+ * (auth, network, Graph outage) is rethrown rather than misreported.
+ * @param {string} accessToken - Graph API access token
+ * @param {string} folder - Folder ID, alias, path, or name
+ * @param {string} label - Warning prefix, e.g. "Target folder"
+ * @returns {Promise<{ folderId?: string, warning?: string }>}
+ */
+async function resolveRuleFolder(accessToken, folder, label) {
+  const spec = looksLikeFolderId(folder)
+    ? { id: folder.trim() }
+    : { name: folder };
+  try {
+    const resolved = await resolveFolder(accessToken, spec);
+    return { folderId: resolved.id };
+  } catch (error) {
+    const message = error.message || '';
+    if (message.includes('ambiguous')) {
+      return {
+        warning: `${label} "${folder}" not found as a single folder. ${message}`,
+      };
+    }
+    if (
+      message.includes('not found') ||
+      message.startsWith('Invalid folder path') ||
+      /status (400|404):/.test(message)
+    ) {
+      // The resolver's reason follows (an empty path segment, Graph's 400 text);
+      // its own not-found message already carries the action=list guidance.
+      const hint = message.includes('action=list')
+        ? ''
+        : ' Use `folders` action=list to see folders (with IDs and full paths), or pass a path like "Parent/Child" or a folderId.';
+      return {
+        warning: `${label} "${folder}" not found. ${message}${hint}`,
+      };
+    }
+    throw error;
+  }
+}
+
 /**
  * Build a Graph API actions object from flat tool parameters.
  * Async because folder resolution requires API calls.
@@ -115,21 +158,23 @@ async function buildActions(args, accessToken) {
   const actions = {};
   const warnings = [];
 
-  // Folder-based actions (name → ID resolution)
-  if (args.moveToFolder) {
-    const folderId = await getFolderIdByName(accessToken, args.moveToFolder);
-    if (!folderId) {
-      warnings.push(`Target folder "${args.moveToFolder}" not found.`);
-    } else {
-      actions.moveToFolder = folderId;
-    }
-  }
-  if (args.copyToFolder) {
-    const folderId = await getFolderIdByName(accessToken, args.copyToFolder);
-    if (!folderId) {
-      warnings.push(`Copy-to folder "${args.copyToFolder}" not found.`);
-    } else {
-      actions.copyToFolder = folderId;
+  // Folder-based actions (ID, alias, nested path or name → ID)
+  const folderActions = [
+    ['moveToFolder', 'Target folder'],
+    ['copyToFolder', 'Copy-to folder'],
+  ];
+  for (const [param, label] of folderActions) {
+    if (args[param]) {
+      const { folderId, warning } = await resolveRuleFolder(
+        accessToken,
+        args[param],
+        label
+      );
+      if (folderId) {
+        actions[param] = folderId;
+      } else {
+        warnings.push(warning);
+      }
     }
   }
 

package/utils/datetime.js

@@ -0,0 +1,170 @@
+/**
+ * Shared ISO 8601 date-time parsing and timezone conversion.
+ *
+ * Nothing here reads the server's local timezone: zoned values are converted
+ * with their own `Z`/offset, and wall-clock values are read in an explicit IANA
+ * zone through Intl, so results are the same on every machine.
+ */
+const config = require('../config');
+
+// An ISO 8601 instant with an explicit zone: `Z` or a ±hh:mm offset. A
+// zone-less value would be read in the server's local timezone by Date.parse,
+// so results would differ between machines; date-only values are rejected for
+// the same reason.
+const ISO_INSTANT =
+  /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
+
+// A wall-clock date-time with no zone, e.g. 2026-03-01T09:00 or
+// 2026-03-01T09:00:00.5. Callers decide which zone it is read in.
+const WALL_TIME =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?$/;
+
+const MIN_YEAR = 1900;
+
+/**
+ * Error raised for a date-time argument that can't be read, so handlers can
+ * report it as a tool error before touching the network.
+ */
+class InvalidDateTimeError extends Error {}
+
+/** True when year/month/day name a real calendar day (no 30 Feb roll-over). */
+function isRealDate(year, month, day) {
+  return (
+    year >= MIN_YEAR &&
+    month >= 1 &&
+    month <= 12 &&
+    new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day
+  );
+}
+
+/**
+ * Parse an ISO 8601 instant that carries `Z` or a ±hh:mm offset.
+ * @returns {number} epoch milliseconds, or NaN when the value isn't one
+ */
+function parseIsoInstant(value) {
+  const s = typeof value === 'string' ? value.trim().replace(/z$/, 'Z') : '';
+  const m = ISO_INSTANT.exec(s);
+  if (!m || !isRealDate(Number(m[1]), Number(m[2]), Number(m[3]))) {
+    return NaN;
+  }
+  return Date.parse(s);
+}
+
+/**
+ * Parse a zone-less wall-clock date-time.
+ * @returns {number[]|null} [year, month, day, hour, minute, second], or null
+ */
+function parseWallTime(value) {
+  const m = typeof value === 'string' ? WALL_TIME.exec(value.trim()) : null;
+  if (!m) return null;
+  const [year, month, day, hour, minute] = m.slice(1, 6).map(Number);
+  const second = m[6] === undefined ? 0 : Number(m[6]);
+  if (
+    !isRealDate(year, month, day) ||
+    hour > 23 ||
+    minute > 59 ||
+    second > 59
+  ) {
+    return null;
+  }
+  return [year, month, day, hour, minute, second];
+}
+
+const formatters = new Map();
+
+/**
+ * Wall-clock date and time of an instant in an IANA zone.
+ * @returns {{date: string, time: string, wallMs: number}|null} `date` is
+ *   YYYY-MM-DD, `time` HH:mm:ss, `wallMs` the wall-clock fields read as UTC;
+ *   null when the zone is unknown to Intl
+ */
+function zonedParts(ms, timeZone) {
+  let fmt = formatters.get(timeZone);
+  if (!fmt) {
+    try {
+      fmt = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+      });
+    } catch (_e) {
+      return null;
+    }
+    formatters.set(timeZone, fmt);
+  }
+  const p = {};
+  for (const { type, value } of fmt.formatToParts(new Date(ms))) {
+    p[type] = value;
+  }
+  const date = `${p.year}-${p.month}-${p.day}`;
+  const time = `${p.hour}:${p.minute}:${p.second}`;
+  return {
+    date,
+    time,
+    wallMs: Date.parse(`${date}T${time}Z`),
+  };
+}
+
+/**
+ * Convert a wall-clock date-time in an IANA zone to an instant.
+ * @returns {number} epoch milliseconds, or NaN for a bad value or zone
+ */
+function zonedWallTimeToUtcMs(wall, timeZone) {
+  const f = parseWallTime(wall);
+  if (!f) return NaN;
+  const guess = Date.UTC(f[0], f[1] - 1, f[2], f[3], f[4], f[5]);
+  const offsetAt = (t) => {
+    const parts = zonedParts(t, timeZone);
+    return parts ? parts.wallMs - t : NaN;
+  };
+  const first = offsetAt(guess);
+  if (Number.isNaN(first)) return NaN;
+  // Re-check the offset at the candidate instant, in case a DST change falls
+  // between the naive guess and the real instant.
+  const second = offsetAt(guess - first);
+  return guess - (second === first ? first : second);
+}
+
+/**
+ * Turn an ISO 8601 date-time into a Graph dateTimeTimeZone envelope.
+ *
+ * - With `Z` or a ±hh:mm offset: the same instant, sent in UTC (Graph wants
+ *   the dateTime without a trailing Z).
+ * - Without a zone: sent unchanged, read in `timeZone` (default
+ *   DEFAULT_TIMEZONE).
+ *
+ * @throws {InvalidDateTimeError} for anything else (date-only, impossible
+ *   dates, free text)
+ */
+function toGraphDateTimeTimeZone(
+  value,
+  paramName,
+  timeZone = config.DEFAULT_TIMEZONE
+) {
+  const instant = parseIsoInstant(value);
+  if (!Number.isNaN(instant)) {
+    return {
+      dateTime: new Date(instant).toISOString().replace(/(?:\.000)?Z$/, ''),
+      timeZone: 'UTC',
+    };
+  }
+  if (parseWallTime(value)) {
+    return { dateTime: value.trim(), timeZone };
+  }
+  throw new InvalidDateTimeError(
+    `Invalid ${paramName}: expected an ISO 8601 date-time with a time, e.g. "2026-03-01T09:00:00Z" (UTC), "2026-03-01T09:00:00+10:00" (offset) or "2026-03-01T09:00:00" (read in ${timeZone}) (got ${JSON.stringify(String(value).slice(0, 40))}).`
+  );
+}
+
+module.exports = {
+  InvalidDateTimeError,
+  parseIsoInstant,
+  zonedParts,
+  zonedWallTimeToUtcMs,
+  toGraphDateTimeTimeZone,
+};