@softeria/ms-365-mcp-server 0.156.2 → 0.157.1

package/README.md

@@ -691,8 +691,8 @@ 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
+`MS365_MCP_ATTACHMENT_URL_TTL_S` seconds. Redeeming it streams the Graph bytes as the
+identity that minted it; 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
@@ -829,11 +829,26 @@ 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
+### Whose identity the bytes are read as
 
-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.
+Under `--trust-proxy-auth` the server reads with its own cached account, and redemption
+looks that account up again.
+
+In plain `--http` and `--obo`, identity arrives per request on the caller's
+`Authorization` header, and a ticket is redeemed later by a fetcher that sends none. So
+the ticket keeps the Graph token the minting request used (the exchanged one, under
+`--obo`) and redemption reads with that token and nothing else. It stays in server memory
+and is never part of the URL.
+
+With `MS365_MCP_OAUTH_TOKEN` set, the ticket keeps that token instead, `--trust-proxy-auth`
+or not.
+
+A token kept this way cannot be refreshed. If it expires before the URL is fetched,
+redemption answers 502. The agent can mint again once its client has a fresh token; an
+expired `MS365_MCP_OAUTH_TOKEN` has to be replaced by the operator.
+
+Tickets live in the memory of the process that minted them, so a URL has to be redeemed
+on the same instance. Behind a load balancer that means one replica or sticky routing.
 
 ## Token Storage
 

package/dist/attachment-route.js

