@littlebearapps/outlook-assistant 3.12.0 → 3.13.0

package/auth/tools.js

@@ -6,6 +6,13 @@ const { getAuthErrorHints } = require('./auth-errors');
 const fs = require('fs');
 const path = require('path');
 const tokenManager = require('./token-manager');
+const {
+  CONFIG_FILE_NAME,
+  isValidClientId,
+  saveClientId,
+  getEnvClientId,
+  getClientIdSource,
+} = require('./client-config');
 const {
   initiateDeviceCodeFlow,
   pollForToken,
@@ -19,6 +26,112 @@ const DEVICE_CODE_STATE_PATH = path.join(
   '.outlook-assistant-pending-auth.json'
 );
 
+const SETUP_GUIDE_URL =
+  'https://github.com/littlebearapps/outlook-assistant/blob/main/docs/how-to/getting-started/connect-outlook-to-claude.md';
+const SAVED_CONFIG_DISPLAY_PATH = `~/${CONFIG_FILE_NAME}`;
+
+/**
+ * Error shown when no client ID resolves (no env var, nothing saved). Written
+ * for the AI client: it tells it what to ask the user and which call to make.
+ * @returns {object} - MCP response ({ content, isError: true })
+ */
+function buildMissingClientIdResponse() {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: [
+          'Error: OUTLOOK_CLIENT_ID is not configured, so sign-in cannot start.',
+          '',
+          '1. Ask the user for the **Application (client) ID** of their Azure app registration (Azure portal → App registrations → their app → Overview). It is a GUID such as `00000000-0000-0000-0000-000000000000`.',
+          `2. Call \`auth action=authenticate clientId=<id>\`. The ID is saved to \`${SAVED_CONFIG_DISPLAY_PATH}\` (it is not a secret) and device-code sign-in starts.`,
+          '',
+          'The client secret is not needed for device-code sign-in (the default); only the browser flow uses it.',
+          `No app registration yet? Follow the setup guide: ${SETUP_GUIDE_URL}`,
+          'Alternatively, set OUTLOOK_CLIENT_ID in the MCP server environment and restart it.',
+        ].join('\n'),
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Validate and save a client ID supplied via `auth action=authenticate`.
+ * @param {unknown} clientId
+ * @returns {{error: object}|{saved: string}} - An MCP error response, or the saved ID
+ */
+function applyClientIdArg(clientId) {
+  if (!isValidClientId(clientId)) {
+    return {
+      error: {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'Error: `clientId` is not a valid Azure Application (client) ID.',
+              '',
+              'It must be the GUID shown as **Application (client) ID** on the app registration Overview page in the Azure portal, e.g. `00000000-0000-0000-0000-000000000000`. Do not use the Directory (tenant) ID, the Object ID or a client secret.',
+              `Setup guide: ${SETUP_GUIDE_URL}`,
+            ].join('\n'),
+          },
+        ],
+        isError: true,
+      },
+    };
+  }
+
+  const env = getEnvClientId();
+  if (env && env.value.trim().toLowerCase() !== clientId.trim().toLowerCase()) {
+    return {
+      error: {
+        content: [
+          {
+            type: 'text',
+            text: [
+              `Error: the ${env.name} environment variable is set to a different client ID, and it takes precedence over a saved one, so the \`clientId\` you supplied would be ignored.`,
+              '',
+              `To use the new ID, change or remove ${env.name} in the MCP server configuration, restart the server, then call \`auth action=authenticate\` again. Nothing was saved.`,
+            ].join('\n'),
+          },
+        ],
+        isError: true,
+      },
+    };
+  }
+
+  try {
+    return { saved: saveClientId(clientId) };
+  } catch (error) {
+    return {
+      error: {
+        content: [
+          {
+            type: 'text',
+            text: `Error: could not save the client ID to ${SAVED_CONFIG_DISPLAY_PATH}: ${error.message}`,
+          },
+        ],
+        isError: true,
+      },
+    };
+  }
+}
+
+/**
+ * Client ID row for `auth about`. The ID itself is never shown.
+ * @returns {string}
+ */
+function describeClientIdStatus() {
+  const source = getClientIdSource();
+  if (source === 'env') {
+    return `Configured (environment: ${getEnvClientId().name})`;
+  }
+  if (source === 'saved') {
+    return `Configured (saved in ${SAVED_CONFIG_DISPLAY_PATH})`;
+  }
+  return 'Not set (run `auth action=authenticate clientId=<Application (client) ID>`)';
+}
+
 // Dynamic tool count — set by index.js after TOOLS array is built
 let _toolCount = 0;
 function setToolCount(count) {
@@ -122,6 +235,7 @@ async function handleAbout() {
     `| Setting | Value |`,
     `|---------|-------|`,
     `| Mailbox | ${identity} |`,
+    `| Client ID | ${describeClientIdStatus()} |`,
     `| Tools | ${_toolCount} across 9 modules |`,
     `| Modules | auth, email, calendar, folder, rules, contacts, categories, settings, advanced |`,
     `| Timezone | ${config.DEFAULT_TIMEZONE} |`,
@@ -185,19 +299,54 @@ async function handleAuthenticate(args) {
     };
   }
 
+  // Optional runtime client ID (for clients that can't set env vars, e.g.
+  // plugin marketplaces): validate, refuse if an env var would override it,
+  // save, then carry on with the normal flow.
+  // null / blank counts as not supplied: some clients send empty optionals.
+  let savedPrefix;
+  const suppliedClientId = args?.clientId;
+  if (
+    suppliedClientId !== undefined &&
+    suppliedClientId !== null &&
+    String(suppliedClientId).trim() !== ''
+  ) {
+    const result = applyClientIdArg(suppliedClientId);
+    if (result.error) {
+      return result.error;
+    }
+    savedPrefix = `Saved your Azure Application (client) ID to \`${SAVED_CONFIG_DISPLAY_PATH}\`.`;
+  }
+
   const method = args?.method || config.AUTH_CONFIG.defaultAuthMethod;
 
   if (method === 'device-code') {
-    return handleDeviceCodeAuth();
+    return handleDeviceCodeAuth(savedPrefix);
   }
 
   // Browser redirect flow (existing behaviour)
-  const authUrl = `${config.AUTH_CONFIG.authServerUrl}/auth?client_id=${config.AUTH_CONFIG.clientId}`;
+  const clientId = config.AUTH_CONFIG.clientId;
+  if (!clientId) {
+    return buildMissingClientIdResponse();
+  }
+  const authUrl = `${config.AUTH_CONFIG.authServerUrl}/auth?client_id=${encodeURIComponent(clientId)}`;
+  const lines = [];
+  if (savedPrefix) {
+    lines.push(savedPrefix, '');
+  }
+  lines.push(
+    `Authentication required. Please visit the following URL to authenticate with Microsoft: ${authUrl}\n\nAfter authentication, you will be redirected back to this application.\n\nNote: The auth server must be running on port 3333. If working remotely, consider using method=device-code instead.`
+  );
+  if (getClientIdSource() !== 'env') {
+    lines.push(
+      '',
+      'The browser flow also needs the client secret: the auth server (`npm run auth-server`) reads OUTLOOK_CLIENT_ID and OUTLOOK_CLIENT_SECRET from its own environment and does not use a saved client ID. Device-code sign-in (the default) needs only the client ID.'
+    );
+  }
   return {
     content: [
       {
         type: 'text',
-        text: `Authentication required. Please visit the following URL to authenticate with Microsoft: ${authUrl}\n\nAfter authentication, you will be redirected back to this application.\n\nNote: The auth server must be running on port 3333. If working remotely, consider using method=device-code instead.`,
+        text: lines.join('\n'),
       },
     ],
   };
@@ -254,26 +403,20 @@ function loadDeviceCodeState() {
  * 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.
+ * @param {string} [prefix] - Optional leading line (e.g. "client ID saved")
  * @returns {object} - MCP response
  */
-async function handleDeviceCodeAuth() {
+async function handleDeviceCodeAuth(prefix) {
   const clientId = config.AUTH_CONFIG.clientId;
   if (!clientId) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Error: OUTLOOK_CLIENT_ID is not configured.',
-        },
-      ],
-    };
+    return buildMissingClientIdResponse();
   }
 
   console.error('[AUTH] Starting device code flow...');
   // Attempt the configured scope set (base, plus `.Shared` when
   // OUTLOOK_SHARED_MAILBOX opts in). If the account can't consent to
   // `.Shared`, handleDeviceCodeComplete re-issues with base scopes.
