@softeria/ms-365-mcp-server 0.155.0 → 0.156.0

package/README.md

@@ -610,7 +610,15 @@ When running as an MCP server, the following options can be used:
 -v                Enable verbose logging
 --read-only       Start server in read-only mode, disabling write operations
 --http [port]     Use Streamable HTTP transport instead of stdio (optionally specify port, default: 3000)
-                  Starts Express.js server with MCP endpoint at /mcp
+                  Starts Express.js server with MCP endpoint at /mcp. Bound to a loopback host
+                  (e.g. --http 127.0.0.1:3000 or --http [::1]:3000) with no --public-url, it
+                  rejects requests whose Host or Origin is not localhost (not applied to the
+                  --attachment-port listener)
+--http-local-file-tools Register download-bytes-to-file over HTTP. Anyone who can reach the port
+                  can write files as the server's user (without a valid token, only an empty
+                  file that is removed again), so enable it only on a single-user machine.
+                  Refused unless --http binds a loopback host with no --public-url and no
+                  --trust-proxy-auth
 --enable-auth-tools Enable login/logout tools when using HTTP mode (disabled by default in HTTP mode)
 --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")
@@ -648,6 +656,7 @@ Environment variables:
 - `MS365_MCP_TRUST_PROXY_HOPS=<n>`: Number of trusted reverse-proxy hops in HTTP mode (default `1`). Accurate per-IP rate limiting depends on this matching your deployment — set to the number of proxies in front of the server, `0` to use the raw socket peer IP, or a comma-separated subnet list
 - `MS365_MCP_ATTACHMENT_PORT=<port>`: Serve the attachment route on its own listener on this port (alternative to --attachment-port; requires `--enable-attachment-urls`)
 - `MS365_MCP_ATTACHMENT_HOST=<host>`: Interface the `MS365_MCP_ATTACHMENT_PORT` listener binds (alternative to --attachment-host; requires `--attachment-port`). Defaults to the host `--http` bound — which for a wildcard `--http` means both ports answer everywhere and the port split isolates nothing. See "Splitting the attachment listener"
+- `MS365_MCP_HTTP_LOCAL_FILE_TOOLS=true|1`: Register download-bytes-to-file over HTTP (alternative to --http-local-file-tools; same restrictions)
 - `MS365_MCP_CLOUD_TYPE=global|china`: Microsoft cloud environment (alternative to --cloud flag)
 - `LOG_LEVEL`: Set logging level (default: 'info')
 - `SILENT=true|1`: Disable console output

package/dist/cli.js

