@softeria/ms-365-mcp-server 0.161.3 → 0.162.0

package/README.md

@@ -633,7 +633,7 @@ npx @softeria/ms-365-mcp-server --list-presets  # See all available presets
 
 Available presets: `mail`, `calendar`, `files`, `personal`, `work`, `excel`, `contacts`, `tasks`, `onenote`, `search`, `users`, `outlook`, `onedrive`, `teams`, `teams-write`, `all`
 
-Each endpoint in `endpoints.json` declares which presets it belongs to via a `presets` array, so every preset is an exact tool-name allow-list that never over-matches across apps (e.g. `mail` does not include shared-mailbox tools; those are in `work`). The universal binary reader `download-bytes` is included in every preset except `teams-write`, so whatever an app returns (a file, an attachment, a photo, a recording) can always be fetched; `get-download-url` (a pre-authenticated URL for drive/SharePoint files) rides with the drive-backed presets. So a preset that can find a file can always read its bytes.
+Each endpoint in `endpoints.json` declares which presets it belongs to via a `presets` array, so every preset is an exact tool-name allow-list that never over-matches across apps (e.g. `mail` does not include shared-mailbox tools; those are in `work`). The universal binary reader `download-bytes` is included in every preset except `teams-write`, so whatever an app returns (a file, an attachment, a photo, a recording) can always be fetched; `get-download-url` (a pre-authenticated URL for drive/SharePoint files) rides with the drive-backed presets, and joins every other preset (bar `teams-write`) when HTTP mode runs with `--enable-attachment-urls`. So a preset that can find a file can always read its bytes.
 
 The `outlook`, `onedrive` and `teams` presets are app-scoped: they expose exactly one Microsoft app. Use these for "expose exactly one app" deployments:
 
@@ -699,7 +699,8 @@ When running as an MCP server, the following options can be used:
                   --trust-proxy-auth
 --enable-auth-tools Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)
 --enable-attachment-urls Let get-download-url mint a server-served URL for byte resources Graph
-                  exposes no pre-authenticated URL for (see "Server-Minted Attachment URLs")
+                  exposes no pre-authenticated URL for (see "Server-Minted Attachment URLs").
+                  Also adds get-download-url to any --preset that lacks it (except teams-write)
 --attachment-port <port> Serve /attachment on its own listener on this port instead of on the
                   MCP app, so a fetcher that can read attachments cannot also reach /mcp
                   (requires --enable-attachment-urls; see "Splitting the attachment listener")
@@ -761,7 +762,13 @@ agent's context. A 73 KB, 3-page PDF costs about 24,500 tokens that way, and the
 cannot parse them anyway.
 
 `--enable-attachment-urls` (HTTP mode, off by default) closes that gap. When Graph has no
-URL of its own, `get-download-url` mints one this server serves:
+URL of its own, `get-download-url` mints one this server serves. With it on,
+`get-download-url` is registered under every `--preset` (except the send-only `teams-write`),
+so a `--preset mail` agent that lists an attachment can mint a URL for it. A minted URL only
+works if the preset's scopes cover the resource: a contacts, tasks or excel preset has no Mail
+scopes, so a URL minted for a mail attachment fails when fetched.
+
+The minted URL looks like:
 
 ```
 GET /attachment?t=<ticket>&dgk=<key-id>&dgx=<expiry>&dgs=<signature>
@@ -802,16 +809,21 @@ is refused with the same 404 as any other bad ticket.
 
 ```
 MS365_MCP_ATTACHMENT_URL_BASE=http://m365-mcp:3000   # required
