@softeria/ms-365-mcp-server 0.115.0 → 0.116.1

package/README.md

@@ -573,6 +573,9 @@ Environment variables:
 - `MS365_MCP_FORCE_WORK_SCOPES=true|1`: Backwards compatibility for MS365_MCP_ORG_MODE
 - `MS365_MCP_OUTPUT_FORMAT=toon`: Enable TOON output format (alternative to --toon flag)
 - `MS365_MCP_MAX_TOP=<n>`: Hard cap for Graph `$top` / `top` on list requests (positive integer). When the model passes a larger value, the server clamps it to `n` so responses stay smaller. Example: `MS365_MCP_MAX_TOP=15`
+- `MS365_MCP_MAX_PAGES=<n>`: Maximum number of pages followed when a tool is called with `fetchAllPages: true` (positive integer, default `100`). Bounds memory and latency for large result sets.
+- `MS365_MCP_MAX_ITEMS=<n>`: Maximum number of items accumulated when `fetchAllPages: true` (positive integer, default `10000`). Pagination stops and the response is truncated once this many items are collected.
+- `MS365_MCP_ALLOW_PAGINATION=0|false|no`: Disable multi-page following entirely. When set, the `fetchAllPages` parameter is not advertised on tools, and any request that still passes it returns only the first page (default: pagination enabled).
 - `MS365_MCP_BODY_FORMAT=html`: Return email bodies as HTML instead of plain text (default: text)
 - `MS365_MCP_CLOUD_TYPE=global|china`: Microsoft cloud environment (alternative to --cloud flag)
 - `LOG_LEVEL`: Set logging level (default: 'info')

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

@@ -183,6 +183,97 @@ describe("graph-tools", () => {
       await tool.handler({ fetchAllPages: true });
       expect(graphClient.graphRequest).toHaveBeenCalledTimes(100);
     });
