@softeria/ms-365-mcp-server 0.150.3 → 0.152.0

package/README.md

@@ -598,6 +598,15 @@ When running as an MCP server, the following options can be used:
 --http [port]     Use Streamable HTTP transport instead of stdio (optionally specify port, default: 3000)
                   Starts Express.js server with MCP endpoint at /mcp
 --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")
+--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")
+--attachment-host <host> Interface the --attachment-port listener binds. Defaults to whatever
+                  --http bound, which with a wildcard --http leaves BOTH ports on every
+                  interface and so isolates nothing — set this to make the split real
+                  (requires --attachment-port; see "Splitting the attachment listener")
 --no-dynamic-registration Disable OAuth Dynamic Client Registration (enabled by default in HTTP mode)
 --enabled-tools <pattern> Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)
 --preset <names>  Use preset tool categories (comma-separated). See "Tool Presets" section above
@@ -623,6 +632,8 @@ Environment variables:
 - `MS365_MCP_MESSAGE_SIGNOFF_SUFFIX=<text>`: Signoff appended to outgoing messages. Default: none. CLI equivalent: `--message-signoff-suffix <text>`. `--no-message-signoff` disables both (see Message Signoff below)
 - `MS365_MCP_RATE_LIMIT_DISABLED=true|1`: Disable per-IP rate limiting in HTTP mode (default: enabled — 30 req/min on `/authorize`, `/token`, `/register`; 120 req/min on `/mcp`)
 - `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_CLOUD_TYPE=global|china`: Microsoft cloud environment (alternative to --cloud flag)
 - `LOG_LEVEL`: Set logging level (default: 'info')
 - `SILENT=true|1`: Disable console output
@@ -638,6 +649,167 @@ Environment variables:
 - `MS365_MCP_EXPECTED_USERNAME`: Require local MSAL auth to use this Microsoft account username (case-insensitive; CLI flag takes precedence)
 - `MS365_MCP_EXPECTED_HOME_ACCOUNT_ID`: Require local MSAL auth to use this exact MSAL homeAccountId (CLI flag takes precedence)
 
