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

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.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",