@littlebearapps/outlook-assistant 3.4.1 → 3.5.0

package/.env.example

@@ -20,3 +20,6 @@ USE_TEST_MODE=false
 
 # Restrict sending to specific domains/addresses (comma-separated)
 # OUTLOOK_ALLOWED_RECIPIENTS=mycompany.com,partner@example.com
+
+# Optional: Enable immutable IDs (IDs persist through folder moves)
+# OUTLOOK_IMMUTABLE_IDS=true

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/outlook-assistant-logo-full.svg" height="200" alt="Outlook Assistant" />
+  <img src="https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/assets/outlook-assistant-logo-full.png" height="200" alt="Outlook Assistant" />
 </p>
 
 <h1 align="center">Outlook Assistant</h1>
@@ -11,13 +11,9 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@littlebearapps/outlook-assistant"><img src="https://img.shields.io/npm/v/@littlebearapps/outlook-assistant" alt="npm version" /></a>
   <a href="https://www.npmjs.com/package/@littlebearapps/outlook-assistant"><img src="https://img.shields.io/npm/dm/@littlebearapps/outlook-assistant" alt="npm downloads" /></a>
-  <a href="https://github.com/littlebearapps/outlook-assistant/stargazers"><img src="https://img.shields.io/github/stars/littlebearapps/outlook-assistant" alt="GitHub stars" /></a>
-  <a href="https://github.com/littlebearapps/outlook-assistant/commits/main"><img src="https://img.shields.io/github/last-commit/littlebearapps/outlook-assistant" alt="Last commit" /></a>
   <a href="https://github.com/littlebearapps/outlook-assistant/actions/workflows/ci.yml"><img src="https://github.com/littlebearapps/outlook-assistant/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
   <a href="https://github.com/littlebearapps/outlook-assistant/actions/workflows/codeql.yml"><img src="https://github.com/littlebearapps/outlook-assistant/actions/workflows/codeql.yml/badge.svg" alt="CodeQL" /></a>
-  <a href="https://github.com/littlebearapps/outlook-assistant/issues"><img src="https://img.shields.io/github/issues/littlebearapps/outlook-assistant" alt="Open issues" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen" alt="Node.js" /></a>
 </p>
 
 Outlook Assistant connects AI assistants to your Microsoft Outlook account through the [Model Context Protocol](https://modelcontextprotocol.io/). Ask your AI assistant to search your inbox, send emails, schedule meetings, manage contacts, and configure mailbox settings — without leaving the conversation. Works with Claude, Cursor, Windsurf, and any MCP-compatible client.
@@ -37,7 +33,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 ### What you can do
 
 - 📨 **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, session rate limiting, and recipient allowlist to prevent mistakes
+- 🛡️ **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
 - 📅 **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
@@ -64,7 +60,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 
 | Module | Tools | What You Can Do |
 |--------|------:|-----------------|
-| **Email** | 6 | `search-emails` (list/search/delta/conversations), `read-email` (content + forensic headers), `send-email` (with dry-run), `update-email` (read status, flags), `attachments`, `export` |
+| **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` |
 | **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` |
@@ -74,7 +70,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) |
 
-**20 tools total** — consolidated from 55 for optimal AI performance. See the [Tools Reference](docs/quickrefs/tools-reference.md) for complete parameter details.
+**21 tools total** — consolidated from 55 for optimal AI performance. See the [Tools Reference](docs/quickrefs/tools-reference.md) for complete parameter details.
 
 ### Export Formats
 
@@ -115,6 +111,7 @@ Outlook Assistant works with both personal and work/school Microsoft accounts, b
 - **Email forensics** — full header analysis (DKIM, SPF, DMARC, delivery chain, spam scores) built in as a first-class feature — useful for phishing investigation, compliance, and security review.
 - **Delta sync** — incremental inbox monitoring returns only what changed since your last check, with tokens for continuous polling. Designed for agent workflows that need to watch a mailbox.
 - **Batch operations** — flag, move, export, or categorise multiple emails in a single call. Search-driven export lets you batch-export results without collecting IDs manually.