+    describe("pagination env caps", () => {
+      const prev = {
+        pages: process.env.MS365_MCP_MAX_PAGES,
+        items: process.env.MS365_MCP_MAX_ITEMS,
+        allow: process.env.MS365_MCP_ALLOW_PAGINATION
+      };
+      afterEach(() => {
+        const restore = (name, value) => value === void 0 ? delete process.env[name] : process.env[name] = value;
+        restore("MS365_MCP_MAX_PAGES", prev.pages);
+        restore("MS365_MCP_MAX_ITEMS", prev.items);
+        restore("MS365_MCP_ALLOW_PAGINATION", prev.allow);
+      });
+      const paginatingResponses = (count) => Array.from({ length: count }, (_, i) => ({
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              value: [{ id: `item-${i}` }],
+              "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=" + (i + 1)
+            })
+          }
+        ]
+      }));
+      it("should honor MS365_MCP_MAX_PAGES below the default", async () => {
+        process.env.MS365_MCP_MAX_PAGES = "2";
+        mockEndpoints.push(makeEndpoint());
+        mockEndpointsJson = [makeConfig()];
+        const graphClient = createMockGraphClient(paginatingResponses(5));
+        const server = createMockServer();
+        const { registerGraphTools } = await loadModule();
+        registerGraphTools(server, graphClient);
+        await server.tools.get("test-tool").handler({ fetchAllPages: true });
+        expect(graphClient.graphRequest).toHaveBeenCalledTimes(2);
+      });
+      it("should honor MS365_MCP_MAX_ITEMS below the default", async () => {
+        process.env.MS365_MCP_MAX_ITEMS = "2";
+        mockEndpoints.push(makeEndpoint());
+        mockEndpointsJson = [makeConfig()];
+        const graphClient = createMockGraphClient([
+          {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  value: [{ id: "1" }, { id: "2" }],
+                  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=2"
+                })
+              }
+            ]
+          },
+          ...paginatingResponses(3)
+        ]);
+        const server = createMockServer();
+        const { registerGraphTools } = await loadModule();
+        registerGraphTools(server, graphClient);
+        const result = await server.tools.get("test-tool").handler({ fetchAllPages: true });
+        expect(graphClient.graphRequest).toHaveBeenCalledTimes(1);
+        expect(JSON.parse(result.content[0].text).value).toHaveLength(2);
+      });
+      it("should not follow nextLink when MS365_MCP_ALLOW_PAGINATION is disabled", async () => {
+        process.env.MS365_MCP_ALLOW_PAGINATION = "0";
+        mockEndpoints.push(makeEndpoint());
+        mockEndpointsJson = [makeConfig()];
+        const graphClient = createMockGraphClient(paginatingResponses(5));
+        const server = createMockServer();
+        const { registerGraphTools } = await loadModule();
+        registerGraphTools(server, graphClient);
+        await server.tools.get("test-tool").handler({ fetchAllPages: true });
+        expect(graphClient.graphRequest).toHaveBeenCalledTimes(1);
+        expect(server.tools.get("test-tool").schema.fetchAllPages).toBeUndefined();
+      });
+      it("should advertise fetchAllPages when pagination is enabled", async () => {
+        delete process.env.MS365_MCP_ALLOW_PAGINATION;
+        mockEndpoints.push(makeEndpoint());
+        mockEndpointsJson = [makeConfig()];
+        const server = createMockServer();
+        const { registerGraphTools } = await loadModule();
+        registerGraphTools(server, createMockGraphClient());
+        expect(server.tools.get("test-tool").schema.fetchAllPages).toBeDefined();
+      });
+      it("should reflect MS365_MCP_MAX_PAGES in the fetchAllPages description", async () => {
+        process.env.MS365_MCP_MAX_PAGES = "7";
+        mockEndpoints.push(makeEndpoint());
+        mockEndpointsJson = [makeConfig()];
+        const server = createMockServer();
+        const { registerGraphTools } = await loadModule();
+        registerGraphTools(server, createMockGraphClient());
+        const schema = server.tools.get("test-tool").schema.fetchAllPages;
+        expect(schema.description).toContain("up to 7 pages");
+      });
+    });
   });
   describe("parameter describe() overrides", () => {
     it("should apply custom descriptions to OData parameters", async () => {

package/dist/graph-tools.js

@@ -41,6 +41,23 @@ 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 formatDisabledToolsForLog(disabledTools) {
   const shown = disabledTools.slice(0, 20).map((tool) => `${tool.toolName} (missing: ${tool.missingScopes.join(", ")})`);
   const suffix = disabledTools.length > shown.length ? `, ... +${disabledTools.length - shown.length} more` : "";
@@ -359,14 +376,20 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
     );
     let response = await graphClient.graphRequest(path2, options);
     const fetchAllPages = params.fetchAllPages === true;
-    if (fetchAllPages && response?.content?.[0]?.text) {
+    const paginationEnabled = paginationAllowed();
+    if (fetchAllPages && !paginationEnabled) {
+      logger.info(
+        "fetchAllPages requested but MS365_MCP_ALLOW_PAGINATION is disabled; returning first page only"
+      );
+    }
+    if (fetchAllPages && paginationEnabled && response?.content?.[0]?.text) {
       try {
         let combinedResponse = JSON.parse(response.content[0].text);
         let allItems = combinedResponse.value || [];
         let nextLink = combinedResponse["@odata.nextLink"];
         let pageCount = 1;
-        const maxPages = 100;
-        const maxItems = 1e4;
+        const maxPages = positiveIntFromEnv("MS365_MCP_MAX_PAGES", DEFAULT_MAX_PAGES);
+        const maxItems = positiveIntFromEnv("MS365_MCP_MAX_ITEMS", DEFAULT_MAX_ITEMS);
         while (nextLink && pageCount < maxPages && allItems.length < maxItems) {
           logger.info(`Fetching page ${pageCount + 1} from: ${nextLink}`);
           const url = new URL(nextLink);
@@ -519,9 +542,10 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
         paramSchema[pathParamName] = z.string().describe(`Path parameter: ${pathParamName}`);
       }
     }
-    if (tool.method.toUpperCase() === "GET" && tool.path.includes("/")) {
+    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 100 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."
+        `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 (paramSchema["filter"] !== void 0 || paramSchema["$filter"] !== void 0) {

package/package.json

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