@littlebearapps/outlook-assistant 3.12.0 → 3.13.0

package/llms-install.md

@@ -11,8 +11,7 @@ Add to your MCP client configuration:
       "command": "npx",
       "args": ["-y", "@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "<user-must-provide>",
-        "OUTLOOK_CLIENT_SECRET": "<user-must-provide>"
+        "OUTLOOK_CLIENT_ID": "<user-must-provide>"
       }
     }
   }
@@ -36,7 +35,10 @@ Users must create an Azure app registration to get credentials:
 6. Click "Register"
 7. Copy the **Application (client) ID** → this is `OUTLOOK_CLIENT_ID`
 
-### Create a client secret:
+If the client ID is left out of the config, the `auth` tool asks for it at sign-in (`auth action=authenticate clientId=<id>`) and saves it to `~/.outlook-assistant-config.json`.
+
+### Create a client secret (browser flow only):
+The default device-code sign-in doesn't need a secret; skip this unless you'll use `method=browser`, and then add `OUTLOOK_CLIENT_SECRET` to the `env` block.
 1. Go to "Certificates & secrets" → "New client secret"
 2. Add a description, select expiration, click "Add"
 3. **Copy the Value immediately** (not the Secret ID) → this is `OUTLOOK_CLIENT_SECRET`
@@ -69,9 +71,13 @@ Add these to the same `env` block if needed:
 |----------|---------|
 | `OUTLOOK_AUTH_AUDIENCE` | `consumers` for Azure apps registered as personal-accounts-only (fixes `AADSTS9002331`); `organizations` or a tenant GUID for work-only apps. Default `common` |
 | `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone for calendar times (default `Australia/Melbourne`) |
-| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on sends per server session |
+| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Default per-session cap for `send-email`, `draft` and `manage-rules` (override one tool with `OUTLOOK_MAX_<TOOL>_PER_SESSION`, e.g. `OUTLOOK_MAX_SEND_EMAIL_PER_SESSION`) |
 | `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of recipient domains/addresses |
 | `OUTLOOK_SHARED_MAILBOX` | Opt-in shared-mailbox support, work/school accounts only: `read` or `true` (read and organise). Also add `Mail.Read.Shared` (and `Mail.ReadWrite.Shared` for `true`) in Azure, restart, then run `auth` with `action=authenticate` and `force=true` |
+| `OUTLOOK_SEARCH_SCAN_LIMIT` | Messages scanned by the local search fallback on personal accounts (default 500, max 5000) |
+| `OUTLOOK_REQUEST_TIMEOUT_MS` | Per-attempt Graph inactivity timeout in milliseconds (default 60000); not an overall deadline |
+
+Run `npx @littlebearapps/outlook-assistant --help` for the full list of environment variables.
 
 ## Configuration Files by Client
 

package/llms.txt

@@ -36,7 +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
+- **Input and file hardening**: IDs with `.`/`..` path segments refused, the access token only ever sent to `graph.microsoft.com`, attachment downloads and exports (including conversation exports) confined to the output directory without overwriting, and a partly written file removed if a write fails
+- **Throttling-aware Graph client**: `429` (and `503`/`504` for non-POST requests) retried honouring `Retry-After`, a per-attempt inactivity timeout (`OUTLOOK_REQUEST_TIMEOUT_MS`, default 60000 ms) and at most 4 requests in flight, so bulk operations neither hang nor throttle themselves
 - **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
@@ -50,15 +51,14 @@ Built by [Little Bear Apps](https://littlebearapps.com).
       "command": "npx",
       "args": ["@littlebearapps/outlook-assistant"],
       "env": {
-        "OUTLOOK_CLIENT_ID": "your-application-client-id",
-        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
+        "OUTLOOK_CLIENT_ID": "your-application-client-id"
       }
     }
   }
 }
 ```
 
-Requires an Azure app registration with Microsoft Graph delegated permissions. See README for full setup.
+`OUTLOOK_CLIENT_SECRET` is only needed for the browser sign-in flow; the default device-code flow uses the client ID alone. Claude Code users can instead install the plugin: `claude plugin marketplace add littlebearapps/outlook-assistant`, then `claude plugin install outlook-assistant@littlebearapps`. Requires an Azure app registration with Microsoft Graph delegated permissions. See README for full setup.
 
 ## Tool Categories
 
@@ -83,6 +83,6 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - [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.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, token handling, and MCP safety controls
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.13.0 — marketplace plugin bundle for Claude Code, GitHub Copilot and Cursor; Azure client ID can be given at sign-in and saved locally; client secret documented as browser-flow only)
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.12.x tool description audit, the patch-release fix queue, 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.12.0",
+  "version": "3.13.0",
   "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",
@@ -18,7 +18,8 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "prepare": "husky || true",
-    "version": "node -e \"const s=require('./server.json');const p=require('./package.json');s.version=p.version;s.packages[0].version=p.version;require('fs').writeFileSync('./server.json',JSON.stringify(s,null,2)+'\\n')\" && git add server.json"
+    "version": "node scripts/sync-version.js && git add server.json plugins/outlook-assistant",
+    "version:check": "node scripts/sync-version.js --check"
   },
   "lint-staged": {
     "*.js": [

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,
+};