-  return initiateDeviceCode(config.AUTH_CONFIG.scopes, 'full');
+  return initiateDeviceCode(config.AUTH_CONFIG.scopes, 'full', prefix);
 }
 
 /**
@@ -318,13 +461,15 @@ async function initiateDeviceCode(scopes, scopesUsed, prefix) {
     return buildDeviceCodeErrorResponse(error);
   }
 
-  // Store in memory and persist to disk
+  // Store in memory and persist to disk. The client ID is recorded because
+  // the device code is bound to it: completion must poll with the same one.
   pendingDeviceCode = {
     deviceCode: response.deviceCode,
     interval: response.interval,
     expiresIn: response.expiresIn,
     expiresAt: Date.now() + response.expiresIn * 1000,
     scopesUsed,
+    clientId,
   };
   saveDeviceCodeState(pendingDeviceCode);
 
@@ -430,7 +575,14 @@ async function handleDeviceCodeComplete() {
     };
   }
 
-  const clientId = config.AUTH_CONFIG.clientId;
+  // Poll with the client ID the code was issued to (older state files don't
+  // record it, so fall back to the current one).
+  const clientId = pendingDeviceCode.clientId || config.AUTH_CONFIG.clientId;
+  if (!clientId) {
+    pendingDeviceCode = null;
+    saveDeviceCodeState(null);
+    return buildMissingClientIdResponse();
+  }
   // Capture which scope set this pending flow attempted, before any mutation.
   const scopesUsed = pendingDeviceCode.scopesUsed || 'full';
   // The scopes we attempted — used as the granted_scopes fallback when the
@@ -455,7 +607,7 @@ async function handleDeviceCodeComplete() {
     // Save tokens using TokenStorage — mark as device-code auth
     const TokenStorage = require('./token-storage');
     const tokenStorage = new TokenStorage({
-      clientId: config.AUTH_CONFIG.clientId,
+      clientId,
       clientSecret: config.AUTH_CONFIG.clientSecret,
       tokenStorePath: config.AUTH_CONFIG.tokenStorePath,
       scopes: config.AUTH_CONFIG.scopes,
@@ -593,8 +745,12 @@ async function handleCheckAuthStatus() {
 
   if (!accessToken) {
     console.error('[CHECK-AUTH-STATUS] No valid access token');
+    const text =
+      getClientIdSource() === 'none'
+        ? `Not authenticated. No Azure Application (client) ID is configured yet: ask the user for the Application (client) ID of their Azure app registration, then call \`auth action=authenticate clientId=<id>\`. Setup guide: ${SETUP_GUIDE_URL}`
+        : 'Not authenticated';
     return {
-      content: [{ type: 'text', text: 'Not authenticated' }],
+      content: [{ type: 'text', text }],
     };
   }
 
@@ -622,7 +778,7 @@ const authTools = [
   {
     name: 'auth',
     description:
-      'Manage authentication with the Microsoft Graph API. action=`status` (default) returns the current auth state and auto-refreshes the access token if it\'s expired but the refresh token is still valid (~90-day window) — call this first to check before other tools. action=`authenticate` starts the OAuth flow: with `method: "device-code"` (default, works headlessly) it returns a code + URL for the user to visit; with `method: "browser"` it opens the local auth server on :3333 (run `npm run auth-server` first). Pass `force: true` to re-authenticate over an existing valid session. action=`device-code-complete` finishes device-code auth after the user enters the code in their browser — call this once authentication shows as successful in the browser. action=`about` returns server version, configured audience, scope list, and other diagnostic info. Tokens persist to `~/.outlook-assistant-tokens.json` and survive server restarts.',
+      'Manage authentication with the Microsoft Graph API. action=`status` (default) returns the current auth state and auto-refreshes the access token if it\'s expired but the refresh token is still valid (~90-day window) — call this first to check before other tools. action=`authenticate` starts the OAuth flow: with `method: "device-code"` (default, works headlessly) it returns a code + URL for the user to visit; with `method: "browser"` it opens the local auth server on :3333 (run `npm run auth-server` first). Pass `force: true` to re-authenticate over an existing valid session. If sign-in reports that OUTLOOK_CLIENT_ID is not configured, ask the user for their Azure Application (client) ID and pass it as `clientId`. action=`device-code-complete` finishes device-code auth after the user enters the code in their browser — call this once authentication shows as successful in the browser. action=`about` returns server version, configured audience, scope list, and other diagnostic info. Tokens persist to `~/.outlook-assistant-tokens.json` and survive server restarts.',
     annotations: {
       title: 'Authentication',
       readOnlyHint: false,
@@ -648,6 +804,11 @@ const authTools = [
           description:
             'Force re-authentication even if already authenticated (action=authenticate only)',
         },
+        clientId: {
+          type: 'string',
+          description:
+            "Optional, action=authenticate only. The user's Azure Application (client) ID (a GUID from the app registration's Overview page). Saved to `~/.outlook-assistant-config.json` and used from then on; it is not a secret. The OUTLOOK_CLIENT_ID environment variable takes precedence when set.",
+        },
       },
       additionalProperties: false,
       required: [],

package/calendar/attendees.js

@@ -0,0 +1,101 @@
+/**
+ * Shared attendee builder for create-event and manage-event update (#249).
+ *
+ * Callers pass each attendee as a plain email string or as
+ * `{ email, type }` where type is `required`, `optional` or `resource`.
+ * Graph's PATCH on `attendees` replaces the whole list, so an entry
+ * without a type takes the type that address already has on the event
+ * (matched case-insensitively) and only falls back to `required` for a
+ * new address. An explicit type always wins.
+ */
+
+const ATTENDEE_TYPES = ['required', 'optional', 'resource'];
+const ATTENDEE_FIELDS = new Set(['email', 'type']);
+
+function invalid(index, reason) {
+  return new Error(`Invalid attendee at position ${index + 1}: ${reason}`);
+}
+
+/**
+ * Validate one attendee entry.
+ * @param {string|object} entry - Email string or {email, type}
+ * @param {number} index - Position in the list (for error messages)
+ * @returns {{email: string, type: (string|undefined)}}
+ * @throws {Error} 'Invalid attendee at position N: …'
+ */
+function normaliseAttendeeInput(entry, index) {
+  if (typeof entry === 'string') {
+    const email = entry.trim();
+    if (!email) throw invalid(index, 'email address is empty.');
+    return { email, type: undefined };
+  }
+
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw invalid(
+      index,
+      `expected an email address or an {email, type} object, got ${JSON.stringify(entry)}.`
+    );
+  }
+
+  const unknown = Object.keys(entry).find((k) => !ATTENDEE_FIELDS.has(k));
+  if (unknown) {
+    throw invalid(
+      index,
+      `unknown attendee field '${unknown}'. Use {email, type}.`
+    );
+  }
+  if (typeof entry.email !== 'string' || !entry.email.trim()) {
+    throw invalid(index, 'email address is missing or empty.');
+  }
+
+  const type = entry.type ?? undefined;
+  if (type !== undefined && !ATTENDEE_TYPES.includes(type)) {
+    throw invalid(
+      index,
+      `type '${type}' must be one of: ${ATTENDEE_TYPES.join(', ')}.`
+    );
+  }
+  return { email: entry.email.trim(), type };
+}
+
+/**
+ * Validate a whole attendee list.
+ * @param {Array} list
+ * @returns {Array<{email: string, type: (string|undefined)}>}
+ */
+function normaliseAttendees(list) {
+  if (!Array.isArray(list)) {
+    throw new Error(
+      'Invalid attendees: expected a list of email addresses or {email, type} objects.'
+    );
+  }
+  return list.map((entry, index) => normaliseAttendeeInput(entry, index));
+}
+
+/**
+ * Build the Graph `attendees` array.
+ * @param {Array} list - Email strings and/or {email, type} objects
+ * @param {Array} current - The event's current Graph attendees (update only)
+ * @returns {Array<{emailAddress: {address: string}, type: string}>}
+ */
+function buildAttendees(list, current = []) {
+  const currentTypes = new Map();
+  for (const attendee of current || []) {
+    const address = attendee?.emailAddress?.address;
+    if (typeof address === 'string' && ATTENDEE_TYPES.includes(attendee.type)) {
+      currentTypes.set(address.toLowerCase(), attendee.type);
+    }
+  }
+
+  return normaliseAttendees(list).map(({ email, type }) => ({
+    emailAddress: { address: email },
+    type: type || currentTypes.get(email.toLowerCase()) || 'required',
+  }));
+}
+
+module.exports = {
+  ATTENDEE_TYPES,
+  normaliseAttendeeInput,
+  normaliseAttendees,
+  buildAttendees,
+};

