@littlebearapps/outlook-assistant 3.4.1 → 3.5.1

package/config.js

@@ -54,6 +54,10 @@ module.exports = {
     ],
     tokenStorePath: path.join(homeDir, '.outlook-assistant-tokens.json'),
     authServerUrl: 'http://localhost:3333',
+    deviceCodeEndpoint:
+      'https://login.microsoftonline.com/common/oauth2/v2.0/devicecode',
+    tokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    defaultAuthMethod: process.env.OUTLOOK_AUTH_METHOD || 'device-code',
   },
 
   // Microsoft Graph API
@@ -90,6 +94,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-install.md

@@ -0,0 +1,90 @@
+# Installing Outlook Assistant
+
+## Quick Install (npx — no global install needed)
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "npx",
+      "args": ["-y", "@littlebearapps/outlook-assistant"],
+      "env": {
+        "OUTLOOK_CLIENT_ID": "<user-must-provide>",
+        "OUTLOOK_CLIENT_SECRET": "<user-must-provide>"
+      }
+    }
+  }
+}
+```
+
+## Prerequisites
+
+1. **Node.js 18+** must be installed
+2. **Azure app registration** is required for authentication (free tier works)
+
+## Getting the Client ID and Secret
+
+Users must create an Azure app registration to get credentials:
+
+1. Go to https://portal.azure.com/ and sign in
+2. Search for "App registrations" → click "New registration"
+3. Name: "Outlook Assistant" (or any name)
+4. Supported account types: "Accounts in any organizational directory and personal Microsoft accounts"
+5. Redirect URI: platform "Web", URI `http://localhost:3333/auth/callback`
+6. Click "Register"
+7. Copy the **Application (client) ID** → this is `OUTLOOK_CLIENT_ID`
+
+### Create a client secret:
+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`
+
+### Add API permissions:
+1. Go to "API permissions" → "Add a permission" → "Microsoft Graph" → "Delegated permissions"
+2. Add: `offline_access`, `User.Read`, `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`, `People.Read`, `MailboxSettings.ReadWrite`
+3. Click "Add permissions"
+
+## First-Time Authentication
+
+After configuring the MCP server:
+
+1. Start the auth server: `npx @littlebearapps/outlook-assistant-auth` (or run `npm run auth-server` from source)
+2. Use the `auth` tool with `action=authenticate` to get an OAuth URL
+3. Open the URL in a browser, sign in with your Microsoft account
+4. Grant permissions — tokens are saved to `~/.outlook-assistant-tokens.json` and refresh automatically
+
+**Note**: The auth server needs `OUTLOOK_CLIENT_ID` and `OUTLOOK_CLIENT_SECRET` as environment variables. If running it separately from the MCP server, export them in your shell or create a `.env` file.
+
+## Configuration Files by Client
+
+### Claude Desktop
+File: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+### Claude Code
+```bash
+claude mcp add outlook -- npx @littlebearapps/outlook-assistant
+```
+
+### Cursor
+File: `.cursor/mcp.json` in your project root
+
+### Windsurf
+File: `~/.codeium/windsurf/mcp_config.json`
+
+## Verify Installation
+
+After authentication, test with:
+- `auth` tool with `action=status` — should show "authenticated"
+- `search-emails` with no parameters — should list recent inbox emails
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| "Invalid client secret" (AADSTS7000215) | Use the secret **Value**, not the Secret ID |
+| Auth URL doesn't work | Start the auth server first |
+| "EADDRINUSE :3333" | Run `npx kill-port 3333` then restart auth server |
+| Empty API responses | Run `auth` tool with `action=status` to check token |
+| Search returns no results (personal account) | Use `from`, `subject`, `to` filters instead of `query` |

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.1",
   "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"
@@ -70,7 +70,8 @@
     ".env.example",
     "README.md",
     "LICENSE",
-    "llms.txt"
+    "llms.txt",
+    "llms-install.md"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",