@littlebearapps/outlook-assistant 3.5.1 → 3.6.0

package/README.md

@@ -34,6 +34,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 
 - 📨 **Search and read emails** — find messages by sender, subject, date, or keywords; read full threads with conversation grouping; batch flag, move, export, or categorise multiple emails at once
 - 🛡️ **Send emails with safety controls** — dry-run preview, pre-send mail tips (out-of-office, mailbox full, delivery restrictions), session rate limiting, and recipient allowlist to prevent mistakes
+- ✏️ **Draft emails for review** — create, update, and send drafts; reply and forward as drafts; preview before saving with dry-run mode
 - 📅 **Manage your calendar** — view upcoming events, schedule meetings with attendees, decline or cancel invitations
 - 📦 **Export emails** — save to Markdown, EML, MBOX, JSON, or HTML for archiving, analysis, or migration; export search results or entire threads in one call
 - 🔍 **Investigate email headers** — check DKIM, SPF, and DMARC authentication; trace delivery chains; analyse spam scores — useful for phishing investigation and compliance
@@ -60,7 +61,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 
 | Module | Tools | What You Can Do |
 |--------|------:|-----------------|
-| **Email** | 7 | `search-emails` (list/search/delta/conversations), `read-email` (content + forensic headers), `send-email` (with dry-run + mail tips), `update-email` (read status, flags), `attachments`, `export`, `get-mail-tips` |
+| **Email** | 8 | `search-emails` (list/search/delta/conversations), `read-email` (content + forensic headers), `send-email` (with dry-run + mail tips), `draft` (create/update/send/delete/reply/forward), `update-email` (read status, flags), `attachments`, `export`, `get-mail-tips` |
 | **Calendar** | 3 | `list-events`, `create-event`, `manage-event` (decline/cancel/delete) |
 | **Contacts** | 2 | `manage-contact` (list/search/get/create/update/delete), `search-people` |
 | **Categories** | 3 | `manage-category` (CRUD), `apply-category`, `manage-focused-inbox` |
@@ -70,7 +71,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 | **Advanced** | 2 | `access-shared-mailbox`, `find-meeting-rooms` |
 | **Auth** | 1 | `auth` (status/authenticate/about) |
 
-**21 tools total** — consolidated from 55 for optimal AI performance. See the [Tools Reference](docs/quickrefs/tools-reference.md) for complete parameter details.
+**22 tools total** — consolidated from 55 for optimal AI performance. See the [Tools Reference](docs/quickrefs/tools-reference.md) for complete parameter details.
 
 ### Export Formats
 
@@ -126,7 +127,9 @@ Outlook Assistant is designed with safety-first principles for AI-driven email a
 - **Session rate limiting** — configurable via `OUTLOOK_MAX_EMAILS_PER_SESSION` (default: unlimited)
 - **Recipient allowlist** — restrict sending to approved addresses/domains via `OUTLOOK_ALLOWED_RECIPIENTS`
 
-**Token-optimised architecture** — Tools are consolidated using the STRAP (Single Tool, Resource, Action Pattern) approach. 21 tools instead of 55 reduces per-turn overhead by ~11,000 tokens (~64%), keeping more of the AI's context window available for your actual conversation. Fewer tools also means the AI selects the right tool more accurately — research shows tool selection degrades beyond ~40 tools.
+**Draft protections** — The `draft` tool shares `send-email` safety controls: dry-run preview, recipient allowlist, mail-tips validation, and rate limiting. The `send` action shares the `send-email` rate limit counter, preventing circumvention via the draft-then-send pathway.
+
+**Token-optimised architecture** — Tools are consolidated using the STRAP (Single Tool, Resource, Action Pattern) approach. 22 tools instead of 55 reduces per-turn overhead by ~11,000 tokens (~64%), keeping more of the AI's context window available for your actual conversation. Fewer tools also means the AI selects the right tool more accurately — research shows tool selection degrades beyond ~40 tools.
 
 > **Important**: These safeguards are defence-in-depth measures that reduce risk, but they are not a guarantee against unintended actions. AI-driven access to your email is inherently sensitive — always review tool calls before approving, particularly for sends and deletes. No automated guardrail is foolproof, and you remain responsible for actions taken through your mailbox.
 
