@softeria/ms-365-mcp-server 0.159.1 → 0.160.0

package/README.md

@@ -776,6 +776,28 @@ credential.
 be minted is one `download-bytes` would fetch for the same caller on the same account. The
 ticket only moves those bytes out of the context window and into a direct transfer.
 
+### Uploading attachments the same way
+
+The same ticket store works in the other direction. `get-upload-url` mints a URL for
+attaching a file to a draft message or an event, so the bytes go straight from the caller
+to Graph instead of passing as base64 `contentBytes` through the agent context:
+
+```
+PUT /attachment?t=<ticket>&dgk=<key-id>&dgx=<expiry>&dgs=<signature>
+Content-Length: <file size>
+
+<raw file bytes>
+```
+
+`target` is the item's attachments collection (`/me/messages/{id}/attachments` for a draft,
+`/me/events/{id}/attachments` for an event); `name` and `contentType` are recorded on the
+attachment. Files under 3 MB are attached inline; larger ones, up to Graph's 150 MB, stream
+through an upload session in 3.75 MiB chunks, so the server never holds more than one chunk.
+`Content-Length` is required. The ticket is single-use and burnt on first presentation
+whatever the outcome, and the upload is attached as the identity that minted it, exactly as
+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.
+
 ### Configuration
 
 ```

package/dist/attachment-route.js

@@ -61,7 +61,7 @@ function createAttachmentHandler(deps) {
       return;
     }
     const ticket = deps.store.redeem(raw);
-    if (!ticket) {
+    if (!ticket || ticket.purpose !== "download") {
       refuse(res);
       return;
     }
@@ -104,7 +104,146 @@ 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") {
+      res.setHeader("allow", "GET, PUT");
+      res.status(405).type("text/plain").send("Method not allowed");
+      return;
+    }
+    const raw = req.query[TICKET_PARAM];
+    if (typeof raw !== "string" || raw.length === 0) {
+      refuse(res);
+      return;
+    }
+    const ticket = deps.store.redeem(raw);
+    if (!ticket || ticket.purpose !== "upload") {
+      refuse(res);
+      return;
+    }
+    if (!isPlainGraphPath(ticket.target)) {
+      logger.error("Attachment upload refused: ticket target is not a plain Graph path");
+      refuse(res);
+      return;
+    }
+    const declared = Number(req.headers["content-length"]);
+    if (!Number.isInteger(declared) || declared < 0) {
+      res.status(411).type("text/plain").send("Content-Length required");
+      return;
+    }
+    if (declared === 0) {
+      res.status(400).type("text/plain").send("Empty upload");
+      return;
+    }
+    if (declared > MAX_UPLOAD_BYTES) {
+      res.status(413).type("text/plain").send(`Upload exceeds ${MAX_UPLOAD_BYTES} bytes`);
+      return;
+    }
+    const graphClient = deps.getGraphClient();
+    if (!graphClient) {
+      logger.error("Attachment upload failed: Graph client is not initialised");
+      res.status(503).type("text/plain").send("Service unavailable");
+      return;
+    }
+    let accessToken;
+    try {
+      accessToken = ticket.kind === "request-token" ? ticket.accessToken : await deps.authManager.getTokenForAccount(ticket.accountName);
+      if (!accessToken) throw new Error("No access token for this ticket");
+    } catch (error) {
+      logger.error(`Attachment upload failed for ${ticket.target}: ${error.message}`);
+      res.status(502).type("text/plain").send("Upstream upload failed");
+      return;
+    }
+    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 });
+    } 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");
+    }
+  };
+}
 export {
+  MAX_UPLOAD_BYTES,
   createAttachmentHandler,
+  createAttachmentUploadHandler,
   forceAttachment
 };

package/dist/graph-tools.js

@@ -15,6 +15,7 @@ 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 {
   buildAttachmentUrl,
   isPlainGraphPath,
@@ -545,6 +546,64 @@ async function checkAccountParamInBearerMode(accountParam, authManager) {
   if (bearerIdentity && bearerIdentity.toLowerCase() === accountParam.toLowerCase()) return null;
   return `The 'account' parameter is not supported in HTTP/OAuth mode: every request uses the identity of the connecting client's bearer token` + (bearerIdentity ? ` ('${bearerIdentity}')` : "") + `, so account switching is not possible. To act as '${accountParam}', reconnect the MCP client authenticated as that account, or run the server in stdio mode (or HTTP with --trust-proxy-auth) where cached accounts are available.`;
 }
