@softeria/ms-365-mcp-server 0.146.2 → 0.148.0

package/README.md

@@ -667,6 +667,20 @@ Parent directories are created automatically. Files are written with `0600` perm
 
 **Without a credential store** (headless Linux, most containers) the key is written to `.cache-key` next to the cache file, with `0600` permissions. That stops the tokens showing up in a stray `cat`, a backup or an accidental commit. It does not protect against anyone who can already read the directory - the key is right there. Use `MS365_MCP_AUTH_CACHE_COMMAND` below if you need the cache in a real secret store.
 
+**Skipping the credential store on purpose:**
+
+```bash
+export MS365_MCP_USE_KEYTAR=0   # also accepts false, no or off
+```
+
+The key then goes to `.cache-key` on every platform, exactly as it does where no credential store exists, and nothing in the server calls keytar. Useful when the credential store prompts on each start - macOS re-asks whenever the calling binary changes, which under `npx` is every version bump - or when the native module misbehaves on your platform rather than simply failing to load. Any other value leaves the credential store in use, and an unrecognised one is warned about rather than passed over silently.
+
+Switching it off strands a cache that was encrypted under a key already in the credential store, since nothing can reach that key any more. The server says so and replaces that cache on the next sign-in, which signs out **every** account it held, not just the one you sign back in as. Unset the variable first if that cache is worth keeping.
+
+Only a cache that nothing on the machine can open is replaced. One that fails to decrypt while a usable key is sitting right there - a truncated file, a downgrade to an older build, a cache from somewhere else - is damage rather than a stranded cache, and is left alone exactly as it is by default.
+
+Two things it deliberately does not do. It never deletes what this server already put in the credential store, on logout or otherwise, because reaching the store is the thing you just asked it to stop doing - clear the `ms-365-mcp-server` entries by hand if you want them gone. And a `.cache-key` that exists but cannot be read (wrong owner on a bind-mounted config directory, say) is treated as recoverable rather than missing: the server refuses both to overwrite a cache and to mint a replacement key, and says so, rather than deleting a key that would work again once the permissions are fixed. Fix the permissions, or delete `.cache-key` yourself to start over - which does mean signing in again.
+
 If the cache cannot be decrypted - key lost, keychain locked, file modified - you are asked to sign in again rather than the server failing to start. The cache file is left exactly as it was: not deleted, and not overwritten by that new sign-in either. A keychain that is merely locked usually reads fine on the next start, and the cache is still there when it does.
 
 The cost is that the new session is not saved while this lasts, so each start asks you to sign in again. If the key is genuinely gone and the cache will never open, delete `.token-cache.json` to start over - the log says so, and names the path.

package/dist/endpoints.json

@@ -165,6 +165,38 @@
     "workScopes": ["Mail.Send.Shared"],
     "llmTip": "Forward a message from a shared mailbox preserving full HTML formatting and attachments. The 'user-id' is the shared mailbox email address. 'toRecipients' is required. The 'comment' field adds text above the forwarded content. Requires Send As permission on the shared mailbox in Exchange."
   },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/createReply",
+    "method": "post",
+    "toolName": "create-shared-mailbox-reply-draft",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"],
+    "llmTip": "Create a reply draft in a shared mailbox preserving thread metadata (conversationId, In-Reply-To, References). The 'user-id' is the shared mailbox email address (e.g. support@contoso.com). Does not send — use send-shared-mailbox-draft to send afterwards. For HTML replies pass Message.body.contentType: 'html' with Message.body.content as HTML. Specifying both 'comment' and Message.body returns 400. Requires delegated access to the shared mailbox."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/createReplyAll",
+    "method": "post",
+    "toolName": "create-shared-mailbox-reply-all-draft",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"],
+    "llmTip": "Create a reply-all draft in a shared mailbox preserving thread metadata (conversationId, In-Reply-To, References). The 'user-id' is the shared mailbox email address. Does not send — use send-shared-mailbox-draft to send afterwards. For HTML replies pass Message.body.contentType: 'html' with Message.body.content as HTML. Specifying both 'comment' and Message.body returns 400. Requires delegated access to the shared mailbox."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/createForward",
+    "method": "post",
+    "toolName": "create-shared-mailbox-forward-draft",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"],
+    "llmTip": "Create a forward draft in a shared mailbox without sending. The 'user-id' is the shared mailbox email address. Does not send — use send-shared-mailbox-draft to send afterwards. Useful when the user wants to review before the forward goes out. Requires delegated access to the shared mailbox."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/send",
+    "method": "post",
+    "toolName": "send-shared-mailbox-draft",
+    "presets": ["work"],
+    "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",
     "method": "get",

