@softeria/ms-365-mcp-server 0.36.1 → 0.38.0

package/README.md

@@ -490,6 +490,25 @@ Environment variables:
 - `MS365_MCP_TENANT_ID`: Custom tenant ID (defaults to 'common' for multi-tenant)
 - `MS365_MCP_OAUTH_TOKEN`: Pre-existing OAuth token for Microsoft Graph API (BYOT method)
 - `MS365_MCP_KEYVAULT_URL`: Azure Key Vault URL for secrets management (see Azure Key Vault section)
+- `MS365_MCP_TOKEN_CACHE_PATH`: Custom file path for MSAL token cache (see Token Storage below)
+- `MS365_MCP_SELECTED_ACCOUNT_PATH`: Custom file path for selected account metadata (see Token Storage below)
+
+## Token Storage
+
+Authentication tokens are stored using the OS credential store (via keytar) when available. If keytar is not installed or fails (common on headless Linux), the server falls back to file-based storage.
+
+**Default fallback paths** are relative to the installed package directory. This means tokens can be lost when the package is reinstalled or updated via npm.
+
+To persist tokens across updates, set custom paths outside the package directory:
+
+```bash
+export MS365_MCP_TOKEN_CACHE_PATH="$HOME/.config/ms365-mcp/.token-cache.json"
+export MS365_MCP_SELECTED_ACCOUNT_PATH="$HOME/.config/ms365-mcp/.selected-account.json"
+```
+
+Parent directories are created automatically. Files are written with `0600` permissions.
+
+> **Security note**: File-based token storage writes sensitive credentials to disk. Ensure the chosen directory has appropriate access controls. The OS credential store (keytar) is preferred when available.
 
 ## Azure Key Vault Integration
 

package/bin/modules/simplified-openapi.mjs

@@ -253,6 +253,8 @@ function reduceProperties(schema, schemaName) {
       'path',
       'method',
       'enabled',
+      'singleValueExtendedProperties',
+      'multiValueExtendedProperties',
     ];
 
     const keptProperties = {};
@@ -264,12 +266,14 @@ function reduceProperties(schema, schemaName) {
       }
     });
 
-    const remainingSlots = 25 - Object.keys(keptProperties).length;
+    const remainingSlots = Math.max(0, 25 - Object.keys(keptProperties).length);
     const otherKeys = propertyKeys.filter((key) => !keptProperties[key]);
 
-    otherKeys.slice(0, remainingSlots).forEach((key) => {
-      keptProperties[key] = properties[key];
-    });
+    if (remainingSlots > 0) {
+      otherKeys.slice(0, remainingSlots).forEach((key) => {
+        keptProperties[key] = properties[key];
+      });
+    }
 
     schema.properties = keptProperties;
     schema.additionalProperties = true;

package/dist/auth.js

@@ -34,8 +34,20 @@ const SERVICE_NAME = "ms-365-mcp-server";
 const TOKEN_CACHE_ACCOUNT = "msal-token-cache";
 const SELECTED_ACCOUNT_KEY = "selected-account";
 const FALLBACK_DIR = path.dirname(fileURLToPath(import.meta.url));
