@littlebearapps/outlook-assistant 3.7.2 → 3.8.0

package/.env.example

@@ -28,3 +28,22 @@ USE_TEST_MODE=false
 # device-code: No auth server needed, works remotely/headless
 # browser: Traditional OAuth redirect via localhost:3333
 # OUTLOOK_AUTH_METHOD=device-code
+
+# Optional: OAuth audience — controls which Microsoft Identity Platform
+# endpoint is used. Must match the Azure app registration's "Supported
+# account types" setting:
+#   common         — personal AND work/school accounts (default; multi-tenant + personal apps)
+#   consumers      — personal Microsoft accounts only
+#   organizations  — work/school accounts only
+#   <tenant-guid>  — single-tenant
+# Example: OUTLOOK_AUTH_AUDIENCE=consumers   (for personal-account-only apps)
+# OUTLOOK_AUTH_AUDIENCE=common
+
+# Optional: Default timezone for calendar events when not explicitly
+# specified by the caller. Use any IANA timezone identifier.
+# Default: Australia/Melbourne
+# Examples:
+#   OUTLOOK_DEFAULT_TIMEZONE=Europe/London
+#   OUTLOOK_DEFAULT_TIMEZONE=America/New_York
+#   OUTLOOK_DEFAULT_TIMEZONE=Asia/Tokyo
+# OUTLOOK_DEFAULT_TIMEZONE=Australia/Melbourne

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.
@@ -22,8 +23,8 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 
 <div align="center">
   <br />
-  <a href="docs/demo/outlook-assistant-demo.mp4">
-    <img src="docs/demo/outlook-assistant-demo.gif" alt="Outlook Assistant Demo — searching emails, reading, and drafting a reply" width="720" style="border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.12);" />
+  <a href="https://github.com/littlebearapps/outlook-assistant/blob/main/docs/demo/outlook-assistant-demo.mp4">
+    <img src="https://raw.githubusercontent.com/littlebearapps/outlook-assistant/main/docs/demo/outlook-assistant-demo.gif" alt="Outlook Assistant Demo — searching emails, reading, and drafting a reply" width="720" style="border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.12);" />
   </a>
   <br />
   <sub>Search inbox → read &amp; summarise → draft a reply — all from the conversation</sub>
@@ -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
@@ -62,7 +63,7 @@ Outlook Assistant connects AI assistants to your Microsoft Outlook account throu
 | Module | Tools | What You Can Do |
 |--------|------:|-----------------|
 | **Email** | 8 | `search-emails` (list/search/delta/conversations), `read-email` (content + forensic headers), `send-email` (with dry-run + mail tips), `draft` (create/update/send/delete/reply/forward), `update-email` (read status, flags), `attachments`, `export`, `get-mail-tips` |