+- **Pre-send intelligence** — check recipients for out-of-office, full mailbox, delivery restrictions, and moderation status before sending — no other Outlook MCP server offers this.
 - **Compound automation** — rules, categories, folders, and Focused Inbox work together. Set up complete inbox management through your AI assistant in one conversation.
 
 ## Safety & Token Efficiency
@@ -124,11 +121,12 @@ Outlook Assistant is designed with safety-first principles for AI-driven email a
 **Destructive action safeguards** — Every tool carries [MCP annotations](https://modelcontextprotocol.io/docs/concepts/tools#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so AI clients can auto-approve safe reads and prompt for confirmation on destructive operations like sending email or deleting events.
 
 **Send-email protections** — The `send-email` tool includes:
+- **Pre-send mail tips** (`checkRecipients: true`) — check recipients for out-of-office, mailbox full, delivery restrictions before sending
 - **Dry-run mode** (`dryRun: true`) — preview composed emails without sending
 - **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. 20 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.
+**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.
 
 > **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.
 
@@ -191,6 +189,10 @@ Then set environment variables in your `.env` or shell.
 <details>
 <summary><strong>Cursor</strong> (<code>.cursor/mcp.json</code>)</summary>
 
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=Outlook%20Assistant&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsaXR0bGViZWFyYXBwcy9vdXRsb29rLWFzc2lzdGFudCJdLCJlbnYiOnsiT1VUTE9PS19DTElFTlRfSUQiOiIiLCJPVVRMT09LX0NMSUVOVF9TRUNSRVQiOiIifX0=)
+
+Or add manually to `.cursor/mcp.json`:
+
 ```json
 {
   "mcpServers": {
@@ -359,11 +361,12 @@ This starts a local server on port 3333 to handle the OAuth callback.
 
 ```
 outlook-assistant/
-├── index.js                 # Main entry point (20 tools)
+├── index.js                 # Main entry point (21 tools)
 ├── config.js                # Configuration settings
 ├── outlook-auth-server.js   # OAuth server (port 3333)
 ├── auth/                    # Authentication module (1 tool)
-├── email/                   # Email module (6 tools)
+├── email/                   # Email module (7 tools)
+│   ├── mail-tips.js         # Pre-send recipient validation
 │   ├── headers.js           # Email header retrieval
 │   ├── mime.js              # Raw MIME/EML content
 │   ├── conversations.js     # Thread listing/export
@@ -377,7 +380,7 @@ outlook-assistant/
 ├── rules/                   # Rules module (1 tool)
 ├── advanced/                # Advanced module (2 tools)
 └── utils/
-    ├── graph-api.js         # Microsoft Graph API client
+    ├── graph-api.js         # Microsoft Graph API client (includes $batch)
     ├── safety.js            # Rate limiting, recipient allowlist, dry-run
     ├── odata-helpers.js     # OData query building
     ├── field-presets.js     # Token-efficient field selections
@@ -444,9 +447,9 @@ USE_TEST_MODE=true npm start
 |-------|-------------|
 | [Getting Started](docs/how-to/getting-started/connect-outlook-to-claude.md) | Install, configure, and authenticate — start here |
 | [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |
-| [How-To Guides](docs/how-to/index.md) | 27 practical guides for email, calendar, contacts, and settings |
+| [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 20 tools with parameters |
+| [Tools Reference](docs/quickrefs/tools-reference.md) | All 21 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/config.js

@@ -90,6 +90,9 @@ module.exports = {
   // Search defaults (reduced for token efficiency)
   DEFAULT_SEARCH_RESULTS: DEFAULT_LIMITS.searchEmails,
 
+  // Immutable IDs (opt-in: IDs persist through folder moves)
+  USE_IMMUTABLE_IDS: process.env.OUTLOOK_IMMUTABLE_IDS === 'true',
+
   // Timezone
   DEFAULT_TIMEZONE: 'Australia/Melbourne', // Updated for Nathan's timezone
 };

package/email/export.js

@@ -281,10 +281,8 @@ async function handleBatchExportEmails(args) {
       }
 
       const csvContent = formatEmailsAsCSV(emails);
-      const csvPath = path.join(
-        outputDir,
-        `batch_export_${new Date().toISOString().slice(0, 10)}.csv`
-      );
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const csvPath = path.join(outputDir, `batch_export_${timestamp}.csv`);
       fs.writeFileSync(csvPath, csvContent, 'utf8');
       const totalBytes = Buffer.byteLength(csvContent, 'utf8');
 

package/email/index.js

@@ -22,6 +22,7 @@ const {
   handleGetConversation,
   handleExportConversation,
 } = require('./conversations');
+const { handleGetMailTips } = require('./mail-tips');
 
 // Import flag handlers from advanced module
 const { handleSetMessageFlag, handleClearMessageFlag } = require('../advanced');
@@ -278,6 +279,11 @@ const emailTools = [
           description:
             'Preview email without sending (default: false). Returns composed email for review.',
         },
+        checkRecipients: {
+          type: 'boolean',
+          description:
+            'Check recipients for out-of-office, mailbox full, delivery restrictions before sending (default: false). Combine with dryRun=true for pre-send review.',
+        },
       },
       required: ['to', 'subject', 'body'],
     },