+## Server-Minted Attachment URLs
+
+`get-download-url` returns Microsoft's own pre-authenticated `@microsoft.graph.downloadUrl`
+for OneDrive and SharePoint items. Graph publishes no such URL for **mail and calendar
+attachments, meeting recordings, or any other `/$value` byte endpoint** — for those, the
+only way to read the bytes has been `download-bytes`, which returns base64 into the
+agent's context. A 73 KB, 3-page PDF costs about 24,500 tokens that way, and the model
+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:
+
+```
+GET /attachment?t=<ticket>&dgk=<key-id>&dgx=<expiry>&dgs=<signature>
+```
+
+The ticket is 32 bytes of CSPRNG output, **single-use**, memory-only, and expires after
+`MS365_MCP_ATTACHMENT_URL_TTL_S` seconds. Redeeming it streams the Graph bytes with this
+server's own token; the fetcher sends no Authorization header and holds no Microsoft
+credential.
+
+**This grants no authority the calling agent did not already have.** Every target that can
+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.
+
+### Configuration
+
+```
+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_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.
+
+### Splitting the attachment listener
+
+By default `/attachment` is served by the same Express app, on the same port, as `/mcp`.
+That is fine when callers are authenticated by a bearer token, and it is a problem when
+they are not. Under `--trust-proxy-auth` the MCP endpoint reads no `Authorization` header
+at all — **reachability is the authentication** — so one shared port means the sidecar you
+allowed through in order to fetch a PDF can also call every tool on the server.
+
+`--attachment-port <port>` (or `MS365_MCP_ATTACHMENT_PORT`) moves the route onto a listener
+of its own, and `--attachment-host <host>` (or `MS365_MCP_ATTACHMENT_HOST`) says which
+interface that listener binds:
+
+```
+ms-365-mcp-server --http 10.89.0.2:3000 --trust-proxy-auth \
+                  --enable-attachment-urls \
+                  --attachment-port 3001 --attachment-host 10.89.1.2
+MS365_MCP_ATTACHMENT_URL_BASE=http://m365-mcp:3001   # note: the attachment port
+```
+
+- `GET /attachment` on **3001** works; on 3000 it is **404** — the MCP app never mounts it.
+- `/mcp` on **3001** is **404**, as is everything else: the second app has the attachment
+  route and nothing more. No OAuth router, no body parsers, no CORS, no health check.
+- The 60 req/min limiter that guards the route follows it onto the new listener.
+- `trust proxy` is **off** on the attachment listener (and `MS365_MCP_TRUST_PROXY_HOPS` is
+  not read for it), unlike the MCP listener, which trusts one hop. This port is meant to be
+  dialled directly on a container network; honouring `X-Forwarded-For` on the server's one
+  uncredentialed surface would let a caller choose its own rate-limit bucket.
+
+The flag requires `--enable-attachment-urls` and refuses to start without it — on its own
+it would open a port with nothing on it while the operator believed the surfaces were
+separated. In stdio mode it warns and is ignored, like the flag it depends on.
+`--attachment-host` likewise requires `--attachment-port`: alone it would name an interface
+for a listener that does not exist.
+
+#### Two ports are not two surfaces unless they bind two interfaces
+
+**This is the part that decides whether any of the above is worth anything.** Read it
+before you deploy the split.
+
+`--attachment-port` on its own separates the two surfaces _inside the process_. It does not
+separate them _on the network_. Without `--attachment-host` the attachment listener inherits
+whatever host `--http` bound — and `--http 3000`, the common form, names no host at all, so
+Node binds the wildcard and **both** ports answer on **every** interface:
+
+```
+ms-365-mcp-server --http 3000 --trust-proxy-auth \
+                  --enable-attachment-urls --attachment-port 3001   # NOT isolated
+```
+
+Container networks grant a peer every port on a container, not one port. Put a
+document-conversion sidecar on a shared bridge so it can fetch `/attachment` on 3001, and
+that same sidecar can dial `:3000/mcp` — which under `--trust-proxy-auth` reads no
+`Authorization` header at all and hands back the full tool catalogue. Nothing fails, nothing
+is logged as an error, and the config looks exactly like the isolated one.
+
+To make it real, give the two listeners **different addresses**, and put only the attachment
+address on the network the fetcher is on:
+
+```yaml
+# docker compose — the MCP port on the agent's own bridge, the attachment port on the
+# bridge shared with the converter. The converter can reach 3001 and cannot route to 3000.
+services:
+  m365-mcp:
+    networks: { agent-net: { ipv4_address: 10.89.0.2 }, convert-net: { ipv4_address: 10.89.1.2 } }
+    command: >
+      --http 10.89.0.2:3000 --trust-proxy-auth
+      --enable-attachment-urls
+      --attachment-port 3001 --attachment-host 10.89.1.2
+  docglean:
+    networks: [convert-net]
+```
+
+The MCP port is then unreachable from `convert-net` **by binding** — there is no socket
+listening on that interface — rather than by a firewall rule that has to keep matching.
+
+The server warns at startup if you run `--trust-proxy-auth` with `--attachment-port` while
+both listeners still answer on a common interface (either sharing an address, or either one
+on the wildcard). Both bound addresses are logged, read back from the socket rather than
+from the flags, so `Server listening on …` and `Attachment listener on …` can be compared
+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.
+
+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
+a wrong port here shows up as a fetch failure in the sidecar, not an error here. Both the
+base and the bound port are logged at startup, one line apart, for exactly that comparison.
+
+### The signature, and who checks what
+
+`dgk`/`dgx`/`dgs` are **not** checked by this server 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
+would prove only that we minted the URL — which the ticket already proves — while coupling
+redemption to the sidecar's clock and to the key surviving a restart.
+
+The wire format is [docglean-mcp](https://github.com/msoukhomlinov/docglean-mcp)'s
+`signing.py` (`canonical_string`), and `src/lib/url-signing.ts` is a port of it. The
+canonical string is `\n`-joined: `v1`, lowercased scheme, lowercased host, the port always
+explicit, the path, the remaining query with `dgk`/`dgx`/`dgs` removed and the rest sorted
+and re-encoded, and the expiry. The test vectors in
+`test/attachment-url-signing.test.ts` were verified against the Python implementation byte
+for byte — three places where the obvious JavaScript disagrees with Python (`!*'()`
+escaping, `+` decoding as a space, and code-point vs UTF-16 sort order) are why that check
+exists rather than being assumed.
+
+The ticket travels in the **query, not the path**, because the verifying sidecar keeps a
+fetched URL's path in its error messages and strips the query.
+
+### Not available in OAuth/OBO mode
+
+Identity there arrives per request on the caller's `Authorization` header, and a ticket is
+redeemed later by a fetcher that sends none. Minting refuses with an explanation rather
+than producing a URL that always fails.
+
 ## Token Storage
 
 Authentication tokens are stored in an encrypted file (AES-256-GCM). Only the 32-byte encryption key goes to the OS credential store via keytar.

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