-| **Calendar** | 3 | `list-events`, `create-event`, `manage-event` (decline/cancel/delete) |
+| **Calendar** | 3 | `list-events`, `create-event`, `manage-event` (update/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` |
 | **Settings** | 1 | `mailbox-settings` (get/set auto-replies/set working hours) |
@@ -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.
@@ -322,6 +336,15 @@ USE_TEST_MODE=false
 
 > **Note:** The server also accepts `MS_CLIENT_ID` and `MS_CLIENT_SECRET` for backwards compatibility.
 
+**Optional overrides** (v3.8.0+) — see [`.env.example`](.env.example) for the full list with commented worked examples:
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `OUTLOOK_AUTH_AUDIENCE` | OAuth audience: `common`, `consumers` (personal-only Azure apps), `organizations`, or single-tenant GUID. Fixes `AADSTS9002331` for personal-only app registrations. | `common` |
+| `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone applied to calendar events when callers don't pass one (e.g. `Europe/London`, `America/New_York`). | `Australia/Melbourne` |
+| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on `send-email` + `draft send` per MCP server lifetime. | unlimited |
+| `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of domains/addresses for sends, drafts, and rule forwards. | unrestricted |
+
 ### MCP Client Configuration
 
 See [Quick Start — Configure Your MCP Client](#3-configure-your-mcp-client) above for Claude Desktop, Claude Code, Cursor, and Windsurf configs.
@@ -356,6 +379,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 +456,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 +496,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 +524,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

@@ -6,6 +6,7 @@ const handleDeclineEvent = require('./decline');
 const handleCreateEvent = require('./create');
 const handleCancelEvent = require('./cancel');
 const handleDeleteEvent = require('./delete');
+const handleUpdateEvent = require('./update');
 
 // Calendar tool definitions (consolidated: 5 → 3)
 const calendarTools = [
@@ -25,6 +26,7 @@ const calendarTools = [
           description: 'Number of events to retrieve (default: 10, max: 50)',
         },
       },
+      additionalProperties: false,
       required: [],
     },
     handler: handleListEvents,
@@ -65,6 +67,7 @@ const calendarTools = [
           description: 'Optional body content for the event',
         },
       },
+      additionalProperties: false,
       required: ['subject', 'start', 'end'],
     },
     handler: handleCreateEvent,
@@ -72,7 +75,7 @@ const calendarTools = [
   {
     name: 'manage-event',
     description:
-      'Manage an existing calendar event. action=decline declines an invitation. action=cancel cancels an event you organised. action=delete permanently removes an event.',
+      'Manage an existing calendar event. action=update edits fields (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart) without rebuilding the event; pass dryRun=true to preview the PATCH payload. action=decline declines an invitation. action=cancel cancels an event you organised. action=delete permanently removes an event.',
     annotations: {
       title: 'Manage Calendar Event',
       readOnlyHint: false,
@@ -84,22 +87,140 @@ const calendarTools = [
       properties: {
         action: {
           type: 'string',
-          enum: ['decline', 'cancel', 'delete'],
+          enum: ['update', 'decline', 'cancel', 'delete'],
           description: 'Action to perform (required)',
         },
         eventId: {
           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',
         },
+        subject: {
+          type: 'string',
+          description: 'New subject (action=update only)',
+        },
+        start: {
+          oneOf: [
+            { type: 'string' },
+            {
+              type: 'object',
+              properties: {
+                dateTime: { type: 'string' },
+                timeZone: { type: 'string' },
+              },
+              required: ['dateTime'],
+              additionalProperties: false,
+            },
+          ],
+          description:
+            'New start time as ISO 8601 string or {dateTime, timeZone} object (action=update only)',
+        },
+        end: {
+          oneOf: [
+            { type: 'string' },
+            {
+              type: 'object',
+              properties: {
+                dateTime: { type: 'string' },
+                timeZone: { type: 'string' },
+              },
+              required: ['dateTime'],
+              additionalProperties: false,
+            },
+          ],
+          description:
+            'New end time as ISO 8601 string or {dateTime, timeZone} object (action=update only)',
+        },
+        attendees: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Full replacement attendee list — pass complete desired list, or [] to clear (action=update only)',
+        },
+        body: {
+          type: 'string',
+          description: 'New body content (action=update only)',
+        },
+        location: {
+          type: 'string',
+          description: 'New location display name (action=update only)',
+        },
+        isOnlineMeeting: {
+          type: 'boolean',
+          description: 'Toggle online meeting flag (action=update only)',
+        },
+        sensitivity: {
+          type: 'string',
+          enum: ['normal', 'personal', 'private', 'confidential'],
+          description: 'Event sensitivity classification (action=update only)',
+        },
+        showAs: {
+          type: 'string',
+          enum: [
+            'free',
+            'tentative',
+            'busy',
+            'oof',
+            'workingElsewhere',
+            'unknown',
+          ],
+          description: 'Free/busy status shown to others (action=update only)',
+        },
+        importance: {
+          type: 'string',
+          enum: ['low', 'normal', 'high'],
+          description: 'Event importance flag (action=update only)',
+        },
+        categories: {
+          type: 'array',
+          items: { type: 'string' },
+          description:
+            'Full replacement category list — pass [] to clear (action=update only)',
+        },
+        reminderMinutesBeforeStart: {
+          type: 'number',
+          description:
+            'Minutes before start to fire the reminder (action=update only)',
+        },
+        dryRun: {
+          type: 'boolean',
+          description:
+            'Preview the PATCH without applying it (action=update only). Returns the body that would be sent to Graph.',
+        },
       },
-      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 'update':
+          return handleUpdateEvent(args);
         case 'decline':
           return handleDeclineEvent(args);
         case 'cancel':
@@ -111,7 +232,7 @@ const calendarTools = [
             content: [
               {
                 type: 'text',
-                text: "Invalid action. Use 'decline', 'cancel', or 'delete'.",
+                text: "Invalid action. Use 'update', 'decline', 'cancel', or 'delete'.",
               },
             ],
           };
@@ -127,4 +248,5 @@ module.exports = {
   handleCreateEvent,
   handleCancelEvent,
   handleDeleteEvent,
+  handleUpdateEvent,
 };