@softeria/ms-365-mcp-server 0.163.0 → 0.165.0

package/README.md

@@ -695,6 +695,8 @@ When running as an MCP server, the following options can be used:
 --http-local-file-tools Register download-bytes-to-file over HTTP. Anyone who can reach the port
                   can write files as the server's user (without a valid token, only an empty
                   file that is removed again), so enable it only on a single-user machine.
+                  With MS365_MCP_UPLOAD_DIRS set it also registers upload-attachment-from-file,
+                  which reads files from those directories.
                   Refused unless --http binds a loopback host with no --public-url and no
                   --trust-proxy-auth
 --enable-auth-tools Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)
@@ -713,6 +715,8 @@ When running as an MCP server, the following options can be used:
 --preset <names>  Use preset tool categories (comma-separated). See "Tool Presets" section above
 --list-presets    List all available presets and exit
 --toon            (experimental) Enable TOON output format for 30-60% token reduction
+--blob-output     File download tools answer an MCP EmbeddedResource with the file instead of
+                  base64 JSON in a text block (see MS365_MCP_BLOB_OUTPUT below)
 --discovery       Dynamic tool discovery: loads tools on demand to reduce initial token usage (see "Dynamic Tool Discovery" above)
 --public-url <url> Public base URL for OAuth when behind a reverse proxy (see Open WebUI section and docs/deployment.md)
 ```
@@ -728,6 +732,8 @@ Environment variables:
 - `MS365_MCP_MAX_PAGES=<n>`: Maximum number of pages followed when a tool is called with `fetchAllPages: true` (positive integer, default `100`). Bounds memory and latency for large result sets.
 - `MS365_MCP_MAX_ITEMS=<n>`: Maximum number of items accumulated when `fetchAllPages: true` (positive integer, default `10000`). Pagination stops and the response is truncated once this many items are collected.
 - `MS365_MCP_ALLOW_PAGINATION=0|false|no`: Disable multi-page following entirely. When set, the `fetchAllPages` parameter is not advertised on tools, and any request that still passes it returns only the first page (default: pagination enabled).
+- `MS365_MCP_BLOB_OUTPUT=true|1`: File download tools (`download-bytes`, `get-mail-message-mime`, `get-shared-mailbox-message-mime`, `get-mail-attachment-content`, `get-shared-mailbox-attachment-content`) answer a short JSON text block (`name`, `contentType`, `size`) and an MCP `EmbeddedResource` with `BlobResourceContents` (`uri`, `mimeType`, `blob`) instead of base64 JSON in text. The `uri`'s last segment is the optional `fileName` argument. Default: off. Alternative to the --blob-output flag.
+- `MS365_MCP_BLOB_MAX_BYTES=<n>`: With blob output on, the largest file a download tool reads (positive integer, default `5242880`). The server stops reading past it and answers an error naming the limit.
 - `MS365_MCP_BODY_FORMAT=html`: Return email bodies as HTML instead of plain text (default: text)
 - `MS365_MCP_MESSAGE_SIGNOFF_PREFIX=<text>`: Signoff prepended to outgoing messages so recipients can tell they were agent-sent, e.g. `🤖`. Default: none. CLI equivalent: `--message-signoff-prefix <text>` (see Message Signoff below)
 - `MS365_MCP_MESSAGE_SIGNOFF_SUFFIX=<text>`: Signoff appended to outgoing messages. Default: none. CLI equivalent: `--message-signoff-suffix <text>`. `--no-message-signoff` disables both (see Message Signoff below)
@@ -735,7 +741,8 @@ Environment variables:
 - `MS365_MCP_TRUST_PROXY_HOPS=<n>`: Number of trusted reverse-proxy hops in HTTP mode (default `1`). Accurate per-IP rate limiting depends on this matching your deployment — set to the number of proxies in front of the server, `0` to use the raw socket peer IP, or a comma-separated subnet list
 - `MS365_MCP_ATTACHMENT_PORT=<port>`: Serve the attachment route on its own listener on this port (alternative to --attachment-port; requires `--enable-attachment-urls`)
 - `MS365_MCP_ATTACHMENT_HOST=<host>`: Interface the `MS365_MCP_ATTACHMENT_PORT` listener binds (alternative to --attachment-host; requires `--attachment-port`). Defaults to the host `--http` bound — which for a wildcard `--http` means both ports answer everywhere and the port split isolates nothing. See "Splitting the attachment listener"
-- `MS365_MCP_HTTP_LOCAL_FILE_TOOLS=true|1`: Register download-bytes-to-file over HTTP (alternative to --http-local-file-tools; same restrictions)
+- `MS365_MCP_HTTP_LOCAL_FILE_TOOLS=true|1`: Register download-bytes-to-file, and upload-attachment-from-file when `MS365_MCP_UPLOAD_DIRS` is set, over HTTP (alternative to --http-local-file-tools; same restrictions)
+- `MS365_MCP_UPLOAD_DIRS=<dirs>`: Directories `upload-attachment-from-file` may read from, as absolute paths separated like `PATH`. Unset (the default) leaves the tool unregistered. See "Attaching a local file in stdio mode"
 - `MS365_MCP_CLOUD_TYPE=global|china`: Microsoft cloud environment (alternative to --cloud flag)
 - `MS365_MCP_GRAPH_BASE_URL=<url>`: Send Graph API requests to this base URL instead of the cloud's `graph.microsoft.com` (e.g. `http://127.0.0.1:10255/tenant-a/graph` for an egress proxy that originates TLS itself). Absolute http(s) URL without query or fragment; a path prefix is kept, so requests go to `<url>/v1.0/...`. The login authority and the On-Behalf-Of token resource are unchanged. Two things bypass it: `get-download-url` returns Graph's pre-authenticated SharePoint URL, and the `302` from `/content` points straight at SharePoint, so whoever follows either connects to SharePoint directly; if you control egress, allow those SharePoint hosts or disable those tools. Not read from `.env`
 - `LOG_LEVEL`: Set logging level (default: 'info')
@@ -805,6 +812,26 @@ whatever the outcome, and the upload is attached as the identity that minted it,
 downloads are fetched. An upload ticket presented to `GET` (or a download ticket to `PUT`)
 is refused with the same 404 as any other bad ticket.
 
