@littlebearapps/outlook-assistant 3.12.1 → 3.14.0

package/folder/delete.js

@@ -3,8 +3,108 @@
  */
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
-const { resolveFolder, WELL_KNOWN } = require('./resolve');
+const { resolveFolder, listChildFolders, WELL_KNOWN } = require('./resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { dryRunResult } = require('../utils/safety');
+
+const COUNT_FIELDS = 'totalItemCount,unreadItemCount';
+const COUNT_SELECT = `id,displayName,childFolderCount,${COUNT_FIELDS}`;
+/** Most subfolders a dry run counts before reporting "at least". */
+const PREVIEW_FOLDER_LIMIT = 100;
+
+const LOSS_NOTE =
+  "It doesn't go to Deleted Items, and Graph doesn't document a way to restore it (Outlook's \"Recover deleted items\" may work for a limited time, but don't rely on it). Move out anything you need first.";
+
+function plural(count, word) {
+  return `${count} ${word}${count === 1 ? '' : 's'}`;
+}
+
+/** The folder's quoted path, or its ID if Graph gave it no name. */
+function folderLabel(resolved, quote = "'") {
+  return resolved.path
+    ? `${quote}${resolved.path}${quote}`
+    : `(unnamed, id ${resolved.id})`;
+}
+
+/**
+ * Count every subfolder below `root`, and the items in them, breadth-first.
+ * Stops after PREVIEW_FOLDER_LIMIT subfolders and flags the count partial.
+ */
+async function countSubfolders(accessToken, root, mailbox) {
+  let subfolders = 0;
+  let items = 0;
+  let partial = false;
+  const queue = root.childFolderCount > 0 ? [root.id] : [];
+  while (queue.length > 0) {
+    if (subfolders >= PREVIEW_FOLDER_LIMIT) {
+      partial = true;
+      break;
+    }
+    const children = await listChildFolders(
+      accessToken,
+      queue.shift(),
+      COUNT_SELECT,
+      mailbox
+    );
+    for (const child of children) {
+      subfolders += 1;
+      items += child.totalItemCount || 0;
+      if (child.childFolderCount > 0) queue.push(child.id);
+    }
+  }
+  return { subfolders, items, partial };
+}
+
+/**
+ * dryRun preview for delete (#274): the folder, and the items and
+ * subfolders that would be lost with it. Reads only, and reads the folder
+ * itself only if resolving it didn't already (`resolved.fields`).
+ */
+async function previewDeleteFolder(accessToken, resolved, mailbox) {
+  const prefix = buildMailboxPrefix(mailbox);
+  const folder =
+    resolved.fields ||
+    (await callGraphAPI(
+      accessToken,
+      'GET',
+      `${prefix}/mailFolders/${resolved.id}`,
+      null,
+      { $select: COUNT_SELECT }
+    ));
+  const items = folder.totalItemCount || 0;
+  const unread = folder.unreadItemCount || 0;
+  const below = await countSubfolders(
+    accessToken,
+    { ...folder, id: resolved.id },
+    mailbox
+  );
+  const where = mailbox ? ` in ${mailbox}` : '';
+  const name = `${folderLabel(resolved)}${where}`;
+
+  let summary;
+  if (items === 0 && below.subfolders === 0) {
+    summary = `Deletes folder ${name}. It's empty: no items or subfolders.`;
+  } else {
+    const atLeast = below.partial ? 'at least ' : '';
+    summary = `Deletes folder ${name} and everything in it: ${plural(items, 'item')}`;
+    if (unread > 0) summary += ` (${unread} unread)`;
+    if (below.subfolders > 0) {
+      summary += `, plus ${atLeast}${plural(below.subfolders, 'subfolder')} holding ${atLeast}${below.items} more ${below.items === 1 ? 'item' : 'items'}`;
+    }
+    summary += '.';
+  }
+
+  return dryRunResult([summary, LOSS_NOTE], {
+    action: 'delete',
+    folderId: resolved.id,
+    path: resolved.path,
+    items,
+    subfolders: below.subfolders,
+    subfolderItems: below.items,
+    partial: below.partial,
+  });
+}
 
 /**
  * Delete folder handler
@@ -22,31 +122,19 @@ const { buildMailboxPrefix } = require('../utils/mailbox');
  * @returns {object} - MCP response
  */
 async function handleDeleteFolder(args) {
-  const { folderId, folderName } = args;
+  const { folderId, folderName, dryRun = false } = args;
   const sharedMailbox = args.sharedMailbox || args.email || null;
   const prefix = buildMailboxPrefix(sharedMailbox);
 
   if (!folderId && !folderName) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Either folderId or folderName is required.',
-        },
-      ],
-    };
+    return toolError('Either folderId or folderName is required.');
   }
 
   // Name/alias guard for the common accidental case.
   if (folderName && WELL_KNOWN[folderName.toLowerCase().trim()]) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Cannot delete protected folder "${folderName}". Protected folders: Inbox, Drafts, Sent Items, Deleted Items, Junk Email, Archive, Outbox.`,
-        },
-      ],
-    };
+    return toolError(
+      `Cannot delete protected folder "${folderName}". Protected folders: Inbox, Drafts, Sent Items, Deleted Items, Junk Email, Archive, Outbox.`
+    );
   }
 
   try {
@@ -60,11 +148,16 @@ async function handleDeleteFolder(args) {
         id: folderId,
         name: folderName,
         mailbox: sharedMailbox,
+        // A dry run by ID reads the counts in the same request.
+        ...(dryRun && { extraSelect: COUNT_FIELDS }),
       });
     } catch (resolveError) {
-      return {
-        content: [{ type: 'text', text: resolveError.message }],
-      };
+      return toolError(resolveError.message);
+    }
+
+    // dryRun: say what would be lost; delete nothing.
+    if (dryRun) {
+      return await previewDeleteFolder(accessToken, resolved, sharedMailbox);
     }
 
     // Delete the folder
@@ -77,29 +170,15 @@ async function handleDeleteFolder(args) {
       content: [
         {
           type: 'text',
-          text: `Folder "${resolved.path}" deleted successfully.`,
+          text: `Folder ${folderLabel(resolved, '"')} deleted successfully.`,
         },
       ],
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error deleting folder: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error deleting folder: ${error.message}`);
   }
 }
 