@@ -513,6 +519,42 @@ const emailTools = [
       }
     },
   },
+  {
+    name: 'get-mail-tips',
+    description:
+      'Check recipients before sending: out-of-office status, mailbox full, external recipients, delivery restrictions, moderation, group member counts, and max message size. No competitor offers this.',
+    annotations: {
+      title: 'Mail Tips',
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+    inputSchema: {
+      type: 'object',
+      properties: {
+        recipients: {
+          oneOf: [
+            {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'Array of email addresses to check',
+            },
+            {
+              type: 'string',
+              description: 'Comma-separated email addresses to check',
+            },
+          ],
+          description: 'Email addresses to check for mail tips',
+        },
+        tipTypes: {
+          type: 'string',
+          description:
+            'Comma-separated tip types to request (default: all). Options: automaticReplies, mailboxFullStatus, customMailTip, externalMemberCount, totalMemberCount, maxMessageSize, deliveryRestriction, moderationStatus, recipientScope, recipientSuggestions',
+        },
+      },
+      required: ['recipients'],
+    },
+    handler: handleGetMailTips,
+  },
 ];
 
 module.exports = {
@@ -534,4 +576,5 @@ module.exports = {
   handleListConversations,
   handleGetConversation,
   handleExportConversation,
+  handleGetMailTips,
 };

package/email/mail-tips.js

@@ -0,0 +1,211 @@
+/**
+ * Mail tips functionality — pre-send validation via Graph API
+ *
+ * Checks recipients for out-of-office, mailbox full, external,
+ * delivery restrictions, and more before sending.
+ */
+const { callGraphAPI } = require('../utils/graph-api');
+const { ensureAuthenticated } = require('../auth');
+
+/**
+ * All available mail tip types from Microsoft Graph API
+ */
+const MAIL_TIP_TYPES = [
+  'automaticReplies',
+  'mailboxFullStatus',
+  'customMailTip',
+  'externalMemberCount',
+  'totalMemberCount',
+  'maxMessageSize',
+  'deliveryRestriction',
+  'moderationStatus',
+  'recipientScope',
+  'recipientSuggestions',
+];
+
+/**
+ * Format mail tips into readable markdown
+ * @param {Array} mailTips - Array of mail tip objects from Graph API
+ * @returns {string} - Formatted markdown output
+ */
+function formatMailTips(mailTips) {
+  const lines = [];
+  let warningCount = 0;
+
+  for (const tip of mailTips) {
+    const email = tip.emailAddress?.address || 'Unknown';
+    const tipLines = [];
+    const warnings = [];
+
+    // Out-of-office / automatic replies
+    if (
+      tip.automaticReplies?.message &&
+      tip.automaticReplies.message.trim() !== ''
+    ) {
+      warnings.push('Out of Office');
+      const reply = tip.automaticReplies;
+      tipLines.push(
+        `  **Out of Office**: ${reply.message.replace(/\n/g, ' ').substring(0, 200)}`
+      );
+      if (reply.scheduledStartTime || reply.scheduledEndTime) {
+        const start = reply.scheduledStartTime?.dateTime || '';
+        const end = reply.scheduledEndTime?.dateTime || '';
+        if (start || end) {
+          tipLines.push(`  *Schedule*: ${start} → ${end}`);
+        }
+      }
+    }
+
+    // Mailbox full
+    if (tip.mailboxFullStatus) {
+      warnings.push('Mailbox Full');
+      tipLines.push(
+        `  **Mailbox Full**: Recipient's mailbox is full — delivery may fail`
+      );
+    }
+
+    // Custom mail tip (admin-configured)
+    if (tip.customMailTip) {
+      warnings.push('Custom Tip');
+      tipLines.push(`  **Notice**: ${tip.customMailTip}`);
+    }
+
+    // Delivery restriction
+    if (tip.deliveryRestriction) {
+      const restriction = tip.deliveryRestriction;
+      if (restriction.isDeliveryRestricted) {
+        warnings.push('Delivery Restricted');
+        tipLines.push(
+          `  **Delivery Restricted**: ${restriction.message || 'Cannot deliver to this recipient'}`
+        );
+      }
+    }
+
+    // Moderation status
+    if (tip.moderationStatus && tip.moderationStatus !== 'notModerated') {
+      warnings.push('Moderated');
+      tipLines.push(
+        `  **Moderated**: Messages to this recipient require approval`
+      );
+    }
+
+    // Recipient scope (external)
+    if (tip.recipientScope === 'external') {
+      tipLines.push(`  **External**: Recipient is outside your organisation`);
+    }
+
+    // Max message size
+    if (tip.maxMessageSize && tip.maxMessageSize > 0) {
+      const sizeMB = (tip.maxMessageSize / (1024 * 1024)).toFixed(1);
+      tipLines.push(`  *Max message size*: ${sizeMB} MB`);
+    }
+
+    // Group member counts
+    if (tip.totalMemberCount > 0) {
+      tipLines.push(
+        `  *Group members*: ${tip.totalMemberCount} total (${tip.externalMemberCount || 0} external)`
+      );
+    }
+
+    // Build section for this recipient
+    const statusIcon = warnings.length > 0 ? '⚠' : '✓';
+    lines.push(`### ${statusIcon} ${email}`);
+
+    if (warnings.length > 0) {
+      lines.push(`**Warnings**: ${warnings.join(', ')}`);
+      warningCount += warnings.length;
+    }
+
+    if (tipLines.length > 0) {
+      lines.push(tipLines.join('\n'));
+    } else {
+      lines.push('  No issues detected');
+    }
+    lines.push('');
+  }
+
+  return { formatted: lines.join('\n'), warningCount };
+}
+
+/**
+ * Get mail tips for specified recipients
+ * @param {object} args - Tool arguments
+ * @returns {object} - MCP response
+ */
+async function handleGetMailTips(args) {
+  const { recipients, tipTypes } = args;
+
+  if (!recipients || recipients.length === 0) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: 'At least one recipient email address is required.',
+        },
+      ],
+    };
+  }
+
+  try {
+    const accessToken = await ensureAuthenticated();
+
+    const requestBody = {
+      EmailAddresses: Array.isArray(recipients)
+        ? recipients
+        : recipients.split(',').map((e) => e.trim()),
+      MailTipsOptions: tipTypes || MAIL_TIP_TYPES.join(','),
+    };
+
+    const response = await callGraphAPI(
+      accessToken,
+      'POST',
+      'me/getMailTips',
+      requestBody
+    );
+
+    const mailTips = response.value || [];
+
+    if (mailTips.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'No mail tips returned for the specified recipients.',
+          },
+        ],
+      };
+    }
+
+    const { formatted, warningCount } = formatMailTips(mailTips);
+
+    let header = `# Mail Tips\n\n`;
+    header += `**Recipients checked**: ${mailTips.length}\n`;
+    header += `**Warnings**: ${warningCount}\n\n`;
+
+    return {
+      content: [{ type: 'text', text: header + formatted }],
+      _meta: {
+        recipientCount: mailTips.length,
+        warningCount,
+      },
+    };
+  } catch (error) {
+    if (error.message === 'Authentication required') {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
+          },
+        ],
+      };
+    }
+    return {
+      content: [
+        { type: 'text', text: `Error getting mail tips: ${error.message}` },
+      ],
+    };
+  }
+}
+
+module.exports = { handleGetMailTips, formatMailTips, MAIL_TIP_TYPES };