+const UPLOAD_TARGET = /^(\/me|\/users\/[^/]+)\/(messages|events)\/[^/]+\/attachments$/;
+const UPLOAD_CONTENT_TYPE = /^[\w.+-]+\/[\w.+-]+$/;
+function uploadError(message) {
+  return { content: [{ type: "text", text: JSON.stringify({ error: message }) }], isError: true };
+}
+async function mintUploadUrl(target, name, contentType, accountParam, authManager) {
+  const minting = getAttachmentMinting();
+  if (!minting) {
+    return uploadError(
+      "This server is not running with --enable-attachment-urls, so no upload URL can be minted. Attach small files with add-mail-attachment (base64 contentBytes)."
+    );
+  }
+  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."
+    );
+  }
+  const cleanName = Array.from(name.trim()).filter((char) => {
+    const code = char.charCodeAt(0);
+    return code > 31 && code !== 127;
+  }).join("").slice(0, 255);
+  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.");
+  }
+  const identityFromRequest = Boolean(authManager?.isOAuthModeEnabled() || getRequestTokens());
+  const requestToken = identityFromRequest ? getRequestTokens()?.accessToken ?? await authManager?.getToken().catch(() => null) ?? void 0 : void 0;
+  if (identityFromRequest && !requestToken) {
+    return uploadError(
+      "No Graph access token is available for this request, so no upload URL can be minted."
+    );
+  }
+  const accountModeError = await checkAccountParamInBearerMode(accountParam, authManager);
+  if (accountModeError) return uploadError(accountModeError);
+  let ticket;
+  try {
+    const upload = { name: cleanName, contentType };
+    ticket = requestToken ? minting.store.mintUploadWithToken(target, requestToken, upload) : minting.store.mintUpload(target, accountParam, upload);
+  } catch (error) {
+    if (error instanceof TicketStoreFullError) return uploadError(error.message);
+    throw error;
+  }
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify({
+          uploadUrl: buildAttachmentUrl(minting.config, ticket.id),
+          method: "PUT",
+          expiresAt: new Date(ticket.expiresAtMs).toISOString(),
+          singleUse: true,
+          maxBytes: MAX_UPLOAD_BYTES,
+          note: 'PUT the raw file bytes with a Content-Length (e.g. curl -T <file> "<uploadUrl>"). Served by this server; valid for one upload until it expires.'
+        })
+      }
+    ]
+  };
+}
 async function mintDownloadUrl(target, accountParam, authManager) {
   const minting = getAttachmentMinting();
   if (!minting) return null;
@@ -610,6 +669,50 @@ async function mintDownloadUrl(target, accountParam, authManager) {
   };
 }
 const UTILITY_TOOLS = [
+  {
+    name: "get-upload-url",
+    method: "PUT",
+    path: "tool:get-upload-url",
+    searchKeywords: "upload attachment attach file draft email attach file event large attachment send file out-of-band upload url",
+    description: 'Mint a short-lived, single-use URL that this server serves for uploading a file as an attachment to a draft message or an event, so the bytes go straight from the caller to Microsoft Graph instead of passing as base64 through the agent context. target is the attachments collection of the item: /me/messages/{message-id}/attachments (a draft; create it first) or /me/events/{event-id}/attachments. PUT the raw file bytes to the returned uploadUrl with a Content-Length (e.g. curl -T file "<uploadUrl>"); the response confirms the attachment. Files under 3 MB are attached directly, larger ones (up to 150 MB) through a Graph upload session. Requires --enable-attachment-urls. Returns { uploadUrl, method, expiresAt, singleUse, maxBytes }.',
+    readOnlyHint: false,
+    openWorldHint: true,
+    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."
+        ),
+        name: z.string().describe("Attachment file name as the recipient will see it, e.g. report.pdf"),
+        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, { authManager }) => {
+      const target = params.target;
+      const name = params.name;
+      if (typeof target !== "string" || target.length === 0) {
+        return uploadError("target is required and must be a non-empty string.");
+      }
+      if (typeof name !== "string" || name.length === 0) {
+        return uploadError("name is required and must be a non-empty string.");
+      }
+      const contentType = typeof params.contentType === "string" && params.contentType.length > 0 ? params.contentType : "application/octet-stream";
+      return mintUploadUrl(
+        target,
+        name,
+        contentType,
+        params.account,
+        authManager
+      );
+    }
+  },
   {
     name: "parse-teams-url",
     method: "POST",

package/dist/lib/attachment-tickets.js

@@ -53,14 +53,14 @@ class AttachmentTicketStore {
       if (ticket.expiresAtMs <= nowMs) this.tickets.delete(id);
     }
   }