package/dist/generated/client.js

@@ -15252,6 +15252,64 @@ Only the policyViolation property of a chatMessage can be updated in application
     ],
     response: z.void()
   },
+  {
+    method: "post",
+    path: "/users/:userId/messages/:messageId/createForward",
+    alias: "create-shared-mailbox-forward-draft",
+    description: `Create a shared mailbox forward draft.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `Action parameters`,
+        type: "Body",
+        schema: create_forward_draft_Body
+      }
+    ],
+    response: z.void()
+  },
+  {
+    method: "post",
+    path: "/users/:userId/messages/:messageId/createReply",
+    alias: "create-shared-mailbox-reply-draft",
+    description: `Create a draft to reply to the sender of a message in either JSON or MIME format. When using JSON format:
+- Specify either a comment or the body property of the message parameter. Specifying both will return an HTTP 400 Bad Request error.
+- If replyTo is specified in the original message, per Internet Message Format (RFC 2822), you should send the reply to the recipients in replyTo, and not the recipients in from.
+- You can update the draft later to add reply content to the body or change other message properties. When using MIME format:
+- Provide the applicable Internet message headers and the MIME content, all encoded in base64 format in the request body.
+- Add any attachments and S/MIME properties to the MIME content. Send the draft message in a subsequent operation. Alternatively, reply to a message in a single operation.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `Action parameters`,
+        type: "Body",
+        schema: create_reply_draft_Body
+      }
+    ],
+    response: z.void()
+  },
+  {
+    method: "post",
+    path: "/users/:userId/messages/:messageId/createReplyAll",
+    alias: "create-shared-mailbox-reply-all-draft",
+    description: `Create a draft to reply to the sender and all recipients of a message in either JSON or MIME format. When using JSON format:
+- Specify either a comment or the body property of the message parameter. Specifying both will return an HTTP 400 Bad Request error.
+- If the original message specifies a recipient in the replyTo property, per Internet Message Format (RFC 2822), you should send the reply to the recipients in the replyTo and toRecipients properties, and not the recipients in the from and toRecipients properties.
+- You can update the draft later to add reply content to the body or change other message properties. When using MIME format:
+- Provide the applicable Internet message headers and the MIME content, all encoded in base64 format in the request body.
+- Add any attachments and S/MIME properties to the MIME content. Send the draft message in a subsequent operation. Alternatively, reply-all to a message in a single action.`,
+    requestFormat: "json",
+    parameters: [
+      {
+        name: "body",
+        description: `Action parameters`,
+        type: "Body",
+        schema: create_reply_draft_Body
+      }
+    ],
+    response: z.void()
+  },
   {
     method: "post",
     path: "/users/:userId/messages/:messageId/forward",
@@ -15328,6 +15386,14 @@ Only the policyViolation property of a chatMessage can be updated in application
     ],
     response: z.void()
   },
