@softeria/ms-365-mcp-server 0.159.1 → 0.161.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/endpoints.json

@@ -197,6 +197,64 @@
     "workScopes": ["Mail.Send.Shared"],
     "llmTip": "Send an existing draft from a shared mailbox. No request body needed — just call with the message ID and the shared mailbox user-id. Draft must exist in the shared mailbox's Drafts folder. Requires Send As permission on the shared mailbox in Exchange."
   },
+  {
+    "pathPattern": "/users/{user-id}/mailFolders",
+    "method": "get",
+    "toolName": "list-shared-mailbox-folders",
+    "descriptionOverride": "List the top-level mail folders in another user's mailbox or a shared mailbox. 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"]
+  },
+  {
+    "pathPattern": "/users/{user-id}/mailFolders/{mailFolder-id}/childFolders",
+    "method": "get",
+    "toolName": "list-shared-mailbox-child-folders",
+    "descriptionOverride": "List the child folders of a mail folder in another user's mailbox or a shared mailbox. 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"]
+  },
+  {
+    "pathPattern": "/users/{user-id}/mailFolders",
+    "method": "post",
+    "toolName": "create-shared-mailbox-folder",
+    "descriptionOverride": "Create a top-level mail folder in another user's mailbox or a shared mailbox. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"]
+  },
+  {
+    "pathPattern": "/users/{user-id}/mailFolders/{mailFolder-id}/childFolders",
+    "method": "post",
+    "toolName": "create-shared-mailbox-child-folder",
+    "descriptionOverride": "Create a subfolder inside a mail folder in another user's mailbox or a shared mailbox. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"]
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/attachments",
+    "method": "get",
+    "toolName": "list-shared-mailbox-attachments",
+    "descriptionOverride": "List the attachments on a message in another user's mailbox or a shared mailbox. 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"],
+    "llmTip": "To download the bytes, call download-bytes or get-download-url with target=/users/{user-id}/messages/{message-id}/attachments/{attachment-id}/$value."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/attachments",
+    "method": "post",
+    "toolName": "add-shared-mailbox-attachment",
+    "descriptionOverride": "Add an attachment under 3MB to a draft message in another user's mailbox or a shared mailbox. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"],
+    "llmTip": "Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}. Graph has no working path for 3MB and above here: upload sessions return 403 in a shared or delegated mailbox."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/attachments/{attachment-id}",
+    "method": "delete",
+    "toolName": "delete-shared-mailbox-attachment",
+    "descriptionOverride": "Delete an attachment from a message in another user's mailbox or a shared mailbox. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"]
+  },
   {
     "pathPattern": "/users",
     "method": "get",
@@ -2394,6 +2452,22 @@
     "scopes": ["Calendars.ReadWrite"],
     "llmTip": "Dismisses a triggered event reminder so it won't re-fire. No request body required. Pair with list-calendar-events or get-schedule to find active reminders."
   },