-  add(target, identity, nowMs) {
+  add(target, identity, nowMs, purpose = { purpose: "download" }) {
     this.sweep(nowMs);
     if (this.tickets.size >= MAX_LIVE_TICKETS) {
       throw new TicketStoreFullError(MAX_LIVE_TICKETS);
     }
     const id = randomBytes(TICKET_BYTES).toString("base64url");
     const expiresAtMs = nowMs + this.ttlSeconds * 1e3;
-    this.tickets.set(id, { ...identity, target, expiresAtMs });
+    this.tickets.set(id, { ...identity, ...purpose, target, expiresAtMs });
     return { id, expiresAtMs };
   }
   /** Mint a ticket redeemed with this server's own token for `accountName`. */
@@ -72,6 +72,21 @@ class AttachmentTicketStore {
     if (!accessToken) throw new Error("A request-token ticket needs a token");
     return this.add(target, { kind: "request-token", accessToken }, nowMs);
   }
+  /** Mint an upload ticket attached as this server's own token for `accountName`. */
+  mintUpload(target, accountName, upload, nowMs = Date.now()) {
+    return this.add(target, { kind: "server-account", accountName }, nowMs, {
+      purpose: "upload",
+      ...upload
+    });
+  }
+  /** Mint an upload ticket attached with `accessToken` and nothing else. */
+  mintUploadWithToken(target, accessToken, upload, nowMs = Date.now()) {
+    if (!accessToken) throw new Error("A request-token ticket needs a token");
+    return this.add(target, { kind: "request-token", accessToken }, nowMs, {
+      purpose: "upload",
+      ...upload
+    });
+  }
   /**
    * Return the ticket and burn it, or undefined.
    *

package/dist/server.js

@@ -8,7 +8,7 @@ import rateLimit from "express-rate-limit";
 import helmet from "helmet";
 import crypto from "node:crypto";
 import { isIP, isIPv6 } from "node:net";
-import { createAttachmentHandler } from "./attachment-route.js";
+import { createAttachmentHandler, createAttachmentUploadHandler } from "./attachment-route.js";
 import { registerAuthTools } from "./auth-tools.js";
 import {
   buildScopesFromEndpoints,
@@ -722,14 +722,13 @@ class MicrosoftGraphServer {
             })
           );
         }
-        attachmentApp.get(
-          ATTACHMENT_ROUTE,
-          createAttachmentHandler({
-            store: ticketStore,
-            getGraphClient: () => this.graphClient,
-            authManager: this.authManager
-          })
-        );
+        const attachmentDeps = {
+          store: ticketStore,
+          getGraphClient: () => this.graphClient,
+          authManager: this.authManager
+        };
+        attachmentApp.get(ATTACHMENT_ROUTE, createAttachmentHandler(attachmentDeps));
+        attachmentApp.put(ATTACHMENT_ROUTE, createAttachmentUploadHandler(attachmentDeps));
         logger.info(
           `  - Attachment URLs: ${attachmentConfig.base}${ATTACHMENT_ROUTE} (ttl ${attachmentConfig.ttlSeconds}s, key id ${attachmentConfig.keyId})`
         );

package/dist/tool-categories.js

@@ -62,6 +62,7 @@ const PRESET_META = {
 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"],
   "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.159.1",
+  "version": "0.160.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",