@littlebearapps/outlook-assistant 3.8.2 → 3.9.0

package/folder/resolve.js

@@ -0,0 +1,315 @@
+/**
+ * Shared, path-aware, ambiguity-aware mail-folder resolver. (#216)
+ *
+ * Replaces the two top-level-only resolvers (`getFolderIdByName` in
+ * email/folder-utils.js and `resolveFolderName` in folder/stats.js) that could
+ * not address nested folders. Accepts, in priority order:
+ *   1. an explicit folder ID (never guessed from a name),
+ *   2. a well-known alias (inbox, archive, sent, ...),
+ *   3. a folder PATH like "Triage/Delete" or "Inbox/Clients/Acme"
+ *      (case-insensitive, traversed segment-by-segment via childFolders),
+ *   4. a bare display name (unique top-level match wins for back-compat;
+ *      otherwise the whole tree is searched, with ambiguity reported).
+ *
+ * Returns `{ id, displayName, parentId, path }`. Throws a caller-friendly Error
+ * on not-found or ambiguity (listing candidate paths + IDs).
+ *
+ * `/` is the path separator, so a folder whose display name literally contains
+ * `/` cannot be addressed by path — use its folderId (documented on the tool).
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+
+// Alias → Graph well-known folder name (usable directly as a path segment).
+const WELL_KNOWN = {
+  inbox: 'inbox',
+  drafts: 'drafts',
+  sent: 'sentitems',
+  sentitems: 'sentitems',
+  'sent items': 'sentitems',
+  deleted: 'deleteditems',
+  deleteditems: 'deleteditems',
+  'deleted items': 'deleteditems',
+  junk: 'junkemail',
+  junkemail: 'junkemail',
+  'junk email': 'junkemail',
+  spam: 'junkemail',
+  archive: 'archive',
+  outbox: 'outbox',
+};
+
+// NB: mailFolder has no selectable `wellKnownName` property (Graph 400s on it,
+// verified against consumer accounts) — well-known folders are addressed by
+// name in the URL, not via a returned field.
+const FOLDER_SELECT = 'id,displayName,parentFolderId,childFolderCount';
+// Safety caps against pathological/looping nesting when walking the tree for a
+// bare-name search. Beyond these we refuse to guess and ask for a path/ID.
+const MAX_TREE_DEPTH = 20;
+const MAX_TREE_REQUESTS = 200;
+
+function notFoundError(spec) {
+  return new Error(
+    `Folder "${spec}" not found. Use \`folders\` action=list to see folders ` +
+      `(with IDs and full paths), pass a folder path like "Parent/Child", or a folderId.`
+  );
+}
+
+function ambiguousError(spec, candidates) {
+  const shown = candidates.slice(0, 20);
+  const lines = shown
+    .map((c) => `  - ${c.path}  (folderId: ${c.id})`)
+    .join('\n');
+  const more =
+    candidates.length > shown.length
+      ? `\n  … and ${candidates.length - shown.length} more`
+      : '';
+  return new Error(
+    `Folder "${spec}" is ambiguous — ${candidates.length} folders match:\n${lines}${more}\n` +
+      `Disambiguate with a folder path (e.g. "Parent/Child") or a folderId.`
+  );
+}
+
+/**
+ * List child folders of `parentId` (or top-level when null), following
+ * @odata.nextLink so folders with many children resolve completely.
+ * @returns {Promise<Array<{id, displayName, parentFolderId, childFolderCount}>>}
+ */
+async function listChildFolders(accessToken, parentId, select = FOLDER_SELECT) {
+  const all = [];
+  let path = parentId
+    ? `me/mailFolders/${parentId}/childFolders`
+    : 'me/mailFolders';
+  let params = { $top: 100, $select: select };
+  // Follow pagination; nextLink already encodes params. Guard against a
+  // repeated/malformed nextLink so a bad server response can't loop forever.
+  const seen = new Set();
+  while (path) {
+    if (seen.has(path)) {
+      throw new Error(
+        'Graph returned a repeated folder pagination link — aborting to avoid a loop.'
+      );
+    }
+    seen.add(path);
+    const resp = await callGraphAPI(accessToken, 'GET', path, null, params);
+    if (Array.isArray(resp.value)) {
+      all.push(...resp.value);
+    }
+    path = resp['@odata.nextLink'] || null;
+    params = {};
+  }
+  return all;
+}
+
+function toRecord(folder, path) {
+  return {
+    id: folder.id,
+    displayName: folder.displayName,
+    parentId: folder.parentFolderId || null,
+    path: path || folder.displayName,
+  };
+}
+
+async function resolveWellKnown(accessToken, alias) {
+  const resp = await callGraphAPI(
+    accessToken,
+    'GET',
+    `me/mailFolders/${WELL_KNOWN[alias]}`,
+    null,
+    { $select: FOLDER_SELECT }
+  );
+  return toRecord(resp, resp.displayName);
+}
+
+async function resolveById(accessToken, id) {
+  const resp = await callGraphAPI(
+    accessToken,
+    'GET',
+    `me/mailFolders/${id}`,
+    null,
+    { $select: FOLDER_SELECT }
+  );
+  return toRecord(resp, resp.displayName);
+}
+
+/**
+ * Build a flat list of every folder with its full path, breadth-first.
+ * Accepts an already-fetched top-level list to avoid re-fetching.
+ */
+async function buildTree(accessToken, topLevel) {
+  const top = topLevel || (await listChildFolders(accessToken, null));
+  const out = [];
+  const visited = new Set();
+  const queue = top.map((f) => ({ folder: f, path: f.displayName, depth: 1 }));
+  let requests = 0;
+  // Index-based iteration (no O(n^2) shift); visited-set defends against
+  // cyclic/duplicate API data.
+  for (let i = 0; i < queue.length; i++) {
+    const { folder, path, depth } = queue[i];
+    if (visited.has(folder.id)) {
+      continue;
+    }
+    visited.add(folder.id);
+    out.push(toRecord(folder, path));
+    if (folder.childFolderCount > 0) {
+      // Refuse to return a "unique" bare-name result from a truncated scan —
+      // a match could exist in the unexplored remainder. Ask for a path/ID.
+      if (depth >= MAX_TREE_DEPTH) {
+        throw new Error(
+          `Folder tree exceeds the ${MAX_TREE_DEPTH}-level resolution limit — ` +
+            'use an explicit folder path or folderId.'
+        );
+      }
+      if (++requests > MAX_TREE_REQUESTS) {
+        throw new Error(
+          'Folder tree is too large to search by bare name — ' +
+            'use an explicit folder path or folderId.'
+        );
+      }
+      const children = await listChildFolders(accessToken, folder.id);
+      for (const child of children) {
+        queue.push({
+          folder: child,
+          path: `${path}/${child.displayName}`,
+          depth: depth + 1,
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function matchName(folders, name) {
+  const lower = name.toLowerCase();
+  return folders.filter((f) => f.displayName.toLowerCase() === lower);
+}
+
+/**
+ * Resolve a bare display name: a unique top-level match wins (fast path,
+ * back-compat); otherwise search the whole tree, reporting ambiguity.
+ */
+async function resolveByName(accessToken, name) {
+  const top = await listChildFolders(accessToken, null);
+  const topMatches = matchName(top, name);
+  if (topMatches.length === 1) {
+    return toRecord(topMatches[0], topMatches[0].displayName);
+  }
+  if (topMatches.length > 1) {
+    throw ambiguousError(
+      name,
+      topMatches.map((m) => ({ id: m.id, path: m.displayName }))
+    );
+  }
+  // Not top-level — search nested folders.
+  const tree = await buildTree(accessToken, top);
+  const matches = matchName(tree, name);
+  if (matches.length === 0) {
+    throw notFoundError(name);
+  }
+  if (matches.length > 1) {
+    throw ambiguousError(name, matches);
+  }
+  return matches[0];
+}
+
+/**
+ * Resolve a path (segments already split/trimmed) by traversing childFolders.
+ */
+async function resolvePath(accessToken, segments) {
+  let current;
+  const first = segments[0];
+  if (WELL_KNOWN[first.toLowerCase()]) {
+    current = await resolveWellKnown(accessToken, first.toLowerCase());
+  } else {
+    const top = await listChildFolders(accessToken, null);
+    const matches = matchName(top, first);
+    if (matches.length === 0) {
+      throw notFoundError(first);
+    }
+    if (matches.length > 1) {
+      throw ambiguousError(
+        first,
+        matches.map((m) => ({ id: m.id, path: m.displayName }))
+      );
+    }
+    current = toRecord(matches[0], matches[0].displayName);
+  }
+
+  for (let i = 1; i < segments.length; i++) {
+    const seg = segments[i];
+    const children = await listChildFolders(accessToken, current.id);
+    const matches = matchName(children, seg);
+    if (matches.length === 0) {
+      throw notFoundError(`${current.path}/${seg}`);
+    }
+    if (matches.length > 1) {
+      throw ambiguousError(
+        `${current.path}/${seg}`,
+        matches.map((m) => ({
+          id: m.id,
+          path: `${current.path}/${m.displayName}`,
+        }))
+      );
+    }
+    current = {
+      id: matches[0].id,
+      displayName: matches[0].displayName,
+      parentId: current.id,
+      path: `${current.path}/${matches[0].displayName}`,
+    };
+  }
+  return current;
+}
+
+/**
+ * Resolve a folder from a name/path and/or explicit ID.
+ * @param {string} accessToken
+ * @param {{name?: string, id?: string}} spec
+ * @returns {Promise<{id: string, displayName: string, parentId: string|null, path: string}>}
+ *   `path` is the full slash-separated path when resolved by name/path/alias;
+ *   when resolved by ID it is the folder's display name only (ancestors are not
+ *   fetched).
+ */
+async function resolveFolder(accessToken, spec = {}) {
+  const id = (spec.id || '').trim();
+  if (id) {
+    return resolveById(accessToken, id);
+  }
+  const name = (spec.name || '').trim();
+  if (!name) {
+    throw new Error('A folder name, path, or folderId is required.');
+  }
+  if (name.includes('/')) {
+    // Trim each segment and drop leading/trailing empties ("/Inbox/" is fine),
+    // but reject INTERIOR empty segments ("A//B") so a typo can't silently
+    // collapse to a real folder — important for the destructive delete path.
+    const segments = name.split('/').map((s) => s.trim());
+    while (segments.length && segments[0] === '') {
+      segments.shift();
+    }
+    while (segments.length && segments[segments.length - 1] === '') {
+      segments.pop();
+    }
+    if (segments.length === 0) {
+      throw new Error(`Invalid folder path "${spec.name}".`);
+    }
+    if (segments.some((s) => s === '')) {
+      throw new Error(
+        `Invalid folder path "${spec.name}": empty path segment.`
+      );
+    }
+    if (segments.length === 1) {
+      return resolveFolder(accessToken, { name: segments[0] });
+    }
+    return resolvePath(accessToken, segments);
+  }
+  if (WELL_KNOWN[name.toLowerCase()]) {
+    return resolveWellKnown(accessToken, name.toLowerCase());
+  }
+  return resolveByName(accessToken, name);
+}
+
+module.exports = {
+  WELL_KNOWN,
+  resolveFolder,
+  listChildFolders,
+  buildTree,
+};

package/folder/stats.js

@@ -6,6 +6,7 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
+const { resolveFolder } = require('./resolve');
 const config = require('../config');
 
 const { VERBOSITY, DEFAULT_LIMITS } = config;
@@ -17,24 +18,25 @@ const { VERBOSITY, DEFAULT_LIMITS } = config;
  */
 async function handleGetFolderStats(args) {
   const folderName = args.folder || 'inbox';
+  const folderIdArg = args.folderId || '';
   const verbosity = args.outputVerbosity || VERBOSITY.STANDARD;
 
   try {
     const accessToken = await ensureAuthenticated();
 
-    // Resolve folder name to ID
-    const folderId = await resolveFolderName(accessToken, folderName);
-
-    if (!folderId) {
+    // Resolve folder (name/path/alias/ID → concrete folder). (#216)
+    let resolved;
+    try {
+      resolved = await resolveFolder(accessToken, {
+        name: folderName,
+        id: folderIdArg,
+      });
+    } catch (resolveError) {
       return {
-        content: [
-          {
-            type: 'text',
-            text: `Folder "${folderName}" not found.`,
-          },
-        ],
+        content: [{ type: 'text', text: resolveError.message }],
       };
     }
+    const folderId = resolved.id;
 
     // Get folder details with full stats
     const folder = await callGraphAPI(
@@ -90,71 +92,6 @@ async function handleGetFolderStats(args) {
   }
 }
 
-/**
- * Resolve folder name to ID
- * @param {string} accessToken - Access token
- * @param {string} folderName - Folder name or well-known name
- * @returns {Promise<string|null>} - Folder ID or null
- */
-async function resolveFolderName(accessToken, folderName) {
-  const wellKnownFolders = {
-    inbox: 'inbox',
-    sent: 'sentitems',
-    sentitems: 'sentitems',
-    'sent items': 'sentitems',
-    drafts: 'drafts',
-    deleted: 'deleteditems',
-    deleteditems: 'deleteditems',
-    'deleted items': 'deleteditems',
-    junk: 'junkemail',
-    junkemail: 'junkemail',
-    'junk email': 'junkemail',
-    spam: 'junkemail',
-    archive: 'archive',
-    outbox: 'outbox',
-  };
-
-  const normalised = folderName.toLowerCase().trim();
-
-  // Check if it's a well-known folder
-  if (wellKnownFolders[normalised]) {
-    try {
-      const response = await callGraphAPI(
-        accessToken,
-        'GET',
-        `me/mailFolders/${wellKnownFolders[normalised]}`,
-        null,
-        { $select: 'id' }
-      );
-      return response.id;
-    } catch (_error) {
-      // Fall through to search
-    }
-  }
-
-  // Search for folder by name
-  try {
-    const response = await callGraphAPI(
-      accessToken,
-      'GET',
-      'me/mailFolders',
-      null,
-      {
-        $filter: `displayName eq '${folderName}'`,
-        $select: 'id',
-      }
-    );
-
-    if (response.value && response.value.length > 0) {
-      return response.value[0].id;
-    }
-  } catch (error) {
-    console.error(`Error searching for folder: ${error.message}`);
-  }
-
-  return null;
-}
-
 /**
  * Get date range of emails in folder
  * @param {string} accessToken - Access token

package/llms.txt

@@ -22,13 +22,13 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 
 ## Key Differentiators
 
-- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently. Explicit "no results" messaging instead of unfiltered fallback.
+- **Progressive search**: Automatically falls back through 4 search strategies when Microsoft's `$search` API is unavailable (personal accounts) — most Graph API wrappers fail silently. Explicit "no results" messaging instead of unfiltered fallback. Cross-folder search (`searchAllFolders`) reliably returns a superset of inbox results.
 - **Remote-friendly auth**: Device code flow (default) — no auth server, no port forwarding, no SSH tunnels. State persists across MCP server restarts. Works from Untether, mosh, SSH, and headless environments.
 - **Email forensics**: Built-in header analysis for DKIM, SPF, DMARC authentication, delivery chains, and spam scores — useful for phishing investigation and compliance
 - **Delta sync**: Incremental inbox monitoring — returns only new, modified, and deleted emails since last check, with tokens for continuous polling
 - **Batch operations**: Flag, move, export, or categorise multiple emails in a single tool call; search-driven export for batch archiving without collecting IDs
 - **Pre-send intelligence**: Check recipients for out-of-office, mailbox full, delivery restrictions, and moderation before sending — no other Outlook MCP server offers this
-- **Compound automation**: Rules + categories + folders + Focused Inbox for complete inbox management in one conversation
+- **Compound automation**: Rules + categories + nested folders (addressable by path or ID) + Focused Inbox for complete inbox management in one conversation
 
 ## Safety & Token Efficiency
 
@@ -63,7 +63,7 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 - **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`
 - **Contacts (2 tools)**: `manage-contact`, `search-people`
-- **Folders (1 tool)**: `folders` — list, create, move, stats
+- **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
@@ -79,6 +79,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.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)
+- [CHANGELOG](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/CHANGELOG.md): Version history (current: v3.9.0 — nested folder addressing by path/ID (#216); reliable cross-folder search with `kqlQuery` renamed to `searchExpression` (#169); plus the v3.8.3 patch — security `overrides` clearing the audit gate (#215), `openWorldHint` on external-content tools (#92), canonical UTC ISO-8601 `list-events` times (#118))
+- [ROADMAP](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/ROADMAP.md): Active milestones (v3.7.5 polish, v3.8.x carry-over, v3.10.0+ new Graph APIs)
 - [SECURITY](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/SECURITY.md): Security policy, token handling, and MCP safety controls

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.8.2",
+  "version": "3.9.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",
@@ -96,6 +96,9 @@
     "node": ">=18.18.0"
   },
   "overrides": {
-    "minimatch": ">=3.1.3"
+    "minimatch": ">=3.1.3",
+    "hono": "^4.12.31",
+    "fast-uri": "^3.1.4",
+    "body-parser": "^2.3.0"
   }
 }

package/utils/graph-api.js

@@ -90,8 +90,18 @@ async function callGraphAPI(
         headers.Prefer = 'IdType="ImmutableId"';
       }
 
-      // Merge any extra headers (caller overrides take precedence)
+      // Merge any extra headers (caller overrides take precedence). `Prefer`
+      // is multi-valued in HTTP (comma-separated); combine both values rather
+      // than letting a caller Prefer (e.g. outlook.timezone) clobber the global
+      // immutable-IDs Prefer, or vice versa.
+      const combinedPrefer =
+        headers.Prefer && extraHeaders.Prefer
+          ? `${headers.Prefer}, ${extraHeaders.Prefer}`
+          : null;
       Object.assign(headers, extraHeaders);
+      if (combinedPrefer) {
+        headers.Prefer = combinedPrefer;
+      }
 
       const options = {
         method: method,