+  {
+    method: "post",
+    path: "/users/:userId/messages/:messageId/send",
+    alias: "send-shared-mailbox-draft",
+    description: `Send an existing draft message. The draft message can be a new message draft, reply draft, reply-all draft, or a forward draft. This method saves the message in the Sent Items folder. Alternatively, send a new message in a single operation.`,
+    requestFormat: "json",
+    response: z.void()
+  },
   {
     method: "get",
     path: "/users/:userId/presence",

package/dist/token-cache-storage.js

@@ -18,6 +18,7 @@ const TOKEN_CACHE_ACCOUNT = "msal-token-cache";
 const SELECTED_ACCOUNT_KEY = "selected-account";
 const AUTH_CACHE_COMMAND_ENV = "MS365_MCP_AUTH_CACHE_COMMAND";
 const AUTH_CACHE_COMMAND_TIMEOUT_ENV = "MS365_MCP_AUTH_CACHE_COMMAND_TIMEOUT_MS";
+const USE_KEYTAR_ENV = "MS365_MCP_USE_KEYTAR";
 const DEFAULT_AUTH_CACHE_COMMAND_TIMEOUT_MS = 1e4;
 const STDERR_LIMIT = 2048;
 const COMMAND_KILL_GRACE_MS = 1e3;
@@ -28,7 +29,33 @@ const CACHE_KEY_FILE = ".cache-key";
 const __filename = fileURLToPath(import.meta.url);
 const LEGACY_DIR = path.join(path.dirname(__filename), "..");
 let keytar = null;
+let loggedKeytarOptOut = false;
+let warnedKeytarValue = false;
+const KEYTAR_OFF_VALUES = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+const KEYTAR_ON_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+function keytarEnabled() {
+  const raw = process.env[USE_KEYTAR_ENV];
+  if (raw === void 0) return true;
+  const value = raw.trim().toLowerCase();
+  if (KEYTAR_OFF_VALUES.has(value)) return false;
+  if (value !== "" && !KEYTAR_ON_VALUES.has(value) && !warnedKeytarValue) {
+    warnedKeytarValue = true;
+    logger.warn(
+      `${USE_KEYTAR_ENV} is set to ${JSON.stringify(raw)}, which is not a value this understands, so the system credential store stays in use. Set it to one of ${[...KEYTAR_OFF_VALUES].join(", ")} to turn it off.`
+    );
+  }
+  return true;
+}
 async function getKeytar() {
+  if (!keytarEnabled()) {
+    if (!loggedKeytarOptOut) {
+      loggedKeytarOptOut = true;
+      logger.info(
+        `${USE_KEYTAR_ENV} is off, using file-based credential storage. Anything this server previously stored under "${SERVICE_NAME}" in the system credential store is now left alone, including on logout, so clear it by hand if you want it gone.`
+      );
+    }
+    return null;
+  }
   if (keytar === void 0) {
     return null;
   }
@@ -172,6 +199,7 @@ function writeFileAtomically(filePath, value) {
 }
 let keyStatePromise;
 let encryptionKeyPromise;
+const mintedKeys = [];
 const legacyKeytarEntries = /* @__PURE__ */ new Set();
 const warnedUndecryptable = /* @__PURE__ */ new Set();
 function resetCacheKeyForTests() {
@@ -180,6 +208,9 @@ function resetCacheKeyForTests() {
   legacyKeytarEntries.clear();
   warnedUndecryptable.clear();
   legacyPathsMigrated = false;
+  loggedKeytarOptOut = false;
+  warnedKeytarValue = false;
+  mintedKeys.length = 0;
 }
 async function clearLegacyKeytarEntry(key) {
   if (!legacyKeytarEntries.delete(key)) return;
@@ -222,16 +253,26 @@ async function readCacheKeys() {
     }
   }
   let fileKeyIndex;
+  let fileKeyUnreadable = false;
   const keyPath = getCacheKeyPath();
-  if (existsSync(keyPath)) {
+  let raw;
+  try {
+    raw = readFileSync(keyPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      fileKeyUnreadable = true;
+      logger.warn(`Could not read the auth cache key file: ${error.message}`);
+    }
+  }
+  if (raw !== void 0) {
     try {
-      keys.push(parseCacheKey(readFileSync(keyPath, "utf8")));
+      keys.push(parseCacheKey(raw));
       fileKeyIndex = keys.length - 1;
     } catch (error) {
       logger.warn(`Ignoring unusable auth cache key file: ${error.message}`);
     }
   }
-  return { keys, fileKeyIndex, canUseKeychain };
+  return { keys, fileKeyIndex, canUseKeychain, fileKeyUnreadable };
 }
 function getEncryptionKey() {
   if (!encryptionKeyPromise) {
@@ -247,7 +288,13 @@ async function resolveEncryptionKey() {
   const state = await loadKeyState();
   const preferred = state.keys[state.fileKeyIndex ?? 0];
   if (preferred) return preferred;
+  if (state.fileKeyUnreadable) {
+    throw new Error(
+      `Refusing to replace the auth cache key at ${getCacheKeyPath()}: it exists but could not be read this run, and minting over it would strand every cache encrypted under it. Fix the permissions on that file, or delete it to start over.`
+    );
+  }
   const minted = await persistCacheKey(generateCacheKey(), state.canUseKeychain);
+  if (!mintedKeys.some((k) => k.equals(minted))) mintedKeys.push(minted);
   state.keys.unshift(minted);
   if (state.fileKeyIndex !== void 0) state.fileKeyIndex += 1;
   return minted;
@@ -278,8 +325,16 @@ async function persistCacheKey(key, canUseKeychain) {
     );
     return key;
   }
+  let existingRaw;
+  try {
+    existingRaw = readFileSync(keyPath, "utf8");
+  } catch (readError) {
+    throw new Error(
+      `Refusing to replace the auth cache key file at ${keyPath}: it could not be read (${readError.message}), so whether it holds a usable key is unknown.`
+    );
+  }
   try {
-    const existing = parseCacheKey(readFileSync(keyPath, "utf8"));
+    const existing = parseCacheKey(existingRaw);
     logger.info("Another process created the auth cache key file first, adopting it");
     return existing;
   } catch (parseError) {
@@ -333,12 +388,17 @@ async function readCacheFile(key, cachePath) {
   }
   if (onDisk === "") return { status: "absent" };
   if (isEncryptedCache(onDisk)) {
-    const { keys } = await loadKeyState();
-    const decrypted = decryptWithAnyKey(onDisk, keys, key);
+    const state = await loadKeyState();
+    const decrypted = decryptWithAnyKey(onDisk, state.keys, key);
     if (decrypted !== void 0) return { status: "decrypted", raw: decrypted };
     keyStatePromise = void 0;
     encryptionKeyPromise = void 0;
-    return { status: "unreadable", reason: "no known key opens it" };
+    const preExisting = state.keys.filter((k) => !mintedKeys.some((m) => m.equals(k)));
+    return {
+      status: "unreadable",
+      reason: state.fileKeyUnreadable ? "a key file is present but could not be read" : preExisting.length > 0 ? "the keys on hand do not open it" : "no known key opens it",
+      noKeyMatched: preExisting.length === 0 && !state.fileKeyUnreadable
+    };
   }
   if (isPlainCacheJson(onDisk)) return { status: "plaintext", raw: onDisk };
   return { status: "unreadable", reason: "not a recognisable auth cache" };
@@ -366,6 +426,15 @@ async function assertOverwritable(key, cachePath) {
     warnedUndecryptable.delete(key);
     return;
   }
+  if (state.noKeyMatched && !keytarEnabled()) {
+    if (!warnedUndecryptable.has(key)) {
+      warnedUndecryptable.add(key);
+      logger.warn(
+        `Replacing ${cachePath}: there is no auth cache key on this machine to open it with, and ${USE_KEYTAR_ENV} is off, so the key it was written under is most likely the one in the system credential store. Signing in again rewrites it against the key file instead. If that cache is worth keeping, stop the server and unset ${USE_KEYTAR_ENV} before signing in.`
+      );
+    }
+    return;
+  }
   if (!warnedUndecryptable.has(key)) {
     warnedUndecryptable.add(key);
     logger.warn(
@@ -614,6 +683,7 @@ export {
   getCacheKeyPath,
   getSelectedAccountPath,
   getTokenCachePath,
+  keytarEnabled,
   migrateLegacyPathsFrom,
   pickNewest,
   resetCacheKeyForTests,

package/package.json

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

@@ -165,6 +165,38 @@
     "workScopes": ["Mail.Send.Shared"],
     "llmTip": "Forward a message from a shared mailbox preserving full HTML formatting and attachments. The 'user-id' is the shared mailbox email address. 'toRecipients' is required. The 'comment' field adds text above the forwarded content. Requires Send As permission on the shared mailbox in Exchange."
   },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/createReply",
+    "method": "post",
+    "toolName": "create-shared-mailbox-reply-draft",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"],
+    "llmTip": "Create a reply draft in a shared mailbox preserving thread metadata (conversationId, In-Reply-To, References). The 'user-id' is the shared mailbox email address (e.g. support@contoso.com). Does not send — use send-shared-mailbox-draft to send afterwards. For HTML replies pass Message.body.contentType: 'html' with Message.body.content as HTML. Specifying both 'comment' and Message.body returns 400. Requires delegated access to the shared mailbox."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/createReplyAll",
+    "method": "post",
+    "toolName": "create-shared-mailbox-reply-all-draft",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"],
+    "llmTip": "Create a reply-all draft in a shared mailbox preserving thread metadata (conversationId, In-Reply-To, References). The 'user-id' is the shared mailbox email address. Does not send — use send-shared-mailbox-draft to send afterwards. For HTML replies pass Message.body.contentType: 'html' with Message.body.content as HTML. Specifying both 'comment' and Message.body returns 400. Requires delegated access to the shared mailbox."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/createForward",
+    "method": "post",
+    "toolName": "create-shared-mailbox-forward-draft",
+    "presets": ["work"],
+    "workScopes": ["Mail.ReadWrite.Shared"],
+    "llmTip": "Create a forward draft in a shared mailbox without sending. The 'user-id' is the shared mailbox email address. Does not send — use send-shared-mailbox-draft to send afterwards. Useful when the user wants to review before the forward goes out. Requires delegated access to the shared mailbox."
+  },
+  {
+    "pathPattern": "/users/{user-id}/messages/{message-id}/send",
+    "method": "post",
+    "toolName": "send-shared-mailbox-draft",
+    "presets": ["work"],
+    "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",
     "method": "get",