@softeria/ms-365-mcp-server 0.113.0 → 0.114.1

package/dist/endpoints.json

@@ -489,12 +489,6 @@
     "toolName": "get-drive-root-item",
     "scopes": ["Files.Read"]
   },
-  {
-    "pathPattern": "/drives/{drive-id}/root",
-    "method": "get",
-    "toolName": "get-drive-root-item",
-    "scopes": ["Files.Read"]
-  },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/children",
     "method": "get",

package/dist/generated/client.js

@@ -365,6 +365,57 @@ const microsoft_graph_teamsTab = z.object({
   webUrl: z.string().describe("Deep link URL of the tab instance. Read-only.").nullish(),
   teamsApp: microsoft_graph_teamsApp.optional()
 }).passthrough();
+const microsoft_graph_targetedChatMessage = z.object({
+  id: z.string().describe("The unique identifier for an entity. Read-only.").optional(),
+  createdDateTime: z.string().regex(
+    /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
+  ).datetime({ offset: true }).describe("Timestamp of when the chat message was created.").nullish(),
+  lastModifiedDateTime: z.string().regex(
+    /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
+  ).datetime({ offset: true }).describe(
+    "Read only. Timestamp when the chat message is created (initial setting) or modified, including when a reaction is added or removed."
+  ).nullish(),
+  body: microsoft_graph_itemBody.optional(),
+  subject: z.string().describe("The subject of the chat message, in plaintext.").nullish(),
+  attachments: z.array(microsoft_graph_chatMessageAttachment).describe("References to attached objects like files, tabs, meetings etc.").optional(),
+  importance: microsoft_graph_chatMessageImportance.optional(),
+  from: microsoft_graph_chatMessageFromIdentitySet.optional(),
+  channelIdentity: microsoft_graph_channelIdentity.optional(),
+  chatId: z.string().describe("If the message was sent in a chat, represents the identity of the chat.").nullish(),
+  deletedDateTime: z.string().regex(
+    /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
+  ).datetime({ offset: true }).describe(
+    "Read only. Timestamp at which the chat message was deleted, or null if not deleted."
+  ).nullish(),
+  etag: z.string().describe("Read-only. Version number of the chat message.").nullish(),
+  eventDetail: microsoft_graph_eventMessageDetail.optional(),
+  lastEditedDateTime: z.string().regex(
+    /^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$/
+  ).datetime({ offset: true }).describe(
+    "Read only. Timestamp when edits to the chat message were made. Triggers an 'Edited' flag in the Teams UI. If no edits are made the value is null."
+  ).nullish(),
+  locale: z.string().describe("Locale of the chat message set by the client. Always set to en-us.").optional(),
+  mentions: z.array(microsoft_graph_chatMessageMention).describe(
+    "List of entities mentioned in the chat message. Supported entities are: user, bot, team, channel, chat, and tag."
+  ).optional(),
+  messageHistory: z.array(microsoft_graph_chatMessageHistoryItem).describe(
+    "List of activity history of a message item, including modification time and actions, such as reactionAdded, reactionRemoved, or reaction changes, on the message."
+  ).optional(),
+  messageType: microsoft_graph_chatMessageType.optional(),
+  policyViolation: microsoft_graph_chatMessagePolicyViolation.optional(),
+  reactions: z.array(microsoft_graph_chatMessageReaction).describe("Reactions for this chat message (for example, Like).").optional(),
+  replyToId: z.string().describe(
+    "Read-only. ID of the parent chat message or root chat message of the thread. (Only applies to chat messages in channels, not chats.)"
+  ).nullish(),
+  summary: z.string().describe(
+    "Summary text of the chat message that could be used for push notifications and summary views or fall back views. Only applies to channel chat messages, not chat messages in a chat."
+  ).nullish(),
+  webUrl: z.string().describe("Read-only. Link to the message in Microsoft Teams.").nullish(),
+  hostedContents: z.array(microsoft_graph_chatMessageHostedContent).describe(
+    "Content in a message hosted by Microsoft Teams - for example, images or code snippets."
+  ).optional(),
+  replies: z.array(microsoft_graph_chatMessage).describe("Replies for a specified message. Supports $expand for channel messages.").optional()
+}).passthrough().passthrough();
 const microsoft_graph_chat = z.object({
   id: z.string().describe("The unique identifier for an entity. Read-only.").optional(),
   chatType: microsoft_graph_chatType.optional(),
@@ -396,7 +447,8 @@ const microsoft_graph_chat = z.object({
   messages: z.array(microsoft_graph_chatMessage).describe("A collection of all the messages in the chat. Nullable.").optional(),
   permissionGrants: z.array(microsoft_graph_resourceSpecificPermissionGrant).describe("A collection of permissions granted to apps for the chat.").optional(),
   pinnedMessages: z.array(microsoft_graph_pinnedChatMessageInfo).describe("A collection of all the pinned messages in the chat. Nullable.").optional(),
-  tabs: z.array(microsoft_graph_teamsTab).describe("A collection of all the tabs in the chat. Nullable.").optional()
+  tabs: z.array(microsoft_graph_teamsTab).describe("A collection of all the tabs in the chat. Nullable.").optional(),
+  targetedMessages: z.array(microsoft_graph_targetedChatMessage).optional()
 }).passthrough();
 const microsoft_graph_ODataErrors_ErrorDetails = z.object({ code: z.string(), message: z.string(), target: z.string().nullish() }).passthrough();
 const microsoft_graph_ODataErrors_InnerError = z.object({
@@ -4666,6 +4718,7 @@ const schemas = {
   microsoft_graph_pinnedChatMessageInfo,
   microsoft_graph_teamsTabConfiguration,
   microsoft_graph_teamsTab,
+  microsoft_graph_targetedChatMessage,
   microsoft_graph_chat,
   microsoft_graph_ODataErrors_ErrorDetails,
   microsoft_graph_ODataErrors_InnerError,

package/dist/graph-client.js

@@ -2,6 +2,11 @@ import logger from "./logger.js";
 import { encode as toonEncode } from "@toon-format/toon";
 import { getCloudEndpoints } from "./cloud-config.js";
 import { getRequestTokens } from "./request-context.js";
+import {
+  fetchWithResilience,
+  getSharedBreaker,
+  loadResilienceConfig
+} from "./lib/graph-resilience.js";
 function isBinaryContentType(contentType) {
   if (!contentType) return false;
   const lower = contentType.toLowerCase().split(";")[0].trim();
@@ -102,12 +107,17 @@ class GraphClient {
       "Content-Type": "application/json",
       ...options.headers
     };
-    return fetch(url, {
-      method: options.method || "GET",
-      headers,
-      // Node's fetch accepts Buffer/Uint8Array; TS BodyInit doesn't.
-      body: options.body
-    });
+    return fetchWithResilience(
+      url,
+      {
+        method: options.method || "GET",
+        headers,
+        // Node's fetch accepts Buffer/Uint8Array; TS BodyInit doesn't.
+        body: options.body
+      },
+      loadResilienceConfig(),
+      getSharedBreaker()
+    );
   }
   serializeData(data, outputFormat, pretty = false) {
     if (outputFormat === "toon") {

package/dist/lib/graph-resilience.js

@@ -0,0 +1,208 @@
+import logger from "../logger.js";
+function loadResilienceConfig() {
+  const intEnv = (name, fallback) => {
+    const raw = process.env[name];
+    if (raw === void 0 || raw === "") return fallback;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0) {
+      logger.warn(`Ignoring invalid ${name}=${JSON.stringify(raw)} (use a non-negative integer)`);
+      return fallback;
+    }
+    return n;
+  };
+  return {
+    maxRetries: intEnv("MS365_MCP_GRAPH_MAX_RETRIES", 3),
+    baseBackoffMs: intEnv("MS365_MCP_GRAPH_BASE_BACKOFF_MS", 200),
+    maxBackoffMs: intEnv("MS365_MCP_GRAPH_MAX_BACKOFF_MS", 5e3),
+    fetchTimeoutMs: intEnv("MS365_MCP_GRAPH_TIMEOUT_MS", 1e5),
+    circuitFailureThreshold: intEnv("MS365_MCP_GRAPH_CIRCUIT_THRESHOLD", 5),
+    circuitCooldownMs: intEnv("MS365_MCP_GRAPH_CIRCUIT_COOLDOWN_MS", 3e4),
+    circuitDisabled: process.env.MS365_MCP_GRAPH_CIRCUIT_DISABLED === "true" || process.env.MS365_MCP_GRAPH_CIRCUIT_DISABLED === "1"
+  };
+}
+class CircuitOpenError extends Error {
+  constructor(cooldownMs) {
+    super(
+      `Graph circuit breaker is open (cooldown ${cooldownMs} ms). Upstream has failed repeatedly; refusing to flood it.`
+    );
+    this.code = "circuit_open";
+    this.name = "CircuitOpenError";
+    this.cooldownMs = cooldownMs;
+  }
+}
+class CircuitBreaker {
+  constructor(threshold, cooldownMs, disabled, now = () => Date.now()) {
+    this.threshold = threshold;
+    this.cooldownMs = cooldownMs;
+    this.disabled = disabled;
+    this.now = now;
+    this.failures = 0;
+    this.openedAt = null;
+  }
+  /**
+   * @returns the time-remaining (in ms) before the circuit can be probed,
+   *          or `null` if the circuit is closed and the call should proceed.
+   */
+  checkBeforeRequest() {
+    if (this.disabled) return null;
+    if (this.openedAt === null) return null;
+    const elapsed = this.now() - this.openedAt;
+    if (elapsed >= this.cooldownMs) {
+      return null;
+    }
+    return this.cooldownMs - elapsed;
+  }
+  recordSuccess() {
+    if (this.failures !== 0 || this.openedAt !== null) {
+      logger.info("Graph circuit: success \u2014 closing breaker");
+    }
+    this.failures = 0;
+    this.openedAt = null;
+  }
+  recordFailure() {
+    if (this.disabled) return;
+    this.failures += 1;
+    if (this.failures >= this.threshold && this.openedAt === null) {
+      this.openedAt = this.now();
+      logger.warn(
+        `Graph circuit: ${this.failures} consecutive failures \u2014 opening breaker for ${this.cooldownMs} ms`
+      );
+    } else if (this.openedAt !== null) {
+      this.openedAt = this.now();
+      logger.warn("Graph circuit: probe failed \u2014 extending cooldown");
+    }
+  }
+  /** Exposed for tests / metrics. */
+  getState() {
+    return {
+      failures: this.failures,
+      openedAt: this.openedAt,
+      open: this.checkBeforeRequest() !== null
+    };
+  }
+}
+function parseRetryAfterMs(header) {
+  if (!header) return null;
+  const trimmed = header.trim();
+  if (trimmed === "") return null;
+  const asInt = Number.parseInt(trimmed, 10);
+  if (Number.isFinite(asInt) && asInt >= 0 && String(asInt) === trimmed) {
+    return Math.min(asInt * 1e3, 6e4);
+  }
+  if (!/[-/:,]| GMT$/i.test(trimmed) && !/\s+\d/.test(trimmed)) {
+    return null;
+  }
+  const dateMs = Date.parse(trimmed);
+  if (Number.isFinite(dateMs)) {
+    const delta = dateMs - Date.now();
+    if (delta <= 0) return 0;
+    return Math.min(delta, 6e4);
+  }
+  return null;
+}
+function backoffDelayMs(attempt, baseMs, maxMs, rand = Math.random) {
+  const exp = Math.min(maxMs, baseMs * 2 ** attempt);
+  return Math.floor(rand() * exp);
+}
+function isRetriableStatus(status) {
+  return status === 429 || status === 503 || status === 504;
+}
+function isMethodIdempotent(method) {
+  const m = method.toUpperCase();
+  return m === "GET" || m === "HEAD" || m === "PUT" || m === "DELETE" || m === "OPTIONS" || m === "TRACE";
+}
+function isAbortError(err) {
+  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
+async function fetchWithResilience(url, init, config, breaker, sleep = (ms) => new Promise((r) => setTimeout(r, ms))) {
+  const remainingCooldown = breaker.checkBeforeRequest();
+  if (remainingCooldown !== null) {
+    throw new CircuitOpenError(remainingCooldown);
+  }
+  const method = (init?.method ?? "GET").toString().toUpperCase();
+  const methodIsIdempotent = isMethodIdempotent(method);
+  let attempt = 0;
+  while (true) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.fetchTimeoutMs);
+    let response = null;
+    let networkError = null;
+    try {
+      response = await fetch(url, { ...init, signal: controller.signal });
+    } catch (err) {
+      networkError = err;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response !== null && !isRetriableStatus(response.status)) {
+      breaker.recordSuccess();
+      return response;
+    }
+    const is429 = response !== null && response.status === 429;
+    const retryAllowedByMethod = methodIsIdempotent || is429;
+    const canRetry = attempt < config.maxRetries && retryAllowedByMethod;
+    if (!canRetry) {
+      breaker.recordFailure();
+      if (response !== null) {
+        if (!retryAllowedByMethod && attempt === 0) {
+          logger.warn(
+            `Graph ${method} ${response.status}: not retried (non-idempotent method, side-effect may have landed)`
+          );
+        }
+        return response;
+      }
+      if (!retryAllowedByMethod && attempt === 0) {
+        logger.warn(
+          `Graph ${method} network error: not retried (non-idempotent method, side-effect may have landed)`
+        );
+      }
+      throw networkError ?? new Error("Graph fetch failed (unknown error)");
+    }
+    let delayMs;
+    if (response !== null && response.status === 429) {
+      const retryAfter = parseRetryAfterMs(response.headers.get("retry-after"));
+      delayMs = retryAfter !== null ? retryAfter : backoffDelayMs(attempt, config.baseBackoffMs, config.maxBackoffMs);
+    } else {
+      delayMs = backoffDelayMs(attempt, config.baseBackoffMs, config.maxBackoffMs);
+    }
+    const reason = response !== null ? `HTTP ${response.status}` : isAbortError(networkError) ? `timeout (${config.fetchTimeoutMs} ms)` : `network error: ${networkError?.message ?? "unknown"}`;
+    logger.warn(
+      `Graph retry ${attempt + 1}/${config.maxRetries} after ${reason} \u2014 sleeping ${delayMs} ms`
+    );
+    if (response !== null) {
+      try {
+        await response.arrayBuffer();
+      } catch {
+      }
+    }
+    breaker.recordFailure();
+    attempt += 1;
+    await sleep(delayMs);
+  }
+}
+let _sharedBreaker = null;
+function getSharedBreaker() {
+  if (_sharedBreaker === null) {
+    const cfg = loadResilienceConfig();
+    _sharedBreaker = new CircuitBreaker(
+      cfg.circuitFailureThreshold,
+      cfg.circuitCooldownMs,
+      cfg.circuitDisabled
+    );
+  }
+  return _sharedBreaker;
+}
+function __resetSharedBreakerForTests() {
+  _sharedBreaker = null;
+}
+export {
+  CircuitBreaker,
+  CircuitOpenError,
+  __resetSharedBreakerForTests,
+  backoffDelayMs,
+  fetchWithResilience,
+  getSharedBreaker,
+  isMethodIdempotent,
+  loadResilienceConfig,
+  parseRetryAfterMs
+};

package/docs/deployment.md

@@ -209,6 +209,7 @@ The client automatically discovers OAuth endpoints and opens a browser for authe
 - **Tool filtering**: use `--enabled-tools <regex>` or `--preset <names>` to restrict available tools
 - **CORS**: configure `MS365_MCP_CORS_ORIGIN` to restrict allowed origins (defaults to `http://localhost:3000`); set explicitly when clients run on a different origin
 - **Structured audit log**: enabled by default. Every tool invocation emits one JSON line on stdout (captured by the container platform's log collector) and to `~/.ms-365-mcp-server/logs/audit.log` (mode `0o600`) with `{ event, request_id, user_principal_name, tool, http_method, status, duration_ms, error_type?, error_code? }`. The schema is intentionally narrow — tool parameters and Graph response bodies are NEVER recorded, and error messages are reduced to `error_type` / `error_code` so upstream library errors do not leak token fragments or query-string PII. Forms the "who accessed what, when" trail required for GDPR / HIPAA / PIPEDA / SOC 2 audit. Opt-out: `MS365_MCP_AUDIT_LOG=false`
+- **Graph resilience**: every call to Microsoft Graph is wrapped with a fetch timeout (default 100 s via `MS365_MCP_GRAPH_TIMEOUT_MS`), retry-with-backoff on 429 / 503 / 504 / network errors (default 3 retries, full-jitter exponential backoff, honours `Retry-After`; 503 / 504 / network errors only retried for idempotent methods, 429 retried on all methods), and a process-wide circuit breaker that opens after 5 consecutive failures and cools down for 30 s (`MS365_MCP_GRAPH_CIRCUIT_THRESHOLD` / `MS365_MCP_GRAPH_CIRCUIT_COOLDOWN_MS`). Disable the breaker for trusted automation: `MS365_MCP_GRAPH_CIRCUIT_DISABLED=true`
 
 ## Exposed Endpoints
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.113.0",
+  "version": "0.114.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",
@@ -60,7 +60,7 @@
     "@types/node": "^22.15.15",
     "@typescript-eslint/eslint-plugin": "^8.38.0",
     "@typescript-eslint/parser": "^8.38.0",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^9.31.0",
     "globals": "^16.3.0",
     "patch-package": "^8.0.1",
@@ -69,7 +69,7 @@
     "tsup": "^8.5.0",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
-    "vitest": "^3.1.1"
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=18"

package/src/endpoints.json

@@ -489,12 +489,6 @@
     "toolName": "get-drive-root-item",
     "scopes": ["Files.Read"]
   },
-  {
-    "pathPattern": "/drives/{drive-id}/root",
-    "method": "get",
-    "toolName": "get-drive-root-item",
-    "scopes": ["Files.Read"]
-  },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/children",
     "method": "get",