@@ -69,6 +69,9 @@ program.name("ms-365-mcp-server").description("Microsoft 365 MCP Server").versio
 ).option(
   "--trust-proxy-auth",
   "In HTTP mode, skip the built-in Bearer-token check on /mcp and ignore any forwarded Authorization header. All callers share the locally cached MSAL identity (same path stdio mode uses). Use only when an upstream reverse proxy has already authenticated the caller."
+).option(
+  "--http-local-file-tools",
+  "In HTTP mode, also register download-bytes-to-file, which writes files on the server as the server's user. Anyone who can reach the port can use it, so enable only on a single-user machine. Refused unless --http binds a loopback host with no --public-url and no --trust-proxy-auth."
 ).option(
   "--allow-unauthenticated-discovery",
   "In HTTP mode, allow MCP discovery requests (initialize, tools/list, prompts/list, resources/list, ping) without a bearer token, so a gateway can enumerate the tool catalog before any user has authenticated. Non-discovery requests (e.g. tools/call) still require a token. Off by default."
@@ -204,6 +207,9 @@ function parseArgs() {
   if (process.env.MS365_MCP_TRUST_PROXY_AUTH === "true" || process.env.MS365_MCP_TRUST_PROXY_AUTH === "1") {
     options.trustProxyAuth = true;
   }
+  if (process.env.MS365_MCP_HTTP_LOCAL_FILE_TOOLS === "true" || process.env.MS365_MCP_HTTP_LOCAL_FILE_TOOLS === "1") {
+    options.httpLocalFileTools = true;
+  }
   if (process.env.MS365_MCP_ALLOW_UNAUTHENTICATED_DISCOVERY === "true" || process.env.MS365_MCP_ALLOW_UNAUTHENTICATED_DISCOVERY === "1") {
     options.allowUnauthenticatedDiscovery = true;
   }

package/dist/graph-tools.js

@@ -699,7 +699,7 @@ const UTILITY_TOOLS = [
     // description at ~40 tokens, so the OneDrive/SharePoint guidance below
     // sits past the cap. That keeps the hint for the reading LLM while letting
     // get-download-url own the high-signal "drive"/"sharepoint" search terms.
-    description: "Write authenticated Microsoft Graph byte content to a local file on the server, returning { path, contentType, bytesWritten } instead of base64. The only out-of-band way to save mail attachments and meeting recordings, whose bytes are exposed solely through authenticated endpoints. Also handles profile photos and Teams hosted content. Writes to an absolute outputPath and never overwrites an existing file. stdio mode only: not available over HTTP. For OneDrive or SharePoint file content, get-download-url is preferred \u2014 it returns a pre-authenticated URL for fully out-of-band download without the server fetching the bytes.",
+    description: "Write authenticated Microsoft Graph byte content to a local file on the server, returning { path, contentType, bytesWritten } instead of base64. The only out-of-band way to save mail attachments and meeting recordings, whose bytes are exposed solely through authenticated endpoints. Also handles profile photos and Teams hosted content. Writes to an absolute outputPath and never overwrites an existing file. stdio mode, or HTTP with --http-local-file-tools. For OneDrive or SharePoint file content, get-download-url is preferred \u2014 it returns a pre-authenticated URL for fully out-of-band download without the server fetching the bytes.",
     readOnlyHint: true,
     openWorldHint: true,
     stdioOnly: true,

package/dist/mcp-instructions.js

@@ -6,7 +6,7 @@ function buildGeneralMcpInstructions(opts) {
     "When you need an organizational user or recipient address, resolve it with list-users (or another directory tool); do not invent SMTP addresses.",
     "Directory $search on collections such as /users or /groups requires ConsistencyLevel: eventual when the tool exposes that header.",
     "Teams chat and channel messages: prefer HTML contentType in the body; plain text is often mangled by Graph.",
-    "Files / binary content: for large drive/SharePoint file content, prefer get-download-url to resolve a pre-authenticated URL for out-of-band download. Use download-bytes for authenticated byte reads such as mail attachments, profile photos, Teams hosted content, and meeting recordings. In stdio mode, download-bytes-to-file writes those same authenticated bytes straight to a local absolute path instead of returning base64 \u2014 the only out-of-band option for large mail attachments and meeting recordings, which get-download-url cannot handle. These tools take relative Microsoft Graph paths, not absolute URLs. For uploads, upload-file-content takes a base64 string body (Graph allows 250MB, but the whole string passes through the agent context and a truncated one is written without error); use create-upload-session for anything but small files."
+    "Files / binary content: for large drive/SharePoint file content, prefer get-download-url to resolve a pre-authenticated URL for out-of-band download. Use download-bytes for authenticated byte reads such as mail attachments, profile photos, Teams hosted content, and meeting recordings. In stdio mode (or HTTP with --http-local-file-tools), download-bytes-to-file writes those same authenticated bytes straight to a local absolute path instead of returning base64 \u2014 the only out-of-band option for large mail attachments and meeting recordings, which get-download-url cannot handle. These tools take relative Microsoft Graph paths, not absolute URLs. For uploads, upload-file-content takes a base64 string body (Graph allows 250MB, but the whole string passes through the agent context and a truncated one is written without error); use create-upload-session for anything but small files."
   ];
   if (opts.readOnly) parts.push("This server is read-only; write operations are disabled.");
   if (opts.multiAccount)

package/dist/server.js

@@ -36,11 +36,40 @@ import { dumpError } from "./crash-logging.js";
 import crypto from "node:crypto";
 import { isIP, isIPv6 } from "node:net";
 import OboClient from "./obo-client.js";
+import { hostHeaderValidation } from "@modelcontextprotocol/sdk/server/middleware/hostHeaderValidation.js";
+const LOOPBACK_HOSTNAMES = ["localhost", "127.0.0.1", "[::1]"];
+function isLoopbackHost(host) {
+  if (!host) return false;
+  const bare = host.toLowerCase().replace(/^\[(.*)\]$/, "$1");
+  return bare === "localhost" || bare === "127.0.0.1" || bare === "::1";
+}
+function loopbackOriginValidation() {
+  return (req, res, next) => {
+    const origin = req.headers.origin;
+    if (origin === void 0) return next();
+    let hostname;
+    try {
+      hostname = new URL(origin).hostname;
+    } catch {
+      hostname = void 0;
+    }
+    if (hostname && LOOPBACK_HOSTNAMES.includes(hostname)) return next();
+    res.status(403).json({
+      jsonrpc: "2.0",
+      error: { code: -32e3, message: `Invalid Origin: ${origin}` },
+      id: null
+    });
+  };
+}
 function parseHttpOption(httpOption) {
   if (typeof httpOption === "boolean") {
     return { host: void 0, port: 3e3 };
   }
   const httpString = httpOption.trim();
+  const bracketed = /^\[([^\]]+)\](?::(.*))?$/.exec(httpString);
+  if (bracketed) {
+    return { host: bracketed[1], port: parseInt(bracketed[2] ?? "") || 3e3 };
+  }
   if (httpString.includes(":")) {
     const [hostPart, portPart] = httpString.split(":");
     const host = hostPart || void 0;
@@ -131,6 +160,14 @@ class MicrosoftGraphServer {
     this.secrets = null;
     this.oboClient = null;
   }
+  isLoopbackOnlyHttp() {
+    if (!this.options.http) return false;
+    const publicUrl = this.options.publicUrl || process.env.MS365_MCP_PUBLIC_URL || this.options.baseUrl || process.env.MS365_MCP_BASE_URL;
+    return !publicUrl && isLoopbackHost(parseHttpOption(this.options.http).host);
+  }
+  hidesStdioOnlyTools() {
+    return Boolean(this.options.http) && !this.options.httpLocalFileTools;
+  }
   createMcpServer() {
     const server = new McpServer(
       {
@@ -161,7 +198,7 @@ class MicrosoftGraphServer {
         this.accountNames,
         this.options.enabledTools,
         this.options.allowedScopes,
-        Boolean(this.options.http)
+        this.hidesStdioOnlyTools()
       );
     } else {
       registerGraphTools(
@@ -174,7 +211,7 @@ class MicrosoftGraphServer {
         this.multiAccount,
         this.accountNames,
         this.options.allowedScopes,
-        Boolean(this.options.http)
+        this.hidesStdioOnlyTools()
       );
     }
     installToolSchemaRefNormalization(server);
@@ -202,6 +239,25 @@ class MicrosoftGraphServer {
         'Account routing disabled: requests use the OAuth bearer identity, so the "account" parameter is not injected into tool schemas'
       );
     }
+    if (this.options.httpLocalFileTools && this.options.http) {
+      if (!this.isLoopbackOnlyHttp()) {
+        throw new Error(
+          "--http-local-file-tools requires --http bound to a loopback host (localhost, 127.0.0.1 or [::1]) and no --public-url: anyone who can reach the port can write files as the server's user."
+        );
+      }
+      if (this.options.trustProxyAuth) {
+        throw new Error(
+          "--http-local-file-tools cannot be combined with --trust-proxy-auth: a proxy in front of the loopback port would let remote callers write files as the server's user."
+        );
+      }
+      logger.warn(
+        "--http-local-file-tools: download-bytes-to-file is registered over HTTP; anyone who can reach this port can write files as the server's user."
+      );
+    } else if (this.options.httpLocalFileTools) {
+      logger.warn(
+        "--http-local-file-tools has no effect in stdio mode, where download-bytes-to-file is always registered."
+      );
+    }
     if (this.options.obo) {
       if (!this.options.http) {
         throw new Error("--obo requires --http (On-Behalf-Of flow only works in HTTP mode).");
@@ -267,6 +323,10 @@ class MicrosoftGraphServer {
     if (this.options.http) {
       const { host, port } = parseHttpOption(this.options.http);
       const app = express();
+      if (this.isLoopbackOnlyHttp()) {
+        app.use(hostHeaderValidation(LOOPBACK_HOSTNAMES));
+        app.use(loopbackOriginValidation());
+      }
       const trustProxyEnv = process.env.MS365_MCP_TRUST_PROXY_HOPS;
       if (trustProxyEnv !== void 0 && trustProxyEnv !== "") {
         const asNum = Number(trustProxyEnv);
@@ -803,6 +863,9 @@ class MicrosoftGraphServer {
 var server_default = MicrosoftGraphServer;
 export {
   server_default as default,
+  isLoopbackHost,
+  loopbackOriginValidation,
   parseAttachmentHostOption,
-  parseAttachmentPortOption
+  parseAttachmentPortOption,
+  parseHttpOption
 };

package/package.json

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