@littlebearapps/outlook-assistant 3.7.2 → 3.7.4

package/README.md

@@ -14,6 +14,7 @@
   <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="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+  <a href="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant"><img src="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant/badges/score.svg" alt="Glama score" /></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.
@@ -36,8 +37,8 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 - 🛡️ **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
+- 📦 **Export emails** — save individual messages to Markdown, EML, JSON, or CSV; export full conversation threads to MBOX or HTML; bulk-export search results in one call
+- 🔍 **Investigate email headers** — full raw header access (DKIM, SPF, DMARC, delivery chain, X-Mailer, X-Originating-IP) for phishing investigation and compliance review
 - 🗂️ **Organise your inbox** — create folders, set up inbox rules, colour-code with categories, manage Focused Inbox — all work together for complete inbox automation
 - 🔄 **Track inbox changes** — delta sync detects new, modified, and deleted emails since your last check, with tokens for incremental polling
 - 👥 **Manage contacts** — search your contact book and organisational directory, create and update contact records
@@ -75,16 +76,18 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 
 ### Export Formats
 
-| Format | Extension | When to Use It |
-|--------|-----------|----------------|
-| `mime` / `eml` | `.eml` | Legal holds, forensic preservation, importing into other mail clients |
-| `mbox` | `.mbox` | Archiving entire conversation threads, migrating between systems |
-| `markdown` | `.md` | Pasting into documents, feeding into AI workflows |
-| `json` | `.json` | Data analysis, pipeline processing, compliance reporting |
-| `html` | `.html` | Visual archival with formatting intact |
-| `csv` | `.csv` | Spreadsheet import, bulk metadata analysis, compliance audits |
+Format support varies by `target`:
 
-Export individual emails, search results, or entire conversation threads — use `target=messages` with a search query to batch-export without manually collecting IDs.
+| Format | Extension | `target=message` (single) | `target=messages` (batch) | `target=conversation` (thread) |
+|--------|-----------|--------|--------|--------|
+| `mime` / `eml` | `.eml` | ✅ | – | ✅ |
+| `mbox` | `.mbox` | – | – | ✅ |
+| `markdown` | `.md` | ✅ | ✅ | ✅ |
+| `json` | `.json` | ✅ | ✅ | ✅ |
+| `html` | `.html` | – | – | ✅ |
+| `csv` | `.csv` | ✅ | ✅ | ✅ |
+
+Export individual emails, search results, or entire conversation threads — use `target=messages` with a search query (or the `query` shortcut) to batch-export without manually collecting IDs.
 
 ## Account Compatibility
 
@@ -100,7 +103,7 @@ Outlook Assistant works with both personal and work/school Microsoft accounts, b
 | Free-text `query` search | Limited — use `subject`, `from`, `to` filters instead | Full KQL support |
 | Categories | Full support | Full support |
 | Mailbox settings | Full support | Full support |
-| Focused Inbox | Not available | Full support |
+| Focused Inbox | API works (overrides stored) but mail routing not affected | Full support |
 | Shared mailboxes | Not available | Requires `Mail.Read.Shared` |
 | Meeting room search | Not available | Requires `Place.Read.All` + admin consent |
 
@@ -109,7 +112,7 @@ Outlook Assistant works with both personal and work/school Microsoft accounts, b
 ### What Makes This Different
 
 - **Progressive search** — on accounts where Microsoft's `$search` API is limited, Outlook Assistant automatically falls back through up to 4 search strategies to find your emails. Most Graph API wrappers fail silently; this one adapts.
-- **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.
+- **Email forensics** — raw header access for DKIM, SPF, DMARC, delivery chain, X-Mailer, X-Originating-IP, and spam scores. Returns the full data so you can investigate phishing, audit compliance, or trace delivery issues. (Auto-verdict is on the v3.8.0 roadmap; today the data is surfaced and analysed in-conversation.)
 - **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.