-MS365_MCP_ATTACHMENT_URL_KEY=...                     # required (or _KEY_FILE=/path)
-MS365_MCP_ATTACHMENT_URL_KEY_ID=1                    # optional, default 1
+MS365_MCP_ATTACHMENT_URL_KEY=...                     # optional (or _KEY_FILE=/path), see below
+MS365_MCP_ATTACHMENT_URL_KEY_ID=1                    # optional, default 1; needs a key
 MS365_MCP_ATTACHMENT_URL_TTL_S=120                   # optional, default 120, max 300
 ```
 
 `MS365_MCP_ATTACHMENT_URL_BASE` is deliberately **not** `MS365_MCP_PUBLIC_URL`: that one is
 browser-facing, for OAuth redirects, while this is fetched server-to-server and is
 commonly a container address. A missing or malformed setting fails at startup rather than
-per-request — a signing feature that comes up without a key would mint URLs nothing can
-verify, silently.
+per-request.
+
+The signing key is optional. Without one, minted URLs are just `/attachment?t=<ticket>` and
+any HTTP client can fetch them; the ticket alone authorises redemption. Set a key only if
+the fetcher verifies the `dgk`/`dgx`/`dgs` signature (see below), such as a docglean-mcp
+sidecar, which will refuse an unsigned URL. Setting `_KEY_ID` without a key, or a `_KEY_FILE` that is
+empty or unreadable, fails at startup.
 
 ### Splitting the attachment listener
 
@@ -897,9 +909,10 @@ directly.
 `--attachment-host` takes a bare IPv4 address, IPv6 address (bracketed `[::1]` or bare
 `::1`) or hostname. It is refused rather than coerced — `--attachment-host 10.0.0.5:3001`
 is an error naming `--attachment-port`, not a bind to something else. Note that
-`MS365_MCP_ATTACHMENT_URL_BASE` still must not be an IPv6 literal (the URL signature covers
-the host and the two implementations normalise IPv6 differently); if you bind the listener
-to an IPv6 address, name it in the base by hostname.
+with a signing key set, `MS365_MCP_ATTACHMENT_URL_BASE` must not be an IPv6 literal (the URL
+signature covers the host and the two implementations normalise IPv6 differently); if you
+bind the listener to an IPv6 address, name it in the base by hostname. Without a key there
+is no such restriction.
 
 Point `MS365_MCP_ATTACHMENT_URL_BASE` at the attachment port. The server cannot check this
 for you: the base is usually a container name on a network this process cannot resolve, so
@@ -908,7 +921,7 @@ base and the bound port are logged at startup, one line apart, for exactly that
 
 ### The signature, and who checks what
 
-`dgk`/`dgx`/`dgs` are **not** checked by this server on redemption, and that is deliberate.
+This server never checks `dgk`/`dgx`/`dgs` on redemption, and that is deliberate.
 They exist for the fetcher: a document-conversion sidecar that refuses to dial a private
 address unless the URL carries a valid HMAC from an origin it has been configured to trust.
 What authorises redemption _here_ is the ticket. Verifying the signature on the way back in

package/dist/cli.js

@@ -29,7 +29,7 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
   "Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)"
 ).option(
   "--enable-attachment-urls",
-  "HTTP mode only. Let get-download-url mint a short-TTL, single-use URL served by this server for Graph byte resources that expose no pre-authenticated URL of their own (mail and event attachments, meeting recordings, other $value endpoints). Requires MS365_MCP_ATTACHMENT_URL_BASE and MS365_MCP_ATTACHMENT_URL_KEY (or _KEY_FILE)"
+  "HTTP mode only. Let get-download-url mint a short-TTL, single-use URL served by this server for Graph byte resources that expose no pre-authenticated URL of their own (mail and event attachments, meeting recordings, other $value endpoints). Also adds get-download-url to any --preset that lacks it (except teams-write). Requires MS365_MCP_ATTACHMENT_URL_BASE; MS365_MCP_ATTACHMENT_URL_KEY (or _KEY_FILE) is optional and adds an HMAC signature for fetchers that verify one"
 ).option(
   "--attachment-port <port>",
   "HTTP mode only. Serve the attachment download route on its own listener on this port instead of on the MCP app, so a caller that can fetch attachments cannot also reach /mcp. Requires --enable-attachment-urls, and MS365_MCP_ATTACHMENT_URL_BASE must name this port. A separate port only isolates the two surfaces if they also bind separate interfaces \u2014 see --attachment-host. Equivalent env var: MS365_MCP_ATTACHMENT_PORT."
@@ -106,7 +106,9 @@ function parseArgs() {
   if (options.preset) {
     const presetNames = options.preset.split(",").map((p) => p.trim());
     try {
-      options.enabledTools = getCombinedPresetPattern(presetNames);
+      options.enabledTools = getCombinedPresetPattern(presetNames, {
+        attachmentUrls: Boolean(options.http && options.enableAttachmentUrls)
+      });
       const requiresOrgMode = presetNames.some((preset) => presetRequiresOrgMode(preset));
       if (requiresOrgMode && !options.orgMode) {
         console.warn(

package/dist/lib/attachment-tickets.js

@@ -5,6 +5,7 @@ const TICKET_PARAM = "t";
 function buildAttachmentUrl(config, ticketId, nowMs = Date.now()) {
   const url = new URL(ATTACHMENT_ROUTE, config.base);
   url.searchParams.set(TICKET_PARAM, ticketId);
+  if (!config.key) return url.toString();
   return signUrl(
     url.toString(),
     { key: config.key, keyId: config.keyId, ttlSeconds: config.ttlSeconds },

package/dist/lib/attachment-url-config.js

@@ -19,13 +19,20 @@ function pythonStrip(value) {
 function readKey(env) {
   const keyFile = env.MS365_MCP_ATTACHMENT_URL_KEY_FILE;
   if (keyFile) {
+    let key;
     try {
-      return pythonStrip(readFileSync(keyFile, "utf8"));
+      key = pythonStrip(readFileSync(keyFile, "utf8"));
     } catch {
       throw new AttachmentUrlConfigError(
         `MS365_MCP_ATTACHMENT_URL_KEY_FILE could not be read: ${keyFile}`
       );
     }
+    if (!key) {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_KEY_FILE is empty: ${keyFile}. Unset it to mint unsigned URLs.`
+      );
+    }
+    return key;
   }
   return env.MS365_MCP_ATTACHMENT_URL_KEY ?? "";
 }