+  {
+    "pathPattern": "/me/events/{event-id}/attachments",
+    "method": "post",
+    "toolName": "add-calendar-event-attachment",
+    "presets": ["calendar", "outlook", "personal"],
+    "scopes": ["Calendars.ReadWrite"],
+    "llmTip": "Under 3MB only. Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}. At 3MB and above use create-calendar-event-attachment-upload-session."
+  },
+  {
+    "pathPattern": "/me/events/{event-id}/attachments/createUploadSession",
+    "method": "post",
+    "toolName": "create-calendar-event-attachment-upload-session",
+    "presets": ["calendar", "outlook", "personal"],
+    "scopes": ["Calendars.ReadWrite"],
+    "llmTip": "For attachments 3MB to 150MB; under 3MB use add-calendar-event-attachment. Body: { AttachmentItem: { attachmentType: 'file', name: 'report.pdf', size: 5000000 } }. Returns a pre-authenticated uploadUrl; the caller PUTs the bytes there itself in ranges up to 4MB."
+  },
   {
     "pathPattern": "/me/events/delta()",
     "method": "get",

package/dist/generated/client.js

@@ -2774,6 +2774,20 @@ const microsoft_graph_driveCollectionResponse = z.object({
   "@odata.nextLink": z.string().nullable(),
   value: z.array(microsoft_graph_drive)
 }).partial().passthrough();
+const microsoft_graph_attachmentType = z.enum(["file", "item", "reference"]);
+const microsoft_graph_attachmentItem = z.object({
+  attachmentType: microsoft_graph_attachmentType.optional(),
+  contentId: z.string().describe(
+    "The CID or Content-Id of the attachment for referencing for the in-line attachments using the <img src='cid:contentId'> tag in HTML messages. Optional."
+  ).nullish(),
+  contentType: z.string().describe("The nature of the data in the attachment. Optional.").nullish(),
+  isInline: z.boolean().describe("true if the attachment is an inline attachment; otherwise, false. Optional.").nullish(),
+  name: z.string().describe(
+    "The display name of the attachment. This can be a descriptive string and doesn't have to be the actual file name. Required."
+  ).nullish(),
+  size: z.number().describe("The length of the attachment in bytes. Required.").nullish()
+}).passthrough();
+const create_calendar_event_attachment_upload_session_Body = z.object({ AttachmentItem: microsoft_graph_attachmentItem }).partial().passthrough();
 const accept_calendar_event_Body = z.object({ SendResponse: z.boolean().nullable().default(false), Comment: z.string().nullable() }).partial().passthrough();
 const decline_calendar_event_Body = z.object({
   ProposedNewTime: z.union([microsoft_graph_timeSlot, z.object({}).partial().passthrough()]),
@@ -3299,20 +3313,6 @@ const microsoft_graph_attachmentCollectionResponse = z.object({
   "@odata.nextLink": z.string().nullable(),
   value: z.array(microsoft_graph_attachment)
 }).partial().passthrough();
-const microsoft_graph_attachmentType = z.enum(["file", "item", "reference"]);
-const microsoft_graph_attachmentItem = z.object({
-  attachmentType: microsoft_graph_attachmentType.optional(),
-  contentId: z.string().describe(
-    "The CID or Content-Id of the attachment for referencing for the in-line attachments using the <img src='cid:contentId'> tag in HTML messages. Optional."
-  ).nullish(),
-  contentType: z.string().describe("The nature of the data in the attachment. Optional.").nullish(),
-  isInline: z.boolean().describe("true if the attachment is an inline attachment; otherwise, false. Optional.").nullish(),
-  name: z.string().describe(
-    "The display name of the attachment. This can be a descriptive string and doesn't have to be the actual file name. Required."
-  ).nullish(),
-  size: z.number().describe("The length of the attachment in bytes. Required.").nullish()
-}).passthrough();
-const create_mail_attachment_upload_session_Body = z.object({ AttachmentItem: microsoft_graph_attachmentItem }).partial().passthrough();
 const create_forward_draft_Body = z.object({
   ToRecipients: z.array(microsoft_graph_recipient),
   Message: z.union([microsoft_graph_message, z.object({}).partial().passthrough()]),
@@ -5149,6 +5149,9 @@ const schemas = {
   microsoft_graph_list,
   microsoft_graph_drive,
   microsoft_graph_driveCollectionResponse,
+  microsoft_graph_attachmentType,
+  microsoft_graph_attachmentItem,
+  create_calendar_event_attachment_upload_session_Body,
   accept_calendar_event_Body,
   decline_calendar_event_Body,
   forward_calendar_event_Body,
@@ -5200,9 +5203,6 @@ const schemas = {
   microsoft_graph_messageRuleCollectionResponse,
   microsoft_graph_messageCollectionResponse,
   microsoft_graph_attachmentCollectionResponse,
-  microsoft_graph_attachmentType,
-  microsoft_graph_attachmentItem,
-  create_mail_attachment_upload_session_Body,
   create_forward_draft_Body,
   create_reply_draft_Body,
   microsoft_graph_attendeeBase,
@@ -9377,6 +9377,38 @@ open extensions or extended properties, and how to specify extended properties.`
     ],
     response: z.void()
   },
+  {
+    method: "post",
+    path: "/me/events/:eventId/attachments",
+    alias: "add-calendar-event-attachment",
+    description: `Use this API to add an attachment to an existing event. This operation limits the size of the attachment you can add to under 3 MB. If an organizer adds an attachment to a meeting event, the organizer can subsequently update the event to send the attachment and update the event for each attendee as well.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `New navigation property`,
+        type: "Body",
+        schema: microsoft_graph_attachment
+      }
+    ],
+    response: z.void()
+  },
+  {
+    method: "post",
+    path: "/me/events/:eventId/attachments/createUploadSession",
+    alias: "create-calendar-event-attachment-upload-session",
+    description: `Create an upload session that allows an app to iteratively upload ranges of a file, so as to attach the file to the specified Outlook item. The item can be a message or event. Use this approach to attach a file if the file size is between 3 MB and 150 MB. To attach a file that's smaller than 3 MB, do a POST operation on the attachments navigation property of the Outlook item; see how to do this for a message or for an event. As part of the response, this action returns an upload URL that you can use in subsequent sequential PUT queries. Request headers for each PUT operation let you specify the exact range of bytes to be uploaded. This allows transfer to be resumed, in case the network connection is dropped during upload. The following are the steps to attach a file to an Outlook item using an upload session: See attach large files to Outlook messages or events for an example.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `Action parameters`,
+        type: "Body",
+        schema: create_calendar_event_attachment_upload_session_Body
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "post",
     path: "/me/events/:eventId/cancel",
@@ -10591,7 +10623,7 @@ resource.`,
         name: "body",
         description: `Action parameters`,
         type: "Body",
-        schema: create_mail_attachment_upload_session_Body
+        schema: create_calendar_event_attachment_upload_session_Body
       }
     ],
     response: z.void()
@@ -15013,6 +15045,148 @@ Only the policyViolation property of a chatMessage can be updated in application
     ],
     response: z.void()
   },
+  {
+    method: "get",
+    path: "/users/:userId/mailFolders",
+    alias: "list-shared-mailbox-folders",
+    description: `The user's mail folders. Read-only. Nullable.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "includeHiddenFolders",
+        type: "Query",
+        schema: z.string().describe("Include Hidden Folders").optional()
+      },
+      {
+        name: "$top",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Show only the first n items").optional()
+      },
+      {
+        name: "$skip",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Skip the first n items").optional()
+      },
+      {
+        name: "$search",
+        type: "Query",
+        schema: z.string().describe("Search items by search phrases").optional()
+      },
+      {
+        name: "$filter",
+        type: "Query",
+        schema: z.string().describe("Filter items by property values").optional()
+      },
+      {
+        name: "$count",
+        type: "Query",
+        schema: z.boolean().describe("Include count of items").optional()
+      },
+      {
+        name: "$orderby",
+        type: "Query",
+        schema: z.array(z.string()).describe("Order items by property values").optional()
+      },
+      {
+        name: "$select",
+        type: "Query",
+        schema: z.array(z.string()).describe("Select properties to be returned").optional()
+      },
+      {
+        name: "$expand",
+        type: "Query",
+        schema: z.array(z.string()).describe("Expand related entities").optional()
+      }
+    ],
+    response: z.void()
+  },
+  {
+    method: "post",
+    path: "/users/:userId/mailFolders",
+    alias: "create-shared-mailbox-folder",
+    description: `Create a shared mailbox folder.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `New navigation property`,
+        type: "Body",
+        schema: microsoft_graph_mailFolder
+      }
+    ],
+    response: z.void()
+  },
+  {
+    method: "get",
+    path: "/users/:userId/mailFolders/:mailFolderId/childFolders",
+    alias: "list-shared-mailbox-child-folders",
+    description: `The collection of child folders in the mailFolder.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "includeHiddenFolders",
+        type: "Query",
+        schema: z.string().describe("Include Hidden Folders").optional()
+      },
+      {
+        name: "$top",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Show only the first n items").optional()
+      },
+      {
+        name: "$skip",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Skip the first n items").optional()
+      },
+      {
+        name: "$search",
+        type: "Query",
+        schema: z.string().describe("Search items by search phrases").optional()
+      },
+      {
+        name: "$filter",
+        type: "Query",
+        schema: z.string().describe("Filter items by property values").optional()
+      },
+      {
+        name: "$count",
+        type: "Query",
+        schema: z.boolean().describe("Include count of items").optional()
+      },
+      {
+        name: "$orderby",
+        type: "Query",
+        schema: z.array(z.string()).describe("Order items by property values").optional()
+      },
+      {
+        name: "$select",
+        type: "Query",
+        schema: z.array(z.string()).describe("Select properties to be returned").optional()
+      },
+      {
+        name: "$expand",
+        type: "Query",
+        schema: z.array(z.string()).describe("Expand related entities").optional()
+      }
+    ],
+    response: z.void()
+  },
+  {
+    method: "post",
+    path: "/users/:userId/mailFolders/:mailFolderId/childFolders",
+    alias: "create-shared-mailbox-child-folder",
+    description: `Create a shared mailbox child folder.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `New navigation property`,
+        type: "Body",
+        schema: microsoft_graph_mailFolder
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "get",
     path: "/users/:userId/mailFolders/:mailFolderId/messages",
@@ -15294,6 +15468,87 @@ Only the policyViolation property of a chatMessage can be updated in application
     ],
     response: z.void()
   },
