@softeria/ms-365-mcp-server 0.133.2 → 0.134.1

package/dist/__tests__/graph-tools.test.js

@@ -48,6 +48,7 @@ function makeEndpoint(overrides = {}) {
       { name: "search", type: "Query", schema: z.string().optional() },
       { name: "select", type: "Query", schema: z.string().optional() },
       { name: "orderby", type: "Query", schema: z.string().optional() },
+      { name: "expand", type: "Query", schema: z.string().optional() },
       { name: "count", type: "Query", schema: z.boolean().optional() },
       { name: "top", type: "Query", schema: z.number().optional() },
       { name: "skip", type: "Query", schema: z.number().optional() }
@@ -378,6 +379,20 @@ describe("graph-tools", () => {
       expect(schema["top"].description).toContain("Start small");
       expect(schema["top"].description).toContain("$select");
     });
+    it("should describe $expand as navigation-properties-only", async () => {
+      const endpoint = makeEndpoint();
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, createMockGraphClient());
+      const schema = server.tools.get("test-tool").schema;
+      expect(schema["expand"]).toBeDefined();
+      expect(schema["expand"].description).not.toBe("Expand related entities");
+      expect(schema["expand"].description).toContain("navigation");
+      expect(schema["expand"].description).toContain("attachments");
+    });
   });
   describe("MS365_MCP_MAX_TOP", () => {
     const prevMaxTop = process.env.MS365_MCP_MAX_TOP;

package/dist/graph-tools.js

@@ -20,15 +20,33 @@ import { getRequestTokens } from "./request-context.js";
 import { parseTeamsUrl } from "./lib/teams-url-parser.js";
 import { buildBM25Index, scoreQuery, tokenize } from "./lib/bm25.js";
 import { describeToolSchema, describeUtilityToolSchema } from "./lib/tool-schema.js";
+import {
+  TOP_UNSUPPORTED_DELTA_TOOLS,
+  shouldOmitTopParam,
+  paginationAllowed,
+  positiveIntFromEnv,
+  DEFAULT_MAX_PAGES,
+  getMaxPages,
+  isFetchAllPagesApplicable,
+  FILTER_PARAM_DESCRIPTION,
+  SEARCH_PARAM_DESCRIPTION,
+  SELECT_PARAM_DESCRIPTION,
+  EXPAND_PARAM_DESCRIPTION,
+  ORDERBY_PARAM_DESCRIPTION,
+  TOP_PARAM_DESCRIPTION,
+  SKIP_PARAM_DESCRIPTION,
+  COUNT_PARAM_DESCRIPTION,
+  CONFIRM_PARAM_DESCRIPTION,
+  TIMEZONE_PARAM_DESCRIPTION,
+  EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION,
+  getAccountParamDescription,
+  getFetchAllPagesParamDescription
+} from "./lib/param-descriptions.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const endpointsData = JSON.parse(
   readFileSync(path.join(__dirname, "endpoints.json"), "utf8")
 );
-const TOP_UNSUPPORTED_DELTA_TOOLS = /* @__PURE__ */ new Set([
-  "list-calendar-events-delta",
-  "list-calendar-view-delta"
-]);
 function withApiVersionPrefix(description, config) {
   return config?.apiVersion === "beta" ? `[beta] ${description}` : description;
 }
@@ -52,23 +70,7 @@ function clampTopQueryParam(queryParams) {
   logger.info(`Clamping $top from ${requested} to ${cap} (MS365_MCP_MAX_TOP)`);
   queryParams["$top"] = String(cap);
 }
-const DEFAULT_MAX_PAGES = 100;
 const DEFAULT_MAX_ITEMS = 1e4;
-function positiveIntFromEnv(name, defaultValue) {
-  const raw = process.env[name];
-  if (raw === void 0 || raw === "") return defaultValue;
-  const n = Number.parseInt(raw, 10);
-  if (!Number.isFinite(n) || n < 1) {
-    logger.warn(`Ignoring invalid ${name}=${JSON.stringify(raw)} (use a positive integer)`);
-    return defaultValue;
-  }
-  return n;
-}
-function paginationAllowed() {
-  const raw = process.env.MS365_MCP_ALLOW_PAGINATION;
-  if (raw === void 0 || raw === "") return true;
-  return !/^(0|false|no)$/i.test(raw.trim());
-}
 function isConfirmGateEnabled() {
   return process.env.MS365_MCP_REQUIRE_CONFIRM === "true";
 }
@@ -1003,72 +1005,59 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
         paramSchema[pathParamName] = z.string().describe(`Path parameter: ${pathParamName}`);
       }
     }
