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

package/README.md

@@ -27,6 +27,7 @@ This server supports multiple Microsoft cloud environments:
 - Comprehensive Microsoft 365 service integration
 - Read-only mode support for safe operations
 - Tool filtering for granular access control
+- [Tool presets](#tool-presets) and [dynamic discovery](#dynamic-tool-discovery) to shrink the tool surface and token usage
 
 ## Output Format: JSON vs TOON
 
@@ -94,7 +95,7 @@ MS365_MCP_OUTPUT_FORMAT=toon npx @softeria/ms-365-mcp-server
 
 ## Supported Services & Tools
 
-The server provides 200+ tools covering most of the Microsoft Graph API surface. Each tool maps 1-to-1 to a Graph API endpoint and is defined declaratively in [`src/endpoints.json`](src/endpoints.json).
+The server provides 300+ tools covering most of the Microsoft Graph API surface. Each tool maps 1-to-1 to a Graph API endpoint and is defined declaratively in [`src/endpoints.json`](src/endpoints.json).
 
 ### Personal Account Tools (Available by default)
 
@@ -509,7 +510,7 @@ Pinning is opt-in and local-MSAL only:
 
 ## Tool Presets
 
-To reduce initial connection overhead, use preset tool categories instead of loading all 90+ tools:
+To reduce initial connection overhead and token usage, use preset tool categories instead of loading the full tool set:
 
 ```bash
 npx @softeria/ms-365-mcp-server --preset mail
@@ -518,7 +519,7 @@ npx @softeria/ms-365-mcp-server --list-presets  # See all available presets
 
 Available presets: `mail`, `calendar`, `files`, `personal`, `work`, `excel`, `contacts`, `tasks`, `onenote`, `search`, `users`, `outlook`, `onedrive`, `teams`, `all`
 
-Each endpoint in `endpoints.json` declares which presets it belongs to via a `presets` array, so every preset is an exact tool-name allow-list that never over-matches across apps (e.g. `mail` does not include shared-mailbox tools; those are in `work`).
+Each endpoint in `endpoints.json` declares which presets it belongs to via a `presets` array, so every preset is an exact tool-name allow-list that never over-matches across apps (e.g. `mail` does not include shared-mailbox tools; those are in `work`). The universal binary reader `download-bytes` is included in every preset, so whatever an app returns (a file, an attachment, a photo, a recording) can always be fetched; `get-download-url` (a pre-authenticated URL for drive/SharePoint files) rides with the drive-backed presets. So a preset that can find a file can always read its bytes.
 
 The `outlook`, `onedrive` and `teams` presets are app-scoped: they expose exactly one Microsoft app. Use these for "expose exactly one app" deployments:
 
@@ -532,7 +533,7 @@ npx @softeria/ms-365-mcp-server --org-mode --preset teams
 
 ## Dynamic Tool Discovery
 
-Instead of loading all 90+ tools upfront, use dynamic discovery so the LLM finds and loads tools only when it needs them:
+Instead of loading every tool upfront, use dynamic discovery so the LLM finds and loads tools only when it needs them:
 
 ```bash
 npx @softeria/ms-365-mcp-server --discovery

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 { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
 vi.mock("../logger.js", () => ({
   default: {
     info: vi.fn(),
@@ -744,6 +747,145 @@ 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("writes decoded binary bytes to the output path and returns metadata", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        makeRequest: vi.fn().mockResolvedValue({
+          message: "OK!",
+          contentType: "image/jpeg",
+          encoding: "base64",
+          contentLength: 2,
+          contentBytes: "aGk="
+        })
+      };
+      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.makeRequest).toHaveBeenCalledTimes(1);
+      const [reqPath, options] = graphClient.makeRequest.mock.calls[0];
+      expect(reqPath).toBe("/me/photo/$value");
+      expect(options.rawResponse).toBe(true);
+      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 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.makeRequest).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 = { makeRequest: 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.makeRequest).not.toHaveBeenCalled();
+      expect(readFileSync(outputPath).toString("utf8")).toBe("original");
+    });
+    it("surfaces a Graph error and writes no file when makeRequest throws", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        makeRequest: 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/);
+      expect(existsSync(outputPath)).toBe(false);
+    });
+    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-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 { writeFile, access } from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
 import { TOOL_CATEGORIES } from "./tool-categories.js";
@@ -186,6 +187,161 @@ 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.makeRequest(target, {
+          accessToken: accountAccessToken,
+          rawResponse: true
+        });
+        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: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                path: outputPath,
+                contentType: result.contentType,
+                bytesWritten: buffer.byteLength
+              })
+            }
+          ]
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
+          isError: true
+        };
+      }
+    }
+  },
   {
     name: "get-download-url",
     method: "GET",
@@ -810,7 +966,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 +1139,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 +1255,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 +1282,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,13 +53,32 @@ const PRESET_META = {
     requiresOrgMode: true
   }
 };
+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"]
+};
+for (const [tool, presets] of Object.entries(SCOPED_UTILITY_TOOLS)) {
+  for (const preset of presets) {
+    if (!Object.prototype.hasOwnProperty.call(PRESET_META, preset)) {
+      throw new Error(
+        `SCOPED_UTILITY_TOOLS["${tool}"] references unknown preset "${preset}" (not in PRESET_META)`
+      );
+    }
+  }
+}
 function presetPattern(preset) {
-  const names = [
+  const endpointNames = [
     ...new Set(endpointEntries.filter((e) => e.presets?.includes(preset)).map((e) => e.toolName))
   ];
-  if (names.length === 0) {
+  if (endpointNames.length === 0) {
     throw new Error(`Preset "${preset}" matches no endpoints in endpoints.json`);
   }
+  const names = [
+    ...endpointNames,
+    ...UNIVERSAL_UTILITY_TOOLS,
+    ...Object.entries(SCOPED_UTILITY_TOOLS).filter(([, presets]) => presets.includes(preset)).map(([name]) => name)
+  ];
   return new RegExp(`^(?:${names.join("|")})$`);
 }
 const TOOL_CATEGORIES = {

package/package.json

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