+  {
+    method: "get",
+    path: "/users/:userId/messages/:messageId/attachments",
+    alias: "list-shared-mailbox-attachments",
+    description: `The fileAttachment and itemAttachment attachments for the message.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "$top",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Show only the first n items").optional()
+      },
+      {
+        name: "$skip",
+        type: "Query",
+        schema: z.number().int().gte(0).describe("Skip the first n items").optional()
+      },
+      {
+        name: "$search",
+        type: "Query",
+        schema: z.string().describe("Search items by search phrases").optional()
+      },
+      {
+        name: "$filter",
+        type: "Query",
+        schema: z.string().describe("Filter items by property values").optional()
+      },
+      {
+        name: "$count",
+        type: "Query",
+        schema: z.boolean().describe("Include count of items").optional()
+      },
+      {
+        name: "$orderby",
+        type: "Query",
+        schema: z.array(z.string()).describe("Order items by property values").optional()
+      },
+      {
+        name: "$select",
+        type: "Query",
+        schema: z.array(z.string()).describe("Select properties to be returned").optional()
+      },
+      {
+        name: "$expand",
+        type: "Query",
+        schema: z.array(z.string()).describe("Expand related entities").optional()
+      }
+    ],
+    response: z.void()
+  },
+  {
+    method: "post",
+    path: "/users/:userId/messages/:messageId/attachments",
+    alias: "add-shared-mailbox-attachment",
+    description: `Add a shared mailbox attachment.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `New navigation property`,
+        type: "Body",
+        schema: microsoft_graph_attachment
+      }
+    ],
+    response: z.void()
+  },
+  {
+    method: "delete",
+    path: "/users/:userId/messages/:messageId/attachments/:attachmentId",
+    alias: "delete-shared-mailbox-attachment",
+    description: `Delete a shared mailbox attachment.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "If-Match",
+        type: "Header",
+        schema: z.string().describe("ETag").optional()
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "post",
     path: "/users/:userId/messages/:messageId/createForward",

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,65 @@ 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) {
+    const smallFileTool = target.includes("/events/") ? "add-calendar-event-attachment" : target.startsWith("/users/") ? "add-shared-mailbox-attachment" : "add-mail-attachment";
+    return uploadError(
+      `This server is not running with --enable-attachment-urls, so no upload URL can be minted. Attach small files with ${smallFileTool} (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 +670,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.161.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

@@ -197,6 +197,64 @@
     "workScopes": ["Mail.Send.Shared"],
     "llmTip": "Send an existing draft from a shared mailbox. No request body needed — just call with the message ID and the shared mailbox user-id. Draft must exist in the shared mailbox's Drafts folder. Requires Send As permission on the shared mailbox in Exchange."
   },
+  {
+    "pathPattern": "/users/{user-id}/mailFolders",
+    "method": "get",
+    "toolName": "list-shared-mailbox-folders",
+    "descriptionOverride": "List the top-level mail folders in another user's mailbox or a shared mailbox. 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"]
+  },
+  {
+    "pathPattern": "/users/{user-id}/mailFolders/{mailFolder-id}/childFolders",
+    "method": "get",
+    "toolName": "list-shared-mailbox-child-folders",
+    "descriptionOverride": "List the child folders of a mail folder in another user's mailbox or a shared mailbox. 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"]
+  },
+  {
+    "pathPattern": "/users/{user-id}/mailFolders",
+    "method": "post",
+    "toolName": "create-shared-mailbox-folder",
+    "descriptionOverride": "Create a top-level mail folder in another user's mailbox or a shared mailbox. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"]
+  },
+  {
+    "pathPattern": "/users/{user-id}/mailFolders/{mailFolder-id}/childFolders",
+    "method": "post",
+    "toolName": "create-shared-mailbox-child-folder",
+    "descriptionOverride": "Create a subfolder inside a mail folder in another user's mailbox or a shared mailbox. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"]
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/attachments",
+    "method": "get",
+    "toolName": "list-shared-mailbox-attachments",
+    "descriptionOverride": "List the attachments on a message in another user's mailbox or a shared mailbox. 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"],
+    "llmTip": "To download the bytes, call download-bytes or get-download-url with target=/users/{user-id}/messages/{message-id}/attachments/{attachment-id}/$value."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/attachments",
+    "method": "post",
+    "toolName": "add-shared-mailbox-attachment",
+    "descriptionOverride": "Add an attachment under 3MB to a draft message in another user's mailbox or a shared mailbox. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"],
+    "llmTip": "Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}. Graph has no working path for 3MB and above here: upload sessions return 403 in a shared or delegated mailbox."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/attachments/{attachment-id}",
+    "method": "delete",
+    "toolName": "delete-shared-mailbox-attachment",
+    "descriptionOverride": "Delete an attachment from a message in another user's mailbox or a shared mailbox. The user-id is the mailbox owner's ID or email address, and delegated access to that mailbox is required.",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"]
+  },
   {
     "pathPattern": "/users",
     "method": "get",
@@ -2394,6 +2452,22 @@
     "scopes": ["Calendars.ReadWrite"],
     "llmTip": "Dismisses a triggered event reminder so it won't re-fire. No request body required. Pair with list-calendar-events or get-schedule to find active reminders."
   },
+  {
+    "pathPattern": "/me/events/{event-id}/attachments",
+    "method": "post",
+    "toolName": "add-calendar-event-attachment",
+    "presets": ["calendar", "outlook", "personal"],
+    "scopes": ["Calendars.ReadWrite"],
+    "llmTip": "Under 3MB only. Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}. At 3MB and above use create-calendar-event-attachment-upload-session."
+  },
+  {
+    "pathPattern": "/me/events/{event-id}/attachments/createUploadSession",
+    "method": "post",
+    "toolName": "create-calendar-event-attachment-upload-session",
+    "presets": ["calendar", "outlook", "personal"],
+    "scopes": ["Calendars.ReadWrite"],
+    "llmTip": "For attachments 3MB to 150MB; under 3MB use add-calendar-event-attachment. Body: { AttachmentItem: { attachmentType: 'file', name: 'report.pdf', size: 5000000 } }. Returns a pre-authenticated uploadUrl; the caller PUTs the bytes there itself in ranges up to 4MB."
+  },
   {
     "pathPattern": "/me/events/delta()",
     "method": "get",