@@ -42,6 +42,52 @@ describe("GraphClient audit metadata", () => {
     expect(result._meta).toMatchObject({ http_status: 200 });
     expect(JSON.parse(result.content[0].text)).toEqual({ id: "user-1" });
   });
+  it("derives result volume from a collection response", async () => {
+    const body = JSON.stringify({
+      value: [{ id: "m1" }, { id: "m2" }, { id: "m3" }],
+      "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=3"
+    });
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(body, { status: 200, headers: { "content-type": "application/json" } })
+    );
+    const result = await createGraphClient().graphRequest("/me/messages");
+    expect(result._meta).toMatchObject({
+      result_count: 3,
+      result_has_more: true,
+      response_bytes: Buffer.byteLength(body, "utf8")
+    });
+  });
+  it("reports result_has_more false, not absent, for a complete collection", async () => {
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(JSON.stringify({ value: [{ id: "m1" }] }), {
+        status: 200,
+        headers: { "content-type": "application/json" }
+      })
+    );
+    const result = await createGraphClient().graphRequest("/me/messages");
+    expect(result._meta).toMatchObject({ result_count: 1, result_has_more: false });
+  });
+  it("omits result fields for a single-object response but still records size", async () => {
+    const body = JSON.stringify({ id: "user-1" });
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(body, { status: 200, headers: { "content-type": "application/json" } })
+    );
+    const result = await createGraphClient().graphRequest("/me");
+    expect(result._meta).toMatchObject({ response_bytes: Buffer.byteLength(body, "utf8") });
+    expect(result._meta).not.toHaveProperty("result_count");
+    expect(result._meta).not.toHaveProperty("result_has_more");
+  });
+  it("records the pre-base64 byte count for binary content", async () => {
+    const raw = Buffer.from("binary-attachment-payload-\xFF\xFE");
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(raw, {
+        status: 200,
+        headers: { "content-type": "application/octet-stream" }
+      })
+    );
+    const result = await createGraphClient().graphRequest("/me/messages/m1/$value");
+    expect(result._meta).toMatchObject({ response_bytes: raw.byteLength });
+  });
   it("preserves HTTP status metadata when response headers are requested", async () => {
     fetchWithResilienceMock.mockResolvedValue(
       new Response(JSON.stringify({ id: "task-1" }), {

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

@@ -333,6 +333,172 @@ describe("graph-tools", () => {
       );
     });
   });
+  describe("audit response volume", () => {
+    it("lifts result volume from _meta onto the audit event", async () => {
+      const endpoint = makeEndpoint({
+        method: "get",
+        path: "/me/messages",
+        alias: "list-mail-messages"
+      });
+      const config = makeConfig({
+        pathPattern: "/me/messages",
+        method: "get",
+        toolName: "list-mail-messages"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [{ type: "text", text: JSON.stringify({ value: [{ id: "m1" }] }) }],
+          _meta: {
+            http_status: 200,
+            result_count: 4821,
+            result_has_more: true,
+            response_bytes: 8412004
+          }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      await server.tools.get("list-mail-messages").handler({});
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          tool: "list-mail-messages",
+          status: "success",
+          result_count: 4821,
+          result_has_more: true,
+          response_bytes: 8412004
+        })
+      );
+    });
+    it("keeps result_has_more when it is false rather than dropping it", async () => {
+      const endpoint = makeEndpoint({
+        method: "get",
+        path: "/me/messages",
+        alias: "list-mail-messages"
+      });
+      const config = makeConfig({
+        pathPattern: "/me/messages",
+        method: "get",
+        toolName: "list-mail-messages"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [{ type: "text", text: JSON.stringify({ value: [] }) }],
+          _meta: { http_status: 200, result_count: 0, result_has_more: false }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      await server.tools.get("list-mail-messages").handler({});
+      const [payload] = auditLogMock.mock.calls[0];
+      expect(payload.result_count).toBe(0);
+      expect(payload.result_has_more).toBe(false);
+    });
+    it("restates count and bytes for the whole read when pages are merged", async () => {
+      mockEndpoints.push(makeEndpoint());
+      mockEndpointsJson = [makeConfig()];
+      const graphClient = createMockGraphClient([
+        {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                value: [{ id: "1" }, { id: "2" }],
+                "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=2"
+              })
+            }
+          ],
+          _meta: { http_status: 200, result_count: 2, result_has_more: true, response_bytes: 1e3 }
+        },
+        {
+          content: [{ type: "text", text: JSON.stringify({ value: [{ id: "3" }] }) }],
+          _meta: { http_status: 200, result_count: 1, result_has_more: false, response_bytes: 700 }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      await server.tools.get("test-tool").handler({ fetchAllPages: true });
+      const [payload] = auditLogMock.mock.calls[0];
+      expect(payload.result_count).toBe(3);
+      expect(payload.result_has_more).toBe(false);
+      expect(payload.response_bytes).toBe(1700);
+    });
+    it("reports result_has_more when the merge loop stopped on a page cap", async () => {
+      const prevMaxPages = process.env.MS365_MCP_MAX_PAGES;
+      process.env.MS365_MCP_MAX_PAGES = "2";
+      try {
+        mockEndpoints.push(makeEndpoint());
+        mockEndpointsJson = [makeConfig()];
+        const graphClient = createMockGraphClient(
+          Array.from({ length: 5 }, (_, i) => ({
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  value: [{ id: `item-${i}` }],
+                  "@odata.nextLink": `https://graph.microsoft.com/v1.0/me/messages?$skip=${i + 1}`
+                })
+              }
+            ],
+            _meta: { http_status: 200, result_count: 1, result_has_more: true, response_bytes: 50 }
+          }))
+        );
+        const server = createMockServer();
+        const { registerGraphTools } = await loadModule();
+        registerGraphTools(server, graphClient);
+        await server.tools.get("test-tool").handler({ fetchAllPages: true });
+        const [payload] = auditLogMock.mock.calls[0];
+        expect(payload.result_count).toBe(2);
+        expect(payload.result_has_more).toBe(true);
+        expect(payload.response_bytes).toBe(100);
+      } finally {
+        if (prevMaxPages === void 0) {
+          delete process.env.MS365_MCP_MAX_PAGES;
+        } else {
+          process.env.MS365_MCP_MAX_PAGES = prevMaxPages;
+        }
+      }
+    });
+    it("omits the volume fields when the client supplied none", async () => {
+      const endpoint = makeEndpoint({ method: "get", path: "/me", alias: "get-current-user" });
+      const config = makeConfig({
+        pathPattern: "/me",
+        method: "get",
+        toolName: "get-current-user"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [{ type: "text", text: JSON.stringify({ id: "user-1" }) }],
+          _meta: { http_status: 200 }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      await server.tools.get("get-current-user").handler({});
+      const [payload] = auditLogMock.mock.calls[0];
+      expect(payload).not.toHaveProperty("result_count");
+      expect(payload).not.toHaveProperty("result_has_more");
+      expect(payload).not.toHaveProperty("response_bytes");
+    });
+  });
   describe("audit recipient metadata", () => {
     const draftEndpoint = () => {
       const endpoint = makeEndpoint({

package/dist/attachment-route.js

@@ -0,0 +1,112 @@
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import logger from "./logger.js";
+import {
+  isPlainGraphPath,
+  TICKET_PARAM
+} from "./lib/attachment-tickets.js";
+const NOT_FOUND_BODY = "Not found";
+function forceAttachment(header) {
+  if (!header) return "attachment";
+  const params = [];
+  let current = "";
+  let quoted = false;
+  for (let i = 0; i < header.length; i += 1) {
+    const char = header[i];
+    if (quoted && char === "\\" && i + 1 < header.length) {
+      current += char + header[i + 1];
+      i += 1;
+      continue;
+    }
+    if (char === '"') quoted = !quoted;
+    else if (char === ";" && !quoted) {
+      params.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  params.push(current);
+  let filename;
+  let extended;
+  for (const param of params.slice(1)) {
+    const eq = param.indexOf("=");
+    if (eq === -1) continue;
+    const name = param.slice(0, eq).trim().toLowerCase();
+    const value = Array.from(param.slice(eq + 1).trim()).filter((char) => {
+      const code = char.charCodeAt(0);
+      return code > 31 && code !== 127;
+    }).join("");
+    if (!value) continue;
+    if (name === "filename*") extended = value;
+    else if (name === "filename") filename = value;
+  }
+  if (extended) return `attachment; filename*=${extended}`;
+  if (filename) return `attachment; filename=${filename}`;
+  return "attachment";
+}
+function refuse(res) {
+  res.status(404).type("text/plain").send(NOT_FOUND_BODY);
+}
+function createAttachmentHandler(deps) {
+  return async (req, res) => {
+    if (req.method !== "GET") {
+      res.setHeader("allow", "GET");
+      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) {
+      refuse(res);
+      return;
+    }
+    if (!isPlainGraphPath(ticket.target)) {
+      logger.error("Attachment redemption refused: ticket target is not a plain Graph path");
+      refuse(res);
+      return;
+    }
+    const graphClient = deps.getGraphClient();
+    if (!graphClient) {
+      logger.error("Attachment redemption failed: Graph client is not initialised");
+      res.status(503).type("text/plain").send("Service unavailable");
+      return;
+    }
+    let stream;
+    try {
+      let accessToken;
+      if (!deps.authManager.isOAuthModeEnabled()) {
+        accessToken = await deps.authManager.getTokenForAccount(ticket.accountName);
+      }
+      stream = await graphClient.downloadStream(ticket.target, { accessToken });
+    } catch (error) {
+      logger.error(
+        `Attachment redemption failed for ${ticket.target}: ${error.message}`
+      );
+      res.status(502).type("text/plain").send("Upstream fetch failed");
+      return;
+    }
+    res.status(200);
+    res.setHeader("content-type", stream.contentType);
+    if (stream.contentLength !== null) {
+      res.setHeader("content-length", String(stream.contentLength));
+    }
+    res.setHeader("content-disposition", forceAttachment(stream.contentDisposition));
+    res.setHeader("cache-control", "no-store");
+    res.setHeader("x-content-type-options", "nosniff");
+    try {
+      await pipeline(Readable.fromWeb(stream.body), res);
+    } catch (error) {
+      logger.error(`Attachment stream aborted for ${ticket.target}: ${error.message}`);
+      res.destroy();
+    }
+  };
+}
+export {
+  createAttachmentHandler,
+  forceAttachment
+};

package/dist/cli.js

@@ -27,6 +27,15 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
 ).option(
   "--enable-auth-tools",
   "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)"
+).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."
+).option(
+  "--attachment-host <host>",
+  "Interface the --attachment-port listener binds (IPv4, IPv6 or hostname). Defaults to whatever --http bound, which with a wildcard --http means both ports answer on every interface \u2014 so a peer allowed onto the network to fetch attachments can also reach /mcp. Bind this to the address the fetcher uses and --http to a different one to make that unreachable rather than merely un-advertised. Requires --attachment-port. Equivalent env var: MS365_MCP_ATTACHMENT_HOST."
 ).option(
   "--enabled-tools <pattern>",
   'Filter tools using regex pattern (e.g., "excel|contact" to enable Excel and Contact tools)'
@@ -127,6 +136,12 @@ function parseArgs() {
     );
     process.exit(1);
   }
+  if (options.attachmentPort === void 0 && process.env.MS365_MCP_ATTACHMENT_PORT !== void 0) {
+    options.attachmentPort = process.env.MS365_MCP_ATTACHMENT_PORT;
+  }
+  if (options.attachmentHost === void 0 && process.env.MS365_MCP_ATTACHMENT_HOST !== void 0) {
+    options.attachmentHost = process.env.MS365_MCP_ATTACHMENT_HOST;
+  }
   if (options.expectedUsername === void 0 && process.env.MS365_MCP_EXPECTED_USERNAME !== void 0) {
     options.expectedUsername = process.env.MS365_MCP_EXPECTED_USERNAME;
   }

package/dist/graph-client.js

@@ -66,6 +66,13 @@ function extractGraphErrorCodeFromBody(body) {
   const code = isRecord(error) ? error.code : body.code;
   return typeof code === "string" ? code : void 0;
 }
+function extractPayloadMetadata(data) {
+  if (!isRecord(data) || !Array.isArray(data.value)) return {};
+  return {
+    result_count: data.value.length,
+    result_has_more: typeof data["@odata.nextLink"] === "string"
+  };
+}
 function extractBatchMetadata(data) {
   if (!isRecord(data) || !Array.isArray(data.responses)) return {};
   const httpStatusCounts = {};
@@ -125,8 +132,10 @@ class GraphClient {
           contentLength: buffer.byteLength,
           contentBytes: buffer.toString("base64")
         };
+        metadata = { ...metadata, response_bytes: buffer.byteLength };
       } else {
         const text = await response.text();
+        metadata = { ...metadata, response_bytes: Buffer.byteLength(text, "utf8") };
         if (text === "") {
           result = { message: TRANSPORT_OK_MESSAGE };
         } else if (options.rawResponse) {
@@ -142,6 +151,7 @@ class GraphClient {
       if (endpoint === "/$batch") {
         metadata = { ...metadata, ...extractBatchMetadata(result) };
       }
+      metadata = { ...metadata, ...extractPayloadMetadata(result) };
       if (options.includeHeaders) {
         const etag = response.headers.get("ETag") || response.headers.get("etag");
         if (result && typeof result === "object" && !Array.isArray(result)) {
@@ -167,6 +177,55 @@ class GraphClient {
    * memory or hit V8's max string length. Creates the file with wx + 0o600 (never
    * overwrites) and removes a partial file if the transfer fails.
    */
+  /**
+   * Fetch Graph binary content and hand back the undrained response stream.
+   *
+   * Same auth, same resilience and the same error mapping as `downloadToFile`,
+   * which is the reason this exists rather than the attachment route calling
+   * `fetch` for itself: token acquisition, the OBO/bearer context tokens, retry
+   * and the 403-scope special case are all in `performRequest`, which is
+   * private. Splitting them would give the route a second, quietly divergent
+   * copy of the auth path.
+   *
+   * The caller owns the body from here and MUST consume or cancel it -- an
+   * abandoned stream holds a socket open until the agent times out.
+   */
+  async downloadStream(endpoint, options = {}) {
+    const contextTokens = getRequestTokens();
+    const accessToken = options.accessToken ?? contextTokens?.accessToken ?? await this.authManager.getToken();
+    if (!accessToken) {
+      throw new Error("No access token available");
+    }
+    const response = await this.performRequest(endpoint, accessToken, options);
+    if (response.status === 403) {
+      const errorText = await response.text();
+      if (errorText.includes("scope") || errorText.includes("permission")) {
+        throw new Error(
+          `Microsoft Graph API scope error: ${response.status} ${response.statusText} - ${errorText}. This tool requires organization mode. Please restart with --org-mode flag.`
+        );
+      }
+      throw new Error(
+        `Microsoft Graph API error: ${response.status} ${response.statusText} - ${errorText}`
+      );
+    }
+    if (!response.ok) {
+      throw new Error(
+        `Microsoft Graph API error: ${response.status} ${response.statusText} - ${await response.text()}`
+      );
+    }
+    if (!response.body) {
+      throw new Error("Microsoft Graph returned an empty response body");
+    }
+    const rawLength = response.headers.get("content-length");
+    const decoded = response.headers.get("content-encoding") !== null;
+    const declaredLength = !decoded && rawLength !== null && /^\d+$/.test(rawLength.trim());
+    return {
+      body: response.body,
+      contentType: response.headers.get("content-type") || "application/octet-stream",
+      contentLength: declaredLength ? Number(rawLength) : null,
+      contentDisposition: response.headers.get("content-disposition")
+    };
+  }
   async downloadToFile(endpoint, destinationPath, options = {}) {
     const fileHandle = await open(destinationPath, "wx", 384);
     let completed = false;