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

package/bin/modules/simplified-openapi.mjs

@@ -145,6 +145,10 @@ export function createAndSaveSimplifiedOpenAPI(
     }
   }
 
+  if (apiVersion === 'beta') {
+    normalizeWildcardSuccessResponses(openApiSpec.paths);
+  }
+
   if (openApiSpec.components && openApiSpec.components.schemas) {
     removeODataTypeRecursively(openApiSpec.components.schemas);
     flattenComplexSchemasRecursively(openApiSpec.components.schemas);
@@ -162,6 +166,29 @@ export function createAndSaveSimplifiedOpenAPI(
   fs.writeFileSync(openapiTrimmedFile, yaml.dump(openApiSpec));
 }
 
+function normalizeWildcardSuccessResponses(paths) {
+  Object.values(paths || {}).forEach((pathItem) => {
+    if (!pathItem || typeof pathItem !== 'object') return;
+
+    Object.entries(pathItem).forEach(([method, operation]) => {
+      if (!operation || typeof operation !== 'object') return;
+      if (!operation.responses || !operation.responses['2XX']) return;
+
+      const hasConcreteSuccess = Object.keys(operation.responses).some((statusCode) =>
+        /^2\d\d$/.test(statusCode)
+      );
+      if (hasConcreteSuccess) {
+        delete operation.responses['2XX'];
+        return;
+      }
+
+      const successStatus = method === 'post' ? '201' : method === 'delete' ? '204' : '200';
+      operation.responses[successStatus] = operation.responses['2XX'];
+      delete operation.responses['2XX'];
+    });
+  });
+}
+
 function removeODataTypeRecursively(obj) {
   if (!obj || typeof obj !== 'object') return;
 

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}",
@@ -1167,6 +1167,30 @@
     "scopes": ["Tasks.ReadWrite"],
     "llmTip": "CRITICAL: Requires If-Match header with ETag from get-planner-bucket (use includeHeaders=true)."
   },