@@ -127,6 +130,17 @@ 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`
 
+> **Recommended setup**: enable both safety belts in your `.mcp.json` from day one. They're off by default; `auth action=about` reports their state and prints a setup hint when unset. See [`.mcp.json.example`](.mcp.json.example) for a copy-paste template.
+>
+> ```json
+> "env": {
+>   "OUTLOOK_CLIENT_ID": "…",
+>   "OUTLOOK_CLIENT_SECRET": "…",
+>   "OUTLOOK_MAX_EMAILS_PER_SESSION": "10",
+>   "OUTLOOK_ALLOWED_RECIPIENTS": "your-domain.com,trusted@example.com"
+> }
+> ```
+
 **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.
@@ -356,6 +370,8 @@ No auth server needed. Works everywhere, including remote/headless environments.
 5. Tokens are saved to `~/.outlook-assistant-tokens.json` and **refresh automatically**
 
 > **Prerequisite**: Enable "Allow public client flows" in Azure Portal > your app > Authentication > Advanced settings.
+>
+> **Server restarts** (v3.7.2+): Device code state is persisted to `~/.outlook-assistant-pending-auth.json`, so `device-code-complete` works even if the MCP server restarts between steps 1 and 4 (e.g., Untether/Telegram bridge, Claude Desktop session changes).
 
 ### Browser Redirect Flow (Alternative)
 
@@ -431,6 +447,10 @@ If using browser flow: start the auth server first with `npm run auth-server`. I
 
 Enable "Allow public client flows" in Azure Portal > App registrations > Authentication > Advanced settings.
 
+### Token refresh fails after ~60 minutes (device code auth)
+
+Fixed in v3.7.2. Earlier versions sent `client_secret` in token refresh requests for device-code auth, which Microsoft rejects for public client flows. Update to v3.7.2+ or re-authenticate.
+
 ### Empty API responses
 
 Check authentication status with the `auth` tool (action=status). Tokens may have expired — re-authenticate if needed.
@@ -467,7 +487,8 @@ 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) | 28 practical guides for email, calendar, contacts, and settings |
+| [How-To Guides](docs/how-to/index.md) | 29 practical guides for email, calendar, contacts, and settings |
+| [Roadmap](ROADMAP.md) | Active milestones (v3.7.5, v3.8.0, v3.9.0) and recent releases |
 | [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 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 |
@@ -494,10 +515,6 @@ For security concerns, please see our [Security Policy](SECURITY.md). Do not ope
 
 See [CHANGELOG.md](CHANGELOG.md) for version history.
 
-## Listed On
-
-<a href="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant"><img width="190" height="100" src="https://glama.ai/mcp/servers/littlebearapps/outlook-assistant/badge" alt="Outlook Assistant on Glama" /></a>
-
 ## About
 
 Built and maintained by [Little Bear Apps](https://littlebearapps.com). Outlook Assistant is open source under the [MIT License](LICENSE).

package/advanced/index.js

@@ -46,7 +46,10 @@ function formatEmail(email, verbosity = 'standard') {
  * Requires Mail.Read.Shared permission
  */
 async function handleAccessSharedMailbox(args) {
-  const { sharedMailbox, folder, count, outputVerbosity } = args;
+  // F-46: accept `email` as alias for `sharedMailbox`. The original
+  // param name is awkward; most callers reach for `email` first.
+  const { folder, count, outputVerbosity } = args;
+  const sharedMailbox = args.sharedMailbox || args.email;
 
   if (!sharedMailbox) {
     return {
@@ -458,11 +461,24 @@ async function handleFindMeetingRooms(args) {
         );
         rooms = roomsResponse.value || [];
       } catch (findRoomsError) {
+        // F-47: distinguish "feature not available on personal account"
+        // from generic permission errors. Personal Outlook.com accounts
+        // surface a 404 here; organizational accounts surface
+        // permission errors. Both look similar in Graph but mean very
+        // different things to the caller.
+        const errMsg = findRoomsError.message || '';
+        const isLikelyPersonal =
+          errMsg.includes('404') ||
+          errMsg.includes('Not Found') ||
+          errMsg.includes('NotFound');
+        const explanation = isLikelyPersonal
+          ? 'Meeting room search is M365-only. Personal Outlook.com accounts cannot use this feature — there are no rooms to find. Connect a Microsoft 365 work/school account to enable.'
+          : 'This feature requires:\n- Places.Read.All permission\n- Meeting rooms configured in your organization';
         return {
           content: [
             {
               type: 'text',
-              text: `Unable to find meeting rooms.\n\n**Note**: This feature requires:\n- Places.Read.All permission\n- Meeting rooms configured in your organization\n\nError: ${findRoomsError.message}`,
+              text: `Unable to find meeting rooms.\n\n**Note**: ${explanation}\n\nError: ${errMsg}`,
             },
           ],
         };
@@ -603,6 +619,11 @@ const advancedTools = [
           type: 'string',
           description: 'Email address of the shared mailbox (required)',
         },
+        email: {
+          type: 'string',
+          description:
+            'Alias for `sharedMailbox` (more intuitive name for the same value).',
+        },
         folder: {
           type: 'string',
           description: 'Folder to read from (default: inbox)',
@@ -617,7 +638,8 @@ const advancedTools = [
           description: 'Output detail level (default: standard)',
         },
       },
-      required: ['sharedMailbox'],
+      additionalProperties: false,
+      required: [],
     },
     handler: handleAccessSharedMailbox,
   },
@@ -654,6 +676,7 @@ const advancedTools = [
           description: 'Output detail level (default: standard)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: handleFindMeetingRooms,

package/auth/tools.js

@@ -28,17 +28,40 @@ async function handleAbout() {
     (s) => s !== 'offline_access'
   );
   const testMode = config.USE_TEST_MODE ? 'Enabled' : 'Disabled';
+  const rateLimitConfigured = Boolean(
+    process.env.OUTLOOK_MAX_EMAILS_PER_SESSION
+  );
+  const allowlistConfigured = Boolean(process.env.OUTLOOK_ALLOWED_RECIPIENTS);
   const rateLimit =
     process.env.OUTLOOK_MAX_EMAILS_PER_SESSION || 'Unlimited (no limit set)';
   const allowlist =
     process.env.OUTLOOK_ALLOWED_RECIPIENTS || 'None (all recipients allowed)';
 
+  // F-2: surface the authenticated user's email so callers and AI
+  // agents can confirm which mailbox is connected. Uses a single
+  // GET /me round-trip when a valid token is available; degrades
+  // gracefully when not authenticated.
+  let identity = 'Not authenticated (run `auth action=authenticate`)';
+  try {
+    const { ensureAuthenticated } = require('./index');
+    const { callGraphAPI } = require('../utils/graph-api');
+    const token = await ensureAuthenticated();
+    const me = await callGraphAPI(token, 'GET', 'me', null, {
+      $select: 'userPrincipalName,mail,displayName',
+    });
+    const upn = me.mail || me.userPrincipalName;
+    identity = me.displayName ? `${me.displayName} <${upn}>` : upn;
+  } catch (_e) {
+    // Leave default identity message in place
+  }
+
   const lines = [
     `# Outlook Assistant Server v${config.SERVER_VERSION}\n`,
     `Provides access to Microsoft Outlook email, calendar, and contacts through Microsoft Graph API.\n`,
     `## Diagnostics\n`,
     `| Setting | Value |`,
     `|---------|-------|`,