package/folder/index.js

@@ -6,19 +6,17 @@ const handleCreateFolder = require('./create');
 const handleMoveEmails = require('./move');
 const handleGetFolderStats = require('./stats');
 const handleDeleteFolder = require('./delete');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError } = require('../utils/tool-error');
+const { dryRunUnsupported } = require('../utils/safety');
 
 // Consolidated folder tool definition
 const folderTools = [
   {
     name: 'folders',
     description:
-      "Manage mail folders (tool-level destructiveHint=true because `delete` removes a folder and its contents; `list` and `stats` are read-only sub-actions despite the annotation). Folders can be addressed by name, by a slash-separated PATH for nested folders (e.g. `Triage/Delete`, `Inbox/Clients/Acme`, case-insensitive), or by explicit ID; `list` output includes each folder's full path and `[id: …]`. A bare name resolves a unique top-level folder first, then searches nested folders (ambiguous names return the candidates — disambiguate with a path or ID). action=`list` (default) returns the folder tree (toggle `includeItemCounts` for unread/total, `includeChildren` for hierarchy). action=`create` makes a new folder under the root, or under `parentFolder` (name/path) / `parentFolderId`, and returns its id. action=`move` relocates emails (`emailIds`) into `targetFolder` (name/path) or `targetFolderId`. action=`stats` returns counts (totalItemCount/unreadItemCount) for `folder` (name/path) or `folderId`, suitable for pagination planning. action=`delete` removes a folder (by `folderName`/path or `folderId`) and its contents — it does not go to Deleted Items, and Graph doesn't document whether it can be restored (some accounts may offer Outlook's \"Recover deleted items\" for a limited time, but don't rely on it), so move out anything you might need first. Every action accepts `sharedMailbox` (alias `email`) to target a shared/delegated mailbox instead of the signed-in account — folder names, paths, and IDs are then resolved inside that mailbox. Protected folders cannot be deleted in any mailbox.",
-    annotations: {
-      title: 'Mail Folders',
-      readOnlyHint: false,
-      destructiveHint: true,
-      openWorldHint: false,
-    },
+      "Manage mail folders. Address a folder by name, by slash-separated path for nested folders (e.g. `Inbox/Clients/Acme`, case-insensitive) or by ID; a bare name matches a unique top-level folder first, then nested ones (an ambiguous name returns the candidates). action=`list` (default) returns the tree with each folder's path and id (`includeItemCounts`, `includeChildren`). action=`create` makes `name` under the root or `parentFolder`/`parentFolderId`. action=`move` moves `emailIds` into `targetFolder`/`targetFolderId`. action=`stats` returns total/unread counts for `folder` or `folderId`. action=`delete` removes a folder (`folderName`/path or `folderId`) with everything in it, subfolders included. It skips Deleted Items and Graph documents no restore path, so pass `dryRun: true` first to see what would be lost. Protected folders (Inbox, Sent Items, etc.) can't be deleted. Every action accepts `sharedMailbox` (alias `email`) to work in a shared or delegated mailbox (default: your own).",
+    ...toolMetadata('folders', 'Mail Folders'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -40,7 +38,7 @@ const folderTools = [
         sharedMailbox: {
           type: 'string',
           description:
-            'Email address of a shared/delegated mailbox to target instead of the signed-in account (all actions). Requires delegate access + Mail.Read.Shared (list/stats) or Mail.ReadWrite.Shared (create/move/delete). Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
+            'Email address of a shared/delegated mailbox to target (all actions; default: the signed-in account). Requires delegate access + Mail.Read.Shared (list/stats) or Mail.ReadWrite.Shared (create/move/delete). Work/school only; needs the server opt-in setting OUTLOOK_SHARED_MAILBOX (otherwise the call is refused with setup guidance).',
         },
         email: {
           type: 'string',
@@ -102,12 +100,20 @@ const folderTools = [
           description:
             'Folder name or path to delete — resolved to ID (action=delete). Cannot delete protected folders (Inbox, Drafts, Sent, etc.)',
         },
+        dryRun: {
+          type: 'boolean',
+          description:
+            'Preview only (action=delete): nothing is deleted. Shows the folder and how many items and subfolders would be lost. Other actions refuse dryRun and change nothing. Default false.',
+        },
       },
       additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
       const action = args.action || 'list';
+      if (args.dryRun && action !== 'delete') {
+        return dryRunUnsupported('folders', action, 'delete');
+      }
       switch (action) {
         case 'create':
           return handleCreateFolder(args);
@@ -120,14 +126,9 @@ const folderTools = [
         case 'list':
           return handleListFolders(args);
         default:
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `Unknown action '${action}'. Valid actions: list, create, move, stats, delete.`,
-              },
-            ],
-          };
+          return toolError(
+            `Unknown action '${action}'. Valid actions: list, create, move, stats, delete.`
+          );
       }
     },
   },