-const FALLBACK_PATH = path.join(FALLBACK_DIR, "..", ".token-cache.json");
-const SELECTED_ACCOUNT_PATH = path.join(FALLBACK_DIR, "..", ".selected-account.json");
+const DEFAULT_TOKEN_CACHE_PATH = path.join(FALLBACK_DIR, "..", ".token-cache.json");
+const DEFAULT_SELECTED_ACCOUNT_PATH = path.join(FALLBACK_DIR, "..", ".selected-account.json");
+function getTokenCachePath() {
+  const envPath = process.env.MS365_MCP_TOKEN_CACHE_PATH?.trim();
+  return envPath || DEFAULT_TOKEN_CACHE_PATH;
+}
+function getSelectedAccountPath() {
+  const envPath = process.env.MS365_MCP_SELECTED_ACCOUNT_PATH?.trim();
+  return envPath || DEFAULT_SELECTED_ACCOUNT_PATH;
+}
+function ensureParentDir(filePath) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+}
 function createMsalConfig(secrets) {
   const cloudEndpoints = getCloudEndpoints(secrets.cloudType);
   return {
@@ -128,8 +140,9 @@ class AuthManager {
           `Keychain access failed, falling back to file storage: ${keytarError.message}`
         );
       }
-      if (!cacheData && existsSync(FALLBACK_PATH)) {
-        cacheData = readFileSync(FALLBACK_PATH, "utf8");
+      const cachePath = getTokenCachePath();
+      if (!cacheData && existsSync(cachePath)) {
+        cacheData = readFileSync(cachePath, "utf8");
       }
       if (cacheData) {
         this.msalApp.getTokenCache().deserialize(cacheData);
@@ -155,8 +168,9 @@ class AuthManager {
           `Keychain access failed for selected account, falling back to file storage: ${keytarError.message}`
         );
       }
-      if (!selectedAccountData && existsSync(SELECTED_ACCOUNT_PATH)) {
-        selectedAccountData = readFileSync(SELECTED_ACCOUNT_PATH, "utf8");
+      const accountPath = getSelectedAccountPath();
+      if (!selectedAccountData && existsSync(accountPath)) {
+        selectedAccountData = readFileSync(accountPath, "utf8");
       }
       if (selectedAccountData) {
         const parsed = JSON.parse(selectedAccountData);
@@ -175,13 +189,17 @@ class AuthManager {
         if (kt) {
           await kt.setPassword(SERVICE_NAME, TOKEN_CACHE_ACCOUNT, cacheData);
         } else {
-          fs.writeFileSync(FALLBACK_PATH, cacheData, { mode: 384 });
+          const cachePath = getTokenCachePath();
+          ensureParentDir(cachePath);
+          fs.writeFileSync(cachePath, cacheData, { mode: 384 });
         }
       } catch (keytarError) {
         logger.warn(
           `Keychain save failed, falling back to file storage: ${keytarError.message}`
         );
-        fs.writeFileSync(FALLBACK_PATH, cacheData, { mode: 384 });
+        const cachePath = getTokenCachePath();
+        ensureParentDir(cachePath);
+        fs.writeFileSync(cachePath, cacheData, { mode: 384 });
       }
     } catch (error) {
       logger.error(`Error saving token cache: ${error.message}`);
@@ -195,13 +213,17 @@ class AuthManager {
         if (kt) {
           await kt.setPassword(SERVICE_NAME, SELECTED_ACCOUNT_KEY, selectedAccountData);
         } else {
-          fs.writeFileSync(SELECTED_ACCOUNT_PATH, selectedAccountData, { mode: 384 });
+          const accountPath = getSelectedAccountPath();
+          ensureParentDir(accountPath);
+          fs.writeFileSync(accountPath, selectedAccountData, { mode: 384 });
         }
       } catch (keytarError) {
         logger.warn(
           `Keychain save failed for selected account, falling back to file storage: ${keytarError.message}`
         );
-        fs.writeFileSync(SELECTED_ACCOUNT_PATH, selectedAccountData, { mode: 384 });
+        const accountPath = getSelectedAccountPath();
+        ensureParentDir(accountPath);
+        fs.writeFileSync(accountPath, selectedAccountData, { mode: 384 });
       }
     } catch (error) {
       logger.error(`Error saving selected account: ${error.message}`);
@@ -359,11 +381,13 @@ class AuthManager {
       } catch (keytarError) {
         logger.warn(`Keychain deletion failed: ${keytarError.message}`);
       }
-      if (fs.existsSync(FALLBACK_PATH)) {
-        fs.unlinkSync(FALLBACK_PATH);
+      const cachePath = getTokenCachePath();
+      if (fs.existsSync(cachePath)) {
+        fs.unlinkSync(cachePath);
       }
-      if (fs.existsSync(SELECTED_ACCOUNT_PATH)) {
-        fs.unlinkSync(SELECTED_ACCOUNT_PATH);
+      const accountPath = getSelectedAccountPath();
+      if (fs.existsSync(accountPath)) {
+        fs.unlinkSync(accountPath);
       }
       return true;
     } catch (error) {
@@ -418,5 +442,7 @@ class AuthManager {
 var auth_default = AuthManager;
 export {
   buildScopesFromEndpoints,
-  auth_default as default
+  auth_default as default,
+  getSelectedAccountPath,
+  getTokenCachePath
 };

package/dist/endpoints.json

@@ -153,14 +153,16 @@
     "method": "get",
     "toolName": "list-calendar-events",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true
   },
   {
     "pathPattern": "/me/events/{event-id}",
     "method": "get",
     "toolName": "get-calendar-event",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true
   },
   {
     "pathPattern": "/me/events",
@@ -187,14 +189,16 @@
     "method": "get",
     "toolName": "list-specific-calendar-events",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events/{event-id}",
     "method": "get",
     "toolName": "get-specific-calendar-event",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events",
@@ -221,7 +225,27 @@
     "method": "get",
     "toolName": "get-calendar-view",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "Returns expanded recurring event instances (not just seriesMaster) within a date range for the default calendar. Requires startDateTime and endDateTime query parameters in ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Use get-specific-calendar-view if you need a non-default calendar."
+  },
+  {
+    "pathPattern": "/me/calendars/{calendar-id}/calendarView",
+    "method": "get",
+    "toolName": "get-specific-calendar-view",
+    "scopes": ["Calendars.Read"],
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "Returns expanded recurring event instances (not just seriesMaster) within a date range for a specific calendar. Requires startDateTime and endDateTime query parameters in ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Each instance includes seriesMasterId and type (occurrence/exception) fields for recurring event linkage. Use fetchAllPages=true to retrieve all results when there are many events."
+  },
+  {
+    "pathPattern": "/me/calendars/{calendar-id}/events/{event-id}/instances",
+    "method": "get",
+    "toolName": "list-calendar-event-instances",
+    "scopes": ["Calendars.Read"],
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "Expand a recurring event into individual instances within a date range. Requires startDateTime and endDateTime query parameters in ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Use this to see all occurrences of a recurring event."
   },
   {
     "pathPattern": "/me/calendars",

package/dist/generated/client.js

@@ -1345,53 +1345,6 @@ const microsoft_graph_attendee = z.object({
   status: microsoft_graph_responseStatus.optional()
 }).strict();
 const microsoft_graph_importance = z.enum(["low", "normal", "high"]);
-const microsoft_graph_physicalAddress = z.object({
-  city: z.string().describe("The city.").nullish(),
-  countryOrRegion: z.string().describe(
-    "The country or region. It's a free-format string value, for example, 'United States'."
-  ).nullish(),
-  postalCode: z.string().describe("The postal code.").nullish(),
-  state: z.string().describe("The state.").nullish(),
-  street: z.string().describe("The street.").nullish()
-}).strict();
-const microsoft_graph_outlookGeoCoordinates = z.object({
-  accuracy: z.number().describe(
-    "The accuracy of the latitude and longitude. As an example, the accuracy can be measured in meters, such as the latitude and longitude are accurate to within 50 meters. [Simplified from 3 options]"
-  ).nullish(),
-  altitude: z.number().describe("The altitude of the location. [Simplified from 3 options]").nullish(),
-  altitudeAccuracy: z.number().describe("The accuracy of the altitude. [Simplified from 3 options]").nullish(),
-  latitude: z.number().describe("The latitude of the location. [Simplified from 3 options]").nullish(),
-  longitude: z.number().describe("The longitude of the location. [Simplified from 3 options]").nullish()
-}).strict();
-const microsoft_graph_locationType = z.enum([
-  "default",
-  "conferenceRoom",
-  "homeAddress",
-  "businessAddress",
-  "geoCoordinates",
-  "streetAddress",
-  "hotel",
-  "restaurant",
-  "localBusiness",
-  "postalAddress"
-]);
-const microsoft_graph_locationUniqueIdType = z.enum([
-  "unknown",
-  "locationStore",
-  "directory",
-  "private",
-  "bing"
-]);
-const microsoft_graph_location = z.object({
-  address: microsoft_graph_physicalAddress.optional(),
-  coordinates: microsoft_graph_outlookGeoCoordinates.optional(),
-  displayName: z.string().describe("The name associated with the location.").nullish(),
-  locationEmailAddress: z.string().describe("Optional email address of the location.").nullish(),
-  locationType: microsoft_graph_locationType.optional(),
-  locationUri: z.string().describe("Optional URI representing the location.").nullish(),
-  uniqueId: z.string().describe("For internal use only.").nullish(),
-  uniqueIdType: microsoft_graph_locationUniqueIdType.optional()
-}).strict();
 const microsoft_graph_event = z.object({
   id: z.string().describe("The unique identifier for an entity. Read-only.").optional(),
   createdDateTime: z.string().regex(
@@ -1410,6 +1363,12 @@ const microsoft_graph_event = z.object({
   attachments: z.array(microsoft_graph_attachment).describe(
     "The collection of FileAttachment, ItemAttachment, and referenceAttachment attachments for the event. Navigation property. Read-only. Nullable."
   ).optional(),
+  singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+    "The collection of single-value extended properties defined for the event. Read-only. Nullable."
+  ).optional(),
+  multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+    "The collection of multi-value extended properties defined for the event. Read-only. Nullable."
+  ).optional(),
   categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
   changeKey: z.string().describe(
     "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -1443,9 +1402,7 @@ const microsoft_graph_event = z.object({
   ).nullish(),
   isOrganizer: z.boolean().describe(
     "Set to true if the calendar owner (specified by the owner property of the calendar) is the organizer of the event (specified by the organizer property of the event). It also applies if a delegate organized the event on behalf of the owner."
-  ).nullish(),
-  isReminderOn: z.boolean().describe("Set to true if an alert is set to remind the user of the event.").nullish(),
-  location: microsoft_graph_location.optional()
+  ).nullish()
 }).strict().passthrough();
 const microsoft_graph_calendar = z.object({
   id: z.string().describe("The unique identifier for an entity. Read-only.").optional(),
@@ -1503,6 +1460,15 @@ const microsoft_graph_chatCollectionResponse = z.object({
   "@odata.nextLink": z.string().nullable(),
   value: z.array(microsoft_graph_chat)
 }).partial().strict();
+const microsoft_graph_physicalAddress = z.object({
+  city: z.string().describe("The city.").nullish(),
+  countryOrRegion: z.string().describe(
+    "The country or region. It's a free-format string value, for example, 'United States'."
+  ).nullish(),
+  postalCode: z.string().describe("The postal code.").nullish(),
+  state: z.string().describe("The state.").nullish(),
+  street: z.string().describe("The street.").nullish()
+}).strict();
 const microsoft_graph_contact = z.object({
   id: z.string().describe("The unique identifier for an entity. Read-only.").optional(),
   displayName: z.string().describe(
@@ -1519,6 +1485,12 @@ const microsoft_graph_contact = z.object({
     "The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z"
   ).nullish(),
   title: z.string().describe("The contact's title.").nullish(),
+  singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+    "The collection of single-value extended properties defined for the contact. Read-only. Nullable."
+  ).optional(),
+  multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+    "The collection of multi-value extended properties defined for the contact. Read-only. Nullable."
+  ).optional(),
   categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
   changeKey: z.string().describe(
     "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -1542,9 +1514,7 @@ const microsoft_graph_contact = z.object({
   homeAddress: microsoft_graph_physicalAddress.optional(),
   homePhones: z.array(z.string().nullable()).describe("The contact's home phone numbers.").optional(),
   imAddresses: z.array(z.string().nullable()).describe("The contact's instant messaging (IM) addresses.").optional(),
-  initials: z.string().describe("The contact's initials.").nullish(),
-  jobTitle: z.string().describe("The contact\u2019s job title.").nullish(),
-  manager: z.string().describe("The name of the contact's manager.").nullish()
+  initials: z.string().describe("The contact's initials.").nullish()
 }).strict().passthrough();
 const microsoft_graph_contactCollectionResponse = z.object({
   "@odata.count": z.number().int().nullable(),
@@ -2453,6 +2423,12 @@ const microsoft_graph_message = z.object({
   body: microsoft_graph_itemBody.optional(),
   subject: z.string().describe("The subject of the message.").nullish(),
   attachments: z.array(microsoft_graph_attachment).describe("The fileAttachment and itemAttachment attachments for the message.").optional(),
+  singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+    "The collection of single-value extended properties defined for the message. Nullable."
+  ).optional(),
+  multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+    "The collection of multi-value extended properties defined for the message. Nullable."
+  ).optional(),
   categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
   changeKey: z.string().describe(
     "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -2477,9 +2453,7 @@ const microsoft_graph_message = z.object({
   isDraft: z.boolean().describe(
     "Indicates whether the message is a draft. A message is a draft if it hasn't been sent yet."
   ).nullish(),
-  isRead: z.boolean().describe("Indicates whether the message has been read.").nullish(),
-  isReadReceiptRequested: z.boolean().describe("Indicates whether a read receipt is requested for the message.").nullish(),
-  parentFolderId: z.string().describe("The unique identifier for the message's parent mailFolder.").nullish()
+  isRead: z.boolean().describe("Indicates whether the message has been read.").nullish()
 }).strict().passthrough();
 const microsoft_graph_mailFolder = z.lazy(
   () => z.object({
@@ -2531,6 +2505,34 @@ const microsoft_graph_attendeeBase = z.object({
   emailAddress: microsoft_graph_emailAddress.optional(),
   type: microsoft_graph_attendeeType.optional()
 }).strict();
+const microsoft_graph_outlookGeoCoordinates = z.object({
+  accuracy: z.number().describe(
+    "The accuracy of the latitude and longitude. As an example, the accuracy can be measured in meters, such as the latitude and longitude are accurate to within 50 meters. [Simplified from 3 options]"
+  ).nullish(),
+  altitude: z.number().describe("The altitude of the location. [Simplified from 3 options]").nullish(),
+  altitudeAccuracy: z.number().describe("The accuracy of the altitude. [Simplified from 3 options]").nullish(),
+  latitude: z.number().describe("The latitude of the location. [Simplified from 3 options]").nullish(),
+  longitude: z.number().describe("The longitude of the location. [Simplified from 3 options]").nullish()
+}).strict();
+const microsoft_graph_locationType = z.enum([
+  "default",
+  "conferenceRoom",
+  "homeAddress",
+  "businessAddress",
+  "geoCoordinates",
+  "streetAddress",
+  "hotel",
+  "restaurant",
+  "localBusiness",
+  "postalAddress"
+]);
+const microsoft_graph_locationUniqueIdType = z.enum([
+  "unknown",
+  "locationStore",
+  "directory",
+  "private",
+  "bing"
+]);
 const microsoft_graph_locationConstraintItem = z.object({
   address: microsoft_graph_physicalAddress.optional(),
   coordinates: microsoft_graph_outlookGeoCoordinates.optional(),
@@ -3493,16 +3495,12 @@ const schemas = {
   microsoft_graph_responseStatus,
   microsoft_graph_attendee,
   microsoft_graph_importance,
-  microsoft_graph_physicalAddress,
-  microsoft_graph_outlookGeoCoordinates,
-  microsoft_graph_locationType,
-  microsoft_graph_locationUniqueIdType,
-  microsoft_graph_location,
   microsoft_graph_event,
   microsoft_graph_calendar,
   microsoft_graph_calendarCollectionResponse,
   microsoft_graph_eventCollectionResponse,
   microsoft_graph_chatCollectionResponse,
+  microsoft_graph_physicalAddress,
   microsoft_graph_contact,
   microsoft_graph_contactCollectionResponse,
   microsoft_graph_storagePlanInformation,
@@ -3588,6 +3586,9 @@ const schemas = {
   create_forward_draft_Body,
   reply_mail_message_Body,
   microsoft_graph_attendeeBase,
+  microsoft_graph_outlookGeoCoordinates,
+  microsoft_graph_locationType,
+  microsoft_graph_locationUniqueIdType,
   microsoft_graph_locationConstraintItem,
   microsoft_graph_locationConstraint,
   microsoft_graph_activityDomain,
@@ -4273,6 +4274,70 @@ const endpoints = makeApi([
     ],
     response: z.void()
   },
+  {
+    method: "get",
+    path: "/me/calendars/:calendarId/calendarView",
+    alias: "get-specific-calendar-view",
+    description: `The calendar view for the calendar. Navigation property. Read-only.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "startDateTime",
+        type: "Query",
+        schema: z.string().describe(
+          "The start date and time of the time range, represented in ISO 8601 format. For example, 2019-11-08T19:00:00-08:00"
+        )
+      },
+      {
+        name: "endDateTime",
+        type: "Query",
+        schema: z.string().describe(
+          "The end date and time of the time range, represented in ISO 8601 format. For example, 2019-11-08T20:00:00-08:00"
+        )
+      },
+      {
+        name: "$top",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Show only the first n items").optional()
+      },
+      {
+        name: "$skip",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Skip the first n items").optional()
+      },
+      {
+        name: "$search",
+        type: "Query",
+        schema: z.string().describe("Search items by search phrases").optional()
+      },
+      {
+        name: "$filter",
+        type: "Query",
+        schema: z.string().describe("Filter items by property values").optional()
+      },
+      {
+        name: "$count",
+        type: "Query",
+        schema: z.boolean().describe("Include count of items").optional()
+      },
+      {
+        name: "$orderby",
+        type: "Query",
+        schema: z.array(z.string()).describe("Order items by property values").optional()
+      },
+      {
+        name: "$select",
+        type: "Query",
+        schema: z.array(z.string()).describe("Select properties to be returned").optional()
+      },
+      {
+        name: "$expand",
+        type: "Query",
+        schema: z.array(z.string()).describe("Expand related entities").optional()
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "get",
     path: "/me/calendars/:calendarId/events",
@@ -4352,6 +4417,12 @@ const endpoints = makeApi([
           attachments: z.array(microsoft_graph_attachment).describe(
             "The collection of FileAttachment, ItemAttachment, and referenceAttachment attachments for the event. Navigation property. Read-only. Nullable."
           ).optional(),
+          singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+            "The collection of single-value extended properties defined for the event. Read-only. Nullable."
+          ).optional(),
+          multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+            "The collection of multi-value extended properties defined for the event. Read-only. Nullable."
+          ).optional(),
           categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
           changeKey: z.string().describe(
             "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -4387,9 +4458,7 @@ const endpoints = makeApi([
           ).nullish(),
           isOrganizer: z.boolean().describe(
             "Set to true if the calendar owner (specified by the owner property of the calendar) is the organizer of the event (specified by the organizer property of the event). It also applies if a delegate organized the event on behalf of the owner."
-          ).nullish(),
-          isReminderOn: z.boolean().describe("Set to true if an alert is set to remind the user of the event.").nullish(),
-          location: microsoft_graph_location.optional()
+          ).nullish()
         }).strict().passthrough()
       }
     ],
@@ -4444,6 +4513,12 @@ const endpoints = makeApi([
           attachments: z.array(microsoft_graph_attachment).describe(
             "The collection of FileAttachment, ItemAttachment, and referenceAttachment attachments for the event. Navigation property. Read-only. Nullable."
           ).optional(),
+          singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+            "The collection of single-value extended properties defined for the event. Read-only. Nullable."
+          ).optional(),
+          multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+            "The collection of multi-value extended properties defined for the event. Read-only. Nullable."
+          ).optional(),
           categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
           changeKey: z.string().describe(
             "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -4479,9 +4554,7 @@ const endpoints = makeApi([
           ).nullish(),
           isOrganizer: z.boolean().describe(
             "Set to true if the calendar owner (specified by the owner property of the calendar) is the organizer of the event (specified by the organizer property of the event). It also applies if a delegate organized the event on behalf of the owner."
-          ).nullish(),
-          isReminderOn: z.boolean().describe("Set to true if an alert is set to remind the user of the event.").nullish(),
-          location: microsoft_graph_location.optional()
+          ).nullish()
         }).strict().passthrough()
       }
     ],
@@ -4502,6 +4575,70 @@ const endpoints = makeApi([
     ],
     response: z.void()
   },
+  {
+    method: "get",
+    path: "/me/calendars/:calendarId/events/:eventId/instances",
+    alias: "list-calendar-event-instances",
+    description: `The occurrences of a recurring series, if the event is a series master. This property includes occurrences that are part of the recurrence pattern, and exceptions modified, but doesn't include occurrences canceled from the series. Navigation property. Read-only. Nullable.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "startDateTime",
+        type: "Query",
+        schema: z.string().describe(
+          "The start date and time of the time range, represented in ISO 8601 format. For example, 2019-11-08T19:00:00-08:00"
+        )
+      },
+      {
+        name: "endDateTime",
+        type: "Query",
+        schema: z.string().describe(
+          "The end date and time of the time range, represented in ISO 8601 format. For example, 2019-11-08T20:00:00-08:00"
+        )
+      },
+      {
+        name: "$top",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Show only the first n items").optional()
+      },
+      {
+        name: "$skip",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Skip the first n items").optional()
+      },
+      {
+        name: "$search",
+        type: "Query",
+        schema: z.string().describe("Search items by search phrases").optional()
+      },
+      {
+        name: "$filter",
+        type: "Query",
+        schema: z.string().describe("Filter items by property values").optional()
+      },
+      {
+        name: "$count",
+        type: "Query",
+        schema: z.boolean().describe("Include count of items").optional()
+      },
+      {
+        name: "$orderby",
+        type: "Query",
+        schema: z.array(z.string()).describe("Order items by property values").optional()
+      },
+      {
+        name: "$select",
+        type: "Query",
+        schema: z.array(z.string()).describe("Select properties to be returned").optional()
+      },
+      {
+        name: "$expand",
+        type: "Query",
+        schema: z.array(z.string()).describe("Expand related entities").optional()
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "get",
     path: "/me/calendarView",
@@ -4694,6 +4831,12 @@ or from some other calendar of the user.`,
             "The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z"
           ).nullish(),
           title: z.string().describe("The contact's title.").nullish(),
+          singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+            "The collection of single-value extended properties defined for the contact. Read-only. Nullable."
+          ).optional(),
+          multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+            "The collection of multi-value extended properties defined for the contact. Read-only. Nullable."
+          ).optional(),
           categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
           changeKey: z.string().describe(
             "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -4717,9 +4860,7 @@ or from some other calendar of the user.`,
           homeAddress: microsoft_graph_physicalAddress.optional(),
           homePhones: z.array(z.string().nullable()).describe("The contact's home phone numbers.").optional(),
           imAddresses: z.array(z.string().nullable()).describe("The contact's instant messaging (IM) addresses.").optional(),
-          initials: z.string().describe("The contact's initials.").nullish(),
-          jobTitle: z.string().describe("The contact\u2019s job title.").nullish(),
-          manager: z.string().describe("The name of the contact's manager.").nullish()
+          initials: z.string().describe("The contact's initials.").nullish()
         }).strict().passthrough()
       }
     ],
@@ -4772,6 +4913,12 @@ or from some other calendar of the user.`,
             "The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z"
           ).nullish(),
           title: z.string().describe("The contact's title.").nullish(),
+          singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+            "The collection of single-value extended properties defined for the contact. Read-only. Nullable."
+          ).optional(),
+          multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+            "The collection of multi-value extended properties defined for the contact. Read-only. Nullable."
+          ).optional(),
           categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
           changeKey: z.string().describe(
             "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -4795,9 +4942,7 @@ or from some other calendar of the user.`,
           homeAddress: microsoft_graph_physicalAddress.optional(),
           homePhones: z.array(z.string().nullable()).describe("The contact's home phone numbers.").optional(),
           imAddresses: z.array(z.string().nullable()).describe("The contact's instant messaging (IM) addresses.").optional(),
-          initials: z.string().describe("The contact's initials.").nullish(),
-          jobTitle: z.string().describe("The contact\u2019s job title.").nullish(),
-          manager: z.string().describe("The name of the contact's manager.").nullish()
+          initials: z.string().describe("The contact's initials.").nullish()
         }).strict().passthrough()
       }
     ],
@@ -4950,6 +5095,12 @@ open extensions or extended properties, and how to specify extended properties.`
           attachments: z.array(microsoft_graph_attachment).describe(
             "The collection of FileAttachment, ItemAttachment, and referenceAttachment attachments for the event. Navigation property. Read-only. Nullable."
           ).optional(),
+          singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+            "The collection of single-value extended properties defined for the event. Read-only. Nullable."
+          ).optional(),
+          multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+            "The collection of multi-value extended properties defined for the event. Read-only. Nullable."
+          ).optional(),
           categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
           changeKey: z.string().describe(
             "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -4985,9 +5136,7 @@ open extensions or extended properties, and how to specify extended properties.`
           ).nullish(),
           isOrganizer: z.boolean().describe(
             "Set to true if the calendar owner (specified by the owner property of the calendar) is the organizer of the event (specified by the organizer property of the event). It also applies if a delegate organized the event on behalf of the owner."
-          ).nullish(),
-          isReminderOn: z.boolean().describe("Set to true if an alert is set to remind the user of the event.").nullish(),
-          location: microsoft_graph_location.optional()
+          ).nullish()
         }).strict().passthrough()
       }
     ],
@@ -5042,6 +5191,12 @@ open extensions or extended properties, and how to specify extended properties.`
           attachments: z.array(microsoft_graph_attachment).describe(
             "The collection of FileAttachment, ItemAttachment, and referenceAttachment attachments for the event. Navigation property. Read-only. Nullable."
           ).optional(),
+          singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+            "The collection of single-value extended properties defined for the event. Read-only. Nullable."
+          ).optional(),
+          multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+            "The collection of multi-value extended properties defined for the event. Read-only. Nullable."
+          ).optional(),
           categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
           changeKey: z.string().describe(
             "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -5077,9 +5232,7 @@ open extensions or extended properties, and how to specify extended properties.`
           ).nullish(),
           isOrganizer: z.boolean().describe(
             "Set to true if the calendar owner (specified by the owner property of the calendar) is the organizer of the event (specified by the organizer property of the event). It also applies if a delegate organized the event on behalf of the owner."
-          ).nullish(),
-          isReminderOn: z.boolean().describe("Set to true if an alert is set to remind the user of the event.").nullish(),
-          location: microsoft_graph_location.optional()
+          ).nullish()
         }).strict().passthrough()
       }
     ],