+### Attaching a local file in stdio mode
+
+In stdio mode the server and the files are on the same machine, so no URL is needed.
+`upload-attachment-from-file` takes the same `target` and an absolute `filePath`, reads the
+file from disk and attaches it, with the same 3 MB and 150 MB limits. It is the upload
+counterpart of `download-bytes-to-file`.
+
+The tool is off until you list the directories it may read from:
+
+```
+MS365_MCP_UPLOAD_DIRS=/Users/me/Documents/invitations:/Users/me/Scans
+```
+
+Entries are absolute paths, separated like `PATH` (`:` on macOS and Linux, `;` on Windows).
+A file outside them is refused, and symlinks are resolved first, so a link inside an allowed
+directory cannot point the read somewhere else. The variable is not read from `.env`.
+
+Over HTTP the tool is registered only with `--http-local-file-tools`, like
+`download-bytes-to-file`.
+
 ### Configuration
 
 ```

package/dist/__tests__/blob-output.test.js

@@ -0,0 +1,106 @@
+import http from "http";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import GraphClient from "../graph-client.js";
+import { fetchWithResilience, loadResilienceConfig } from "../lib/graph-resilience.js";
+vi.mock("../logger.js", () => ({
+  default: { info: vi.fn(), warn: vi.fn(), error: vi.fn(), debug: vi.fn() }
+}));
+vi.mock("../lib/graph-resilience.js", async (importOriginal) => ({
+  ...await importOriginal(),
+  fetchWithResilience: vi.fn()
+}));
+const fetchMock = vi.mocked(fetchWithResilience);
+const client = () => new GraphClient({ getToken: vi.fn().mockResolvedValue("token") }, {
+  clientId: "c",
+  tenantId: "t",
+  cloudType: "global"
+});
+const pdf = Buffer.from("%PDF-1.4 test bytes \0
\xFF", "latin1");
+const opts = { forceBinary: true, maxBytes: 1024, blobOutput: { fileName: "a b.pdf" } };
+describe("blob output", () => {
+  beforeEach(() => vi.clearAllMocks());
+  it("answers a text block and an EmbeddedResource with the exact bytes", async () => {
+    fetchMock.mockResolvedValue(
+      new Response(pdf, { status: 200, headers: { "content-type": "application/pdf" } })
+    );
+    const res = await client().graphRequest("/me/messages/m/attachments/a/$value", opts);
+    expect(JSON.parse(res.content[0].text)).toEqual({
+      name: "a b.pdf",
+      contentType: "application/pdf",
+      size: pdf.length
+    });
+    const item = res.content[1];
+    expect(item.type).toBe("resource");
+    expect(item.resource.uri).toBe("file:///a%20b.pdf");
+    expect(item.resource.mimeType).toBe("application/pdf");
+    expect(Buffer.from(item.resource.blob, "base64").equals(pdf)).toBe(true);
+  });
+  it("keeps the old base64 JSON when blob output is not asked for", async () => {
+    fetchMock.mockResolvedValue(
+      new Response(pdf, { headers: { "content-type": "application/pdf" } })
+    );
+    const res = await client().graphRequest("/x/$value", { forceBinary: true });
+    expect(res.content).toHaveLength(1);
+    expect(JSON.parse(res.content[0].text).contentBytes).toBe(pdf.toString("base64"));
+  });
+  it("refuses a body over the cap by Content-Length without reading it", async () => {
+    fetchMock.mockResolvedValue(
+      new Response(Buffer.alloc(2048), { headers: { "content-length": "2048" } })
+    );
+    const res = await client().graphRequest("/x/$value", opts);
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain("download limit of 1024 bytes");
+  });
+  it("stops reading a body over the cap when no length is declared", async () => {
+    let pulled = 0;
+    const body = new ReadableStream({
+      pull(controller) {
+        pulled += 512;
+        controller.enqueue(new Uint8Array(512));
+        if (pulled >= 1024 * 1024) controller.close();
+      }
+    });
+    fetchMock.mockResolvedValue(new Response(body));
+    const res = await client().graphRequest("/x/$value", opts);
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toContain("download limit of 1024 bytes");
+    expect(pulled).toBeLessThan(16 * 1024);
+  });
+  it("accepts a body exactly at the cap", async () => {
+    fetchMock.mockResolvedValue(new Response(Buffer.alloc(1024)));
+    const res = await client().graphRequest("/x/$value", opts);
+    expect(res.isError).toBeUndefined();
+    expect(JSON.parse(res.content[0].text).size).toBe(1024);
+  });
+});
+describe("redirects that leave the Graph origin", () => {
+  const servers = [];
+  const listen = (h) => new Promise((resolve) => {
+    const s = http.createServer(h).listen(0, "127.0.0.1", () => {
+      servers.push(s);
+      resolve(`http://127.0.0.1:${s.address().port}`);
+    });
+  });
+  afterEach(() => servers.splice(0).forEach((s) => s.close()));
+  it("arrive without the Authorization header", async () => {
+    const real = await vi.importActual(
+      "../lib/graph-resilience.js"
+    );
+    let seen = "unset";
+    const other = await listen((req, res2) => {
+      seen = req.headers.authorization;
+      res2.end("bytes");
+    });
+    const graph = await listen((_req, res2) => {
+      res2.writeHead(302, { location: `${other}/file` }).end();
+    });
+    const res = await real.fetchWithResilience(
+      `${graph}/v1.0/x`,
+      { headers: { Authorization: "Bearer secret" } },
+      loadResilienceConfig(),
+      real.getSharedBreaker()
+    );
+    expect(await res.text()).toBe("bytes");
+    expect(seen).toBeUndefined();
+  });
+});

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

@@ -1,4 +1,12 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync
+} from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -2248,6 +2256,28 @@ describe("graph-tools", () => {
       expect(options.accessToken).toBeUndefined();
       expect(options.forceBinary).toBe(true);
       expect(options.rawResponse).toBe(true);
+      expect(options.blobOutput).toBeUndefined();
+      expect(options.maxBytes).toBeUndefined();
+    });
+    it("asks for a capped blob resource when blob output is on", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      process.env.MS365_MCP_BLOB_OUTPUT = "true";
+      process.env.MS365_MCP_BLOB_MAX_BYTES = "1234";
+      try {
+        const graphClient = { graphRequest: vi.fn().mockResolvedValue({ content: [] }) };
+        const server = createMockServer();
+        const { registerGraphTools } = await loadModule();
+        registerGraphTools(server, graphClient);
+        await server.tools.get("download-bytes").handler({ target: "/me/messages/m1/attachments/a1/$value", fileName: "drawing.pdf" });
+        const [, options] = graphClient.graphRequest.mock.calls[0];
+        expect(options.forceBinary).toBe(true);
+        expect(options.maxBytes).toBe(1234);
+        expect(options.blobOutput).toEqual({ fileName: "drawing.pdf" });
+      } finally {
+        delete process.env.MS365_MCP_BLOB_OUTPUT;
+        delete process.env.MS365_MCP_BLOB_MAX_BYTES;
+      }
     });
     it("rejects absolute URLs (Graph paths only)", async () => {
       mockEndpoints.length = 0;
@@ -2423,6 +2453,148 @@ describe("graph-tools", () => {
       expect(httpServer.tools.has("download-bytes")).toBe(true);
     });
   });