@@ -78,10 +78,8 @@ function createAttachmentHandler(deps) {
     }
     let stream;
     try {
-      let accessToken;
-      if (!deps.authManager.isOAuthModeEnabled()) {
-        accessToken = await deps.authManager.getTokenForAccount(ticket.accountName);
-      }
+      const accessToken = ticket.kind === "request-token" ? ticket.accessToken : await deps.authManager.getTokenForAccount(ticket.accountName);
+      if (!accessToken) throw new Error("No access token for this ticket");
       stream = await graphClient.downloadStream(ticket.target, { accessToken });
     } catch (error) {
       logger.error(

package/dist/graph-tools.js

@@ -529,13 +529,15 @@ async function checkAccountParamInBearerMode(accountParam, authManager) {
 async function mintDownloadUrl(target, accountParam, authManager) {
   const minting = getAttachmentMinting();
   if (!minting) return null;
-  if (authManager?.isOAuthModeEnabled() || getRequestTokens()) {
+  const identityFromRequest = Boolean(authManager?.isOAuthModeEnabled() || getRequestTokens());
+  const requestToken = identityFromRequest ? getRequestTokens()?.accessToken ?? await authManager?.getToken().catch(() => null) ?? void 0 : void 0;
+  if (identityFromRequest && !requestToken) {
     return {
       content: [
         {
           type: "text",
           text: JSON.stringify({
-            error: "Server-minted download URLs are unavailable when Graph identity comes from the request (OAuth, OBO, or bearer mode): the URL is redeemed later without an Authorization header, so the bytes would be fetched as a different identity than the one that asked for them. Use download-bytes."
+            error: "No Graph access token is available for this request, so no download URL can be minted. Use download-bytes."
           })
         }
       ],
@@ -564,7 +566,7 @@ async function mintDownloadUrl(target, accountParam, authManager) {
   }
   let ticket;
   try {
-    ticket = minting.store.mint(target, accountParam);
+    ticket = requestToken ? minting.store.mintWithToken(target, requestToken) : minting.store.mint(target, accountParam);
   } catch (error) {
     if (error instanceof TicketStoreFullError) {
       return {
@@ -846,7 +848,7 @@ const UTILITY_TOOLS = [
     buildSchema: (ctx) => {
       const schema = {
         target: z.string().describe(
-          'Relative Microsoft Graph path starting with "/". Either a driveItem content path or the item path itself, e.g. /drives/{drive-id}/items/{driveItem-id}/content, /me/drive/items/{driveItem-id}/content, or /sites/{site-id}/drive/items/{driveItem-id}. A trailing /content is optional and is stripped automatically for drive items. Mail attachment $value paths and meeting recordings are not supported (Graph exposes no pre-authenticated URL for them).'
+          'Relative Microsoft Graph path starting with "/". Either a driveItem content path or the item path itself, e.g. /drives/{drive-id}/items/{driveItem-id}/content, /me/drive/items/{driveItem-id}/content, or /sites/{site-id}/drive/items/{driveItem-id}. A trailing /content is optional and is stripped automatically for drive items. Mail attachment $value paths and meeting recordings are accepted on a server running with --enable-attachment-urls.'
         )
       };
       if (ctx.multiAccount) {

package/dist/lib/attachment-tickets.js

@@ -44,16 +44,25 @@ class AttachmentTicketStore {
       if (ticket.expiresAtMs <= nowMs) this.tickets.delete(id);
     }
   }
-  mint(target, accountName, nowMs = Date.now()) {
+  add(target, identity, nowMs) {
     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, { target, accountName, expiresAtMs });
+    this.tickets.set(id, { ...identity, target, expiresAtMs });
     return { id, expiresAtMs };
   }
+  /** Mint a ticket redeemed with this server's own token for `accountName`. */
+  mint(target, accountName, nowMs = Date.now()) {
+    return this.add(target, { kind: "server-account", accountName }, nowMs);
+  }
+  /** Mint a ticket redeemed with `accessToken` and nothing else. */
+  mintWithToken(target, accessToken, nowMs = Date.now()) {
+    if (!accessToken) throw new Error("A request-token ticket needs a token");
+    return this.add(target, { kind: "request-token", accessToken }, nowMs);
+  }
   /**
    * Return the ticket and burn it, or undefined.
    *

package/dist/lib/microsoft-auth.js

@@ -169,7 +169,7 @@ function unwrapToken(result, failureMessage) {
   logger.error(`${failureMessage}: ${result.raw}`);
   throw new Error(`${failureMessage}: ${result.raw}`);
 }
-async function exchangeCodeForToken(code, redirectUri, clientId, clientSecret, tenantId = "common", codeVerifier, cloudType = "global") {
+async function exchangeCodeForToken(code, redirectUri, clientId, clientSecret, tenantId = "common", codeVerifier, cloudType = "global", scope) {
   const cloudEndpoints = getCloudEndpoints(cloudType);
   const params = new URLSearchParams({
     grant_type: "authorization_code",
@@ -180,6 +180,9 @@ async function exchangeCodeForToken(code, redirectUri, clientId, clientSecret, t
   if (codeVerifier) {
     params.append("code_verifier", codeVerifier);
   }
+  if (scope) {
+    params.append("scope", scope);
+  }
   return requestToken(
     `${cloudEndpoints.authority}/${tenantId}/oauth2/v2.0/token`,
     params,
@@ -187,13 +190,16 @@ async function exchangeCodeForToken(code, redirectUri, clientId, clientSecret, t
     "Failed to exchange code for token"
   );
 }
-async function refreshAccessToken(refreshToken, clientId, clientSecret, tenantId = "common", cloudType = "global") {
+async function refreshAccessToken(refreshToken, clientId, clientSecret, tenantId = "common", cloudType = "global", scope) {
   const cloudEndpoints = getCloudEndpoints(cloudType);
   const params = new URLSearchParams({
     grant_type: "refresh_token",
     refresh_token: refreshToken,
     client_id: clientId
   });
+  if (scope) {
+    params.append("scope", scope);
+  }
   return requestToken(
     `${cloudEndpoints.authority}/${tenantId}/oauth2/v2.0/token`,
     params,

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 (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."
+    "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. For large mail attachments and meeting recordings that is one out-of-band option; get-download-url is the other, on a server running with --enable-attachment-urls. 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

@@ -217,6 +217,17 @@ class MicrosoftGraphServer {
     installToolSchemaRefNormalization(server);
     return server;
   }
+  /**
+   * Under --obo the token Entra issues to the MCP client is for this app
+   * itself (`<clientId>/access_as_user`). Personal Microsoft accounts refuse
+   * to redeem a code or refresh token for that audience unless the request
+   * names the scope (AADSTS70011), so both /token grants send it in OBO mode.
+   * Outside OBO the request is unchanged.
+   */
+  oboRedemptionScope() {
+    if (!this.options.obo || !this.secrets?.clientId) return void 0;
+    return `${this.secrets.clientId}/access_as_user offline_access`;
+  }
   async initialize(version) {
     this.secrets = await getSecrets();
     this.version = version;
@@ -582,7 +593,8 @@ class MicrosoftGraphServer {
               clientSecret,
               tenantId,
               matchedPkceEntry?.serverCodeVerifier || body.code_verifier,
-              this.secrets.cloudType
+              this.secrets.cloudType,
+              this.oboRedemptionScope()
             );
             if (matchedPkceState && this.pkceStore.get(matchedPkceState) === matchedPkceEntry) {
               this.pkceStore.delete(matchedPkceState);
@@ -602,7 +614,8 @@ class MicrosoftGraphServer {
               clientId,
               clientSecret,
               tenantId,
-              this.secrets.cloudType
+              this.secrets.cloudType,
+              this.oboRedemptionScope()
             );
             res.json(result);
           } else {
@@ -692,12 +705,6 @@ class MicrosoftGraphServer {
         }
       );
       const attachmentConfig = loadAttachmentUrlConfig(Boolean(this.options.enableAttachmentUrls));
-      const mintingAlwaysRefused = this.authManager?.isOAuthModeEnabled() === true || !this.options.trustProxyAuth;
-      if (attachmentConfig && mintingAlwaysRefused) {
-        logger.warn(
-          "--enable-attachment-urls is on, but this server takes its Graph identity from the request in plain --http mode, and minting is refused whenever it does (the URL is redeemed later with no Authorization header, so the bytes would be fetched as a different identity). get-download-url will keep answering with download-bytes. Server-minted URLs need --trust-proxy-auth, where the server uses its own token."
-        );
-      }
       let attachmentApp = null;
       if (attachmentConfig) {
         const ticketStore = new AttachmentTicketStore(attachmentConfig.ttlSeconds);

package/package.json

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