@@ -5409,6 +5562,12 @@ folder collection and navigate to another folder. By default, this operation doe
           body: microsoft_graph_itemBody.optional(),
           subject: z.string().describe("The subject of the message.").nullish(),
           attachments: z.array(microsoft_graph_attachment).describe("The fileAttachment and itemAttachment attachments for the message.").optional(),
+          singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+            "The collection of single-value extended properties defined for the message. Nullable."
+          ).optional(),
+          multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+            "The collection of multi-value extended properties defined for the message. Nullable."
+          ).optional(),
           categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
           changeKey: z.string().describe(
             "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -5433,9 +5592,7 @@ folder collection and navigate to another folder. By default, this operation doe
           isDraft: z.boolean().describe(
             "Indicates whether the message is a draft. A message is a draft if it hasn't been sent yet."
           ).nullish(),
-          isRead: z.boolean().describe("Indicates whether the message has been read.").nullish(),
-          isReadReceiptRequested: z.boolean().describe("Indicates whether a read receipt is requested for the message.").nullish(),
-          parentFolderId: z.string().describe("The unique identifier for the message's parent mailFolder.").nullish()
+          isRead: z.boolean().describe("Indicates whether the message has been read.").nullish()
         }).strict().passthrough()
       }
     ],
@@ -5487,6 +5644,12 @@ folder collection and navigate to another folder. By default, this operation doe
           body: microsoft_graph_itemBody.optional(),
           subject: z.string().describe("The subject of the message.").nullish(),
           attachments: z.array(microsoft_graph_attachment).describe("The fileAttachment and itemAttachment attachments for the message.").optional(),