+  describe("upload-attachment-from-file", () => {
+    const TOOL = "upload-attachment-from-file";
+    const TARGET = "/me/events/evt1/attachments";
+    let tmpDir;
+    let allowed;
+    beforeEach(() => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      tmpDir = realpathSync(mkdtempSync(join(tmpdir(), "uaff-")));
+      allowed = join(tmpDir, "allowed");
+      mkdirSync(allowed);
+      process.env.MS365_MCP_UPLOAD_DIRS = allowed;
+    });
+    afterEach(() => {
+      delete process.env.MS365_MCP_UPLOAD_DIRS;
+      vi.unstubAllGlobals();
+      rmSync(tmpDir, { recursive: true, force: true });
+    });
+    async function register(graphClient, options) {
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient, options);
+      return server;
+    }
+    it("is not registered unless MS365_MCP_UPLOAD_DIRS is set", async () => {
+      delete process.env.MS365_MCP_UPLOAD_DIRS;
+      const server = await register({});
+      expect(server.tools.has(TOOL)).toBe(false);
+      expect(server.tools.has("download-bytes-to-file")).toBe(true);
+    });
+    it("is not registered in read-only mode or over HTTP", async () => {
+      expect((await register({}, { readOnly: true })).tools.has(TOOL)).toBe(false);
+      expect((await register({}, { httpMode: true })).tools.has(TOOL)).toBe(false);
+    });
+    it("attaches a small file inline, named after the file", async () => {
+      const bytes = Buffer.from([37, 80, 68, 70, 0, 255]);
+      writeFileSync(join(allowed, "invitation.pdf"), bytes);
+      const graphClient = { makeRequest: vi.fn().mockResolvedValue({ id: "att1" }) };
+      const server = await register(graphClient);
+      const result = await server.tools.get(TOOL).handler({ target: TARGET, filePath: join(allowed, "invitation.pdf") });
+      expect(result.isError).toBeUndefined();
+      expect(JSON.parse(result.content[0].text)).toEqual({
+        name: "invitation.pdf",
+        size: bytes.length,
+        id: "att1"
+      });
+      expect(graphClient.makeRequest).toHaveBeenCalledTimes(1);
+      const [reqPath, options] = graphClient.makeRequest.mock.calls[0];
+      expect(reqPath).toBe(TARGET);
+      expect(options.method).toBe("POST");
+      expect(JSON.parse(options.body)).toEqual({
+        "@odata.type": "#microsoft.graph.fileAttachment",
+        name: "invitation.pdf",
+        contentType: "application/octet-stream",
+        contentBytes: bytes.toString("base64")
+      });
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({ event: "tool.call", tool: TOOL, status: "success" })
+      );
+    });
+    it("uses the given name and content type", async () => {
+      writeFileSync(join(allowed, "scan-0042.bin"), "x");
+      const graphClient = { makeRequest: vi.fn().mockResolvedValue({ id: "att1" }) };
+      const server = await register(graphClient);
+      await server.tools.get(TOOL).handler({
+        target: "/me/messages/msg1/attachments",
+        filePath: join(allowed, "scan-0042.bin"),
+        name: "flyer.pdf",
+        contentType: "application/pdf"
+      });
+      const body = JSON.parse(graphClient.makeRequest.mock.calls[0][1].body);
+      expect(body.name).toBe("flyer.pdf");
+      expect(body.contentType).toBe("application/pdf");
+    });
+    it("sends a file of 3 MB or more through an upload session in chunks", async () => {
+      const size = 4 * 1024 * 1024 + 123;
+      const bytes = Buffer.alloc(size, 7);
+      writeFileSync(join(allowed, "big.bin"), bytes);
+      const graphClient = {
+        makeRequest: vi.fn().mockResolvedValue({ uploadUrl: "https://upload.example/session" })
+      };
+      const ranges = [];
+      let uploaded = 0;
+      vi.stubGlobal(
+        "fetch",
+        vi.fn(
+          async (_url, init) => {
+            ranges.push(init.headers["Content-Range"]);
+            uploaded += init.body.byteLength;
+            return new Response(null, { status: 202 });
+          }
+        )
+      );
+      const server = await register(graphClient);
+      const result = await server.tools.get(TOOL).handler({ target: TARGET, filePath: join(allowed, "big.bin") });
+      expect(result.isError).toBeUndefined();
+      expect(JSON.parse(result.content[0].text)).toEqual({ name: "big.bin", size });
+      const [reqPath, options] = graphClient.makeRequest.mock.calls[0];
+      expect(reqPath).toBe(`${TARGET}/createUploadSession`);
+      expect(JSON.parse(options.body).AttachmentItem).toMatchObject({ name: "big.bin", size });
+      const chunk = 320 * 1024 * 12;
+      expect(ranges).toEqual([
+        `bytes 0-${chunk - 1}/${size}`,
+        `bytes ${chunk}-${size - 1}/${size}`
+      ]);
+      expect(uploaded).toBe(size);
+    });
+    it("refuses a file outside the allowed directories, also through a symlink", async () => {
+      writeFileSync(join(tmpDir, "secret.txt"), "secret");
+      symlinkSync(join(tmpDir, "secret.txt"), join(allowed, "link.txt"));
+      const graphClient = { makeRequest: vi.fn() };
+      const server = await register(graphClient);
+      for (const filePath of [join(tmpDir, "secret.txt"), join(allowed, "link.txt")]) {
+        const result = await server.tools.get(TOOL).handler({ target: TARGET, filePath });
+        expect(result.isError).toBe(true);
+        expect(JSON.parse(result.content[0].text).error).toMatch(/does not exist or is outside/);
+      }
+      expect(graphClient.makeRequest).not.toHaveBeenCalled();
+    });
+    it("refuses an empty file and a target that is not an attachments collection", async () => {
+      writeFileSync(join(allowed, "empty.txt"), "");
+      writeFileSync(join(allowed, "a.txt"), "a");
+      const graphClient = { makeRequest: vi.fn() };
+      const server = await register(graphClient);
+      const call = async (args) => JSON.parse((await server.tools.get(TOOL).handler(args)).content[0].text).error;
+      expect(await call({ target: TARGET, filePath: join(allowed, "empty.txt") })).toMatch(
+        /file is empty/
+      );
+      expect(
+        await call({ target: "/me/drive/root:/a.txt:/content", filePath: join(allowed, "a.txt") })
+      ).toMatch(/attachments collection/);
+      expect(graphClient.makeRequest).not.toHaveBeenCalled();
+    });
+    it("answers a Graph failure as a tool error", async () => {
+      writeFileSync(join(allowed, "a.txt"), "a");
+      const graphClient = { makeRequest: vi.fn().mockRejectedValue(new Error("Graph said no")) };
+      const server = await register(graphClient);
+      const result = await server.tools.get(TOOL).handler({ target: TARGET, filePath: join(allowed, "a.txt") });
+      expect(result.isError).toBe(true);
+      expect(JSON.parse(result.content[0].text).error).toBe("Graph said no");
+    });
+  });
   describe("get-download-url", () => {
     it("strips /content, fetches item metadata, and returns the pre-authed downloadUrl", async () => {
       mockEndpoints.length = 0;

package/dist/attachment-route.js

@@ -5,6 +5,7 @@ import {
   isPlainGraphPath,
   TICKET_PARAM
 } from "./lib/attachment-tickets.js";
+import { MAX_UPLOAD_BYTES, uploadAttachment } from "./lib/attachment-upload.js";
 const NOT_FOUND_BODY = "Not found";
 function forceAttachment(header) {
   if (!header) return "attachment";
@@ -104,26 +105,6 @@ function createAttachmentHandler(deps) {
     }
   };
 }
-const MAX_UPLOAD_BYTES = 150 * 1024 * 1024;
-const INLINE_UPLOAD_LIMIT = 3 * 1024 * 1024;
-const UPLOAD_CHUNK_BYTES = 320 * 1024 * 12;
-async function putChunk(uploadUrl, chunk, start, total) {
-  const end = start + chunk.length - 1;
-  const response = await fetch(uploadUrl, {
-    method: "PUT",
-    headers: {
-      "Content-Type": "application/octet-stream",
-      "Content-Length": String(chunk.length),
-      "Content-Range": `bytes ${start}-${end}/${total}`
-    },
-    // A standalone ArrayBuffer: fetch's body typing wants a BufferSource, and a
-    // Buffer view over a pooled slab is neither the right type nor the right bytes.
-    body: chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength)
-  });
-  if (![200, 201, 202].includes(response.status)) {
-    throw new Error(`Upload session chunk ${start}-${end} answered HTTP ${response.status}`);
-  }
-}
 function createAttachmentUploadHandler(deps) {
   return async (req, res) => {
     if (req.method !== "PUT") {
@@ -177,64 +158,18 @@ function createAttachmentUploadHandler(deps) {
     res.setHeader("cache-control", "no-store");
     res.setHeader("x-content-type-options", "nosniff");
     try {
-      if (declared < INLINE_UPLOAD_LIMIT) {
-        const chunks = [];
-        let received = 0;
-        for await (const chunk of req) {
-          received += chunk.length;
-          if (received > declared) throw new Error("Body exceeds Content-Length");
-          chunks.push(chunk);
-        }
-        if (received !== declared) throw new Error("Body shorter than Content-Length");
-        const created = await graphClient.makeRequest(ticket.target, {
-          method: "POST",
-          accessToken,
-          body: JSON.stringify({
-            "@odata.type": "#microsoft.graph.fileAttachment",
-            name: ticket.name,
-            contentType: ticket.contentType,
-            contentBytes: Buffer.concat(chunks).toString("base64")
-          })
-        });
-        res.status(201).json({ ok: true, name: ticket.name, size: declared, id: created?.id });
-        return;
-      }
-      const session = await graphClient.makeRequest(`${ticket.target}/createUploadSession`, {
-        method: "POST",
-        accessToken,
-        body: JSON.stringify({
-          AttachmentItem: {
-            attachmentType: "file",
-            name: ticket.name,
-            size: declared,
-            contentType: ticket.contentType
-          }
-        })
-      });
-      if (!session?.uploadUrl) throw new Error("Upload session returned no uploadUrl");
-      let pending = [];
-      let pendingBytes = 0;
-      let offset = 0;
-      for await (const piece of req) {
-        pending.push(piece);
-        pendingBytes += piece.length;
-        if (offset + pendingBytes > declared) throw new Error("Body exceeds Content-Length");
-        while (pendingBytes >= UPLOAD_CHUNK_BYTES) {
-          const joined = Buffer.concat(pending);
-          const chunk = joined.subarray(0, UPLOAD_CHUNK_BYTES);
-          await putChunk(session.uploadUrl, chunk, offset, declared);
-          offset += chunk.length;
-          const rest = joined.subarray(UPLOAD_CHUNK_BYTES);
-          pending = rest.length ? [Buffer.from(rest)] : [];
-          pendingBytes = rest.length;
-        }
-      }
-      if (pendingBytes > 0) {
-        await putChunk(session.uploadUrl, Buffer.concat(pending), offset, declared);
-        offset += pendingBytes;
-      }
-      if (offset !== declared) throw new Error("Body shorter than Content-Length");
-      res.status(201).json({ ok: true, name: ticket.name, size: declared });
+      const created = await uploadAttachment(
+        graphClient,
+        {
+          target: ticket.target,
+          name: ticket.name,
+          contentType: ticket.contentType,
+          size: declared,
+          accessToken
+        },
+        req
+      );
+      res.status(201).json({ ok: true, name: ticket.name, size: declared, id: created.id });
     } catch (error) {
       logger.error(`Attachment upload failed for ${ticket.target}: ${error.message}`);
       if (!res.headersSent) res.status(502).type("text/plain").send("Upstream upload failed");
@@ -242,7 +177,6 @@ function createAttachmentUploadHandler(deps) {
   };
 }
 export {
-  MAX_UPLOAD_BYTES,
   createAttachmentHandler,
   createAttachmentUploadHandler,
   forceAttachment

package/dist/cli.js

@@ -3,6 +3,7 @@ import { readFileSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { assertSignoffMarkersVisible } from "./lib/message-signoff.js";
+import { assertUploadDirsAbsolute } from "./lib/upload-dirs.js";
 import { getCombinedPresetPattern, listPresets, presetRequiresOrgMode } from "./tool-categories.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const packageJsonPath = path.join(__dirname, "..", "package.json");
@@ -74,7 +75,10 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
   "In HTTP mode, skip the built-in Bearer-token check on /mcp and ignore any forwarded Authorization header. All callers share the locally cached MSAL identity (same path stdio mode uses). Use only when an upstream reverse proxy has already authenticated the caller."
 ).option(
   "--http-local-file-tools",
-  "In HTTP mode, also register download-bytes-to-file, which writes files on the server as the server's user. Anyone who can reach the port can use it, so enable only on a single-user machine. Refused unless --http binds a loopback host with no --public-url and no --trust-proxy-auth."
+  "In HTTP mode, also register the local file tools: download-bytes-to-file, which writes files on the server as the server's user, and upload-attachment-from-file, which reads files from the MS365_MCP_UPLOAD_DIRS directories when that is set. Anyone who can reach the port can use them, so enable only on a single-user machine. Refused unless --http binds a loopback host with no --public-url and no --trust-proxy-auth."
+).option(
+  "--blob-output",
+  "File download tools (get-mail-message-mime, get-shared-mailbox-message-mime, get-mail-attachment-content, get-shared-mailbox-attachment-content) answer an MCP EmbeddedResource with the file instead of base64 JSON in a text block. Off by default."
 ).option(
   "--allow-unauthenticated-discovery",
   "In HTTP mode, allow MCP discovery requests (initialize, tools/list, prompts/list, resources/list, ping) without a bearer token, so a gateway can enumerate the tool catalog before any user has authenticated. Non-discovery requests (e.g. tools/call) still require a token. Off by default."
@@ -97,7 +101,11 @@ function parseArgs() {
     process.env.MS365_MCP_MESSAGE_SIGNOFF_SUFFIX = "";
     process.env.MS365_MCP_MESSAGE_SIGNOFF_PREFIX = "";
   }
+  if (options.blobOutput) {
+    process.env.MS365_MCP_BLOB_OUTPUT = "true";
+  }
   assertSignoffMarkersVisible();
+  assertUploadDirsAbsolute();
   if (options.listPresets) {
     const presets = listPresets();
     console.log(JSON.stringify({ presets }, null, 2));

package/dist/endpoints.json

@@ -949,8 +949,40 @@
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.Read"],
     "acceptType": "text/plain",
+    "blobOutput": true,
     "llmTip": "Download an email message as raw RFC 5322 MIME content (.eml format). Use this when archiving an email to disk preserving all original headers, body, and inline-encoded attachments. Returns the MIME stream as text. Find the message id with list-mail-messages first."
   },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/$value",
+    "method": "get",
+    "toolName": "get-shared-mailbox-message-mime",
+    "descriptionOverride": "Download the raw MIME source (RFC 5322 .eml content) of a message in another user's mailbox or a shared mailbox, by message ID. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.Read.Shared"],
+    "acceptType": "text/plain",
+    "blobOutput": true,
+    "llmTip": "Download a message of a shared mailbox as an .eml. Find the message id with list-shared-mailbox-messages first. With the server's blob output on, the bytes come back as a file resource; pass fileName to name it."
+  },
+  {
+    "pathPattern": "/me/messages/{message-id}/attachments/{attachment-id}/$value",
+    "method": "get",
+    "toolName": "get-mail-attachment-content",
+    "descriptionOverride": "Download the raw bytes of a file attachment of an Outlook message in the signed-in user's mailbox, by message ID and attachment ID.",
+    "presets": ["mail", "outlook", "personal"],
+    "scopes": ["Mail.Read"],
+    "blobOutput": true,
+    "llmTip": "Find the attachment id with list-mail-attachments first. With the server's blob output on, the bytes come back as a file resource; pass fileName (the attachment's name) to name it. Files over the server's download limit are refused with an error naming the limit."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/attachments/{attachment-id}/$value",
+    "method": "get",
+    "toolName": "get-shared-mailbox-attachment-content",
+    "descriptionOverride": "Download the raw bytes of a file attachment of a message in another user's mailbox or a shared mailbox, by message ID and attachment ID. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.Read.Shared"],
+    "blobOutput": true,
+    "llmTip": "Find the attachment id with list-shared-mailbox-attachments first. With the server's blob output on, the bytes come back as a file resource; pass fileName (the attachment's name) to name it. Files over the server's download limit are refused with an error naming the limit."
+  },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range(address='{address}')",
     "method": "patch",

package/dist/generated/client.js

@@ -10618,6 +10618,26 @@ resource.`,
     ],
     response: z.void()
   },
+  {
+    method: "get",
+    path: "/me/messages/:messageId/attachments/:attachmentId/$value",
+    alias: "get-mail-attachment-content",
+    description: `Get mail attachment content.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "messageId",
+        type: "Path",
+        schema: z.string().describe("Path parameter: message-id")
+      },
+      {
+        name: "attachmentId",
+        type: "Path",
+        schema: z.string().describe("Path parameter: attachment-id")
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "post",
     path: "/me/messages/:messageId/attachments/createUploadSession",
@@ -15571,6 +15591,14 @@ Only the policyViolation property of a chatMessage can be updated in application
     ],
     response: z.void()
   },
+  {
+    method: "get",
+    path: "/users/:userId/messages/:messageId/$value",
+    alias: "get-shared-mailbox-message-mime",
+    description: `The unique identifier for an entity. Read-only.`,
+    requestFormat: "json",
+    response: z.void()
+  },
   {
     method: "get",
     path: "/users/:userId/messages/:messageId/attachments",
@@ -15652,6 +15680,31 @@ Only the policyViolation property of a chatMessage can be updated in application
     ],
     response: z.void()
   },
+  {
+    method: "get",
+    path: "/users/:userId/messages/:messageId/attachments/:attachmentId/$value",
+    alias: "get-shared-mailbox-attachment-content",
+    description: `Get shared mailbox attachment content.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "userId",
+        type: "Path",
+        schema: z.string().describe("Path parameter: user-id")
+      },
+      {
+        name: "messageId",
+        type: "Path",
+        schema: z.string().describe("Path parameter: message-id")
+      },
+      {
+        name: "attachmentId",
+        type: "Path",
+        schema: z.string().describe("Path parameter: attachment-id")
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "post",
     path: "/users/:userId/messages/:messageId/createForward",

package/dist/graph-client.js

@@ -97,6 +97,58 @@ function extractBatchMetadata(data) {
     ...Object.keys(errorCodeCounts).length > 0 ? { graph_batch_error_code_counts: errorCodeCounts } : {}
   };
 }
+const DEFAULT_BLOB_MAX_BYTES = 5 * 1024 * 1024;
+function isBlobOutputEnabled() {
+  return /^(1|true)$/i.test(process.env.MS365_MCP_BLOB_OUTPUT ?? "");
+}
+function getBlobMaxBytes() {
+  const n = Number(process.env.MS365_MCP_BLOB_MAX_BYTES);
+  return Number.isInteger(n) && n > 0 ? n : DEFAULT_BLOB_MAX_BYTES;
+}
+async function readBody(response, maxBytes) {
+  if (maxBytes === void 0) return Buffer.from(await response.arrayBuffer());
+  const tooLarge = () => new Error(`The file is larger than the download limit of ${maxBytes} bytes.`);
+  const declared = Number(response.headers?.get?.("content-length"));
+  if (declared > maxBytes) {
+    await response.body?.cancel();
+    throw tooLarge();
+  }
+  const chunks = [];
+  let total = 0;
+  const reader = response.body?.getReader();
+  while (reader) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > maxBytes) {
+      await reader.cancel();
+      throw tooLarge();
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks);
+}
+function toBlobResponse(data, blob) {
+  const d = data;
+  if (!d || typeof d.contentBytes !== "string") return void 0;
+  const mimeType = d.contentType?.split(";")[0].trim() || "application/octet-stream";
+  const name = blob.fileName?.split("/").join("_").split(String.fromCharCode(92)).join("_") || "download";
+  const size = Buffer.byteLength(d.contentBytes, "base64");
+  return {
+    content: [
+      { type: "text", text: JSON.stringify({ name, contentType: mimeType, size }) },
+      // shortcut: ContentItem is text-only; this is the one non-text item, passed through as is.
+      {
+        type: "resource",
+        resource: {
+          uri: `file:///${encodeURIComponent(name)}`,
+          mimeType,
+          blob: d.contentBytes
+        }
+      }
+    ]
+  };
+}
 class GraphClient {
   constructor(authManager, secrets, outputFormat = "json") {
     this.outputFormat = "json";
@@ -125,7 +177,7 @@ class GraphClient {
       const isBinaryResponse = options.forceBinary === true || isBinaryContentType(contentTypeHeader);
       let metadata = { http_status: response.status };
       let result;
-      const buffer = Buffer.from(await response.arrayBuffer());
+      const buffer = await readBody(response, options.maxBytes);
       metadata = { ...metadata, response_bytes: buffer.byteLength };
       let text;
       if (!isBinaryResponse) {
@@ -343,8 +395,9 @@ class GraphClient {
       );
       const { data, metadata } = await this.makeRequestWithMetadata(endpoint, options);
       const outputFormat = options.forceJsonOutput ? "json" : this.outputFormat;
+      const blobResponse = options.blobOutput && !options.excludeResponse ? toBlobResponse(data, options.blobOutput) : void 0;
       return this.withResponseMetadata(
-        this.formatJsonResponse(data, options.rawResponse, options.excludeResponse, outputFormat),
+        blobResponse ?? this.formatJsonResponse(data, options.rawResponse, options.excludeResponse, outputFormat),
         metadata
       );
     } catch (error) {
@@ -446,7 +499,10 @@ class GraphClient {
 }
 var graph_client_default = GraphClient;
 export {
+  DEFAULT_BLOB_MAX_BYTES,
   GraphApiError,
   graph_client_default as default,
-  isBinaryContentType
+  getBlobMaxBytes,
+  isBinaryContentType,
+  isBlobOutputEnabled
 };

package/dist/graph-tools.js

@@ -14,8 +14,10 @@ import {
 } from "./auth.js";
 import { api as betaApi } from "./generated/client-beta.js";
 import { api } from "./generated/client.js";
+import { getBlobMaxBytes, isBlobOutputEnabled } from "./graph-client.js";
 import { getAttachmentMinting } from "./lib/attachment-minting.js";
-import { MAX_UPLOAD_BYTES } from "./attachment-route.js";
+import { MAX_UPLOAD_BYTES, uploadAttachment } from "./lib/attachment-upload.js";
+import { getUploadDirs, openUploadFile } from "./lib/upload-dirs.js";
 import {
   buildAttachmentUrl,
   isPlainGraphPath,
@@ -497,6 +499,7 @@ function collectDeniedToolPolicies(options) {
   for (const utility of UTILITY_TOOLS) {
     if (options.readOnly && !utility.readOnlyHint) continue;
     if (options.httpMode && utility.stdioOnly) continue;
+    if (utility.enabled && !utility.enabled()) continue;
     if (options.enabledToolsRegex && !options.enabledToolsRegex.test(utility.name)) {
       deniedTools.set(utility.name, {
         toolName: utility.name,
@@ -548,9 +551,16 @@ async function checkAccountParamInBearerMode(accountParam, authManager) {
 }
 const UPLOAD_TARGET = /^(\/me|\/users\/[^/]+)\/(messages|events)\/[^/]+\/attachments$/;
 const UPLOAD_CONTENT_TYPE = /^[\w.+-]+\/[\w.+-]+$/;
+const UPLOAD_TARGET_ERROR = "target must be the attachments collection of a draft message or an event: /me/messages/{message-id}/attachments or /me/events/{event-id}/attachments.";
 function uploadError(message) {
   return { content: [{ type: "text", text: JSON.stringify({ error: message }) }], isError: true };
 }
+function cleanAttachmentName(name) {
+  return Array.from(name.trim()).filter((char) => {
+    const code = char.charCodeAt(0);
+    return code > 31 && code !== 127;
+  }).join("").slice(0, 255);
+}
 async function mintUploadUrl(target, name, contentType, accountParam, authManager) {
   const minting = getAttachmentMinting();
   if (!minting) {
@@ -560,14 +570,9 @@ async function mintUploadUrl(target, name, contentType, accountParam, authManage
     );
   }
   if (!UPLOAD_TARGET.test(target) || !isPlainGraphPath(target)) {
-    return uploadError(
-      "target must be the attachments collection of a draft message or an event: /me/messages/{message-id}/attachments or /me/events/{event-id}/attachments."
-    );
+    return uploadError(UPLOAD_TARGET_ERROR);
   }
-  const cleanName = Array.from(name.trim()).filter((char) => {
-    const code = char.charCodeAt(0);
-    return code > 31 && code !== 127;
-  }).join("").slice(0, 255);
+  const cleanName = cleanAttachmentName(name);
   if (!cleanName) return uploadError("name is required.");
   if (!UPLOAD_CONTENT_TYPE.test(contentType)) {
     return uploadError("contentType must be a MIME type such as application/pdf.");
@@ -714,6 +719,111 @@ const UTILITY_TOOLS = [
       );
     }
   },
+  {
+    name: "upload-attachment-from-file",
+    method: "POST",
+    path: "tool:upload-attachment-from-file",
+    searchKeywords: "attach local file upload file from disk attach file path draft email attach file event attachment without base64",
+    description: "Attach a local file on the server to a draft message or an event, read straight from disk instead of passing as base64 through the agent context. target is the attachments collection, e.g. /me/messages/{message-id}/attachments or /me/events/{event-id}/attachments. Files up to 150 MB; the server picks an inline upload or an upload session by size. filePath must be absolute and inside a directory listed in MS365_MCP_UPLOAD_DIRS. stdio mode, or HTTP with --http-local-file-tools.",
+    readOnlyHint: false,
+    openWorldHint: true,
+    stdioOnly: true,
+    enabled: () => getUploadDirs().length > 0,
+    buildSchema: (ctx) => {
+      const schema = {
+        target: z.string().describe(
+          "Attachments collection of a draft message or an event, e.g. /me/messages/{message-id}/attachments or /me/events/{event-id}/attachments."
+        ),
+        filePath: z.string().describe(
+          "Absolute path of the file on the server's filesystem, e.g. /Users/me/documents/invitation.pdf. Must be inside a directory the server allows uploads from."
+        ),
+        name: z.string().optional().describe(
+          "Attachment file name as the recipient will see it. Defaults to the file name of filePath."
+        ),
+        contentType: z.string().optional().describe(
+          "MIME type of the file, e.g. application/pdf. Defaults to application/octet-stream."
+        )
+      };
+      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 filePath = params.filePath;
+      const accountParam = params.account;
+      if (typeof target !== "string" || target.length === 0) {
+        return uploadError("target is required and must be a non-empty string.");
+      }
+      if (typeof filePath !== "string" || filePath.length === 0) {
+        return uploadError("filePath is required and must be a non-empty string.");
+      }
+      if (!UPLOAD_TARGET.test(target) || !isPlainGraphPath(target)) {
+        return uploadError(UPLOAD_TARGET_ERROR);
+      }
+      const contentType = typeof params.contentType === "string" && params.contentType.length > 0 ? params.contentType : "application/octet-stream";
+      if (!UPLOAD_CONTENT_TYPE.test(contentType)) {
+        return uploadError("contentType must be a MIME type such as application/pdf.");
+      }
+      const name = cleanAttachmentName(
+        typeof params.name === "string" && params.name.trim().length > 0 ? params.name : path.basename(filePath)
+      );
+      if (!name) return uploadError("name is required.");
+      let file;
+      try {
+        file = await openUploadFile(filePath, getUploadDirs());
+      } catch (error) {
+        return uploadError(error.message);
+      }
+      try {
+        if (file.size === 0) return uploadError("The file is empty.");
+        if (file.size > MAX_UPLOAD_BYTES) {
+          return uploadError(
+            `The file is ${file.size} bytes; the largest attachment is ${MAX_UPLOAD_BYTES} bytes.`
+          );
+        }
+        const accountModeError = await checkAccountParamInBearerMode(accountParam, authManager);
+        if (accountModeError) return uploadError(accountModeError);
+        let accountAccessToken;
+        if (authManager && !authManager.isOAuthModeEnabled() && !getRequestTokens()) {
+          accountAccessToken = await authManager.getTokenForAccount(accountParam);
+        }
+        const created = await uploadAttachment(
+          graphClient,
+          { target, name, contentType, size: file.size, accessToken: accountAccessToken },
+          // end pins the read to the size that was declared, should the file grow meanwhile
+          file.handle.createReadStream({
+            autoClose: false,
+            highWaterMark: 1024 * 1024,
+            end: file.size - 1
+          })
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                name,
+                size: file.size,
+                ...created.id ? { id: created.id } : {}
+              })
+            }
+          ]
+        };
+      } catch (error) {
+        const metadata = thrownErrorAuditFields(error);
+        return {
+          ...uploadError(error.message),
+          ...Object.keys(metadata).length > 0 ? { _meta: metadata } : {}
+        };
+      } finally {
+        await file.handle.close();
+      }
+    }
+  },
   {
     name: "parse-teams-url",
     method: "POST",
@@ -747,14 +857,17 @@ 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 }. 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.',
+    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. With the server's blob output on, the bytes come back as a file resource instead (capped by the server's download limit); pass fileName to name it.`,
     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, use get-meeting-recording-content where available; Microsoft Graph returns authenticated recording bytes, not a pre-authenticated download URL.'
-        )
+        ),
+        fileName: z.string().describe(
+          "Name of the file, used as the last segment of the returned resource URI when the server runs with blob output. Optional."
+        ).optional()
       };
       if (ctx.multiAccount) {
         schema["account"] = z.string().optional().describe(
@@ -806,10 +919,17 @@ const UTILITY_TOOLS = [
         if (authManager && !authManager.isOAuthModeEnabled() && !getRequestTokens()) {
           accountAccessToken = await authManager.getTokenForAccount(accountParam);
         }
+        const blob = isBlobOutputEnabled() ? {
+          maxBytes: getBlobMaxBytes(),
+          blobOutput: {
+            fileName: typeof params.fileName === "string" ? params.fileName : void 0
+          }
+        } : {};
         return await graphClient.graphRequest(target, {
           accessToken: accountAccessToken,
           rawResponse: true,
-          forceBinary: true
+          forceBinary: true,
+          ...blob
         });
       } catch (error) {
         return {
@@ -1422,6 +1542,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
     );
     const strayBodyFields = {};
     for (const [paramName, paramValue] of Object.entries(params)) {
+      if (paramName === "fileName" && config?.blobOutput) continue;
       if ([
         "account",
         "confirm",
@@ -1663,6 +1784,13 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
       method: tool.method.toUpperCase(),
       headers
     };
+    if (config?.blobOutput && isBlobOutputEnabled()) {
+      options.forceBinary = true;
+      options.maxBytes = getBlobMaxBytes();
+      options.blobOutput = {
+        fileName: typeof params.fileName === "string" ? params.fileName : void 0
+      };
+    }
     if (config?.apiVersion) {
       options.apiVersion = config.apiVersion;
     }
@@ -1855,10 +1983,9 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
       } catch {
       }
     }
-    const content = response.content.map((item) => ({
-      type: "text",
-      text: item.text
-    }));
+    const content = response.content.map(
+      (item) => item.type === "resource" ? item : { type: "text", text: item.text }
+    );
     auditLog({
       event: "tool.call",
       request_id: requestId,
@@ -1989,6 +2116,11 @@ function registerGraphTools(server, graphClient, options = {}) {
     if (endpointConfig?.acceptType && paramSchema["Accept"] === void 0) {
       paramSchema["Accept"] = z.string().describe(getAcceptParamDescription(endpointConfig.acceptType)).optional();
     }
+    if (endpointConfig?.blobOutput && paramSchema["fileName"] === void 0) {
+      paramSchema["fileName"] = z.string().describe(
+        "Name of the file, used as the last segment of the returned resource URI when the server runs with blob output. Optional."
+      ).optional();
+    }
     if (isFetchAllPagesApplicable(tool)) {
       const maxPages = getMaxPages();
       paramSchema["fetchAllPages"] = z.boolean().describe(getFetchAllPagesParamDescription(maxPages, tool.alias)).optional();
@@ -2062,6 +2194,7 @@ function registerGraphTools(server, graphClient, options = {}) {
   for (const utility of UTILITY_TOOLS) {
     if (readOnly && !utility.readOnlyHint) continue;
     if (httpMode && utility.stdioOnly) continue;
+    if (utility.enabled && !utility.enabled()) continue;
     if (enabledToolsRegex && !enabledToolsRegex.test(utility.name)) continue;
     try {
       registerUtilityToolWithMcp(server, utility, utilityCtx);
@@ -2225,6 +2358,7 @@ function registerDiscoveryTools(server, graphClient, options = {}) {
   const utilityTools = UTILITY_TOOLS.filter((u) => {
     if (readOnly && !u.readOnlyHint) return false;
     if (httpMode && u.stdioOnly) return false;
+    if (u.enabled && !u.enabled()) return false;
     if (enabledToolsRegex && !enabledToolsRegex.test(u.name)) return false;
     return true;
   });

package/dist/lib/attachment-upload.js

@@ -0,0 +1,81 @@
+const MAX_UPLOAD_BYTES = 150 * 1024 * 1024;
+const INLINE_UPLOAD_LIMIT = 3 * 1024 * 1024;
+const UPLOAD_CHUNK_BYTES = 320 * 1024 * 12;
+async function putChunk(uploadUrl, chunk, start, total) {
+  const end = start + chunk.length - 1;
+  const response = await fetch(uploadUrl, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/octet-stream",
+      "Content-Length": String(chunk.length),
+      "Content-Range": `bytes ${start}-${end}/${total}`
+    },
+    // A standalone ArrayBuffer: fetch's body typing wants a BufferSource, and a
+    // Buffer view over a pooled slab is neither the right type nor the right bytes.
+    body: chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength)
+  });
+  if (![200, 201, 202].includes(response.status)) {
+    throw new Error(`Upload session chunk ${start}-${end} answered HTTP ${response.status}`);
+  }
+}
+async function uploadAttachment(graphClient, upload, source) {
+  const { target, name, contentType, size, accessToken } = upload;
+  if (size < INLINE_UPLOAD_LIMIT) {
+    const chunks = [];
+    let received = 0;
+    for await (const chunk of source) {
+      received += chunk.length;
+      if (received > size) throw new Error(`Source is longer than the declared ${size} bytes`);
+      chunks.push(chunk);
+    }
+    if (received !== size) throw new Error(`Source ended before the declared ${size} bytes`);
+    const created = await graphClient.makeRequest(target, {
+      method: "POST",
+      accessToken,
+      body: JSON.stringify({
+        "@odata.type": "#microsoft.graph.fileAttachment",
+        name,
+        contentType,
+        contentBytes: Buffer.concat(chunks).toString("base64")
+      })
+    });
+    return { id: created?.id };
+  }
+  const session = await graphClient.makeRequest(`${target}/createUploadSession`, {
+    method: "POST",
+    accessToken,
+    body: JSON.stringify({
+      AttachmentItem: { attachmentType: "file", name, size, contentType }
+    })
+  });
+  if (!session?.uploadUrl) throw new Error("Upload session returned no uploadUrl");
+  let pending = [];
+  let pendingBytes = 0;
+  let offset = 0;
+  for await (const piece of source) {
+    pending.push(piece);
+    pendingBytes += piece.length;
+    if (offset + pendingBytes > size) {
+      throw new Error(`Source is longer than the declared ${size} bytes`);
+    }
+    while (pendingBytes >= UPLOAD_CHUNK_BYTES) {
+      const joined = Buffer.concat(pending);
+      const chunk = joined.subarray(0, UPLOAD_CHUNK_BYTES);
+      await putChunk(session.uploadUrl, chunk, offset, size);
+      offset += chunk.length;
+      const rest = joined.subarray(UPLOAD_CHUNK_BYTES);
+      pending = rest.length ? [Buffer.from(rest)] : [];
+      pendingBytes = rest.length;
+    }
+  }
+  if (pendingBytes > 0) {
+    await putChunk(session.uploadUrl, Buffer.concat(pending), offset, size);
+    offset += pendingBytes;
+  }
+  if (offset !== size) throw new Error(`Source ended before the declared ${size} bytes`);
+  return {};
+}
+export {
+  MAX_UPLOAD_BYTES,
+  uploadAttachment
+};

package/dist/lib/upload-dirs.js

@@ -0,0 +1,61 @@
+import { constants } from "fs";
+import { open, realpath, stat } from "fs/promises";
+import path from "path";
+const UPLOAD_DIRS_ENV = "MS365_MCP_UPLOAD_DIRS";
+function uploadDirEntries() {
+  return (process.env[UPLOAD_DIRS_ENV] ?? "").split(path.delimiter).map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+function getUploadDirs() {
+  return uploadDirEntries().filter((entry) => path.isAbsolute(entry));
+}
+function assertUploadDirsAbsolute() {
+  const relative = uploadDirEntries().filter((entry) => !path.isAbsolute(entry));
+  if (relative.length > 0) {
+    throw new Error(
+      `${UPLOAD_DIRS_ENV} entries must be absolute paths, got: ${relative.join(", ")}`
+    );
+  }
+}
+function isInside(dir, file) {
+  const relative = path.relative(dir, file);
+  return relative.length > 0 && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+async function openUploadFile(filePath, dirs) {
+  const refused = new Error(
+    `filePath does not exist or is outside the directories allowed by ${UPLOAD_DIRS_ENV} (${dirs.join(", ")}).`
+  );
+  if (!path.isAbsolute(filePath)) {
+    throw new Error(`filePath must be an absolute path. Received: ${filePath}`);
+  }
+  let realFile;
+  try {
+    realFile = await realpath(filePath);
+  } catch {
+    throw refused;
+  }
+  const realDirs = await Promise.all(dirs.map((dir) => realpath(dir).catch(() => null)));
+  if (!realDirs.some((dir) => dir !== null && isInside(dir, realFile))) throw refused;
+  const checked = await stat(realFile, { bigint: true }).catch(() => null);
+  if (!checked) throw refused;
+  if (!checked.isFile()) throw new Error("filePath is not a regular file.");
+  let handle;
+  try {
+    handle = await open(realFile, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  } catch {
+    throw refused;
+  }
+  let stats;
+  try {
+    stats = await handle.stat({ bigint: true });
+    if (!stats.isFile() || stats.dev !== checked.dev || stats.ino !== checked.ino) throw refused;
+  } catch {
+    await handle.close();
+    throw refused;
+  }
+  return { handle, size: Number(stats.size) };
+}
+export {
+  assertUploadDirsAbsolute,
+  getUploadDirs,
+  openUploadFile
+};

package/dist/server.js

@@ -251,11 +251,11 @@ class MicrosoftGraphServer {
         );
       }
       logger.warn(
-        "--http-local-file-tools: download-bytes-to-file is registered over HTTP; anyone who can reach this port can write files as the server's user."
+        "--http-local-file-tools: download-bytes-to-file is registered over HTTP, and upload-attachment-from-file too when MS365_MCP_UPLOAD_DIRS is set; anyone who can reach this port can write files, and read files from those directories, as the server's user."
       );
     } else if (this.options.httpLocalFileTools) {
       logger.warn(
-        "--http-local-file-tools has no effect in stdio mode, where download-bytes-to-file is always registered."
+        "--http-local-file-tools has no effect in stdio mode, where the local file tools need no flag."
       );
     }
     if (this.options.obo) {

package/dist/tool-categories.js

@@ -63,6 +63,7 @@ const UNIVERSAL_UTILITY_TOOLS = ["download-bytes", "download-bytes-to-file"];
 const SCOPED_UTILITY_TOOLS = {
   "get-download-url": ["files", "onedrive", "personal", "work", "search"],
   "get-upload-url": ["mail", "calendar", "outlook", "personal", "work"],
+  "upload-attachment-from-file": ["mail", "calendar", "outlook", "personal", "work"],
   "parse-teams-url": ["teams", "teams-write", "work"]
 };
 for (const [tool, presets] of Object.entries(SCOPED_UTILITY_TOOLS)) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.163.0",
+  "version": "0.165.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

@@ -949,8 +949,40 @@
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.Read"],
     "acceptType": "text/plain",
+    "blobOutput": true,
     "llmTip": "Download an email message as raw RFC 5322 MIME content (.eml format). Use this when archiving an email to disk preserving all original headers, body, and inline-encoded attachments. Returns the MIME stream as text. Find the message id with list-mail-messages first."
   },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/$value",
+    "method": "get",
+    "toolName": "get-shared-mailbox-message-mime",
+    "descriptionOverride": "Download the raw MIME source (RFC 5322 .eml content) of a message in another user's mailbox or a shared mailbox, by message ID. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.Read.Shared"],
+    "acceptType": "text/plain",
+    "blobOutput": true,
+    "llmTip": "Download a message of a shared mailbox as an .eml. Find the message id with list-shared-mailbox-messages first. With the server's blob output on, the bytes come back as a file resource; pass fileName to name it."
+  },
+  {
+    "pathPattern": "/me/messages/{message-id}/attachments/{attachment-id}/$value",
+    "method": "get",
+    "toolName": "get-mail-attachment-content",
+    "descriptionOverride": "Download the raw bytes of a file attachment of an Outlook message in the signed-in user's mailbox, by message ID and attachment ID.",
+    "presets": ["mail", "outlook", "personal"],
+    "scopes": ["Mail.Read"],
+    "blobOutput": true,
+    "llmTip": "Find the attachment id with list-mail-attachments first. With the server's blob output on, the bytes come back as a file resource; pass fileName (the attachment's name) to name it. Files over the server's download limit are refused with an error naming the limit."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/attachments/{attachment-id}/$value",
+    "method": "get",
+    "toolName": "get-shared-mailbox-attachment-content",
+    "descriptionOverride": "Download the raw bytes of a file attachment of a message in another user's mailbox or a shared mailbox, by message ID and attachment ID. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.Read.Shared"],
+    "blobOutput": true,
+    "llmTip": "Find the attachment id with list-shared-mailbox-attachments first. With the server's blob output on, the bytes come back as a file resource; pass fileName (the attachment's name) to name it. Files over the server's download limit are refused with an error naming the limit."
+  },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/workbook/worksheets/{workbookWorksheet-id}/range(address='{address}')",
     "method": "patch",