@softeria/ms-365-mcp-server 0.132.1 → 0.133.1

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

@@ -1,5 +1,8 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { z } from "zod";
+import { tmpdir } from "os";
+import { join } from "path";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
 vi.mock("../logger.js", () => ({
   default: {
     info: vi.fn(),
@@ -744,6 +747,159 @@ describe("graph-tools", () => {
       expect(payload.error).toMatch(/relative Microsoft Graph path/);
     });
   });
+  describe("download-bytes-to-file", () => {
+    let tmpDir;
+    beforeEach(() => {
+      tmpDir = mkdtempSync(join(tmpdir(), "dbtf-"));
+    });
+    afterEach(() => {
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("streams bytes to the output path and returns metadata", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        downloadToFile: vi.fn().mockResolvedValue({
+          contentType: "image/jpeg",
+          contentLength: 2
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("download-bytes-to-file");
+      expect(tool).toBeDefined();
+      const outputPath = join(tmpDir, "photo.jpg");
+      const result = await tool.handler({ target: "/me/photo/$value", outputPath });
+      expect(graphClient.downloadToFile).toHaveBeenCalledTimes(1);
+      const [reqPath, dest, options] = graphClient.downloadToFile.mock.calls[0];
+      expect(reqPath).toBe("/me/photo/$value");
+      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 });
+    });
+    it("rejects a relative outputPath", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = { downloadToFile: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const result = await server.tools.get("download-bytes-to-file").handler({ target: "/me/photo/$value", outputPath: "relative/path.jpg" });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/absolute path/);
+      expect(graphClient.downloadToFile).not.toHaveBeenCalled();
+    });
+    it("rejects absolute URLs in target (Graph paths only)", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, {});
+      const result = await server.tools.get("download-bytes-to-file").handler({
+        target: "https://example.sharepoint.com/d/abc?temp=signed",
+        outputPath: join(tmpDir, "x.bin")
+      });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/relative Microsoft Graph path/);
+    });
+    it("refuses to overwrite an existing file and skips the Graph call", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const outputPath = join(tmpDir, "existing.bin");
+      writeFileSync(outputPath, "original");
+      const graphClient = { downloadToFile: vi.fn() };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const result = await server.tools.get("download-bytes-to-file").handler({ target: "/me/photo/$value", outputPath });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/already exists/);
+      expect(graphClient.downloadToFile).not.toHaveBeenCalled();
+      expect(readFileSync(outputPath).toString("utf8")).toBe("original");
+    });
+    it("surfaces a Graph error when downloadToFile throws", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        downloadToFile: vi.fn().mockRejectedValue(new Error("Microsoft Graph API error: 404 Not Found"))
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const outputPath = join(tmpDir, "missing.bin");
+      const result = await server.tools.get("download-bytes-to-file").handler({ target: "/me/messages/abc/attachments/xyz/$value", outputPath });
+      expect(result.isError).toBe(true);
+      const payload = JSON.parse(result.content[0].text);
+      expect(payload.error).toMatch(/404 Not Found/);
+    });
+    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;
+      mockEndpointsJson = [];
+      const { registerGraphTools } = await loadModule();
+      const stdioServer = createMockServer();
+      registerGraphTools(stdioServer, {});
+      expect(stdioServer.tools.has("download-bytes-to-file")).toBe(true);
+      expect(stdioServer.tools.has("download-bytes")).toBe(true);
+      const httpServer = createMockServer();
+      registerGraphTools(
+        httpServer,
+        {},
+        false,
+        void 0,
+        false,
+        void 0,
+        false,
+        [],
+        void 0,
+        true
+      );
+      expect(httpServer.tools.has("download-bytes-to-file")).toBe(false);
+      expect(httpServer.tools.has("download-bytes")).toBe(true);
+    });
+  });
   describe("get-download-url", () => {
     it("strips /content, fetches item metadata, and returns the pre-authed downloadUrl", async () => {
       mockEndpoints.length = 0;

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,6 +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 { access } from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
 import { TOOL_CATEGORIES } from "./tool-categories.js";
@@ -186,6 +187,141 @@ const UTILITY_TOOLS = [
       }
     }
   },
+  {
+    name: "download-bytes-to-file",
+    method: "GET",
+    path: "tool:download-bytes-to-file",
+    searchKeywords: "save to disk save to file write file to disk save attachment to disk save recording to disk write bytes to local file output path",
+    // Front-loaded on purpose: the discovery search index caps a tool's
+    // description at ~40 tokens, so the OneDrive/SharePoint guidance below
+    // sits past the cap. That keeps the hint for the reading LLM while letting
+    // get-download-url own the high-signal "drive"/"sharepoint" search terms.
+    description: "Write authenticated Microsoft Graph byte content to a local file on the server, returning { path, contentType, bytesWritten } instead of base64. The only out-of-band way to save mail attachments and meeting recordings, whose bytes are exposed solely through authenticated endpoints. Also handles profile photos and Teams hosted content. Writes to an absolute outputPath and never overwrites an existing file. stdio mode only: not available over HTTP. For OneDrive or SharePoint file content, get-download-url is preferred \u2014 it returns a pre-authenticated URL for fully out-of-band download without the server fetching the bytes.",
+    readOnlyHint: true,
+    openWorldHint: true,
+    stdioOnly: 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, use get-meeting-recording-content where available; Microsoft Graph returns authenticated recording bytes, not a pre-authenticated download URL.'
+        ),
+        outputPath: z.string().describe(
+          "Absolute path on the server's filesystem where the bytes are written, e.g. /Users/me/downloads/invoice.pdf. Must be absolute; relative paths are rejected. The parent directory must already exist, and an existing file is never overwritten (the call errors if outputPath already exists)."
+        )
+      };
+      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 outputPath = params.outputPath;
+      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. /me/photo/$value or /drives/{drive-id}/items/{driveItem-id}/content. Absolute URLs are not accepted; if you have an @microsoft.graph.downloadUrl, use the equivalent /content or /$value path instead (Graph 302-redirects to the same bytes).'
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (typeof outputPath !== "string" || outputPath.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: "outputPath is required and must be a non-empty string."
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      if (!path.isAbsolute(outputPath)) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: `outputPath must be an absolute path, e.g. /Users/me/downloads/file.ext. Received: ${outputPath}`
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      let fileExists = false;
+      try {
+        await access(outputPath);
+        fileExists = true;
+      } catch {
+      }
+      if (fileExists) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `file already exists at ${outputPath}` })
+            }
+          ],
+          isError: true
+        };
+      }
+      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 result = await graphClient.downloadToFile(target, outputPath, {
+          accessToken: accountAccessToken
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                path: outputPath,
+                contentType: result.contentType,
+                bytesWritten: result.contentLength
+              })
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+          isError: true
+        };
+      }
+    }
+  },
   {
     name: "get-download-url",
     method: "GET",
@@ -810,7 +946,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
     };
   }
 }