@@ -50,20 +57,26 @@ function loadAttachmentUrlConfig(enabled, env = process.env) {
       `MS365_MCP_ATTACHMENT_URL_BASE must be http or https, got ${parsedBase.protocol}`
     );
   }
-  if (parsedBase.hostname.startsWith("[")) {
-    throw new AttachmentUrlConfigError(
-      `MS365_MCP_ATTACHMENT_URL_BASE must not be an IPv6 literal: the URL signature covers the host, and this runtime and the verifying sidecar normalise IPv6 spellings differently, so every minted URL would be refused. Use a hostname (a container or service name) instead of ${parsedBase.hostname}.`
-    );
-  }
   if (parsedBase.search || parsedBase.hash) {
     throw new AttachmentUrlConfigError(
       "MS365_MCP_ATTACHMENT_URL_BASE must not carry a query string or fragment."
     );
   }
   const key = readKey(env);
-  if (!key) {
+  if (key && !key.trim()) {
+    throw new AttachmentUrlConfigError(
+      "MS365_MCP_ATTACHMENT_URL_KEY is whitespace only. Set a real key, or unset it to mint unsigned URLs."
+    );
+  }
+  if (key) {
+    if (parsedBase.hostname.startsWith("[")) {
+      throw new AttachmentUrlConfigError(
+        `MS365_MCP_ATTACHMENT_URL_BASE must not be an IPv6 literal: the URL signature covers the host, and this runtime and the verifying sidecar normalise IPv6 spellings differently, so every minted URL would be refused. Use a hostname (a container or service name) instead of ${parsedBase.hostname}.`
+      );
+    }
+  } else if (env.MS365_MCP_ATTACHMENT_URL_KEY_ID) {
     throw new AttachmentUrlConfigError(
-      "--enable-attachment-urls requires MS365_MCP_ATTACHMENT_URL_KEY or MS365_MCP_ATTACHMENT_URL_KEY_FILE -- the HMAC key shared with the sidecar that will verify the minted URL."
+      "MS365_MCP_ATTACHMENT_URL_KEY_ID is set but no signing key is: set MS365_MCP_ATTACHMENT_URL_KEY or MS365_MCP_ATTACHMENT_URL_KEY_FILE, or unset the key id."
     );
   }
   for (let index = 0; index < key.length; index += 1) {
@@ -92,7 +105,7 @@ function loadAttachmentUrlConfig(enabled, env = process.env) {
   }
   return {
     base: parsedBase.origin,
-    key,
+    key: key || void 0,
     keyId,
     ttlSeconds
   };

package/dist/server.js

@@ -730,7 +730,7 @@ class MicrosoftGraphServer {
         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})`
+          `  - Attachment URLs: ${attachmentConfig.base}${ATTACHMENT_ROUTE} (ttl ${attachmentConfig.ttlSeconds}s, ${attachmentConfig.key ? `signed, key id ${attachmentConfig.keyId}` : "unsigned"})`
         );
         if (dedicated) {
           logger.info(

package/dist/tool-categories.js

@@ -101,7 +101,7 @@ const TOOL_CATEGORIES = {
     description: "All available tools"
   }
 };
-function getCombinedPresetPattern(presets) {
+function getCombinedPresetPattern(presets, { attachmentUrls = false } = {}) {
   const patterns = presets.map((preset) => {
     const category = TOOL_CATEGORIES[preset];
     if (!category) {
@@ -111,6 +111,9 @@ function getCombinedPresetPattern(presets) {
     }
     return category.pattern.source;
   });
+  if (attachmentUrls && presets.some((p) => !PRESET_META[p]?.omitUniversalUtilities) && !patterns.some((p) => new RegExp(p).test("get-download-url"))) {
+    patterns.push("^get-download-url$");
+  }
   return patterns.join("|");
 }
 function listPresets() {

package/package.json

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