package/folder/list.js

@@ -3,6 +3,8 @@
  */
 const { ensureAuthenticated } = require('../auth');
 const { listChildFolders } = require('./resolve');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * List folders handler
@@ -52,24 +54,10 @@ async function handleListFolders(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error listing folders: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing folders: ${error.message}`);
   }
 }
 
@@ -133,7 +121,7 @@ async function getAllFoldersHierarchy(
           sharedMailbox
         );
       } catch (error) {
-        console.error(
+        log.debug(
           `Error getting child folders for "${folder.displayName}": ${error.message}`
         );
         warnings.push(

package/folder/move.js

@@ -5,6 +5,8 @@ const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { resolveFolder } = require('./resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 /**
  * Move emails handler
@@ -19,25 +21,15 @@ async function handleMoveEmails(args) {
   const sharedMailbox = args.sharedMailbox || args.email || null;
 
   if (!emailIds) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Email IDs are required. Please provide a comma-separated list of email IDs to move.',
-        },
-      ],
-    };
+    return toolError(
+      'Email IDs are required. Please provide a comma-separated list of email IDs to move.'
+    );
   }
 
   if (!targetFolder && !targetFolderId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Target folder is required — pass `targetFolder` (name or "Parent/Child" path) or `targetFolderId`.',
-        },
-      ],
-    };
+    return toolError(
+      'Target folder is required — pass `targetFolder` (name or "Parent/Child" path) or `targetFolderId`.'
+    );
   }
 
   try {
@@ -51,14 +43,7 @@ async function handleMoveEmails(args) {
       .filter((id) => id);
 
     if (ids.length === 0) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: 'No valid email IDs provided.',
-          },
-        ],
-      };
+      return toolError('No valid email IDs provided.');
     }
 
     // Move emails
@@ -85,24 +70,10 @@ async function handleMoveEmails(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error moving emails: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error moving emails: ${error.message}`);
   }
 }
 