-function registerGraphTools(server, graphClient, readOnly = false, enabledToolsPattern, orgMode = false, authManager, multiAccount = false, accountNames = [], allowedScopesValue) {
+function registerGraphTools(server, graphClient, readOnly = false, enabledToolsPattern, orgMode = false, authManager, multiAccount = false, accountNames = [], allowedScopesValue, httpMode = false) {
   let enabledToolsRegex;
   if (enabledToolsPattern) {
     try {
@@ -983,6 +1119,7 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
   };
   for (const utility of UTILITY_TOOLS) {
     if (readOnly && !utility.readOnlyHint) continue;
+    if (httpMode && utility.stdioOnly) continue;
     if (enabledToolsRegex && !enabledToolsRegex.test(utility.name)) continue;
     try {
       registerUtilityToolWithMcp(server, utility, utilityCtx);
@@ -1098,7 +1235,7 @@ function scoreDiscoveryQuery(query, index) {
   ranked.sort((a, b) => b.score - a.score);
   return ranked;
 }
-function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode = false, authManager, multiAccount = false, accountNames = [], enabledTools, allowedScopesValue) {
+function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode = false, authManager, multiAccount = false, accountNames = [], enabledTools, allowedScopesValue, httpMode = false) {
   let enabledToolsRegex;
   if (enabledTools) {
     try {
@@ -1125,6 +1262,7 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
   }
   const utilityTools = UTILITY_TOOLS.filter((u) => {
     if (readOnly && !u.readOnlyHint) return false;
+    if (httpMode && u.stdioOnly) return false;
     if (enabledToolsRegex && !enabledToolsRegex.test(u.name)) return false;
     return true;
   });

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: 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."
+    "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. In stdio mode, download-bytes-to-file writes those same authenticated bytes straight to a local absolute path instead of returning base64 \u2014 the only out-of-band option for large mail attachments and meeting recordings, which get-download-url cannot handle. These 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/dist/server.js

@@ -88,7 +88,8 @@ class MicrosoftGraphServer {
         this.multiAccount,
         this.accountNames,
         this.options.enabledTools,
-        this.options.allowedScopes
+        this.options.allowedScopes,
+        Boolean(this.options.http)
       );
     } else {
       registerGraphTools(
@@ -100,7 +101,8 @@ class MicrosoftGraphServer {
         this.authManager,
         this.multiAccount,
         this.accountNames,
-        this.options.allowedScopes
+        this.options.allowedScopes,
+        Boolean(this.options.http)
       );
     }
     installToolSchemaRefNormalization(server);

package/dist/tool-categories.js

@@ -53,7 +53,7 @@ const PRESET_META = {
     requiresOrgMode: true
   }
 };
-const UNIVERSAL_UTILITY_TOOLS = ["download-bytes"];
+const UNIVERSAL_UTILITY_TOOLS = ["download-bytes", "download-bytes-to-file"];
 const SCOPED_UTILITY_TOOLS = {
   "get-download-url": ["files", "onedrive", "personal", "work", "search"],
   "parse-teams-url": ["teams", "work"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.132.1",
+  "version": "0.133.1",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",