package/calendar/cancel.js

@@ -30,10 +30,11 @@ async function handleCancelEvent(args) {
     // Build API endpoint
     const endpoint = `me/events/${eventId}/cancel`;
 
-    // Request body
-    const body = {
-      comment: comment || 'Cancelled via API',
-    };
+    // Only send a comment the caller gave; no placeholder text.
+    const body = {};
+    if (typeof comment === 'string' && comment.trim() !== '') {
+      body.comment = comment;
+    }
 
     // Make API call
     await callGraphAPI(accessToken, 'POST', endpoint, body);

package/calendar/create.js

@@ -4,6 +4,7 @@
 const { callGraphAPI } = require('../utils/graph-api');
 const { ensureAuthenticated } = require('../auth');
 const { DEFAULT_TIMEZONE } = require('../config');
+const { buildAttendees } = require('./attendees');
 
 /**
  * Create event handler
@@ -24,6 +25,19 @@ async function handleCreateEvent(args) {
     };
   }
 
+  // Plain strings are required attendees; {email, type} sets the type (#249).
+  let graphAttendees;
+  if (attendees) {
+    try {
+      graphAttendees = buildAttendees(attendees);
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error.message }],
+        isError: true,
+      };
+    }
+  }
+
   try {
     // Get access token
     const accessToken = await ensureAuthenticated();
@@ -42,10 +56,7 @@ async function handleCreateEvent(args) {
         dateTime: end.dateTime || end,
         timeZone: end.timeZone || DEFAULT_TIMEZONE,
       },
-      attendees: attendees?.map((email) => ({
-        emailAddress: { address: email },
-        type: 'required',
-      })),
+      attendees: graphAttendees,
       body: { contentType: 'HTML', content: body || '' },
     };
 

package/calendar/decline.js

@@ -10,7 +10,7 @@ const { ensureAuthenticated } = require('../auth');
  * @returns {object} - MCP response
  */
 async function handleDeclineEvent(args) {
-  const { eventId, comment } = args;
+  const { eventId, comment, sendResponse } = args;
 
   if (!eventId) {
     return {
@@ -30,10 +30,15 @@ async function handleDeclineEvent(args) {
     // Build API endpoint
     const endpoint = `me/events/${eventId}/decline`;
 
-    // Request body
-    const body = {
-      comment: comment || 'Declined via API',
-    };
+    // Only send what the caller gave: no placeholder comment, and Graph's
+    // own default (notify the organiser) unless sendResponse is set.
+    const body = {};
+    if (typeof comment === 'string' && comment.trim() !== '') {
+      body.comment = comment;
+    }
+    if (typeof sendResponse === 'boolean') {
+      body.sendResponse = sendResponse;
+    }
 
     // Make API call
     await callGraphAPI(accessToken, 'POST', endpoint, body);

package/calendar/index.js

@@ -7,13 +7,31 @@ const handleCreateEvent = require('./create');
 const handleCancelEvent = require('./cancel');
 const handleDeleteEvent = require('./delete');
 const handleUpdateEvent = require('./update');
+const { ATTENDEE_TYPES } = require('./attendees');
+
+// One attendee: an email string, or {email, type} (#249). schema-coerce
+// doesn't validate inside array items, so calendar/attendees.js re-checks.
+const ATTENDEE_ITEM_SCHEMA = {
+  oneOf: [
+    { type: 'string' },
+    {
+      type: 'object',
+      properties: {
+        email: { type: 'string' },
+        type: { type: 'string', enum: [...ATTENDEE_TYPES] },
+      },
+      required: ['email'],
+      additionalProperties: false,
+    },
+  ],
+};
 
 // Calendar tool definitions (consolidated: 5 → 3)
 const calendarTools = [
   {
     name: 'list-events',
     description:
-      'List calendar events for the signed-in user (read-only). By default returns upcoming events (start ≥ now). Optional `startAfter`, `startBefore` and `subject` filters find past, current or specifically-named events; supplying any of them replaces the default "now" lower bound and the filters are AND-ed together. Results are oldest first, except when the search only looks backwards (`startBefore` without `startAfter`, or `subject` alone), where they are newest first. Returns an array of events with id, subject, start/end, attendees, location, organiser, and webLink. Use `count` (default 10, max 50) to control page size. Each start/end is returned as a canonical UTC ISO-8601 instant (e.g. `2026-04-02T22:00:00.000Z`) followed by a labelled local rendering in the configured display timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`) — the UTC value is authoritative, so consumers never have to guess the zone.',
+      'List calendar events for the signed-in user (read-only). By default returns upcoming events (start ≥ now). Optional `startAfter`, `startBefore` and `subject` filters find past, current or specifically-named events; supplying any of them replaces the default "now" lower bound and the filters are AND-ed together. Results are oldest first, except when the search only looks backwards (`startBefore` without `startAfter`, or `subject` alone), where they are newest first. Each event shows its subject, location, start/end, a body preview and its id. Use `count` (default 10, max 100) to control page size. Each start/end is returned as a canonical UTC ISO-8601 instant (e.g. `2026-04-02T22:00:00.000Z`) followed by a labelled local rendering in the configured display timezone (default Australia/Melbourne; override with `OUTLOOK_DEFAULT_TIMEZONE`) — the UTC value is authoritative, so consumers never have to guess the zone.',
     annotations: {
       title: 'List Calendar Events',
       readOnlyHint: true,
@@ -24,7 +42,7 @@ const calendarTools = [
       properties: {
         count: {
           type: 'number',
-          description: 'Number of events to retrieve (default: 10, max: 50)',
+          description: 'Number of events to retrieve (default: 10, max: 100)',
         },
         startAfter: {
           type: 'string',
@@ -77,10 +95,9 @@ const calendarTools = [
         },
         attendees: {
           type: 'array',
-          items: {
-            type: 'string',
-          },
-          description: 'List of attendee email addresses',
+          items: ATTENDEE_ITEM_SCHEMA,
+          description:
+            "Attendees: email address strings (required attendees) or {email, type} objects, where type is 'required', 'optional' or 'resource' (a room or equipment)",
         },
         body: {
           type: 'string',
@@ -95,7 +112,7 @@ const calendarTools = [
   {
     name: 'manage-event',
     description:
-      "Manage an existing calendar event (destructive: covers update/decline/cancel/delete — use dryRun where supported to preview). action=`update` edits fields in place via PATCH (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart) — only fields you pass are changed; pass `dryRun: true` to preview the PATCH payload. action=`decline` declines an invitation (optional `comment`). action=`cancel` cancels an event you organised and notifies attendees. action=`delete` permanently removes the event. Returns the updated event on update; status confirmation otherwise. Note: there is no `accept` action — accept invitations in the Outlook UI (Graph's accept verb is unreliable across personal/M365).",
+      "Manage an existing calendar event (destructive: covers update/decline/cancel/delete — use dryRun where supported to preview). action=`update` edits fields in place via PATCH (subject, start, end, attendees, body, location, isOnlineMeeting, sensitivity, showAs, importance, categories, reminderMinutesBeforeStart) — only fields you pass are changed; pass `dryRun: true` to preview the PATCH payload. action=`decline` declines an invitation (optional `comment`; `sendResponse: false` declines without notifying the organiser). action=`cancel` cancels an event you organised and notifies attendees. action=`delete` removes the event from your calendar (Graph doesn't document a guaranteed recovery path, so don't count on restoring it); deleting a meeting you organised that has attendees still emails them a cancellation, so use `cancel` (with an optional `comment`) when you want to control that message. Returns the updated event on update; status confirmation otherwise. Note: there is no `accept` action — accept invitations in the Outlook UI (Graph's accept verb is unreliable across personal/M365).",
     annotations: {
       title: 'Manage Calendar Event',
       readOnlyHint: false,
@@ -121,7 +138,13 @@ const calendarTools = [
         },
         comment: {
           type: 'string',
-          description: 'Optional comment for declining or cancelling the event',
+          description:
+            'Message sent with a decline or cancel (optional; omitted if not given)',
+        },
+        sendResponse: {
+          type: 'boolean',
+          description:
+            'Send the decline to the organiser (action=decline only; default true). Pass false to decline without notifying the organiser.',
         },
         subject: {
           type: 'string',
@@ -161,9 +184,9 @@ const calendarTools = [
         },
         attendees: {
           type: 'array',
-          items: { type: 'string' },
+          items: ATTENDEE_ITEM_SCHEMA,
           description:
-            'Full replacement attendee list — pass complete desired list, or [] to clear (action=update only)',
+            "Full replacement attendee list — pass the complete desired list, or [] to clear (action=update only). Each entry is an email address string or an {email, type} object (type 'required', 'optional' or 'resource'). A string, or an object without a type, keeps the type that address already has on the event (new addresses are required); an explicit type always wins.",
         },
         body: {
           type: 'string',

package/calendar/list.js

@@ -8,13 +8,8 @@ const {
   escapeODataString,
   buildODataFilter,
 } = require('../utils/odata-helpers');
+const { parseIsoInstant } = require('../utils/datetime');
 
-// An ISO 8601 instant with an explicit zone: `Z` or a ±hh:mm offset. A
-// zone-less value would be read in the server's local timezone by Date.parse,
-// so results would differ between machines; date-only values are rejected for
-// the same reason.
-const ISO_INSTANT =
-  /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
 const MAX_SUBJECT_LENGTH = 255;
 
 /**
@@ -31,18 +26,8 @@ class ListEventsArgumentError extends Error {}
  * does not enforce JSON Schema `format`, so we enforce here at runtime.
  */
 function toUtcIsoDateTime(value, paramName) {
-  const s = typeof value === 'string' ? value.trim() : '';
-  const m = ISO_INSTANT.exec(s);
-  const parsed = m ? Date.parse(s) : NaN;
-  const valid =
-    m &&
-    !Number.isNaN(parsed) &&
-    Number(m[1]) >= 1900 &&
-    // Reject dates Date.parse would roll over, e.g. 2026-02-30 -> 2 March.
-    new Date(
-      Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]))
-    ).getUTCDate() === Number(m[3]);
-  if (!valid) {
+  const parsed = parseIsoInstant(value);
+  if (Number.isNaN(parsed)) {
     throw new ListEventsArgumentError(
       `Invalid ${paramName}: expected an ISO 8601 datetime with "Z" or a ±hh:mm offset, e.g. "2026-01-01T00:00:00Z" (got ${JSON.stringify(String(value).slice(0, 40))}).`
     );
@@ -224,7 +209,13 @@ function formatLocal(utcIso, tz) {
  * @returns {object} - MCP response
  */
 async function handleListEvents(args) {
-  const count = Math.min(args.count || 10, config.MAX_RESULT_COUNT);
+  // Whole number in 1..MAX_RESULT_COUNT: Graph rejects $top below 1 or
+  // fractional, and the schema promises the cap.
+  const requested = args.count == null ? 10 : Math.floor(args.count);
+  const count = Math.min(
+    Math.max(Number.isFinite(requested) ? requested : 10, 1),
+    config.MAX_RESULT_COUNT
+  );
 
   // Validate arguments before authenticating, so a bad argument is reported
   // as such (and never reaches the network).