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

package/README.md

@@ -154,7 +154,7 @@ SharePoint supports two enterprise permission models:
 - Broad tenant scopes such as `Sites.Read.All`, `Sites.ReadWrite.All`, and `Sites.Manage.All`.
 - Microsoft Graph `Sites.Selected`, where SharePoint site access is granted to the app on specific site collections and Graph evaluates the signed-in user's own permissions at request time.
 
-The default org-mode behavior continues to request the broad SharePoint scopes used by existing deployments. Enterprises that want selected-site SharePoint access can set an allowlist containing `Sites.Selected` instead of broad `Sites.*.All` scopes. Direct site/list/item tools that target an explicit SharePoint site can run with `Sites.Selected`; tenant-wide SharePoint discovery and search tools still require broad SharePoint scopes.
+The default org-mode behavior continues to request the broad SharePoint scopes used by existing deployments. Enterprises that want selected-site SharePoint access can set an allowlist containing `Sites.Selected` instead of broad `Sites.*.All` scopes. Direct site/list/item tools that target an explicit SharePoint site, and the `/drives/{drive-id}/...` item tools (list, get, upload, folder, move/rename, copy, versions) for drives of a granted site, can run with `Sites.Selected`; tenant-wide SharePoint discovery and search tools still require broad SharePoint scopes.
 
 ```bash
 npx @softeria/ms-365-mcp-server \

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

@@ -1074,14 +1074,18 @@ describe("graph-tools", () => {
       if (prevAllowPagination === void 0) delete process.env.MS365_MCP_ALLOW_PAGINATION;
       else process.env.MS365_MCP_ALLOW_PAGINATION = prevAllowPagination;
     });
-    const callWith = async (args) => {
+    const callForResult = 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);
+      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({
@@ -1166,10 +1170,78 @@ describe("graph-tools", () => {
       const path = await callWith({ $skiptoken: "abc123" });
       expect(path).toContain("$skiptoken=abc123");
     });
-    it("omits $skiptoken entirely when blank", async () => {
-      const path = await callWith({ skiptoken: "   " });
+    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=");

package/dist/endpoints.json

@@ -621,14 +621,14 @@
     "method": "get",
     "toolName": "get-drive-root-item",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.Read"]
+    "scopes": [["Files.Read"], ["Sites.Selected"]]
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/children",
     "method": "get",
     "toolName": "list-folder-files",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.Read"]
+    "scopes": [["Files.Read"], ["Sites.Selected"]]
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -642,7 +642,7 @@
     "method": "put",
     "toolName": "upload-file-content",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "Body is a base64-encoded string of the file bytes; the server decodes it before PUT. Graph accepts up to 250MB here, but the whole string travels as a tool argument and a truncated one decodes to a truncated file with no error, so use create-upload-session rather than emitting a large base64 string. For new files use path format: /items/root:/path/to/file.txt:/content. Overwrites existing files without warning."
   },
   {
@@ -650,7 +650,7 @@
     "method": "post",
     "toolName": "create-upload-session",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "For large file uploads (no size limit, and no minimum unlike the Outlook attachment session). Returns a pre-authenticated uploadUrl; the caller PUTs the bytes there itself. This server does not perform the PUT. For new files use path: /items/{parentId}:/{fileName}:/createUploadSession. Body (optional): { item: { '@microsoft.graph.conflictBehavior': 'rename' } }."
   },
   {
@@ -658,7 +658,7 @@
     "method": "get",
     "toolName": "get-drive-item",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.Read"],
+    "scopes": [["Files.Read"], ["Sites.Selected"]],
     "llmTip": "Gets metadata for a file or folder: name, size, lastModifiedDateTime, createdBy, webUrl, file (mimeType, hashes), folder (childCount), parentReference, and @microsoft.graph.downloadUrl. For large drive/SharePoint files, call get-download-url with target=/drives/{drive-id}/items/{driveItem-id}/content to fetch out-of-band with no Authorization header. For small files where base64 in the tool response is acceptable, call download-bytes with the same /content target."
   },
   {
@@ -666,7 +666,7 @@
     "method": "patch",
     "toolName": "move-rename-onedrive-item",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "Move and/or rename a file or folder. To move, provide parentReference with the target folder's id. To rename, provide a new name. Both can be done in a single request."
   },
   {
@@ -674,7 +674,7 @@
     "method": "post",
     "toolName": "create-onedrive-folder",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "Creates a new folder inside the specified drive item. Body must include name (string) and folder ({}) fields. Use @microsoft.graph.conflictBehavior to control behavior on name conflict: 'rename' (default), 'replace', or 'fail'."
   },
   {
@@ -698,7 +698,7 @@
     "method": "post",
     "toolName": "copy-drive-item",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "Asynchronously copy a file or folder to a new location and/or name. Body: { parentReference: { driveId: '...', id: '...' }, name?: 'New Name.xlsx' }. Returns 202 Accepted with a Location header pointing at a monitor URL for the async job. Ideal for duplicating templates (e.g. clone an Armhr Census Template per prospect), bulk file provisioning, or preserving an immutable snapshot of a working file."
   },
   {
@@ -738,7 +738,7 @@
     "method": "get",
     "toolName": "list-drive-item-versions",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.Read"],
+    "scopes": [["Files.Read"], ["Sites.Selected"]],
     "llmTip": "Lists version history of a file. Each version has id, lastModifiedDateTime, lastModifiedBy, and size. Use the version id with /versions/{id}/content to download a specific version."
   },
   {

package/dist/graph-tools.js

@@ -58,8 +58,7 @@ import {
   getAccountParamDescription,
   getFetchAllPagesParamDescription,
   SKIPTOKEN_PARAM_DESCRIPTION,
-  isSkiptokenApplicable,
-  normalizeSkiptoken
+  isSkiptokenApplicable
 } from "./lib/param-descriptions.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -225,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";
@@ -1265,11 +1308,8 @@ 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"];
-    }
+    const skiptokenError = normalizeSkiptokenQueryParam(queryParams, tool.alias);
+    if (skiptokenError) return skiptokenError;
     clampTopQueryParam(queryParams);
     const searchError = normalizeSearchQueryParam(queryParams, tool.path, tool.alias);
     if (searchError) return searchError;

package/dist/lib/param-descriptions.js

@@ -35,7 +35,7 @@ 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 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;
@@ -44,22 +44,6 @@ function isSkiptokenApplicable(tool, paramNames) {
   }
   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.';
@@ -118,7 +102,6 @@ export {
   getODataParamDescription,
   isFetchAllPagesApplicable,
   isSkiptokenApplicable,
-  normalizeSkiptoken,
   paginationAllowed,
   positiveIntFromEnv,
   shouldOmitTopParam

package/package.json

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

@@ -621,14 +621,14 @@
     "method": "get",
     "toolName": "get-drive-root-item",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.Read"]
+    "scopes": [["Files.Read"], ["Sites.Selected"]]
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/children",
     "method": "get",
     "toolName": "list-folder-files",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.Read"]
+    "scopes": [["Files.Read"], ["Sites.Selected"]]
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -642,7 +642,7 @@
     "method": "put",
     "toolName": "upload-file-content",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "Body is a base64-encoded string of the file bytes; the server decodes it before PUT. Graph accepts up to 250MB here, but the whole string travels as a tool argument and a truncated one decodes to a truncated file with no error, so use create-upload-session rather than emitting a large base64 string. For new files use path format: /items/root:/path/to/file.txt:/content. Overwrites existing files without warning."
   },
   {
@@ -650,7 +650,7 @@
     "method": "post",
     "toolName": "create-upload-session",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "For large file uploads (no size limit, and no minimum unlike the Outlook attachment session). Returns a pre-authenticated uploadUrl; the caller PUTs the bytes there itself. This server does not perform the PUT. For new files use path: /items/{parentId}:/{fileName}:/createUploadSession. Body (optional): { item: { '@microsoft.graph.conflictBehavior': 'rename' } }."
   },
   {
@@ -658,7 +658,7 @@
     "method": "get",
     "toolName": "get-drive-item",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.Read"],
+    "scopes": [["Files.Read"], ["Sites.Selected"]],
     "llmTip": "Gets metadata for a file or folder: name, size, lastModifiedDateTime, createdBy, webUrl, file (mimeType, hashes), folder (childCount), parentReference, and @microsoft.graph.downloadUrl. For large drive/SharePoint files, call get-download-url with target=/drives/{drive-id}/items/{driveItem-id}/content to fetch out-of-band with no Authorization header. For small files where base64 in the tool response is acceptable, call download-bytes with the same /content target."
   },
   {
@@ -666,7 +666,7 @@
     "method": "patch",
     "toolName": "move-rename-onedrive-item",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "Move and/or rename a file or folder. To move, provide parentReference with the target folder's id. To rename, provide a new name. Both can be done in a single request."
   },
   {
@@ -674,7 +674,7 @@
     "method": "post",
     "toolName": "create-onedrive-folder",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "Creates a new folder inside the specified drive item. Body must include name (string) and folder ({}) fields. Use @microsoft.graph.conflictBehavior to control behavior on name conflict: 'rename' (default), 'replace', or 'fail'."
   },
   {
@@ -698,7 +698,7 @@
     "method": "post",
     "toolName": "copy-drive-item",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.ReadWrite"],
+    "scopes": [["Files.ReadWrite"], ["Sites.Selected"]],
     "llmTip": "Asynchronously copy a file or folder to a new location and/or name. Body: { parentReference: { driveId: '...', id: '...' }, name?: 'New Name.xlsx' }. Returns 202 Accepted with a Location header pointing at a monitor URL for the async job. Ideal for duplicating templates (e.g. clone an Armhr Census Template per prospect), bulk file provisioning, or preserving an immutable snapshot of a working file."
   },
   {
@@ -738,7 +738,7 @@
     "method": "get",
     "toolName": "list-drive-item-versions",
     "presets": ["files", "onedrive", "personal"],
-    "scopes": ["Files.Read"],
+    "scopes": [["Files.Read"], ["Sites.Selected"]],
     "llmTip": "Lists version history of a file. Each version has id, lastModifiedDateTime, lastModifiedBy, and size. Use the version id with /versions/{id}/content to download a specific version."
   },
   {