@softeria/ms-365-mcp-server 0.133.0 → 0.133.2

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

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { z } from "zod";
 import { tmpdir } from "os";
 import { join } from "path";
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
 vi.mock("../logger.js", () => ({
   default: {
     info: vi.fn(),
@@ -755,16 +755,13 @@ describe("graph-tools", () => {
     afterEach(() => {
       rmSync(tmpDir, { recursive: true, force: true });
     });
-    it("writes decoded binary bytes to the output path and returns metadata", async () => {
+    it("streams bytes to the output path and returns metadata", async () => {
       mockEndpoints.length = 0;
       mockEndpointsJson = [];
       const graphClient = {
-        makeRequest: vi.fn().mockResolvedValue({
-          message: "OK!",
+        downloadToFile: vi.fn().mockResolvedValue({
           contentType: "image/jpeg",
-          encoding: "base64",
-          contentLength: 2,
-          contentBytes: "aGk="
+          contentLength: 2
         })
       };
       const server = createMockServer();
@@ -774,38 +771,19 @@ describe("graph-tools", () => {
       expect(tool).toBeDefined();
       const outputPath = join(tmpDir, "photo.jpg");
       const result = await tool.handler({ target: "/me/photo/$value", outputPath });
-      expect(graphClient.makeRequest).toHaveBeenCalledTimes(1);
-      const [reqPath, options] = graphClient.makeRequest.mock.calls[0];
+      expect(graphClient.downloadToFile).toHaveBeenCalledTimes(1);
+      const [reqPath, dest, options] = graphClient.downloadToFile.mock.calls[0];
       expect(reqPath).toBe("/me/photo/$value");
-      expect(options.rawResponse).toBe(true);
+      expect(dest).toBe(outputPath);
+      expect(options).toStrictEqual({ accessToken: void 0 });
       expect(result.isError).toBeUndefined();
       const payload = JSON.parse(result.content[0].text);
       expect(payload).toEqual({ path: outputPath, contentType: "image/jpeg", bytesWritten: 2 });
-      expect(existsSync(outputPath)).toBe(true);
-      expect(readFileSync(outputPath).toString("utf8")).toBe("hi");
-    });
-    it("writes a text/JSON body verbatim from rawResponse", async () => {
-      mockEndpoints.length = 0;
-      mockEndpointsJson = [];
-      const graphClient = {
-        makeRequest: vi.fn().mockResolvedValue({
-          message: "OK!",
-          contentType: "text/plain",
-          rawResponse: "line1\nline2\n"
-        })
-      };
-      const server = createMockServer();
-      const { registerGraphTools } = await loadModule();
-      registerGraphTools(server, graphClient);
-      const outputPath = join(tmpDir, "note.txt");
-      const result = await server.tools.get("download-bytes-to-file").handler({ target: "/me/drive/root:/note.txt:/content", outputPath });
-      expect(result.isError).toBeUndefined();
-      expect(readFileSync(outputPath).toString("utf8")).toBe("line1\nline2\n");
     });
     it("rejects a relative outputPath", async () => {
       mockEndpoints.length = 0;
       mockEndpointsJson = [];
-      const graphClient = { makeRequest: vi.fn() };
+      const graphClient = { downloadToFile: vi.fn() };
       const server = createMockServer();
       const { registerGraphTools } = await loadModule();
       registerGraphTools(server, graphClient);
@@ -813,7 +791,7 @@ describe("graph-tools", () => {
       expect(result.isError).toBe(true);
       const payload = JSON.parse(result.content[0].text);
       expect(payload.error).toMatch(/absolute path/);
-      expect(graphClient.makeRequest).not.toHaveBeenCalled();
+      expect(graphClient.downloadToFile).not.toHaveBeenCalled();
     });
     it("rejects absolute URLs in target (Graph paths only)", async () => {
       mockEndpoints.length = 0;
@@ -834,7 +812,7 @@ describe("graph-tools", () => {
       mockEndpointsJson = [];
       const outputPath = join(tmpDir, "existing.bin");
       writeFileSync(outputPath, "original");
-      const graphClient = { makeRequest: vi.fn() };
+      const graphClient = { downloadToFile: vi.fn() };
       const server = createMockServer();
       const { registerGraphTools } = await loadModule();
       registerGraphTools(server, graphClient);
@@ -842,14 +820,14 @@ describe("graph-tools", () => {
       expect(result.isError).toBe(true);
       const payload = JSON.parse(result.content[0].text);
       expect(payload.error).toMatch(/already exists/);
-      expect(graphClient.makeRequest).not.toHaveBeenCalled();
+      expect(graphClient.downloadToFile).not.toHaveBeenCalled();
       expect(readFileSync(outputPath).toString("utf8")).toBe("original");
     });
-    it("surfaces a Graph error and writes no file when makeRequest throws", async () => {
+    it("surfaces a Graph error when downloadToFile throws", async () => {
       mockEndpoints.length = 0;
       mockEndpointsJson = [];
       const graphClient = {
-        makeRequest: vi.fn().mockRejectedValue(new Error("Microsoft Graph API error: 404 Not Found"))
+        downloadToFile: vi.fn().mockRejectedValue(new Error("Microsoft Graph API error: 404 Not Found"))
       };
       const server = createMockServer();
       const { registerGraphTools } = await loadModule();
@@ -859,7 +837,43 @@ describe("graph-tools", () => {
       expect(result.isError).toBe(true);
       const payload = JSON.parse(result.content[0].text);
       expect(payload.error).toMatch(/404 Not Found/);
-      expect(existsSync(outputPath)).toBe(false);
+    });
+    it("forwards the resolved account token to downloadToFile in multi-account mode", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        downloadToFile: vi.fn().mockResolvedValue({ contentType: "application/pdf", contentLength: 3 })
+      };
+      const authManager = {
+        isOAuthModeEnabled: vi.fn().mockReturnValue(false),
+        getToken: vi.fn().mockResolvedValue(null),
+        getTokenForAccount: vi.fn().mockResolvedValue("account-2-token")
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient,
+        false,
+        void 0,
+        false,
+        authManager,
+        true,
+        ["user1@domain.com", "user2@domain.com"]
+      );
+      const outputPath = join(tmpDir, "invoice.pdf");
+      const result = await server.tools.get("download-bytes-to-file").handler({
+        target: "/me/messages/m1/attachments/a1/$value",
+        outputPath,
+        account: "user2@domain.com"
+      });
+      expect(result.isError).toBeUndefined();
+      expect(authManager.getTokenForAccount).toHaveBeenCalledWith("user2@domain.com");
+      expect(graphClient.downloadToFile).toHaveBeenCalledWith(
+        "/me/messages/m1/attachments/a1/$value",
+        outputPath,
+        { accessToken: "account-2-token" }
+      );
     });
     it("is registered in stdio mode but hidden in HTTP mode", async () => {
       mockEndpoints.length = 0;

package/dist/endpoints.json

@@ -10,6 +10,7 @@
     "pathPattern": "/me/messages",
     "method": "get",
     "toolName": "list-mail-messages",
+    "descriptionOverride": "List, search, and filter Outlook email messages in the signed-in user's mailbox across all folders. Returns message metadata (subject, from, receivedDateTime, isRead, hasAttachments) plus a body preview. Use $search for keyword queries, $filter to narrow by sender/read state/date, $top to limit page size, and $select to trim fields.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.Read"],
     "llmTip": "List read search my Outlook emails across folders. CRITICAL: When searching emails, the $search parameter value MUST be wrapped in double quotes. Format: $search=\"your search query here\". Use KQL (Keyword Query Language) syntax to search specific properties: 'from:', 'subject:', 'body:', 'to:', 'cc:', 'bcc:', 'attachment:', 'hasAttachments:', 'importance:', 'received:', 'sent:'. Examples: $search=\"from:john@example.com\" | $search=\"subject:meeting AND hasAttachments:true\" | $search=\"body:urgent AND received>=2024-01-01\" | $search=\"from:john AND importance:high\". Remember: ALWAYS wrap the entire search expression in double quotes! Reference: https://learn.microsoft.com/en-us/graph/search-query-parameter IMPORTANT: Always use $select to limit returned fields and reduce response size. Recommended default: $select=id,subject,from,toRecipients,receivedDateTime,bodyPreview,isRead,hasAttachments. Use bodyPreview instead of body for listings. To read the full email body, use get-mail-message with the specific message id."
@@ -72,6 +73,7 @@
     "pathPattern": "/me/messages/{message-id}",
     "method": "get",
     "toolName": "get-mail-message",
+    "descriptionOverride": "Get a single Outlook email message by its message ID, including full subject, sender, recipients, body, and attachment flags. Use list-mail-messages first to obtain the message ID.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.Read"]
   },
@@ -157,6 +159,7 @@
     "pathPattern": "/me/messages",
     "method": "post",
     "toolName": "create-draft-email",
+    "descriptionOverride": "Create a draft Outlook email message in the signed-in user's Drafts folder. Set subject, body, toRecipients, ccRecipients, and importance. The draft is saved, not sent — use send-mail to send a message directly, or send the draft afterwards.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"]
   },
@@ -164,6 +167,7 @@
     "pathPattern": "/me/messages/{message-id}",
     "method": "delete",
     "toolName": "delete-mail-message",
+    "descriptionOverride": "Delete an Outlook email message by its message ID. This is a soft delete that moves the message to Deleted Items.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"],
     "llmTip": "Soft delete — moves to Deleted Items. To permanently delete, delete again from Deleted Items."
@@ -180,6 +184,7 @@
     "pathPattern": "/me/messages/{message-id}",
     "method": "patch",
     "toolName": "update-mail-message",
+    "descriptionOverride": "Update an existing Outlook email message by its message ID — for example mark it read or unread (isRead), flag it (flag), change its categories, importance, or edit a draft's subject, body, or recipients.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"]
   },
@@ -820,6 +825,7 @@
     "pathPattern": "/me/messages/{message-id}/$value",
     "method": "get",
     "toolName": "get-mail-message-mime",
+    "descriptionOverride": "Download the raw MIME source (RFC 822 .eml content) of an Outlook email message by its message ID. Returns the complete original message including headers and encoded attachments.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.Read"],
     "acceptType": "text/plain",

package/dist/graph-client.js

@@ -7,6 +7,8 @@ import {
   getSharedBreaker,
   loadResilienceConfig
 } from "./lib/graph-resilience.js";
+import { open, stat, unlink } from "fs/promises";
+import { pipeline } from "stream/promises";
 function isBinaryContentType(contentType) {
   if (!contentType) return false;
   const lower = contentType.toLowerCase().split(";")[0].trim();
@@ -100,6 +102,65 @@ class GraphClient {
       throw error;
     }
   }
+  /**
+   * Stream Graph byte content straight to a file, without holding the whole
+   * payload in memory. download-bytes-to-file uses this for big mail attachments
+   * and meeting recordings, where makeRequest's base64 buffering would blow up
+   * memory or hit V8's max string length. Creates the file with wx + 0o600 (never
+   * overwrites) and removes a partial file if the transfer fails.
+   */
+  async downloadToFile(endpoint, destinationPath, options = {}) {
+    const fileHandle = await open(destinationPath, "wx", 384);
+    let completed = false;
+    try {
+      const contextTokens = getRequestTokens();
+      const accessToken = options.accessToken ?? contextTokens?.accessToken ?? await this.authManager.getToken();
+      if (!accessToken) {
+        throw new Error("No access token available");
+      }
+      const response = await this.performRequest(endpoint, accessToken, options);
+      if (response.status === 403) {
+        const errorText = await response.text();
+        if (errorText.includes("scope") || errorText.includes("permission")) {
+          throw new Error(
+            `Microsoft Graph API scope error: ${response.status} ${response.statusText} - ${errorText}. This tool requires organization mode. Please restart with --org-mode flag.`
+          );
+        }
+        throw new Error(
+          `Microsoft Graph API error: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      if (!response.ok) {
+        throw new Error(
+          `Microsoft Graph API error: ${response.status} ${response.statusText} - ${await response.text()}`
+        );
+      }
+      if (!response.body) {
+        throw new Error("Microsoft Graph returned an empty response body");
+      }
+      await pipeline(response.body, fileHandle.createWriteStream());
+      completed = true;
+      let contentLength;
+      try {
+        contentLength = (await stat(destinationPath)).size;
+      } catch {
+        const header = Number(response.headers.get("content-length"));
+        contentLength = Number.isFinite(header) ? header : 0;
+      }
+      return {
+        contentType: response.headers.get("content-type") || "application/octet-stream",
+        contentLength
+      };
+    } catch (error) {
+      logger.error("Microsoft Graph file download failed:", error);
+      throw error;
+    } finally {
+      await fileHandle.close().catch(() => void 0);
+      if (!completed) {
+        await unlink(destinationPath).catch(() => void 0);
+      }
+    }
+  }
   async performRequest(endpoint, accessToken, options) {
     const cloudEndpoints = getCloudEndpoints(this.secrets.cloudType);
     const apiVersion = options.apiVersion || "v1.0";

package/dist/graph-tools.js

@@ -12,7 +12,7 @@ import { api as betaApi } from "./generated/client-beta.js";
 const allEndpoints = [...api.endpoints, ...betaApi.endpoints];
 import { z } from "zod";
 import { readFileSync } from "fs";
-import { writeFile, access } from "fs/promises";
+import { access } from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
 import { TOOL_CATEGORIES } from "./tool-categories.js";
@@ -299,29 +299,9 @@ const UTILITY_TOOLS = [
         if (authManager && !authManager.isOAuthModeEnabled() && !getRequestTokens()) {
           accountAccessToken = await authManager.getTokenForAccount(accountParam);
         }
-        const result = await graphClient.makeRequest(target, {
-          accessToken: accountAccessToken,
-          rawResponse: true
+        const result = await graphClient.downloadToFile(target, outputPath, {
+          accessToken: accountAccessToken
         });
-        let buffer;
-        if (result.encoding === "base64" && typeof result.contentBytes === "string") {
-          buffer = Buffer.from(result.contentBytes, "base64");
-        } else if (typeof result.rawResponse === "string") {
-          buffer = Buffer.from(result.rawResponse, "utf8");
-        } else {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify({
-                  error: "Graph response contained no downloadable bytes for this target."
-                })
-              }
-            ],
-            isError: true
-          };
-        }
-        await writeFile(outputPath, buffer, { flag: "wx" });
         return {
           content: [
             {
@@ -329,7 +309,7 @@ const UTILITY_TOOLS = [
               text: JSON.stringify({
                 path: outputPath,
                 contentType: result.contentType,
-                bytesWritten: buffer.byteLength
+                bytesWritten: result.contentLength
               })
             }
           ]

package/package.json

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

@@ -10,6 +10,7 @@
     "pathPattern": "/me/messages",
     "method": "get",
     "toolName": "list-mail-messages",
+    "descriptionOverride": "List, search, and filter Outlook email messages in the signed-in user's mailbox across all folders. Returns message metadata (subject, from, receivedDateTime, isRead, hasAttachments) plus a body preview. Use $search for keyword queries, $filter to narrow by sender/read state/date, $top to limit page size, and $select to trim fields.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.Read"],
     "llmTip": "List read search my Outlook emails across folders. CRITICAL: When searching emails, the $search parameter value MUST be wrapped in double quotes. Format: $search=\"your search query here\". Use KQL (Keyword Query Language) syntax to search specific properties: 'from:', 'subject:', 'body:', 'to:', 'cc:', 'bcc:', 'attachment:', 'hasAttachments:', 'importance:', 'received:', 'sent:'. Examples: $search=\"from:john@example.com\" | $search=\"subject:meeting AND hasAttachments:true\" | $search=\"body:urgent AND received>=2024-01-01\" | $search=\"from:john AND importance:high\". Remember: ALWAYS wrap the entire search expression in double quotes! Reference: https://learn.microsoft.com/en-us/graph/search-query-parameter IMPORTANT: Always use $select to limit returned fields and reduce response size. Recommended default: $select=id,subject,from,toRecipients,receivedDateTime,bodyPreview,isRead,hasAttachments. Use bodyPreview instead of body for listings. To read the full email body, use get-mail-message with the specific message id."
@@ -72,6 +73,7 @@
     "pathPattern": "/me/messages/{message-id}",
     "method": "get",
     "toolName": "get-mail-message",
+    "descriptionOverride": "Get a single Outlook email message by its message ID, including full subject, sender, recipients, body, and attachment flags. Use list-mail-messages first to obtain the message ID.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.Read"]
   },
@@ -157,6 +159,7 @@
     "pathPattern": "/me/messages",
     "method": "post",
     "toolName": "create-draft-email",
+    "descriptionOverride": "Create a draft Outlook email message in the signed-in user's Drafts folder. Set subject, body, toRecipients, ccRecipients, and importance. The draft is saved, not sent — use send-mail to send a message directly, or send the draft afterwards.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"]
   },
@@ -164,6 +167,7 @@
     "pathPattern": "/me/messages/{message-id}",
     "method": "delete",
     "toolName": "delete-mail-message",
+    "descriptionOverride": "Delete an Outlook email message by its message ID. This is a soft delete that moves the message to Deleted Items.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"],
     "llmTip": "Soft delete — moves to Deleted Items. To permanently delete, delete again from Deleted Items."
@@ -180,6 +184,7 @@
     "pathPattern": "/me/messages/{message-id}",
     "method": "patch",
     "toolName": "update-mail-message",
+    "descriptionOverride": "Update an existing Outlook email message by its message ID — for example mark it read or unread (isRead), flag it (flag), change its categories, importance, or edit a draft's subject, body, or recipients.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"]
   },
@@ -820,6 +825,7 @@
     "pathPattern": "/me/messages/{message-id}/$value",
     "method": "get",
     "toolName": "get-mail-message-mime",
+    "descriptionOverride": "Download the raw MIME source (RFC 822 .eml content) of an Outlook email message by its message ID. Returns the complete original message including headers and encoded attachments.",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.Read"],
     "acceptType": "text/plain",