+          singleValueExtendedProperties: z.array(microsoft_graph_singleValueLegacyExtendedProperty).describe(
+            "The collection of single-value extended properties defined for the message. Nullable."
+          ).optional(),
+          multiValueExtendedProperties: z.array(microsoft_graph_multiValueLegacyExtendedProperty).describe(
+            "The collection of multi-value extended properties defined for the message. Nullable."
+          ).optional(),
           categories: z.array(z.string().nullable()).describe("The categories associated with the item").optional(),
           changeKey: z.string().describe(
             "Identifies the version of the item. Every time the item is changed, changeKey changes as well. This allows Exchange to apply changes to the correct version of the object. Read-only."
@@ -5511,9 +5674,7 @@ folder collection and navigate to another folder. By default, this operation doe
           isDraft: z.boolean().describe(
             "Indicates whether the message is a draft. A message is a draft if it hasn't been sent yet."
           ).nullish(),
-          isRead: z.boolean().describe("Indicates whether the message has been read.").nullish(),
-          isReadReceiptRequested: z.boolean().describe("Indicates whether a read receipt is requested for the message.").nullish(),
-          parentFolderId: z.string().describe("The unique identifier for the message's parent mailFolder.").nullish()
+          isRead: z.boolean().describe("Indicates whether the message has been read.").nullish()
         }).strict().passthrough()
       }
     ],

