@littlebearapps/outlook-assistant 3.7.1 → 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/token-storage.js

@@ -49,11 +49,13 @@ class TokenStorage {
       }
     }
 
-    if (!this.config.clientId || !this.config.clientSecret) {
+    if (!this.config.clientId) {
       console.warn(
-        'TokenStorage: OUTLOOK_CLIENT_ID or OUTLOOK_CLIENT_SECRET is not configured. Token operations might fail.'
+        'TokenStorage: OUTLOOK_CLIENT_ID is not configured. Token operations will fail.'
       );
     }
+    // client_secret is only required for browser flow (confidential client).
+    // Device code flow (public client) does not use client_secret.
   }
 
   async _loadTokensFromFile() {
@@ -158,14 +160,24 @@ class TokenStorage {
       return this._refreshPromise.then((tokens) => tokens.access_token);
     }
 
-    console.log('Attempting to refresh access token...');
-    const postData = querystring.stringify({
+    // Device code flow is a public client flow — Microsoft rejects client_secret
+    // in refresh requests for tokens obtained via device code.
+    // Browser flow (confidential client) requires client_secret.
+    const isDeviceCode = this.tokens.auth_method === 'device-code';
+    console.log(
+      `Attempting to refresh access token (auth_method: ${this.tokens.auth_method || 'browser'})...`
+    );
+
+    const refreshParams = {
       client_id: this.config.clientId,
-      client_secret: this.config.clientSecret,
       grant_type: 'refresh_token',
       refresh_token: this.tokens.refresh_token,
       scope: this.config.scopes.join(' '),
-    });
+    };
+    if (!isDeviceCode) {
+      refreshParams.client_secret = this.config.clientSecret;
+    }
+    const postData = querystring.stringify(refreshParams);
 
     const requestOptions = {
       method: 'POST',

package/auth/tools.js

@@ -2,9 +2,17 @@
  * Authentication-related tools for the Outlook Assistant server
  */
 const config = require('../config');
+const fs = require('fs');
+const path = require('path');
 const tokenManager = require('./token-manager');
 const { initiateDeviceCodeFlow, pollForToken } = require('./device-code');
 
+// Path for persisting device code state across MCP server restarts
+const DEVICE_CODE_STATE_PATH = path.join(
+  process.env.HOME || process.env.USERPROFILE,
+  '.outlook-assistant-pending-auth.json'
+);
+
 // Dynamic tool count — set by index.js after TOOLS array is built
 let _toolCount = 0;
 function setToolCount(count) {
@@ -20,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} |`,
@@ -42,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: [
       {
@@ -89,12 +141,57 @@ async function handleAuthenticate(args) {
   };
 }
 
-// Module-level state for pending device code flow
+// In-memory state for pending device code flow (also persisted to disk)
 let pendingDeviceCode = null;
 
+/**
+ * Save device code state to disk so it survives MCP server restarts.
+ * Uses mode 0o600 (owner-only) — same as token file.
+ * @param {object|null} state - Device code state or null to delete
+ */
+function saveDeviceCodeState(state) {
+  try {
+    if (state) {
+      fs.writeFileSync(DEVICE_CODE_STATE_PATH, JSON.stringify(state), {
+        mode: 0o600,
+      });
+    } else if (fs.existsSync(DEVICE_CODE_STATE_PATH)) {
+      fs.unlinkSync(DEVICE_CODE_STATE_PATH);
+    }
+  } catch (error) {
+    console.error(
+      `[AUTH] Failed to ${state ? 'save' : 'clean up'} device code state: ${error.message}`
+    );
+  }
+}
+
+/**
+ * Load device code state from disk (fallback when in-memory state is lost).
+ * Returns null if no state exists or if the state has expired.
+ * @returns {object|null}
+ */
+function loadDeviceCodeState() {
+  try {
+    if (!fs.existsSync(DEVICE_CODE_STATE_PATH)) {
+      return null;
+    }
+    const state = JSON.parse(fs.readFileSync(DEVICE_CODE_STATE_PATH, 'utf8'));
+    if (Date.now() > state.expiresAt) {
+      console.error('[AUTH] Persisted device code has expired, cleaning up');
+      saveDeviceCodeState(null);
+      return null;
+    }
+    return state;
+  } catch (error) {
+    console.error(`[AUTH] Failed to load device code state: ${error.message}`);
+    return null;
+  }
+}
+
 /**
  * Device code flow step 1 — request a code for the user to enter.
  * Returns the code + URL immediately. Call device-code-complete to finish.
+ * State is persisted to disk so it survives MCP server restarts.
  * @returns {object} - MCP response
  */
 async function handleDeviceCodeAuth() {
@@ -116,13 +213,14 @@ async function handleDeviceCodeAuth() {
     config.AUTH_CONFIG.scopes
   );
 
-  // Store for the completion step
+  // Store in memory and persist to disk
   pendingDeviceCode = {
     deviceCode: response.deviceCode,
     interval: response.interval,
     expiresIn: response.expiresIn,
     expiresAt: Date.now() + response.expiresIn * 1000,
   };
+  saveDeviceCodeState(pendingDeviceCode);
 
   console.error(
     `[AUTH] Device code: ${response.userCode}, expires in ${response.expiresIn}s`
@@ -146,9 +244,15 @@ async function handleDeviceCodeAuth() {
 
 /**
  * Device code flow step 2 — poll until the user completes authentication.
+ * Checks in-memory state first, falls back to disk-persisted state.
  * @returns {object} - MCP response
  */
 async function handleDeviceCodeComplete() {
+  // Try in-memory first, fall back to disk (survives server restarts)
+  if (!pendingDeviceCode) {
+    pendingDeviceCode = loadDeviceCodeState();
+  }
+
   if (!pendingDeviceCode) {
     return {
       content: [
@@ -162,6 +266,7 @@ async function handleDeviceCodeComplete() {
 
   if (Date.now() > pendingDeviceCode.expiresAt) {
     pendingDeviceCode = null;
+    saveDeviceCodeState(null);
     return {
       content: [
         {
@@ -184,8 +289,9 @@ async function handleDeviceCodeComplete() {
     );
 
     pendingDeviceCode = null;
+    saveDeviceCodeState(null);
 
-    // Save tokens using TokenStorage
+    // Save tokens using TokenStorage — mark as device-code auth
     const TokenStorage = require('./token-storage');
     const tokenStorage = new TokenStorage({
       clientId: config.AUTH_CONFIG.clientId,
@@ -202,6 +308,7 @@ async function handleDeviceCodeComplete() {
       expires_at: Date.now() + tokenResponse.expires_in * 1000,
       scope: tokenResponse.scope,
       token_type: tokenResponse.token_type,
+      auth_method: 'device-code',
     };
     await tokenStorage._saveTokensToFile();
 
@@ -217,6 +324,7 @@ async function handleDeviceCodeComplete() {
     };
   } catch (error) {
     pendingDeviceCode = null;
+    saveDeviceCodeState(null);
     return {
       content: [
         {
@@ -305,6 +413,7 @@ const authTools = [
             'Force re-authentication even if already authenticated (action=authenticate only)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: async (args) => {
@@ -317,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);