@softeria/ms-365-mcp-server 0.152.0 → 0.153.0

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

@@ -1068,6 +1068,115 @@ describe("graph-tools", () => {
       expect(payload).not.toHaveProperty("target_resource");
     });
   });
+  describe("skiptoken cursor", () => {
+    const prevAllowPagination = process.env.MS365_MCP_ALLOW_PAGINATION;
+    afterEach(() => {
+      if (prevAllowPagination === void 0) delete process.env.MS365_MCP_ALLOW_PAGINATION;
+      else process.env.MS365_MCP_ALLOW_PAGINATION = prevAllowPagination;
+    });
+    const callWith = async (args) => {
+      mockEndpoints.push(makeEndpoint());
+      mockEndpointsJson = [makeConfig()];
+      const graphClient = createMockGraphClient();
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      await server.tools.get("test-tool").handler(args);
+      return graphClient.graphRequest.mock.calls[0][0];
+    };
+    const singleObjectEndpoint = () => makeEndpoint({
+      alias: "get-thing",
+      path: "/me/thing",
+      parameters: [
+        { name: "select", type: "Query", schema: z.string().optional() },
+        { name: "expand", type: "Query", schema: z.string().optional() }
+      ]
+    });
+    const registerAnd = async (endpoint, config) => {
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, createMockGraphClient());
+      return server;
+    };
+    it("omits skiptoken on single-object GETs", async () => {
+      const server = await registerAnd(
+        singleObjectEndpoint(),
+        makeConfig({ toolName: "get-thing", pathPattern: "/me/thing" })
+      );
+      expect(server.tools.get("get-thing").schema.skiptoken).toBeUndefined();
+    });
+    it("keeps skiptoken on delta tools that have $top stripped", async () => {
+      const endpoint = makeEndpoint({
+        alias: "list-calendar-events-delta",
+        path: "/me/calendarView/delta"
+      });
+      const server = await registerAnd(
+        endpoint,
+        makeConfig({
+          toolName: "list-calendar-events-delta",
+          pathPattern: "/me/calendarView/delta"
+        })
+      );
+      const schema = server.tools.get("list-calendar-events-delta").schema;
+      expect(schema.top).toBeUndefined();
+      expect(schema.skiptoken).toBeDefined();
+    });
+    it("advertises skiptoken on GET list tools", async () => {
+      mockEndpoints.push(makeEndpoint());
+      mockEndpointsJson = [makeConfig()];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, createMockGraphClient());
+      expect(server.tools.get("test-tool").schema.skiptoken).toBeDefined();
+    });
+    it("still advertises skiptoken when MS365_MCP_ALLOW_PAGINATION is disabled", async () => {
+      process.env.MS365_MCP_ALLOW_PAGINATION = "0";
+      mockEndpoints.push(makeEndpoint());
+      mockEndpointsJson = [makeConfig()];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, createMockGraphClient());
+      expect(server.tools.get("test-tool").schema.fetchAllPages).toBeUndefined();
+      expect(server.tools.get("test-tool").schema.skiptoken).toBeDefined();
+    });
+    it("forwards a bare token as $skiptoken", async () => {
+      const path = await callWith({ skiptoken: "abc123" });
+      expect(path).toContain("$skiptoken=abc123");
+    });
+    it("does not double-encode a token copied from @odata.nextLink", async () => {
+      const path = await callWith({ skiptoken: "eyJhIjoxfQ%3d%3d" });
+      expect(path).toContain("$skiptoken=eyJhIjoxfQ%3D%3D");
+      expect(path).not.toContain("%253");
+    });
+    it("extracts the token when handed a whole nextLink URL", async () => {
+      const path = await callWith({
+        skiptoken: "https://graph.microsoft.com/v1.0/me/chats?$top=5&$filter=x&$skiptoken=tok123"
+      });
+      expect(path).toContain("$skiptoken=tok123");
+      expect(path).not.toContain("graph.microsoft.com");
+    });
+    it("keeps only the cursor when the nextLink has params after it", async () => {
+      const path = await callWith({ skiptoken: "$skiptoken=tok123&$top=5" });
+      expect(path).toContain("$skiptoken=tok123");
+      expect(path).not.toContain("tok123&");
+    });
+    it("accepts the $-prefixed param name", async () => {
+      const path = await callWith({ $skiptoken: "abc123" });
+      expect(path).toContain("$skiptoken=abc123");
+    });
+    it("omits $skiptoken entirely when blank", async () => {
+      const path = await callWith({ skiptoken: "   " });
+      expect(path).not.toContain("skiptoken");
+    });
+    it("sends the cursor alongside the original query options", async () => {
+      const path = await callWith({ filter: "chatType eq 'oneOnOne'", top: 5, skiptoken: "tok" });
+      expect(path).toContain("$filter=");
+      expect(path).toContain("$top=5");
+      expect(path).toContain("$skiptoken=tok");
+    });
+  });
   describe("fetchAllPages pagination", () => {
     it("should follow @odata.nextLink and combine results", async () => {
       const endpoint = makeEndpoint();

package/dist/graph-tools.js

@@ -56,7 +56,10 @@ import {
   EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION,
   getAcceptParamDescription,
   getAccountParamDescription,
-  getFetchAllPagesParamDescription
+  getFetchAllPagesParamDescription,
+  SKIPTOKEN_PARAM_DESCRIPTION,
+  isSkiptokenApplicable,
+  normalizeSkiptoken
 } from "./lib/param-descriptions.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -1143,6 +1146,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
         "expand",
         "orderby",
         "skip",
+        "skiptoken",
         "top",
         "count",
         "search",
@@ -1261,6 +1265,11 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
     if (TOP_UNSUPPORTED_DELTA_TOOLS.has(tool.alias)) {
       delete queryParams["$top"];
     }
+    if (queryParams["$skiptoken"]) {
+      const cursor = normalizeSkiptoken(queryParams["$skiptoken"]);
+      if (cursor) queryParams["$skiptoken"] = cursor;
+      else delete queryParams["$skiptoken"];
+    }
     clampTopQueryParam(queryParams);
     const searchError = normalizeSearchQueryParam(queryParams, tool.path, tool.alias);
     if (searchError) return searchError;
@@ -1600,6 +1609,9 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
       const maxPages = getMaxPages();
       paramSchema["fetchAllPages"] = z.boolean().describe(getFetchAllPagesParamDescription(maxPages)).optional();
     }
+    if (isSkiptokenApplicable(tool, Object.keys(paramSchema))) {
+      paramSchema["skiptoken"] = z.string().describe(SKIPTOKEN_PARAM_DESCRIPTION).optional();
+    }
     if (paramSchema["filter"] !== void 0 || paramSchema["$filter"] !== void 0) {
       const key = paramSchema["$filter"] !== void 0 ? "$filter" : "filter";
       paramSchema[key] = z.string().describe(FILTER_PARAM_DESCRIPTION).optional();

package/dist/lib/param-descriptions.js

@@ -35,6 +35,31 @@ const EXPAND_PARAM_DESCRIPTION = 'Navigation properties to inline, e.g. attachme
 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 SKIPTOKEN_PARAM_DESCRIPTION = "Opaque cursor for the next page, taken from the previous response. Copy the $skiptoken value out of @odata.nextLink (or paste the whole nextLink URL \u2014 the token is extracted from it) and resend it with the SAME $filter/$select/$expand/$top as the first call. Use this to walk pages one at a time instead of fetchAllPages. Omit it for the first page.";
+const COLLECTION_QUERY_PARAMS = /* @__PURE__ */ new Set(["top", "filter", "orderby", "count"]);
+function isSkiptokenApplicable(tool, paramNames) {
+  if (tool.method.toUpperCase() !== "GET") return false;
+  for (const name of paramNames) {
+    if (COLLECTION_QUERY_PARAMS.has(name.replace(/^\$/, "").toLowerCase())) return true;
+  }
+  return false;
+}
+function normalizeSkiptoken(raw) {
+  let token = raw.trim();
+  const marker = token.match(/(?:\$|%24)skiptoken=/i);
+  if (marker?.index !== void 0) {
+    token = token.slice(marker.index + marker[0].length);
+    token = token.split("&")[0];
+  }
+  if (token.includes("%")) {
+    try {
+      token = decodeURIComponent(token);
+    } catch {
+      logger.warn("skiptoken looks percent-encoded but could not be decoded; sending as-is");
+    }
+  }
+  return token;
+}
 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.';
@@ -81,6 +106,7 @@ export {
   ORDERBY_PARAM_DESCRIPTION,
   SEARCH_PARAM_DESCRIPTION,
   SELECT_PARAM_DESCRIPTION,
+  SKIPTOKEN_PARAM_DESCRIPTION,
   SKIP_PARAM_DESCRIPTION,
   TIMEZONE_PARAM_DESCRIPTION,
   TOP_PARAM_DESCRIPTION,
@@ -91,6 +117,8 @@ export {
   getMaxPages,
   getODataParamDescription,
   isFetchAllPagesApplicable,
+  isSkiptokenApplicable,
+  normalizeSkiptoken,
   paginationAllowed,
   positiveIntFromEnv,
   shouldOmitTopParam

package/dist/lib/tool-schema.js

@@ -4,6 +4,8 @@ import {
   getODataParamDescription,
   shouldOmitTopParam,
   isFetchAllPagesApplicable,
+  isSkiptokenApplicable,
+  SKIPTOKEN_PARAM_DESCRIPTION,
   getMaxPages,
   getFetchAllPagesParamDescription,
   getAccountParamDescription,
@@ -57,6 +59,18 @@ function describeToolSchema(tool, config, ctx = {}) {
       schema: { type: "boolean" }
     });
   }
+  if (isSkiptokenApplicable(
+    { method: tool.method },
+    params.map((p) => p.name)
+  )) {
+    params.push({
+      name: "skiptoken",
+      in: "Query",
+      required: false,
+      description: SKIPTOKEN_PARAM_DESCRIPTION,
+      schema: { type: "string" }
+    });
+  }
   if (ctx.multiAccount) {
     params.push({
       name: "account",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.152.0",
+  "version": "0.153.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",