@softeria/ms-365-mcp-server 0.126.0 → 0.127.0

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

@@ -91,6 +91,10 @@ function createMockServer() {
     tools
   };
 }
+function makeJwt(payload) {
+  const body = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  return `header.${body}.signature`;
+}
 describe("graph-tools", () => {
   beforeEach(() => {
     mockEndpoints.length = 0;
@@ -665,6 +669,351 @@ describe("graph-tools", () => {
       expect(payload.error).toMatch(/relative Microsoft Graph path/);
     });
   });
+  describe("get-download-url", () => {
+    it("strips /content, fetches item metadata, and returns the pre-authed downloadUrl", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const downloadUrl = "https://contoso.sharepoint.com/download.aspx?tempauth=abc";
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                id: "item1",
+                name: "report.pdf",
+                size: 12727,
+                file: { mimeType: "application/pdf" },
+                "@microsoft.graph.downloadUrl": downloadUrl
+              })
+            }
+          ]
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      expect(tool).toBeDefined();
+      const result = await tool.handler({
+        target: "/drives/d1/items/item1/content"
+      });
+      const [requestedPath] = graphClient.graphRequest.mock.calls[0];
+      expect(requestedPath).toBe("/drives/d1/items/item1");
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.downloadUrl).toBe(downloadUrl);
+      expect(payload.name).toBe("report.pdf");
+      expect(payload.size).toBe(12727);
+      expect(payload.contentType).toBe("application/pdf");
+    });
+    it("rejects query-shaped targets instead of silently changing request semantics", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { graphRequest: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/drives/d1/items/item1/content?$select=id,name"
+      });
+      expect(result.isError).toBe(true);
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toContain("must not include query parameters");
+    });
+    it("rejects non-drive Graph targets before making an authenticated request", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { graphRequest: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/me/messages/m1"
+      });
+      expect(result.isError).toBe(true);
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toContain("target must identify a driveItem");
+    });
+    it("rejects mail attachment $value paths (no pre-authed URL exists)", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { graphRequest: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/me/messages/m1/attachments/a1/$value"
+      });
+      expect(result.isError).toBe(true);
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/do not expose a pre-authenticated download URL/);
+    });
+    it("rejects calendar event attachment $value paths (no pre-authed URL exists)", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { graphRequest: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/me/events/e1/attachments/a1/$value"
+      });
+      expect(result.isError).toBe(true);
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/Mail and calendar event attachments/);
+    });
+    it("rejects group mailbox attachment paths (no pre-authed URL exists)", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { graphRequest: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/groups/g1/messages/m1/attachments/a1/$value"
+      });
+      expect(result.isError).toBe(true);
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/Mail and calendar event attachments/);
+    });
+    it("rejects list-item driveItem relationships until callers provide a drive item path", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { graphRequest: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/sites/site1/lists/list1/items/item1/driveItem"
+      });
+      expect(result.isError).toBe(true);
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toContain("target must identify a driveItem");
+    });
+    it("errors when the resource exposes no downloadUrl", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [{ type: "text", text: JSON.stringify({ id: "item1", name: "x" }) }]
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({ target: "/drives/d1/items/item1" });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/No pre-authenticated download URL/);
+    });
+    it("surfaces the underlying Graph error instead of masking it as no-downloadUrl", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "Microsoft Graph API error: 403 Forbidden" })
+            }
+          ]
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({ target: "/drives/d1/items/item1/content" });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/403 Forbidden/);
+      expect(payload.error).not.toMatch(/No pre-authenticated download URL/);
+    });
+    it('does not falsely reject drive folders literally named "attachments"', async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const downloadUrl = "https://contoso.sharepoint.com/download.aspx?tempauth=xyz";
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                name: "report.pdf",
+                "@microsoft.graph.downloadUrl": downloadUrl
+              })
+            }
+          ]
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/me/drive/root:/Project/attachments/report.pdf:/content"
+      });
+      expect(result.isError).toBeFalsy();
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.downloadUrl).toBe(downloadUrl);
+    });
+    it("does not falsely reject drive item paths containing messages and attachments folders", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const downloadUrl = "https://contoso.sharepoint.com/download.aspx?tempauth=folders";
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                name: "report.pdf",
+                "@microsoft.graph.downloadUrl": downloadUrl
+              })
+            }
+          ]
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/me/drive/root:/messages/m1/attachments/a1/report.pdf:/content"
+      });
+      expect(result.isError).toBeFalsy();
+      const [requestedPath] = graphClient.graphRequest.mock.calls[0];
+      expect(requestedPath).toBe("/me/drive/root:/messages/m1/attachments/a1/report.pdf:");
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.downloadUrl).toBe(downloadUrl);
+    });
+    it("allows SharePoint site drive item paths", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const downloadUrl = "https://contoso.sharepoint.com/download.aspx?tempauth=site-drive";
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                name: "site-report.pdf",
+                "@microsoft.graph.downloadUrl": downloadUrl
+              })
+            }
+          ]
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/sites/site1/drive/items/item1/content"
+      });
+      expect(result.isError).toBeFalsy();
+      const [requestedPath] = graphClient.graphRequest.mock.calls[0];
+      expect(requestedPath).toBe("/sites/site1/drive/items/item1");
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.downloadUrl).toBe(downloadUrl);
+    });
+    it("does not strip a drive item path whose item name is content", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const downloadUrl = "https://contoso.sharepoint.com/download.aspx?tempauth=content-file";
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                name: "content",
+                "@microsoft.graph.downloadUrl": downloadUrl
+              })
+            }
+          ]
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/me/drive/root:/Project/content:"
+      });
+      expect(result.isError).toBeFalsy();
+      const [requestedPath] = graphClient.graphRequest.mock.calls[0];
+      expect(requestedPath).toBe("/me/drive/root:/Project/content:");
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.downloadUrl).toBe(downloadUrl);
+    });
+    it("rejects meeting recording content paths because Graph returns authenticated bytes", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { graphRequest: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-download-url");
+      const result = await tool.handler({
+        target: "/me/onlineMeetings/meeting1/recordings/recording1/content"
+      });
+      expect(result.isError).toBe(true);
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/Meeting recordings do not expose/);
+    });
+    it("refuses mismatched account param in bearer mode before resolving download URL", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { graphRequest: vi.fn() };
+      const authManager = {
+        isOAuthModeEnabled: vi.fn().mockReturnValue(false),
+        getToken: vi.fn().mockResolvedValue(null),
+        getTokenForAccount: vi.fn()
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient,
+        false,
+        void 0,
+        false,
+        authManager,
+        true,
+        ["user1@domain.com", "user2@domain.com"]
+      );
+      const { requestContext } = await import("../request-context.js");
+      const tool = server.tools.get("get-download-url");
+      const bearer = makeJwt({ upn: "user1@domain.com" });
+      const result = await requestContext.run(
+        { accessToken: bearer },
+        () => tool.handler({
+          target: "/drives/d1/items/item1/content",
+          account: "user2@domain.com"
+        })
+      );
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("'account' parameter is not supported");
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+      expect(authManager.getTokenForAccount).not.toHaveBeenCalled();
+    });
+  });
   describe("allowed scopes filtering", () => {
     it("registerGraphTools hides Graph tools outside the allowed scopes", async () => {
       mockEndpoints.push(
@@ -788,6 +1137,9 @@ describe("graph-tools", () => {
       const targetParam = schema.parameters.find((p) => p.name === "target");
       expect(targetParam).toBeDefined();
       expect(targetParam.required).toBe(true);
+      expect(targetParam.description).toContain("authenticated recording bytes");
+      expect(targetParam.description).not.toContain("returns a URL");
+      expect(schema.description).toContain("For large drive/SharePoint file content");
     });
     it("execute-tool dispatches to download-bytes for a Graph path", async () => {
       mockEndpoints.length = 0;

package/dist/endpoints.json

@@ -594,7 +594,7 @@
     "toolName": "get-drive-item",
     "presets": ["files", "onedrive", "personal"],
     "scopes": ["Files.Read"],
-    "llmTip": "Gets metadata for a file or folder: name, size, lastModifiedDateTime, createdBy, webUrl, file (mimeType, hashes), folder (childCount), parentReference, and @microsoft.graph.downloadUrl. For the bytes, call download-bytes with target=/drives/{drive-id}/items/{driveItem-id}/content (Graph redirects to the same downloadUrl)."
+    "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."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -1904,8 +1904,7 @@
     "toolName": "get-meeting-recording-content",
     "presets": ["teams", "work"],
     "workScopes": ["OnlineMeetingRecording.Read.All"],
-    "returnDownloadUrl": true,
-    "llmTip": "Returns a temporary download URL for the meeting recording in MP4 format. Use the download URL to access the video file. The recording may be large — do not attempt to stream it inline."
+    "llmTip": "Returns the authenticated meeting recording video bytes in MP4 format. The recording may be large; prefer out-of-band handling by the client when possible, but Microsoft Graph does not expose a pre-authenticated download URL for this resource."
   },
   {
     "pathPattern": "/me/onlineMeetings/{onlineMeeting-id}/attendanceReports",

package/dist/graph-tools.js

@@ -115,13 +115,13 @@ const UTILITY_TOOLS = [
     name: "download-bytes",
     method: "GET",
     path: "tool:download-bytes",
-    description: 'Download binary content from Microsoft Graph and return it as base64. Single tool for any binary read: drive file content, mail attachment, profile photo, Teams hosted content, meeting recording. Returns { contentType, encoding: "base64", contentLength, contentBytes }.',
+    description: 'Download binary content from Microsoft Graph and return it as base64. Single tool for any binary read: drive file content, mail attachment, profile photo, Teams hosted content, meeting recording. Returns { contentType, encoding: "base64", contentLength, contentBytes }. For large drive/SharePoint file content, prefer get-download-url, which returns a pre-authenticated URL to stream bytes out-of-band instead of base64 through the agent context.',
     readOnlyHint: true,
     openWorldHint: true,
     buildSchema: (ctx) => {
       const schema = {
         target: z.string().describe(
-          'Relative Microsoft Graph path starting with "/". Common paths: /drives/{drive-id}/items/{driveItem-id}/content (drive file content); /me/messages/{message-id}/attachments/{attachment-id}/$value (mail attachment, list-mail-attachments returns the IDs); /me/photo/$value or /users/{user-id}/photo/$value (profile photo); /chats/{chat-id}/messages/{chatMessage-id}/hostedContents/{chatMessageHostedContent-id}/$value (Teams chat hosted content, list-chat-message-hosted-contents returns the IDs); /teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents/{chatMessageHostedContent-id}/$value (Teams channel hosted content). For meeting recordings (often large), use get-meeting-recording-content which returns a URL for out-of-band download by the client.'
+          'Relative Microsoft Graph path starting with "/". Common paths: /drives/{drive-id}/items/{driveItem-id}/content (drive file content); /me/messages/{message-id}/attachments/{attachment-id}/$value (mail attachment, list-mail-attachments returns the IDs); /me/photo/$value or /users/{user-id}/photo/$value (profile photo); /chats/{chat-id}/messages/{chatMessage-id}/hostedContents/{chatMessageHostedContent-id}/$value (Teams chat hosted content, list-chat-message-hosted-contents returns the IDs); /teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents/{chatMessageHostedContent-id}/$value (Teams channel hosted content). For meeting recordings, use get-meeting-recording-content where available; Microsoft Graph returns authenticated recording bytes, not a pre-authenticated download URL.'
         )
       };
       if (ctx.multiAccount) {
@@ -178,6 +178,198 @@ const UTILITY_TOOLS = [
         };
       }
     }
+  },
+  {
+    name: "get-download-url",
+    method: "GET",
+    path: "tool:get-download-url",
+    searchKeywords: "download file download drive file download onedrive file sharepoint file download large drive file large sharepoint file large file out-of-band download pre-authenticated url",
+    description: "Resolve a short-lived, pre-authenticated download URL for Microsoft Graph binary content that exposes one (drive/SharePoint file content). The returned URL streams the bytes with NO Authorization header, so the client can fetch it straight to disk (e.g. curl) without round-tripping base64 through the agent context. Prefer this over download-bytes for any file above a few KB or any bulk download. Returns { downloadUrl, name?, size?, contentType? }. NOTE: mail file attachments (/messages/{id}/attachments/{id}/$value) and meeting recordings do NOT expose a pre-authenticated URL \u2014 Graph offers no such link for them; use download-bytes for small ones.",
+    readOnlyHint: true,
+    openWorldHint: true,
+    buildSchema: (ctx) => {
+      const schema = {
+        target: z.string().describe(
+          'Relative Microsoft Graph path starting with "/". Either a driveItem content path or the item path itself, e.g. /drives/{drive-id}/items/{driveItem-id}/content, /me/drive/items/{driveItem-id}/content, or /sites/{site-id}/drive/items/{driveItem-id}. A trailing /content is optional and is stripped automatically for drive items. Mail attachment $value paths and meeting recordings are not supported (Graph exposes no pre-authenticated URL for them).'
+        )
+      };
+      if (ctx.multiAccount) {
+        schema["account"] = z.string().optional().describe(
+          "Account to use when multiple Microsoft accounts are configured. Required when multiple accounts exist (see list-accounts)."
+        );
+      }
+      return schema;
+    },
+    execute: async (params, { graphClient, authManager }) => {
+      const target = params.target;
+      const accountParam = params.account;
+      if (typeof target !== "string" || target.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "target is required and must be a non-empty string." })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (!target.startsWith("/")) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: 'target must be a relative Microsoft Graph path starting with "/", e.g. /drives/{drive-id}/items/{driveItem-id}/content.'
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const queryIdx = target.indexOf("?");
+      if (queryIdx >= 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "target must not include query parameters. Pass the drive item /content path or item metadata path without $select, $expand, or other query options."
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const pathPart = target.replace(/\/+$/, "");
+      if (/^(\/me|\/users\/[^/]+)\/messages\/[^/]+\/attachments\//.test(pathPart) || /^(\/me|\/users\/[^/]+)\/events\/[^/]+\/attachments\//.test(pathPart) || /^\/groups\/[^/]+\/messages\/[^/]+\/attachments\//.test(pathPart) || /^\/groups\/[^/]+\/events\/[^/]+\/attachments\//.test(pathPart)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "Mail and calendar event attachments do not expose a pre-authenticated download URL. Use download-bytes for small attachments."
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (/^(\/me|\/users\/[^/]+)\/onlineMeetings\/[^/]+\/recordings\/[^/]+(?:\/content)?$/.test(
+        pathPart
+      ) || /^\/communications\/calls\/[^/]+\/recordings\/[^/]+(?:\/content)?$/.test(pathPart)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "Meeting recordings do not expose a pre-authenticated download URL. Use download-bytes for small recordings or get-meeting-recording-content where available."
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (pathPart.endsWith("/$value")) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "$value byte endpoints do not expose a pre-authenticated download URL. Use download-bytes to read these bytes."
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const isDriveItemById = /^\/drives\/[^/]+\/items\/[^/]+(?:\/content)?$/.test(pathPart) || /^\/(?:me|users\/[^/]+|groups\/[^/]+|sites\/[^/]+)\/drive\/items\/[^/]+(?:\/content)?$/.test(
+        pathPart
+      ) || /^\/(?:groups\/[^/]+|sites\/[^/]+)\/drives\/[^/]+\/items\/[^/]+(?:\/content)?$/.test(
+        pathPart
+      );
+      const isDriveItemByPath = /^\/drives\/[^/]+\/root:\/.+:(?:\/content)?$/.test(pathPart) || /^\/(?:me|users\/[^/]+|groups\/[^/]+|sites\/[^/]+)\/drive\/root:\/.+:(?:\/content)?$/.test(
+        pathPart
+      ) || /^\/(?:groups\/[^/]+|sites\/[^/]+)\/drives\/[^/]+\/root:\/.+:(?:\/content)?$/.test(
+        pathPart
+      );
+      if (!isDriveItemById && !isDriveItemByPath) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "target must identify a driveItem in OneDrive or SharePoint. Use a drive item metadata path or /content path, such as /drives/{drive-id}/items/{driveItem-id}/content, /me/drive/items/{driveItem-id}, /sites/{site-id}/drive/items/{driveItem-id}, or /me/drive/root:/path/file.ext:/content. Other Graph byte resources must use download-bytes."
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const isDriveContentEndpoint = /\/items\/[^/]+\/content$/.test(pathPart) || pathPart.endsWith(":/content");
+      const itemPath = isDriveContentEndpoint ? pathPart.slice(0, -"/content".length) : pathPart;
+      try {
+        const accountModeError = await checkAccountParamInBearerMode(accountParam, authManager);
+        if (accountModeError) {
+          return {
+            content: [{ type: "text", text: JSON.stringify({ error: accountModeError }) }],
+            isError: true
+          };
+        }
+        let accountAccessToken;
+        if (authManager && !authManager.isOAuthModeEnabled() && !getRequestTokens()) {
+          accountAccessToken = await authManager.getTokenForAccount(accountParam);
+        }
+        const response = await graphClient.graphRequest(itemPath, {
+          accessToken: accountAccessToken
+        });
+        if (response?.isError) {
+          return response;
+        }
+        const text = response?.content?.[0]?.text;
+        let item;
+        if (typeof text === "string") {
+          try {
+            item = JSON.parse(text);
+          } catch {
+            item = void 0;
+          }
+        }
+        const downloadUrl = item?.["@microsoft.graph.downloadUrl"];
+        if (!downloadUrl) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "No pre-authenticated download URL is available for this resource. It may not be a drive item, or it exposes bytes only via download-bytes."
+                })
+              }
+            ],
+            isError: true
+          };
+        }
+        const file = item?.file;
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                downloadUrl,
+                name: item?.name,
+                size: item?.size,
+                contentType: file?.mimeType
+              })
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+          isError: true
+        };
+      }
+    }
   }
 ];
 function registerUtilityToolWithMcp(server, utility, ctx) {
@@ -747,8 +939,20 @@ function buildDiscoverySearchIndex(toolsRegistry, utilityTools = []) {
     const nt = tokenize(utility.name);
     nameTokens.set(utility.name, new Set(nt));
     const pathTokens = tokenize(utility.path);
+    const keywordTokens = tokenize(utility.searchKeywords);
     const descTokens = tokenize(utility.description).slice(0, DESC_CAP_TOKENS);
-    const tokens = [...nt, ...nt, ...nt, ...nt, ...nt, ...pathTokens, ...pathTokens, ...descTokens];
+    const tokens = [
+      ...nt,
+      ...nt,
+      ...nt,
+      ...nt,
+      ...nt,
+      ...pathTokens,
+      ...pathTokens,
+      ...keywordTokens,
+      ...keywordTokens,
+      ...descTokens
+    ];
     docs.push({ id: utility.name, tokens });
   }
   return { bm25: buildBM25Index(docs), nameTokens };

package/dist/mcp-instructions.js

@@ -6,7 +6,7 @@ function buildGeneralMcpInstructions(opts) {
     "When you need an organizational user or recipient address, resolve it with list-users (or another directory tool); do not invent SMTP addresses.",
     "Directory $search on collections such as /users or /groups requires ConsistencyLevel: eventual when the tool exposes that header.",
     "Teams chat and channel messages: prefer HTML contentType in the body; plain text is often mangled by Graph.",
-    "Files / binary content: use download-bytes for any binary read (drive file content, mail attachments, profile photos, Teams hosted content, meeting recordings); pass it a Graph path or an absolute @microsoft.graph.downloadUrl from a metadata response. For uploads, upload-file-content takes a base64 string body up to 4MB; use create-upload-session above that."
+    "Files / binary content: for large drive/SharePoint file content, prefer get-download-url to resolve a pre-authenticated URL for out-of-band download. Use download-bytes for authenticated byte reads such as mail attachments, profile photos, Teams hosted content, and meeting recordings. Both tools take relative Microsoft Graph paths, not absolute URLs. For uploads, upload-file-content takes a base64 string body up to 4MB; use create-upload-session above that."
   ];
   if (opts.readOnly) parts.push("This server is read-only; write operations are disabled.");
   if (opts.multiAccount)

package/package.json

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

@@ -594,7 +594,7 @@
     "toolName": "get-drive-item",
     "presets": ["files", "onedrive", "personal"],
     "scopes": ["Files.Read"],
-    "llmTip": "Gets metadata for a file or folder: name, size, lastModifiedDateTime, createdBy, webUrl, file (mimeType, hashes), folder (childCount), parentReference, and @microsoft.graph.downloadUrl. For the bytes, call download-bytes with target=/drives/{drive-id}/items/{driveItem-id}/content (Graph redirects to the same downloadUrl)."
+    "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."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -1904,8 +1904,7 @@
     "toolName": "get-meeting-recording-content",
     "presets": ["teams", "work"],
     "workScopes": ["OnlineMeetingRecording.Read.All"],
-    "returnDownloadUrl": true,
-    "llmTip": "Returns a temporary download URL for the meeting recording in MP4 format. Use the download URL to access the video file. The recording may be large — do not attempt to stream it inline."
+    "llmTip": "Returns the authenticated meeting recording video bytes in MP4 format. The recording may be large; prefer out-of-band handling by the client when possible, but Microsoft Graph does not expose a pre-authenticated download URL for this resource."
   },
   {
     "pathPattern": "/me/onlineMeetings/{onlineMeeting-id}/attendanceReports",