@softeria/ms-365-mcp-server 0.163.0 → 0.164.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)
@@ -735,7 +737,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 +808,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__/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";
@@ -2423,6 +2431,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,7 @@ 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(
   "--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."
@@ -98,6 +99,7 @@ function parseArgs() {
     process.env.MS365_MCP_MESSAGE_SIGNOFF_PREFIX = "";
   }
   assertSignoffMarkersVisible();
+  assertUploadDirsAbsolute();
   if (options.listPresets) {
     const presets = listPresets();
     console.log(JSON.stringify({ presets }, null, 2));

package/dist/graph-tools.js

@@ -15,7 +15,8 @@ import {
 import { api as betaApi } from "./generated/client-beta.js";
 import { api } from "./generated/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 +498,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 +550,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 +569,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 +718,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",
@@ -2062,6 +2171,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 +2335,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.164.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",