-    if (tool.method.toUpperCase() === "GET" && tool.path.includes("/") && paginationAllowed()) {
-      const maxPages = positiveIntFromEnv("MS365_MCP_MAX_PAGES", DEFAULT_MAX_PAGES);
-      paramSchema["fetchAllPages"] = z.boolean().describe(
-        `Follow @odata.nextLink and merge up to ${maxPages} pages into one response. Can return enormous payloads\u2014only when the user explicitly needs a full export. Prefer a small $top first, then paginate or narrow with $filter/$search.`
-      ).optional();
+    if (isFetchAllPagesApplicable(tool)) {
+      const maxPages = getMaxPages();
+      paramSchema["fetchAllPages"] = z.boolean().describe(getFetchAllPagesParamDescription(maxPages)).optional();
     }
     if (paramSchema["filter"] !== void 0 || paramSchema["$filter"] !== void 0) {
       const key = paramSchema["$filter"] !== void 0 ? "$filter" : "filter";
-      paramSchema[key] = z.string().describe(
-        "OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search."
-      ).optional();
+      paramSchema[key] = z.string().describe(FILTER_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["search"] !== void 0 || paramSchema["$search"] !== void 0) {
       const key = paramSchema["$search"] !== void 0 ? "$search" : "search";
-      paramSchema[key] = z.string().describe("KQL search query \u2014 wrap value in double quotes. Cannot combine with $filter.").optional();
+      paramSchema[key] = z.string().describe(SEARCH_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["select"] !== void 0 || paramSchema["$select"] !== void 0) {
       const key = paramSchema["$select"] !== void 0 ? "$select" : "select";
-      paramSchema[key] = z.string().describe("Comma-separated fields to return, e.g. id,subject,from,receivedDateTime").optional();
+      paramSchema[key] = z.string().describe(SELECT_PARAM_DESCRIPTION).optional();
+    }
+    if (paramSchema["expand"] !== void 0 || paramSchema["$expand"] !== void 0) {
+      const key = paramSchema["$expand"] !== void 0 ? "$expand" : "expand";
+      paramSchema[key] = z.array(z.string()).describe(EXPAND_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["orderby"] !== void 0 || paramSchema["$orderby"] !== void 0) {
       const key = paramSchema["$orderby"] !== void 0 ? "$orderby" : "orderby";
-      paramSchema[key] = z.string().describe("Sort expression, e.g. receivedDateTime desc").optional();
+      paramSchema[key] = z.string().describe(ORDERBY_PARAM_DESCRIPTION).optional();
     }
-    if (TOP_UNSUPPORTED_DELTA_TOOLS.has(tool.alias)) {
+    if (shouldOmitTopParam(tool.alias)) {
       delete paramSchema["top"];
       delete paramSchema["$top"];
     } else if (paramSchema["top"] !== void 0 || paramSchema["$top"] !== void 0) {
       const key = paramSchema["$top"] !== void 0 ? "$top" : "top";
-      paramSchema[key] = z.number().describe(
-        "Page size (Graph $top). Start small (e.g. 5\u201315) so responses fit the model context; raise only if needed. Use $select to return fewer fields per item. For more rows, use @odata.nextLink from the response instead of a very large $top."
-      ).optional();
+      paramSchema[key] = z.number().describe(TOP_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["skip"] !== void 0 || paramSchema["$skip"] !== void 0) {
       const key = paramSchema["$skip"] !== void 0 ? "$skip" : "skip";
-      paramSchema[key] = z.number().describe("Items to skip for pagination. Not supported with $search.").optional();
+      paramSchema[key] = z.number().describe(SKIP_PARAM_DESCRIPTION).optional();
     }
     if (paramSchema["count"] !== void 0 || paramSchema["$count"] !== void 0) {
       const countKey = paramSchema["$count"] !== void 0 ? "$count" : "count";
-      paramSchema[countKey] = z.boolean().describe(
-        "Set true to enable advanced query mode (ConsistencyLevel: eventual). Required for complex $filter on flag/flagStatus or contains()."
-      ).optional();
+      paramSchema[countKey] = z.boolean().describe(COUNT_PARAM_DESCRIPTION).optional();
     }
     if (multiAccount) {
-      const accountHint = accountNames.length > 0 ? `Known accounts: ${accountNames.join(", ")}. ` : "";
-      paramSchema["account"] = z.string().describe(
-        `${accountHint}Microsoft account email to use for this request. Required when multiple accounts are configured. Use the list-accounts tool to discover all currently available accounts.`
-      ).optional();
+      paramSchema["account"] = z.string().describe(getAccountParamDescription(accountNames)).optional();
     }
     paramSchema["includeHeaders"] = z.boolean().describe("Include response headers (including ETag) in the response metadata").optional();
     paramSchema["excludeResponse"] = z.boolean().describe("Exclude the full response body and only return success or failure indication").optional();
     const destructive = isDestructiveOperation(tool.method, endpointConfig);
     if (destructive) {
-      paramSchema["confirm"] = z.boolean().describe(
-        'For destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: "confirmation_required" } without touching user data.'
-      ).optional();
+      paramSchema["confirm"] = z.boolean().describe(CONFIRM_PARAM_DESCRIPTION).optional();
     }
     if (endpointConfig?.supportsTimezone) {
-      paramSchema["timezone"] = z.string().describe(
-        '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();
+      paramSchema["timezone"] = z.string().describe(TIMEZONE_PARAM_DESCRIPTION).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();
+      paramSchema["expandExtendedProperties"] = z.boolean().describe(EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION).optional();
     }
     let toolDescription = withApiVersionPrefix(
       (endpointConfig?.descriptionOverride ?? tool.description) || `Execute ${tool.method.toUpperCase()} request to ${tool.path}`,
@@ -1367,7 +1356,7 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
     async ({ tool_name }) => {
       const entry = toolsRegistry.get(tool_name);
       if (entry) {
-        const schema = describeToolSchema(entry.tool, entry.config);
+        const schema = describeToolSchema(entry.tool, entry.config, { multiAccount, accountNames });
         return {
           content: [{ type: "text", text: JSON.stringify(schema, null, 2) }]
         };

package/dist/lib/param-descriptions.js

@@ -0,0 +1,93 @@
+import logger from "../logger.js";
+const TOP_UNSUPPORTED_DELTA_TOOLS = /* @__PURE__ */ new Set([
+  "list-calendar-events-delta",
+  "list-calendar-view-delta"
+]);
+function shouldOmitTopParam(toolAlias) {
+  return TOP_UNSUPPORTED_DELTA_TOOLS.has(toolAlias);
+}
+function paginationAllowed() {
+  const raw = process.env.MS365_MCP_ALLOW_PAGINATION;
+  if (raw === void 0 || raw === "") return true;
+  return !/^(0|false|no)$/i.test(raw.trim());
+}
+const DEFAULT_MAX_PAGES = 100;
+function positiveIntFromEnv(name, defaultValue) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw === "") return defaultValue;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1) {
+    logger.warn(`Ignoring invalid ${name}=${JSON.stringify(raw)} (use a positive integer)`);
+    return defaultValue;
+  }
+  return n;
+}
+function getMaxPages() {
+  return positiveIntFromEnv("MS365_MCP_MAX_PAGES", DEFAULT_MAX_PAGES);
+}
+function isFetchAllPagesApplicable(tool) {
+  return tool.method.toUpperCase() === "GET" && tool.path.includes("/") && paginationAllowed();
+}
+const FILTER_PARAM_DESCRIPTION = "OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search.";
+const SEARCH_PARAM_DESCRIPTION = "KQL search query \u2014 wrap value in double quotes. Cannot combine with $filter.";
+const SELECT_PARAM_DESCRIPTION = "Comma-separated fields to return, e.g. id,subject,from,receivedDateTime";
+const EXPAND_PARAM_DESCRIPTION = 'Navigation properties to inline, e.g. attachments on a message or event. Only navigation properties can be expanded: expanding a non-navigation property such as a message body fails with "Parsing OData Select and Expand failed", and an unsupported value may be ignored rather than reported. Request ordinary fields with $select instead.';
+const ORDERBY_PARAM_DESCRIPTION = "Sort expression, e.g. receivedDateTime desc";
+const TOP_PARAM_DESCRIPTION = "Page size (Graph $top). Start small (e.g. 5\u201315) so responses fit the model context; raise only if needed. Use $select to return fewer fields per item. For more rows, use @odata.nextLink from the response instead of a very large $top.";
+const SKIP_PARAM_DESCRIPTION = "Items to skip for pagination. Not supported with $search.";
+const COUNT_PARAM_DESCRIPTION = "Set true to enable advanced query mode (ConsistencyLevel: eventual). Required for complex $filter on flag/flagStatus or contains().";
+const CONFIRM_PARAM_DESCRIPTION = 'For destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: "confirmation_required" } without touching user data.';
+const TIMEZONE_PARAM_DESCRIPTION = 'IANA timezone name (e.g., "America/New_York", "Europe/London", "Asia/Tokyo") for calendar event times. If not specified, times are returned in UTC.';
+const EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION = "When true, expands singleValueExtendedProperties on each event. Use this to retrieve custom extended properties (e.g., sync metadata) stored on calendar events.";
+function getAccountParamDescription(accountNames) {
+  const accountHint = accountNames.length > 0 ? `Known accounts: ${accountNames.join(", ")}. ` : "";
+  return `${accountHint}Microsoft account email to use for this request. Required when multiple accounts are configured. Use the list-accounts tool to discover all currently available accounts.`;
+}
+function getFetchAllPagesParamDescription(maxPages) {
+  return `Follow @odata.nextLink and merge up to ${maxPages} pages into one response. Can return enormous payloads\u2014only when the user explicitly needs a full export. Prefer a small $top first, then paginate or narrow with $filter/$search.`;
+}
+function getODataParamDescription(bareName) {
+  switch (bareName) {
+    case "filter":
+      return FILTER_PARAM_DESCRIPTION;
+    case "search":
+      return SEARCH_PARAM_DESCRIPTION;
+    case "select":
+      return SELECT_PARAM_DESCRIPTION;
+    case "expand":
+      return EXPAND_PARAM_DESCRIPTION;
+    case "orderby":
+      return ORDERBY_PARAM_DESCRIPTION;
+    case "top":
+      return TOP_PARAM_DESCRIPTION;
+    case "skip":
+      return SKIP_PARAM_DESCRIPTION;
+    case "count":
+      return COUNT_PARAM_DESCRIPTION;
+    default:
+      return void 0;
+  }
+}
+export {
+  CONFIRM_PARAM_DESCRIPTION,
+  COUNT_PARAM_DESCRIPTION,
+  DEFAULT_MAX_PAGES,
+  EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION,
+  EXPAND_PARAM_DESCRIPTION,
+  FILTER_PARAM_DESCRIPTION,
+  ORDERBY_PARAM_DESCRIPTION,
+  SEARCH_PARAM_DESCRIPTION,
+  SELECT_PARAM_DESCRIPTION,
+  SKIP_PARAM_DESCRIPTION,
+  TIMEZONE_PARAM_DESCRIPTION,
+  TOP_PARAM_DESCRIPTION,
+  TOP_UNSUPPORTED_DELTA_TOOLS,
+  getAccountParamDescription,
+  getFetchAllPagesParamDescription,
+  getMaxPages,
+  getODataParamDescription,
+  isFetchAllPagesApplicable,
+  paginationAllowed,
+  positiveIntFromEnv,
+  shouldOmitTopParam
+};

package/dist/lib/tool-schema.js

@@ -1,5 +1,16 @@
 import { zodToJsonSchema } from "zod-to-json-schema";
 import { isDestructiveOperation } from "./destructive-ops.js";
+import {
+  getODataParamDescription,
+  shouldOmitTopParam,
+  isFetchAllPagesApplicable,
+  getMaxPages,
+  getFetchAllPagesParamDescription,
+  getAccountParamDescription,
+  CONFIRM_PARAM_DESCRIPTION,
+  TIMEZONE_PARAM_DESCRIPTION,
+  EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION
+} from "./param-descriptions.js";
 function unwrapOptional(schema) {
   const def = schema._def;
   const typeName = def?.typeName;
@@ -8,17 +19,22 @@ function unwrapOptional(schema) {
   }
   return { inner: schema, optional: false };
 }
-function describeToolSchema(tool, config) {
-  const params = (tool.parameters ?? []).map((p) => {
+function bareParamName(name) {
+  return name.startsWith("$") ? name.slice(1) : name;
+}
+function describeToolSchema(tool, config, ctx = {}) {
+  const omitTop = shouldOmitTopParam(tool.alias);
+  const params = (tool.parameters ?? []).filter((p) => !(omitTop && bareParamName(p.name) === "top")).map((p) => {
     const { inner, optional } = unwrapOptional(p.schema);
     const isPath = p.type === "Path";
     const jsonSchema = zodToJsonSchema(inner, { target: "jsonSchema7", $refStrategy: "none" });
     const { $schema: _s, ...schema } = jsonSchema;
+    const override = p.type === "Query" ? getODataParamDescription(bareParamName(p.name)) : void 0;
     return {
       name: p.name,
       in: p.type,
       required: isPath || !optional,
-      description: p.description,
+      description: override ?? p.description,
       schema
     };
   });
@@ -27,7 +43,43 @@ function describeToolSchema(tool, config) {
       name: "confirm",
       in: "Query",
       required: false,
-      description: 'For destructive operations when the confirm gate is enabled (MS365_MCP_REQUIRE_CONFIRM=true; off by default). Set to true only after the user has explicitly approved this action. When the gate is on, calls without confirm: true return { error: "confirmation_required" } without touching user data.',
+      description: CONFIRM_PARAM_DESCRIPTION,
+      schema: { type: "boolean" }
+    });
+  }
+  if (isFetchAllPagesApplicable({ method: tool.method, path: tool.path })) {
+    params.push({
+      name: "fetchAllPages",
+      in: "Query",
+      required: false,
+      description: getFetchAllPagesParamDescription(getMaxPages()),
+      schema: { type: "boolean" }
+    });
+  }
+  if (ctx.multiAccount) {
+    params.push({
+      name: "account",
+      in: "Query",
+      required: false,
+      description: getAccountParamDescription(ctx.accountNames ?? []),
+      schema: { type: "string" }
+    });
+  }
+  if (config?.supportsTimezone) {
+    params.push({
+      name: "timezone",
+      in: "Query",
+      required: false,
+      description: TIMEZONE_PARAM_DESCRIPTION,
+      schema: { type: "string" }
+    });
+  }
+  if (config?.supportsExpandExtendedProperties) {
+    params.push({
+      name: "expandExtendedProperties",
+      in: "Query",
+      required: false,
+      description: EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION,
       schema: { type: "boolean" }
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.133.2",
+  "version": "0.134.1",
   "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",