package/email/send.js

@@ -9,6 +9,7 @@ const {
   checkRecipientAllowlist,
   formatDryRunPreview,
 } = require('../utils/safety');
+const { handleGetMailTips } = require('./mail-tips');
 
 /**
  * Send email handler
@@ -25,6 +26,7 @@ async function handleSendEmail(args) {
     importance = 'normal',
     saveToSentItems = true,
     dryRun = false,
+    checkRecipients = false,
   } = args;
 
   // Validate required parameters
@@ -99,6 +101,48 @@ async function handleSendEmail(args) {
     const allowlistError = checkRecipientAllowlist(allRecipients);
     if (allowlistError) return allowlistError;
 
+    // Pre-send mail tips check
+    if (checkRecipients) {
+      const allAddresses = allRecipients.map((r) => r.emailAddress.address);
+      const tipsResult = await handleGetMailTips({
+        recipients: allAddresses,
+      });
+
+      // If there are warnings, prepend them to the response
+      if (tipsResult._meta?.warningCount > 0 && dryRun) {
+        // In dry-run mode, include mail tips in the preview
+        const tipsText = tipsResult.content[0]?.text || '';
+        const preview = formatDryRunPreview({
+          message: {
+            subject,
+            body: {
+              contentType:
+                /<(html|div|p|h[1-6]|br|table|ul|ol|li|span|a\s|img|strong|em|b|i)\b/i.test(
+                  body
+                )
+                  ? 'html'
+                  : 'text',
+              content: body,
+            },
+            toRecipients,
+            ccRecipients: ccRecipients.length > 0 ? ccRecipients : undefined,
+            bccRecipients: bccRecipients.length > 0 ? bccRecipients : undefined,
+            importance,
+          },
+          saveToSentItems,
+        });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: tipsText + '\n\n---\n\n' + preview.content[0].text,
+            },
+          ],
+          _meta: { mailTips: tipsResult._meta },
+        };
+      }
+    }
+
     // Prepare email object
     const emailObject = {
       message: {

package/llms.txt

@@ -11,12 +11,12 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 - **License**: MIT
 - **Node.js**: >= 18.0.0
 - **Authentication**: OAuth 2.0 with Microsoft Graph API (requires Azure app registration)
-- **Tools**: 20 consolidated tools across 9 modules (reduced from 55 for optimal AI performance)
+- **Tools**: 21 tools across 9 modules (reduced from 55 for optimal AI performance)
 
 ## Why Outlook Assistant?
 
 - Read, search, send, and export emails directly from Claude instead of switching apps
-- 6 email tools covering search, conversations, attachments, and bulk export
+- 7 email tools covering search, conversations, attachments, bulk export, and pre-send mail tips
 - Manage calendar events, contacts, rules, categories, and mailbox settings in one place
 - Export to multiple formats: MIME/EML, MBOX, Markdown, JSON, HTML
 
@@ -26,13 +26,14 @@ Built by [Little Bear Apps](https://littlebearapps.com).
 - **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
 
 ## Safety & Token Efficiency
 
-- **MCP safety annotations** on all 20 tools — AI clients auto-approve reads and prompt for destructive operations
-- **Send-email protections**: dry-run preview, session rate limiting, recipient allowlist
-- **Token-optimised**: 20 tools instead of 55 saves ~11,000 tokens per turn (~64% reduction), improving AI accuracy and context efficiency
+- **MCP safety annotations** on all 21 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
+- **Token-optimised**: 21 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
 
 ## Quick Start
@@ -57,7 +58,7 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 ## Tool Categories
 
 - **Authentication (1 tool)**: `auth` — OAuth flow, status, about
-- **Email (6 tools)**: `search-emails`, `read-email`, `send-email`, `update-email`, `attachments`, `export`
+- **Email (7 tools)**: `search-emails`, `read-email`, `send-email`, `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
@@ -69,7 +70,7 @@ Requires an Azure app registration with Microsoft Graph delegated permissions. S
 ## Documentation
 
 - [README](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/README.md): Full documentation including setup, Azure configuration, and usage
-- [Tools Reference](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/quickrefs/tools-reference.md): All 20 tools with parameters and safety annotations
+- [Tools Reference](https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/quickrefs/tools-reference.md): All 21 tools with parameters and safety annotations
 - [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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@littlebearapps/outlook-assistant",
-  "version": "3.4.1",
+  "version": "3.5.0",
   "mcpName": "io.github.littlebearapps/outlook-assistant",
-  "description": "Outlook Assistant — MCP server with 20 tools for email, calendar, contacts, and settings via Microsoft Graph API",
+  "description": "Outlook Assistant — MCP server with 21 tools for email, calendar, contacts, and settings via Microsoft Graph API",
   "main": "index.js",
   "bin": {
     "outlook-assistant": "./index.js"

package/utils/graph-api.js

@@ -12,6 +12,7 @@ const mockData = require('./mock-data');
  * @param {string} path - API endpoint path
  * @param {object} data - Data to send for POST/PUT requests
  * @param {object} queryParams - Query parameters
+ * @param {object} extraHeaders - Additional headers (e.g. Prefer for immutable IDs)
  * @returns {Promise<object>} - The API response
  */
 async function callGraphAPI(
@@ -19,7 +20,8 @@ async function callGraphAPI(
   method,
   path,
   data = null,
-  queryParams = {}
+  queryParams = {},
+  extraHeaders = {}
 ) {
   // For test tokens, we'll simulate the API call
   if (config.USE_TEST_MODE && accessToken.startsWith('test_access_token_')) {
@@ -75,12 +77,22 @@ async function callGraphAPI(
     }
 
     return new Promise((resolve, reject) => {
+      const headers = {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+      };
+
+      // Add immutable IDs header when enabled globally
+      if (config.USE_IMMUTABLE_IDS) {
+        headers.Prefer = 'IdType="ImmutableId"';
+      }
+
+      // Merge any extra headers (caller overrides take precedence)
+      Object.assign(headers, extraHeaders);
+
       const options = {
         method: method,
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          'Content-Type': 'application/json',
-        },
+        headers,
       };
 
       const req = https.request(finalUrl, options, (res) => {
@@ -202,6 +214,58 @@ async function callGraphAPIPaginated(
   }
 }
 
+/**
+ * Sends multiple Graph API requests in a single batch call ($batch).
+ * Supports up to 20 requests per batch (Graph API limit).
+ * @param {string} accessToken - The access token for authentication
+ * @param {Array<{id: string, method: string, url: string, body?: object, headers?: object}>} requests - Batch requests
+ * @returns {Promise<Array<{id: string, status: number, body: object}>>} - Array of responses
+ */
+async function callGraphAPIBatch(accessToken, requests) {
+  if (!Array.isArray(requests) || requests.length === 0) {
+    throw new Error('Batch requests must be a non-empty array');
+  }
+
+  if (requests.length > 20) {
+    throw new Error('Batch requests cannot exceed 20 (Graph API limit)');
+  }
+
+  // Test mode
+  if (config.USE_TEST_MODE && accessToken.startsWith('test_access_token_')) {
+    return requests.map((req) => ({
+      id: req.id,
+      status: 200,
+      body: mockData.simulateGraphAPIResponse(
+        req.method,
+        req.url,
+        req.body || null,
+        {}
+      ),
+    }));
+  }
+
+  const batchPayload = {
+    requests: requests.map((req) => ({
+      id: req.id,
+      method: req.method,
+      url: req.url.startsWith('/') ? req.url : `/${req.url}`,
+      ...(req.body && { body: req.body }),
+      ...(req.headers && { headers: req.headers }),
+    })),
+  };
+
+  const response = await callGraphAPI(
+    accessToken,
+    'POST',
+    '$batch',
+    batchPayload
+  );
+
+  return (response.responses || []).sort(
+    (a, b) => parseInt(a.id) - parseInt(b.id)
+  );
+}
+
 /**
  * Calls Graph API to get raw MIME content (for email export)
  * @param {string} accessToken - The access token for authentication
@@ -264,5 +328,6 @@ async function callGraphAPIRaw(accessToken, emailId) {
 module.exports = {
   callGraphAPI,
   callGraphAPIPaginated,
+  callGraphAPIBatch,
   callGraphAPIRaw,
 };