+    `| Mailbox | ${identity} |`,
     `| Tools | ${_toolCount} across 9 modules |`,
     `| Modules | auth, email, calendar, folder, rules, contacts, categories, settings, advanced |`,
     `| Timezone | ${config.DEFAULT_TIMEZONE} |`,
@@ -50,6 +73,27 @@ async function handleAbout() {
     `**Scopes**: ${scopes.join(', ')}`,
   ];
 
+  // F-1 / F-48: warn when no safety belts are wired up. AI-assisted
+  // sending is significantly safer with a session rate limit and a
+  // recipient allowlist; both are off by default.
+  if (!rateLimitConfigured || !allowlistConfigured) {
+    lines.push('');
+    lines.push('## ⚠ Safety Belts Not Configured\n');
+    lines.push(
+      'No rate limit or recipient allowlist is set. For safer AI-assisted sending, add to your `.mcp.json` env block:'
+    );
+    lines.push('```');
+    if (!rateLimitConfigured) {
+      lines.push('OUTLOOK_MAX_EMAILS_PER_SESSION=10');
+    }
+    if (!allowlistConfigured) {
+      lines.push(
+        'OUTLOOK_ALLOWED_RECIPIENTS=your-domain.com,trusted@example.com'
+      );
+    }
+    lines.push('```');
+  }
+
   return {
     content: [
       {
@@ -369,6 +413,7 @@ const authTools = [
             'Force re-authentication even if already authenticated (action=authenticate only)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -381,8 +426,16 @@ const authTools = [
         case 'about':
           return handleAbout();
         case 'status':
-        default:
           return handleCheckAuthStatus();
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: status, authenticate, device-code-complete, about.`,
+              },
+            ],
+          };
       }
     },
   },

package/calendar/index.js

@@ -25,6 +25,7 @@ const calendarTools = [
           description: 'Number of events to retrieve (default: 10, max: 50)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: handleListEvents,
@@ -65,6 +66,7 @@ const calendarTools = [
           description: 'Optional body content for the event',
         },
       },
+      additionalProperties: false,
       required: ['subject', 'start', 'end'],
     },
     handler: handleCreateEvent,
@@ -91,14 +93,38 @@ const calendarTools = [
           type: 'string',
           description: 'The ID of the event',
         },
+        id: {
+          type: 'string',
+          description:
+            'Alias for `eventId` (canonical per the v3.7.3 alias pass).',
+        },
         comment: {
           type: 'string',
           description: 'Optional comment for declining or cancelling the event',
         },
       },
-      required: ['action', 'eventId'],
+      additionalProperties: false,
+      required: ['action'],
     },
     handler: async (args) => {
+      // F-37: accept `id` as alias for `eventId` so callers don't have
+      // to remember which tool uses which name. Both work; eventId
+      // remains the canonical Graph param.
+      const normalised = { ...args };
+      if (!normalised.eventId && normalised.id) {
+        normalised.eventId = normalised.id;
+      }
+      if (!normalised.eventId) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'Required parameter `eventId` (or alias `id`) is missing.',
+            },
+          ],
+        };
+      }
+      args = normalised;
       switch (args.action) {
         case 'decline':
           return handleDeclineEvent(args);

package/categories/index.js

@@ -116,9 +116,9 @@ async function handleListCategories(args) {
       output.push('|----------|-------|-----|');
       categories.forEach((cat) => {
         const colorName = COLOR_NAMES[cat.color] || cat.color;
-        const idDisplay =
-          outputVerbosity === 'full' ? cat.id : `${cat.id.substring(0, 8)}...`;
-        output.push(`| ${cat.displayName} | ${colorName} | ${idDisplay} |`);
+        // F-9: emit full IDs at standard verbosity. Truncated IDs were
+        // unusable downstream (the ellipsis became part of the copy).
+        output.push(`| ${cat.displayName} | ${colorName} | ${cat.id} |`);
       });
     }
 
@@ -255,7 +255,9 @@ async function handleCreateCategory(args) {
  * Update category handler
  */
 async function handleUpdateCategory(args) {
-  const { id, displayName, color } = args;
+  // F-34: accept `categoryId` as a deprecated alias for `id`.
+  const id = args.id || args.categoryId;
+  const { displayName, color } = args;
 
   if (!id) {
     return {
@@ -298,34 +300,45 @@ async function handleUpdateCategory(args) {
     if (displayName) updateData.displayName = displayName;
     if (color) updateData.color = color;
 
-    const response = await callGraphAPI(
+    await callGraphAPI(
       accessToken,
       'PATCH',
       `me/outlook/masterCategories/${id}`,
       updateData
     );
 
-    // 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;
+    // F-35: Graph silently drops master-category color updates on
+    // some account types. Re-fetch the category and diff requested
+    // values against what Graph actually stored, so the caller
+    // doesn't get a misleading "Category updated!" when nothing
+    // changed.
+    const fresh = await callGraphAPI(
+      accessToken,
+      'GET',
+      `me/outlook/masterCategories/${id}`
+    );
 
-    const updatedCategory = {
-      ...response,
-      displayName: updatedName,
-      color: updatedColor,
-    };
+    const warnings = [];
+    if (color && fresh.color !== color) {
+      warnings.push(
+        `Requested color \`${color}\` but Graph stored \`${fresh.color}\` (master-category colors may be immutable on this account type).`
+      );
+    }
+    if (displayName && fresh.displayName !== displayName) {
+      warnings.push(
+        `Requested name \`${displayName}\` but Graph stored \`${fresh.displayName}\`.`
+      );
+    }
+
+    const colorName = COLOR_NAMES[fresh.color] || fresh.color;
+    let text = `Category updated!\n\n**Name**: ${fresh.displayName}\n**Color**: ${colorName} (${fresh.color})\n**ID**: ${fresh.id || id}`;
+    if (warnings.length > 0) {
+      text += `\n\n**⚠ Warning**:\n${warnings.map((w) => `- ${w}`).join('\n')}`;
+    }
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: `Category updated!\n\n**Name**: ${updatedName}\n**Color**: ${colorName} (${updatedColor})\n**ID**: ${response.id || id}`,
-        },
-      ],
-      _meta: {
-        category: formatCategory(updatedCategory),
-      },
+      content: [{ type: 'text', text }],
+      _meta: { category: formatCategory(fresh) },
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
@@ -353,7 +366,8 @@ async function handleUpdateCategory(args) {
  * Delete category handler
  */
 async function handleDeleteCategory(args) {
-  const { id } = args;
+  // F-34: accept `categoryId` as a deprecated alias for `id`.
+  const id = args.id || args.categoryId;
 
   if (!id) {
     return {
@@ -824,8 +838,9 @@ const categoriesTools = [
       properties: {
         action: {
           type: 'string',
-          enum: ['list', 'create', 'update', 'delete'],
-          description: 'Action to perform (default: list)',
+          enum: ['list', 'create', 'update', 'set', 'delete'],
+          description:
+            "Action to perform (default: list). 'set' is a deprecated alias for 'update'.",
         },
         // list params
         outputVerbosity: {
@@ -850,7 +865,12 @@ const categoriesTools = [
           type: 'string',
           description: 'Category ID (action=update/delete, required)',
         },
+        categoryId: {
+          type: 'string',
+          description: 'DEPRECATED: alias for `id`. Will be removed in v3.8.0.',
+        },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -858,13 +878,22 @@ const categoriesTools = [
       switch (action) {
         case 'create':
           return handleCreateCategory(args);
+        case 'set': // deprecated alias
         case 'update':
           return handleUpdateCategory(args);
         case 'delete':
           return handleDeleteCategory(args);
         case 'list':
-        default:
           return handleListCategories(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, create, update, delete.`,
+              },
+            ],
+          };
       }
     },
   },
@@ -901,6 +930,7 @@ const categoriesTools = [
             'set (replace all), add (append), remove (remove specific). Default: set',
         },
       },
+      additionalProperties: false,
       required: ['categories'],
     },
     handler: handleApplyCategory,
@@ -945,6 +975,7 @@ const categoriesTools = [
             'Where to put emails from this sender (action=set, default: focused)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -955,8 +986,16 @@ const categoriesTools = [
         case 'delete':
           return handleSetFocusedInboxOverride(args);
         case 'list':
-        default:
           return handleGetFocusedInboxOverrides(args);
+        default:
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Unknown action '${action}'. Valid actions: list, set, delete.`,
+              },
+            ],
+          };
       }
     },
   },