@@ -149,10 +152,11 @@ npx @littlebearapps/outlook-assistant
 You need a Microsoft Azure app registration to authenticate. See the **[Azure Setup Guide](docs/guides/azure-setup.md)** for a detailed walkthrough (including first-time Azure account creation), or if you've done this before:
 
 1. Create a new app registration at [portal.azure.com](https://portal.azure.com/)
-2. Set redirect URI to `http://localhost:3333/auth/callback`
-3. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
-4. Create a client secret and copy the **Value** (not the Secret ID)
-5. Enable **"Allow public client flows"** in Authentication > Advanced settings (for device code flow)
+2. Add Microsoft Graph delegated permissions (Mail, Calendar, Contacts)
+3. Create a client secret and copy the **Value** (not the Secret ID)
+4. Under Authentication > **Add a platform** > **Mobile and desktop applications** — check `nativeclient` URI
+5. Enable **"Allow public client flows"** in Authentication > Advanced settings
+6. _(Optional)_ Set redirect URI to `http://localhost:3333/auth/callback` — only needed for browser auth flow
 
 ### 3. Configure Your MCP Client
 
@@ -373,7 +377,7 @@ This starts a local server on port 3333 to handle the OAuth callback.
 
 ```
 outlook-assistant/
-├── index.js                 # Main entry point (21 tools)
+├── index.js                 # Main entry point (22 tools)
 ├── config.js                # Configuration settings
 ├── outlook-auth-server.js   # OAuth server (port 3333)
 ├── auth/                    # Authentication module (1 tool)
@@ -465,7 +469,7 @@ USE_TEST_MODE=true npm start
 | [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |
 | [How-To Guides](docs/how-to/index.md) | 28 practical guides for email, calendar, contacts, and settings |
 | [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 21 tools with parameters |
+| [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 |
 
 Full documentation: [docs/](docs/README.md)

package/auth/index.js

@@ -4,7 +4,7 @@
 const tokenManager = require('./token-manager');
 const TokenStorage = require('./token-storage');
 const config = require('../config');
-const { authTools } = require('./tools');
+const { authTools, setToolCount } = require('./tools');
 
 // Singleton TokenStorage instance with auto-refresh support
 const tokenStorage = new TokenStorage({
@@ -39,5 +39,6 @@ module.exports = {
   tokenManager, // deprecated: use tokenStorage
   tokenStorage,
   authTools,
+  setToolCount,
   ensureAuthenticated,
 };

package/auth/tools.js

@@ -5,6 +5,12 @@ const config = require('../config');
 const tokenManager = require('./token-manager');
 const { initiateDeviceCodeFlow, pollForToken } = require('./device-code');
 
+// Dynamic tool count — set by index.js after TOOLS array is built
+let _toolCount = 0;
+function setToolCount(count) {
+  _toolCount = count;
+}
+
 /**
  * About tool handler
  * @returns {object} - MCP response
@@ -25,7 +31,7 @@ async function handleAbout() {
     `## Diagnostics\n`,
     `| Setting | Value |`,
     `|---------|-------|`,
-    `| Tools | 20 across 9 modules |`,
+    `| Tools | ${_toolCount} across 9 modules |`,
     `| Modules | auth, email, calendar, folder, rules, contacts, categories, settings, advanced |`,
     `| Timezone | ${config.DEFAULT_TIMEZONE} |`,
     `| Test Mode | ${testMode} |`,
@@ -320,6 +326,7 @@ const authTools = [
 
 module.exports = {
   authTools,
+  setToolCount,
   handleAbout,
   handleAuthenticate,
   handleDeviceCodeAuth,

package/categories/index.js

@@ -305,17 +305,26 @@ async function handleUpdateCategory(args) {
       updateData
     );
 
-    const colorName = COLOR_NAMES[response.color] || response.color;
+    // Prefer input values over response (PATCH may return partial data)
+    const updatedName = displayName || response.displayName;
+    const updatedColor = color || response.color;
+    const colorName = COLOR_NAMES[updatedColor] || updatedColor;
+
+    const updatedCategory = {
+      ...response,
+      displayName: updatedName,
+      color: updatedColor,
+    };
 
     return {
       content: [
         {
           type: 'text',
-          text: `Category updated!\n\n**Name**: ${response.displayName}\n**Color**: ${colorName} (${response.color})\n**ID**: ${response.id}`,
+          text: `Category updated!\n\n**Name**: ${updatedName}\n**Color**: ${colorName} (${updatedColor})\n**ID**: ${response.id || id}`,
         },
       ],
       _meta: {
-        category: formatCategory(response),
+        category: formatCategory(updatedCategory),
       },
     };
   } catch (error) {
@@ -428,7 +437,9 @@ async function handleApplyCategory(args) {
     };
   }
 
-  if (!categories || !Array.isArray(categories) || categories.length === 0) {
+  const applyAction = action || 'set'; // 'set', 'add', 'remove'
+
+  if (!categories || !Array.isArray(categories)) {
     return {
       content: [
         {
@@ -439,7 +450,17 @@ async function handleApplyCategory(args) {
     };
   }
 
-  const applyAction = action || 'set'; // 'set', 'add', 'remove'
+  // Empty array is only valid for action=set (clears all categories)
+  if (categories.length === 0 && applyAction !== 'set') {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'Categories array cannot be empty for add/remove. Use action=set with an empty array to clear all categories.',
+        },
+      ],
+    };
+  }
 
   try {
     const accessToken = await ensureAuthenticated();

package/email/conversations.js

@@ -17,6 +17,8 @@ const {
   formatEmailsAsCSV,
   VERBOSITY,
 } = require('../utils/response-formatter');
+// Note: buildFromFilter/buildToFilter from search.js use OData $filter which causes
+// InefficientFilter on personal accounts with $orderby. Client-side filtering used instead.
 
 /**
  * Format a date for filenames
@@ -65,10 +67,12 @@ async function handleListConversations(args) {
       'id',
       'subject',
       'from',
+      'toRecipients',
       'receivedDateTime',
       'conversationId',
       'conversationIndex',
       'isRead',
+      'hasAttachments',
       'bodyPreview',
     ].join(',');
 
@@ -79,6 +83,34 @@ async function handleListConversations(args) {
       $top: 200, // Get more to group
     };
 
+    // Apply simple $filter conditions that Graph API supports on personal accounts
+    // Complex filters (contains on subject, endswith on email) cause InefficientFilter
+    // errors, so those are handled client-side after fetching.
+    const serverFilterConditions = [];
+    if (args.hasAttachments === true) {
+      serverFilterConditions.push('hasAttachments eq true');
+    }
+    if (args.receivedAfter) {
+      try {
+        const afterDate = new Date(args.receivedAfter).toISOString();
+        serverFilterConditions.push(`receivedDateTime ge ${afterDate}`);
+      } catch (_e) {
+        /* ignore invalid date */
+      }
+    }
+    if (args.receivedBefore) {
+      try {
+        const beforeDate = new Date(args.receivedBefore).toISOString();
+        serverFilterConditions.push(`receivedDateTime le ${beforeDate}`);
+      } catch (_e) {
+        /* ignore invalid date */
+      }
+    }
+
+    if (serverFilterConditions.length > 0) {
+      queryParams.$filter = serverFilterConditions.join(' and ');
+    }
+
     const response = await callGraphAPI(
       accessToken,
       'GET',
@@ -86,7 +118,33 @@ async function handleListConversations(args) {
       null,
       queryParams
     );
-    const messages = response.value || [];
+    let messages = response.value || [];
+
+    // Client-side filtering for conditions that cause InefficientFilter on personal accounts
+    if (args.subject) {
+      const subjectLower = args.subject.toLowerCase();
+      messages = messages.filter((m) =>
+        (m.subject || '').toLowerCase().includes(subjectLower)
+      );
+    }
+    if (args.from) {
+      const fromLower = args.from.toLowerCase();
+      messages = messages.filter((m) => {
+        const addr = (m.from?.emailAddress?.address || '').toLowerCase();
+        const name = (m.from?.emailAddress?.name || '').toLowerCase();
+        return addr.includes(fromLower) || name.includes(fromLower);
+      });
+    }
+    if (args.to) {
+      const toLower = args.to.toLowerCase();
+      messages = messages.filter((m) =>
+        (m.toRecipients || []).some((r) => {
+          const addr = (r.emailAddress?.address || '').toLowerCase();
+          const name = (r.emailAddress?.name || '').toLowerCase();
+          return addr.includes(toLower) || name.includes(toLower);
+        })
+      );
+    }
 
     // Group by conversationId
     const conversations = new Map();