@@ -157,7 +128,7 @@ async function moveEmailsToFolder(
           newId: moved?.id || emailId,
         });
       } catch (error) {
-        console.error(`Error moving email ${emailId}: ${error.message}`);
+        log.debug(`Error moving email ${emailId}: ${error.message}`);
         results.failed.push({
           id: emailId,
           error: error.message,
@@ -203,7 +174,7 @@ async function moveEmailsToFolder(
       results,
     };
   } catch (error) {
-    console.error(`Error in moveEmailsToFolder: ${error.message}`);
+    log.debug(`Error in moveEmailsToFolder: ${error.message}`);
     throw error;
   }
 }

package/folder/resolve.js

@@ -132,15 +132,18 @@ async function resolveWellKnown(accessToken, alias, mailbox) {
   return toRecord(resp, resp.displayName);
 }
 
-async function resolveById(accessToken, id, mailbox) {
+async function resolveById(accessToken, id, mailbox, extraSelect) {
   const resp = await callGraphAPI(
     accessToken,
     'GET',
     `${buildMailboxPrefix(mailbox)}/mailFolders/${id}`,
     null,
-    { $select: FOLDER_SELECT }
+    { $select: extraSelect ? `${FOLDER_SELECT},${extraSelect}` : FOLDER_SELECT }
   );
-  return toRecord(resp, resp.displayName);
+  // The ID asked for stands in if a response leaves `id` out.
+  const folder = { ...resp, id: resp?.id || id };
+  const record = toRecord(folder, folder.displayName);
+  return extraSelect ? { ...record, fields: folder } : record;
 }
 
 /**
@@ -300,8 +303,10 @@ function looksLikeFolderId(value) {
 /**
  * Resolve a folder from a name/path and/or explicit ID.
  * @param {string} accessToken
- * @param {{name?: string, id?: string, mailbox?: string|null}} spec
- * @returns {Promise<{id: string, displayName: string, parentId: string|null, path: string}>}
+ * @param {{name?: string, id?: string, mailbox?: string|null, extraSelect?: string}} spec
+ *   `extraSelect`: more fields to read when resolving by ID (e.g. item
+ *   counts), returned as `fields` so the caller needn't read the folder again
+ * @returns {Promise<{id: string, displayName: string, parentId: string|null, path: string, fields?: object}>}
  *   `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).
@@ -310,7 +315,7 @@ async function resolveFolder(accessToken, spec = {}) {
   const mailbox = spec.mailbox || null;
   const id = (spec.id || '').trim();
   if (id) {
-    return resolveById(accessToken, id, mailbox);
+    return resolveById(accessToken, id, mailbox, spec.extraSelect);
   }
   const name = (spec.name || '').trim();
   if (!name) {

package/folder/stats.js

@@ -9,6 +9,8 @@ const { ensureAuthenticated } = require('../auth');
 const { resolveFolder } = require('./resolve');
 const { buildMailboxPrefix } = require('../utils/mailbox');
 const config = require('../config');
+const { toolError, authRequiredError } = require('../utils/tool-error');
+const { log } = require('../utils/logger');
 
 const { VERBOSITY, DEFAULT_LIMITS } = config;
 
@@ -36,9 +38,7 @@ async function handleGetFolderStats(args) {
         mailbox: sharedMailbox,
       });
     } catch (resolveError) {
-      return {
-        content: [{ type: 'text', text: resolveError.message }],
-      };
+      return toolError(resolveError.message);
     }
     const folderId = resolved.id;
 
@@ -75,24 +75,10 @@ async function handleGetFolderStats(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'authenticate' tool first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error getting folder stats: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error getting folder stats: ${error.message}`);
   }
 }
 
@@ -139,7 +125,7 @@ async function getEmailDateRange(accessToken, folderId, mailbox = null) {
       return { newest, oldest };
     }
   } catch (error) {
-    console.error(`Error getting date range: ${error.message}`);
+    log.debug(`Error getting date range: ${error.message}`);
   }
 
   return null;

package/index.js

@@ -31,11 +31,15 @@ stdio. It is normally launched by an MCP client (Claude Desktop, Claude Code)
 rather than run by hand — started from a terminal it will simply wait on stdin.
 
 Key environment variables:
-  OUTLOOK_CLIENT_ID                 Azure app registration client ID
-  OUTLOOK_CLIENT_SECRET             Client secret VALUE (not the Secret ID)
+  OUTLOOK_CLIENT_ID                 Azure Application (client) ID. If you can't set env
+                                    vars, pass it to the auth tool instead (action=authenticate
+                                    clientId=<id>); it's saved to ~/.outlook-assistant-config.json
+  OUTLOOK_CLIENT_SECRET             Client secret VALUE (not the Secret ID); browser flow only
   OUTLOOK_AUTH_METHOD               device-code (default) | browser
   OUTLOOK_AUTH_AUDIENCE             common | consumers | organizations | <tenant-guid>
   OUTLOOK_SHARED_MAILBOX            Opt in to shared mailboxes: read | true (work/school only)
+  OUTLOOK_READ_ONLY                 Set to "true" to refuse every tool call that would change,
+                                    send or delete anything (reads and sign-in still work)
   OUTLOOK_ALLOWED_RECIPIENTS        Comma-separated recipient allowlist
   OUTLOOK_MAX_EMAILS_PER_SESSION    Default cap per session for every rate-limited tool
                                     (send-email, draft, manage-rules); 0 or unset = no cap
@@ -45,6 +49,9 @@ Key environment variables:
   OUTLOOK_IMMUTABLE_IDS             Set to "true" for message IDs that survive folder moves
   OUTLOOK_SEARCH_SCAN_LIMIT         Local search fallback window (default 500, max 5000)
   OUTLOOK_REQUEST_TIMEOUT_MS        Graph request inactivity timeout (default 60000)
+  OUTLOOK_DEBUG                     Set to "true" for detailed stderr logs (addresses redacted)
+  OUTLOOK_EXPORT_DIR                Extra folder export/attachment downloads may write to
+                                    (besides the temp directory, ~/Downloads, ~/Documents)
   USE_TEST_MODE                     Set to "true" to run against mock data
 
 Documentation: https://github.com/littlebearapps/outlook-assistant`;
@@ -72,27 +79,26 @@ Documentation: https://github.com/littlebearapps/outlook-assistant`;
   process.exit(0);
 }
 
-const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const {
   StdioServerTransport,
 } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const config = require('./config');
-const { createRequestHandler } = require('./request-handler');
-
-// Import module tools
-const { authTools, setToolCount } = require('./auth');
-const { calendarTools } = require('./calendar');
-const { emailTools } = require('./email');
-const { folderTools } = require('./folder');
-const { rulesTools } = require('./rules');
-const { contactsTools } = require('./contacts');
-const { categoriesTools } = require('./categories');
-const { settingsTools } = require('./settings');
-const { advancedTools } = require('./advanced');
+const { createServer } = require('./server');
+
+const { setToolCount } = require('./auth');
+const { TOOLS } = require('./tools');
+const { isDebugEnabled } = require('./utils/logger');
 
 // Log startup information
-console.error(`STARTING ${config.SERVER_NAME.toUpperCase()} MCP SERVER`);
+console.error(
+  `STARTING ${config.SERVER_NAME.toUpperCase()} MCP SERVER v${config.SERVER_VERSION}`
+);
 console.error(`Test mode is ${config.USE_TEST_MODE ? 'enabled' : 'disabled'}`);
+if (isDebugEnabled()) {
+  console.error(
+    'Debug logging is on (OUTLOOK_DEBUG): stderr includes search terms, subjects and Graph errors, with addresses and IDs redacted.'
+  );
+}
 
 // F-1 / F-48: warn at startup when safety belts are unset. Mirrors the
 // warning surfaced by `auth action=about`. Visible to operators reading
@@ -107,38 +113,10 @@ if (
   );
 }
 
-// Combine all tools
-const TOOLS = [
-  ...authTools,
-  ...calendarTools,
-  ...emailTools,
-  ...folderTools,
-  ...rulesTools,
-  ...contactsTools,
-  ...categoriesTools,
-  ...settingsTools,
-  ...advancedTools,
-];
-
 // Set dynamic tool count for auth about handler
 setToolCount(TOOLS.length);
 
-// Create server with tools capabilities
-const server = new Server(
-  { name: config.SERVER_NAME, version: config.SERVER_VERSION },
-  {
-    capabilities: {
-      tools: TOOLS.reduce((acc, tool) => {
-        acc[tool.name] = {};
-        return acc;
-      }, {}),
-    },
-  }
-);
-
-// Handle all requests. Dispatch + error-shaping logic lives in
-// request-handler.js so it is unit-testable without starting the transport.
-server.fallbackRequestHandler = createRequestHandler(TOOLS);
+const server = createServer(TOOLS);
 
 // Make the script executable
 process.on('SIGTERM', () => {