+  {
+    "pathPattern": "/planner/tasks/{plannerTask-id}/messages",
+    "method": "get",
+    "toolName": "list-planner-task-messages",
+    "scopes": ["Tasks.Read"],
+    "apiVersion": "beta",
+    "llmTip": "Lists messages in a Planner task's chat — the modern Planner 'task chat', distinct from the legacy conversationThreadId comments (which live in the M365 group conversation thread). Each message has id, content (HTML), createdBy, createdDateTime, mentions, reactions. BETA Graph API: subject to change; delegated work/school accounts only — no application permissions, no personal Microsoft accounts, global cloud only (not GCC/DoD/21Vianet)."
+  },
+  {
+    "pathPattern": "/planner/tasks/{plannerTask-id}/messages",
+    "method": "post",
+    "toolName": "create-planner-task-message",
+    "scopes": ["Tasks.ReadWrite"],
+    "apiVersion": "beta",
+    "llmTip": "Posts a message to a Planner task's chat (the modern 'task chat', not the legacy conversationThreadId comment). Microsoft is retiring the classic task comments experience and hiding it from the task (Planner 2026 update), so task chat is the current supported way to post per-task updates teammates will see, with @mentions. Body: { content: 'plain text or sanitized HTML', mentions?: [{ mentioned: 'user-id', position: 0, mentionType: 'user' }] } (mentions optional). No ETag/If-Match required. BETA Graph API: subject to change; delegated work/school accounts only — no application permissions, no personal Microsoft accounts, global cloud only (not GCC/DoD/21Vianet)."
+  },
+  {
+    "pathPattern": "/planner/tasks/{plannerTask-id}/messages/{plannerTaskChatMessage-id}",
+    "method": "delete",
+    "toolName": "delete-planner-task-message",
+    "scopes": ["Tasks.ReadWrite"],
+    "apiVersion": "beta",
+    "llmTip": "Deletes a message from a Planner task's chat. No request body; If-Match is optional if you want conditional deletion; returns 204. BETA Graph API: subject to change; delegated work/school accounts only — no application permissions, no personal Microsoft accounts, global cloud only (not GCC/DoD/21Vianet)."
+  },
   {
     "pathPattern": "/me/contacts",
     "method": "get",
@@ -1880,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/generated/client-beta.js

@@ -690,6 +690,58 @@ const microsoft_graph_ODataErrors_MainError = z.object({
   innerError: microsoft_graph_ODataErrors_InnerError.optional()
 }).passthrough();
 const microsoft_graph_ODataErrors_ODataError = z.object({ error: microsoft_graph_ODataErrors_MainError }).passthrough();
+const microsoft_graph_plannerTaskChatMentionType = z.enum([
+  "user",
+  "application",
+  "unknownFutureValue"
+]);
+const microsoft_graph_plannerTaskChatMention = z.object({
+  mentioned: z.string().describe("The ID of the mentioned user.").nullish(),
+  mentionType: microsoft_graph_plannerTaskChatMentionType.optional(),
+  position: z.number().gte(-2147483648).lte(2147483647).describe("The zero-based position of the mention in the message content.").optional()
+}).passthrough();
+const microsoft_graph_plannerTaskChatMessageType = z.enum([
+  "richTextHtml",
+  "plainText",
+  "unknownFutureValue"
+]);
+const microsoft_graph_plannerTaskChatReactionEvent = z.object({
+  createdBy: microsoft_graph_identitySet.optional(),
+  createdDateTime: z.string().regex(
+    /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
+  ).datetime({ offset: true }).describe(
+    "The date and time when the reaction was added. The timestamp type represents date and time information using ISO 8601 format and is always in UTC. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z."
+  ).optional()
+}).passthrough();
+const microsoft_graph_plannerTaskChatReaction = z.object({
+  reactionEvents: z.array(microsoft_graph_plannerTaskChatReactionEvent).optional(),
+  reactionType: z.string().describe("The type of reaction, such as like, heart, or emoji characters.").nullish()
+}).passthrough();
+const microsoft_graph_plannerTaskChatMessage = z.object({
+  id: z.string().describe("The unique identifier for an entity. Read-only.").optional(),
+  content: z.string().describe("The content of the chat message. Supports plain text and sanitized HTML.").nullish(),
+  createdBy: microsoft_graph_identitySet.optional(),
+  createdDateTime: z.string().regex(
+    /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
+  ).datetime({ offset: true }).describe(
+    "The date and time when the message was created. The timestamp type represents date and time information using ISO 8601 format and is always in UTC. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z."
+  ).optional(),
+  deletedDateTime: z.string().regex(
+    /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
+  ).datetime({ offset: true }).nullish(),
+  editedDateTime: z.string().regex(
+    /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
+  ).datetime({ offset: true }).nullish(),
+  mentions: z.array(microsoft_graph_plannerTaskChatMention).describe("The list of mentions in the message.").optional(),
+  messageType: microsoft_graph_plannerTaskChatMessageType.optional(),
+  parentEntityId: z.string().describe("The ID of the parent plannerTask that this message belongs to.").nullish(),
+  reactions: z.array(microsoft_graph_plannerTaskChatReaction).describe("The reactions on the message.").optional()
+}).passthrough();
+const microsoft_graph_plannerTaskChatMessageCollectionResponse = z.object({
+  "@odata.count": z.number().int().nullable(),
+  "@odata.nextLink": z.string().nullable(),
+  value: z.array(microsoft_graph_plannerTaskChatMessage)
+}).partial().passthrough();
 const schemas = {
   microsoft_graph_allowedAudiences,
   microsoft_graph_identity,
@@ -741,7 +793,14 @@ const schemas = {
   microsoft_graph_ODataErrors_ErrorDetails,
   microsoft_graph_ODataErrors_InnerError,
   microsoft_graph_ODataErrors_MainError,
-  microsoft_graph_ODataErrors_ODataError
+  microsoft_graph_ODataErrors_ODataError,
+  microsoft_graph_plannerTaskChatMentionType,
+  microsoft_graph_plannerTaskChatMention,
+  microsoft_graph_plannerTaskChatMessageType,
+  microsoft_graph_plannerTaskChatReactionEvent,
+  microsoft_graph_plannerTaskChatReaction,
+  microsoft_graph_plannerTaskChatMessage,
+  microsoft_graph_plannerTaskChatMessageCollectionResponse
 };
 const endpoints = makeApi([
   {
@@ -762,6 +821,87 @@ const endpoints = makeApi([
         schema: z.array(z.string()).describe("Expand related entities").optional()
       }
     ],
+    response: microsoft_graph_profile
+  },
+  {
+    method: "get",
+    path: "/planner/tasks/:plannerTaskId/messages",
+    alias: "list-planner-task-messages",
+    description: `Retrieve a list of plannerTaskChatMessage objects associated with a plannerTask.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "$top",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Show only the first n items").optional()
+      },
+      {
+        name: "$skip",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Skip the first n items").optional()
+      },
+      {
+        name: "$search",
+        type: "Query",
+        schema: z.string().describe("Search items by search phrases").optional()
+      },
+      {
+        name: "$filter",
+        type: "Query",
+        schema: z.string().describe("Filter items by property values").optional()
+      },
+      {
+        name: "$count",
+        type: "Query",
+        schema: z.boolean().describe("Include count of items").optional()
+      },
+      {
+        name: "$orderby",
+        type: "Query",
+        schema: z.array(z.string()).describe("Order items by property values").optional()
+      },
+      {
+        name: "$select",
+        type: "Query",
+        schema: z.array(z.string()).describe("Select properties to be returned").optional()
+      },
+      {
+        name: "$expand",
+        type: "Query",
+        schema: z.array(z.string()).describe("Expand related entities").optional()
+      }
+    ],
+    response: microsoft_graph_plannerTaskChatMessageCollectionResponse
+  },
+  {
+    method: "post",
+    path: "/planner/tasks/:plannerTaskId/messages",
+    alias: "create-planner-task-message",
+    description: `Create a new plannerTaskChatMessage on a plannerTask.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `New navigation property`,
+        type: "Body",
+        schema: microsoft_graph_plannerTaskChatMessage
+      }
+    ],
+    response: microsoft_graph_plannerTaskChatMessage
+  },
+  {
+    method: "delete",
+    path: "/planner/tasks/:plannerTaskId/messages/:plannerTaskChatMessageId",
+    alias: "delete-planner-task-message",
+    description: `Delete a plannerTaskChatMessage object.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "If-Match",
+        type: "Header",
+        schema: z.string().describe("ETag").optional()
+      }
+    ],
     response: z.void()
   }
 ]);

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.125.1",
+  "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}",
@@ -1167,6 +1167,30 @@
     "scopes": ["Tasks.ReadWrite"],
     "llmTip": "CRITICAL: Requires If-Match header with ETag from get-planner-bucket (use includeHeaders=true)."
   },
+  {
+    "pathPattern": "/planner/tasks/{plannerTask-id}/messages",
+    "method": "get",
+    "toolName": "list-planner-task-messages",
+    "scopes": ["Tasks.Read"],
+    "apiVersion": "beta",
+    "llmTip": "Lists messages in a Planner task's chat — the modern Planner 'task chat', distinct from the legacy conversationThreadId comments (which live in the M365 group conversation thread). Each message has id, content (HTML), createdBy, createdDateTime, mentions, reactions. BETA Graph API: subject to change; delegated work/school accounts only — no application permissions, no personal Microsoft accounts, global cloud only (not GCC/DoD/21Vianet)."
+  },
+  {
+    "pathPattern": "/planner/tasks/{plannerTask-id}/messages",
+    "method": "post",
+    "toolName": "create-planner-task-message",
+    "scopes": ["Tasks.ReadWrite"],
+    "apiVersion": "beta",
+    "llmTip": "Posts a message to a Planner task's chat (the modern 'task chat', not the legacy conversationThreadId comment). Microsoft is retiring the classic task comments experience and hiding it from the task (Planner 2026 update), so task chat is the current supported way to post per-task updates teammates will see, with @mentions. Body: { content: 'plain text or sanitized HTML', mentions?: [{ mentioned: 'user-id', position: 0, mentionType: 'user' }] } (mentions optional). No ETag/If-Match required. BETA Graph API: subject to change; delegated work/school accounts only — no application permissions, no personal Microsoft accounts, global cloud only (not GCC/DoD/21Vianet)."
+  },
+  {
+    "pathPattern": "/planner/tasks/{plannerTask-id}/messages/{plannerTaskChatMessage-id}",
+    "method": "delete",
+    "toolName": "delete-planner-task-message",
+    "scopes": ["Tasks.ReadWrite"],
+    "apiVersion": "beta",
+    "llmTip": "Deletes a message from a Planner task's chat. No request body; If-Match is optional if you want conditional deletion; returns 204. BETA Graph API: subject to change; delegated work/school accounts only — no application permissions, no personal Microsoft accounts, global cloud only (not GCC/DoD/21Vianet)."
+  },
   {
     "pathPattern": "/me/contacts",
     "method": "get",
@@ -1880,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",