package/dist/graph-tools.js

@@ -19,7 +19,13 @@ async function executeGraphTool(tool, config, graphClient, params) {
     const headers = {};
     let body = null;
     for (const [paramName, paramValue] of Object.entries(params)) {
-      if (["fetchAllPages", "includeHeaders", "excludeResponse", "timezone"].includes(paramName)) {
+      if ([
+        "fetchAllPages",
+        "includeHeaders",
+        "excludeResponse",
+        "timezone",
+        "expandExtendedProperties"
+      ].includes(paramName)) {
         continue;
       }
       const odataParams = [
@@ -86,6 +92,15 @@ async function executeGraphTool(tool, config, graphClient, params) {
       headers["Prefer"] = `outlook.timezone="${params.timezone}"`;
       logger.info(`Setting timezone header: Prefer: outlook.timezone="${params.timezone}"`);
     }
+    if (config?.supportsExpandExtendedProperties && params.expandExtendedProperties === true) {
+      const expandValue = "singleValueExtendedProperties";
+      if (queryParams["$expand"]) {
+        queryParams["$expand"] += `,${expandValue}`;
+      } else {
+        queryParams["$expand"] = expandValue;
+      }
+      logger.info(`Adding $expand=${expandValue} for extended properties`);
+    }
     if (config?.contentType) {
       headers["Content-Type"] = config.contentType;
       logger.info(`Setting custom Content-Type: ${config.contentType}`);
@@ -257,6 +272,11 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
         'IANA timezone name (e.g., "America/New_York", "Europe/London", "Asia/Tokyo") for calendar event times. If not specified, times are returned in UTC.'
       ).optional();
     }
+    if (endpointConfig?.supportsExpandExtendedProperties) {
+      paramSchema["expandExtendedProperties"] = z.boolean().describe(
+        "When true, expands singleValueExtendedProperties on each event. Use this to retrieve custom extended properties (e.g., sync metadata) stored on calendar events."
+      ).optional();
+    }
     let toolDescription = tool.description || `Execute ${tool.method.toUpperCase()} request to ${tool.path}`;
     if (endpointConfig?.llmTip) {
       toolDescription += `

package/logs/mcp-server.log

@@ -1,10 +1,10 @@
-2026-02-09 08:24:59 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
-2026-02-09 08:24:59 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
-2026-02-09 08:24:59 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
-2026-02-09 08:24:59 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me/messages
-2026-02-09 08:24:59 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me/calendar
-2026-02-09 08:24:59 INFO: Using environment variables for secrets
-2026-02-09 08:24:59 INFO: Using environment variables for secrets
-2026-02-09 08:24:59 INFO: Using environment variables for secrets
-2026-02-09 08:24:59 INFO: Using environment variables for secrets
-2026-02-09 08:24:59 INFO: Using environment variables for secrets
+2026-02-09 22:59:33 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
+2026-02-09 22:59:33 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
+2026-02-09 22:59:33 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
+2026-02-09 22:59:33 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me/messages
+2026-02-09 22:59:33 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me/calendar
+2026-02-09 22:59:34 INFO: Using environment variables for secrets
+2026-02-09 22:59:34 INFO: Using environment variables for secrets
+2026-02-09 22:59:34 INFO: Using environment variables for secrets
+2026-02-09 22:59:34 INFO: Using environment variables for secrets
+2026-02-09 22:59:34 INFO: Using environment variables for secrets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.36.1",
+  "version": "0.38.0",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",

package/src/endpoints.json

@@ -153,14 +153,16 @@
     "method": "get",
     "toolName": "list-calendar-events",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true
   },
   {
     "pathPattern": "/me/events/{event-id}",
     "method": "get",
     "toolName": "get-calendar-event",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true
   },
   {
     "pathPattern": "/me/events",
@@ -187,14 +189,16 @@
     "method": "get",
     "toolName": "list-specific-calendar-events",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events/{event-id}",
     "method": "get",
     "toolName": "get-specific-calendar-event",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events",
@@ -221,7 +225,27 @@
     "method": "get",
     "toolName": "get-calendar-view",
     "scopes": ["Calendars.Read"],
-    "supportsTimezone": true
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "Returns expanded recurring event instances (not just seriesMaster) within a date range for the default calendar. Requires startDateTime and endDateTime query parameters in ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Use get-specific-calendar-view if you need a non-default calendar."
+  },
+  {
+    "pathPattern": "/me/calendars/{calendar-id}/calendarView",
+    "method": "get",
+    "toolName": "get-specific-calendar-view",
+    "scopes": ["Calendars.Read"],
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "Returns expanded recurring event instances (not just seriesMaster) within a date range for a specific calendar. Requires startDateTime and endDateTime query parameters in ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Each instance includes seriesMasterId and type (occurrence/exception) fields for recurring event linkage. Use fetchAllPages=true to retrieve all results when there are many events."
+  },
+  {
+    "pathPattern": "/me/calendars/{calendar-id}/events/{event-id}/instances",
+    "method": "get",
+    "toolName": "list-calendar-event-instances",
+    "scopes": ["Calendars.Read"],
+    "supportsTimezone": true,
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "Expand a recurring event into individual instances within a date range. Requires startDateTime and endDateTime query parameters in ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Use this to see all occurrences of a recurring event."
   },
   {
     "pathPattern": "/me/calendars",