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

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

@@ -1068,6 +1068,187 @@ 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 callForResult = async (args) => {
+      mockEndpoints.push(makeEndpoint());
+      mockEndpointsJson = [makeConfig()];
+      const graphClient = createMockGraphClient();
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const result = await server.tools.get("test-tool").handler(args);
+      return { result, graphClient };
+    };
+    const callWith = async (args) => {
+      const { graphClient } = await callForResult(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.each(["", "   "])("omits $skiptoken entirely when blank (%j)", async (blank) => {
+      const path = await callWith({ skiptoken: blank });
+      expect(path).not.toContain("skiptoken");
+    });
+    it("sends $skip when the nextLink pages with $skip", async () => {
+      const path = await callWith({
+        top: 10,
+        skiptoken: "https://graph.microsoft.com/v1.0/me/messages?$top=10&$skip=10"
+      });
+      expect(path).toContain("$skip=10");
+      expect(path).not.toContain("skiptoken");
+    });
+    it("ignores a cursor-looking value inside another query param", async () => {
+      const path = await callWith({
+        skiptoken: "https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq '%24skip=100'&$skip=10"
+      });
+      expect(path).toContain("$skip=10");
+      expect(path).not.toContain("100");
+    });
+    it("refuses a link with no cursor to page with", async () => {
+      const { result, graphClient } = await callForResult({
+        skiptoken: "https://graph.microsoft.com/v1.0/me/mailFolders/inbox/messages/delta()?$deltatoken=abc"
+      });
+      expect(result.isError).toBe(true);
+      expect(JSON.parse(result.content[0].text).error).toBe("invalid_skiptoken");
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+    });
+    it("refuses a delta token= link without calling it a deltaLink", async () => {
+      const { result, graphClient } = await callForResult({
+        skiptoken: "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
+      });
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toBe("invalid_skiptoken");
+      expect(payload.message).not.toContain("deltaLink");
+      expect(payload.message).toContain("fetchAllPages");
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+    });
+    it("refuses a link whose $skiptoken carries no value", async () => {
+      const { result } = await callForResult({
+        skiptoken: "https://graph.microsoft.com/v1.0/me/chats?$skiptoken=&$top=5"
+      });
+      expect(result.isError).toBe(true);
+      expect(JSON.parse(result.content[0].text).error).toBe("invalid_skiptoken");
+    });
+    it("accepts an encoded %24skiptoken marker", async () => {
+      const path = await callWith({
+        skiptoken: "https://graph.microsoft.com/v1.0/me/chats?%24top=5&%24skiptoken=tok123"
+      });
+      expect(path).toContain("$skiptoken=tok123");
+    });
+    it.each([
+      ["https://graph.microsoft.com/v1.0/me/messages?$top=10&$skip=0", "$skip=0"],
+      ["https://graph.microsoft.com/v1.0/me/messages?%24top=10&%24skip=10", "$skip=10"]
+    ])("reads the $skip cursor out of %s", async (link, expected) => {
+      const path = await callWith({ skiptoken: link });
+      expect(path).toContain(expected);
+    });
+    it("refuses a $skip cursor that is not a plain number", async () => {
+      const { result } = await callForResult({
+        skiptoken: "https://graph.microsoft.com/v1.0/me/messages?$skip=10junk"
+      });
+      expect(JSON.parse(result.content[0].text).error).toBe("invalid_skiptoken");
+    });
+    it("offers no fetchAllPages in the refusal when pagination is disabled", async () => {
+      process.env.MS365_MCP_ALLOW_PAGINATION = "0";
+      const { result } = await callForResult({
+        skiptoken: "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
+      });
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toBe("invalid_skiptoken");
+      expect(payload.message).not.toContain("fetchAllPages");
+    });
+    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,9 @@ import {
   EXPAND_EXTENDED_PROPERTIES_PARAM_DESCRIPTION,
   getAcceptParamDescription,
   getAccountParamDescription,
-  getFetchAllPagesParamDescription
+  getFetchAllPagesParamDescription,
+  SKIPTOKEN_PARAM_DESCRIPTION,
+  isSkiptokenApplicable
 } from "./lib/param-descriptions.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -222,6 +224,50 @@ function normalizeSearchQueryParam(queryParams, path2, toolAlias) {
     queryParams["$search"] = normalized;
   }
 }
+function normalizeSkiptokenQueryParam(queryParams, toolAlias) {
+  const raw = queryParams["$skiptoken"];
+  if (raw === void 0) return;
+  delete queryParams["$skiptoken"];
+  let token = raw.trim();
+  if (token === "") return;
+  const cursorlessLink = () => {
+    logger.warn(`Refusing ${toolAlias}: 'skiptoken' has no $skiptoken or $skip to page with`);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            error: "invalid_skiptoken",
+            tool: toolAlias,
+            message: "The value passed as skiptoken has no $skiptoken or $skip to page with. The drive and sites delta tools page with a token= link, which skiptoken cannot resend." + (paginationAllowed() ? " Remove skiptoken and retry with fetchAllPages set to true to follow the link, or remove it for the first page." : " Remove skiptoken and retry for the first page.")
+          })
+        }
+      ],
+      isError: true
+    };
+  };
+  const marker = token.match(/(?:^|[?&])(?:\$|%24)skiptoken=/i);
+  if (marker?.index !== void 0) {
+    token = token.slice(marker.index + marker[0].length).split("&")[0];
+    if (token === "") return cursorlessLink();
+  } else if (/:\/\/|\?|^(?:\$|%24)\w+=/.test(token)) {
+    const skip = token.match(/(?:^|[?&])(?:\$|%24)skip=(\d+)(?=&|$)/i)?.[1];
+    if (skip === void 0) return cursorlessLink();
+    logger.info(
+      `Auto-corrected parameter 'skiptoken': link pages with $skip, sending $skip=${skip}`
+    );
+    queryParams["$skip"] = skip;
+    return;
+  }
+  if (token.includes("%")) {
+    try {
+      token = decodeURIComponent(token);
+    } catch {
+      logger.warn("skiptoken looks percent-encoded but could not be decoded; sending as-is");
+    }
+  }
+  queryParams["$skiptoken"] = token;
+}
 const DEFAULT_MAX_ITEMS = 1e4;
 function isConfirmGateEnabled() {
   return process.env.MS365_MCP_REQUIRE_CONFIRM === "true";
@@ -1143,6 +1189,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
         "expand",
         "orderby",
         "skip",
+        "skiptoken",
         "top",
         "count",
         "search",
@@ -1261,6 +1308,8 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
     if (TOP_UNSUPPORTED_DELTA_TOOLS.has(tool.alias)) {
       delete queryParams["$top"];
     }
+    const skiptokenError = normalizeSkiptokenQueryParam(queryParams, tool.alias);
+    if (skiptokenError) return skiptokenError;
     clampTopQueryParam(queryParams);
     const searchError = normalizeSearchQueryParam(queryParams, tool.path, tool.alias);
     if (searchError) return searchError;
@@ -1600,6 +1649,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,15 @@ 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 = "Next page: the @odata.nextLink from the previous response. Keep the other arguments the same.";
+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;
+}
 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 +90,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 +101,7 @@ export {
   getMaxPages,
   getODataParamDescription,
   isFetchAllPagesApplicable,
+  isSkiptokenApplicable,
   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.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",