@softeria/ms-365-mcp-server 0.142.0 → 0.144.0

package/dist/graph-client.js

@@ -7,6 +7,7 @@ import {
   getSharedBreaker,
   loadResilienceConfig
 } from "./lib/graph-resilience.js";
+import { applyMessageSignoffToRequest } from "./lib/message-signoff.js";
 import { open, stat, unlink } from "fs/promises";
 import { pipeline } from "stream/promises";
 function isBinaryContentType(contentType) {
@@ -30,6 +31,62 @@ function isBinaryContentType(contentType) {
   }
   return false;
 }
+class GraphApiError extends Error {
+  constructor(message, httpStatus, graphErrorCode) {
+    super(message);
+    this.name = "GraphApiError";
+    this.httpStatus = httpStatus;
+    this.graphErrorCode = graphErrorCode;
+  }
+}
+function extractGraphErrorCode(errorText) {
+  try {
+    const body = JSON.parse(errorText);
+    const code = body.error?.code ?? body.code;
+    return typeof code === "string" ? code : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function definedMetadata(metadata) {
+  return Object.fromEntries(
+    Object.entries(metadata).filter(([, value]) => value !== void 0)
+  );
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function incrementCount(counts, key) {
+  counts[key] = (counts[key] ?? 0) + 1;
+}
+function extractGraphErrorCodeFromBody(body) {
+  if (!isRecord(body)) return void 0;
+  const error = body.error;
+  const code = isRecord(error) ? error.code : body.code;
+  return typeof code === "string" ? code : void 0;
+}
+function extractBatchMetadata(data) {
+  if (!isRecord(data) || !Array.isArray(data.responses)) return {};
+  const httpStatusCounts = {};
+  const errorCodeCounts = {};
+  for (const item of data.responses) {
+    if (!isRecord(item)) continue;
+    const status = item.status;
+    if (typeof status !== "number" || !Number.isInteger(status)) continue;
+    incrementCount(httpStatusCounts, String(status));
+    if (status >= 400) {
+      const errorCode = extractGraphErrorCodeFromBody(item.body);
+      if (errorCode) {
+        incrementCount(errorCodeCounts, errorCode);
+      }
+    }
+  }
+  return {
+    graph_batch_subrequest_count: data.responses.length,
+    ...Object.keys(httpStatusCounts).length > 0 ? { graph_batch_http_status_counts: httpStatusCounts } : {},
+    ...Object.keys(errorCodeCounts).length > 0 ? { graph_batch_error_code_counts: errorCodeCounts } : {}
+  };
+}
 class GraphClient {
   constructor(authManager, secrets, outputFormat = "json") {
     this.outputFormat = "json";
@@ -38,6 +95,9 @@ class GraphClient {
     this.outputFormat = outputFormat;
   }
   async makeRequest(endpoint, options = {}) {
+    return (await this.makeRequestWithMetadata(endpoint, options)).data;
+  }
+  async makeRequestWithMetadata(endpoint, options = {}) {
     const contextTokens = getRequestTokens();
     const accessToken = options.accessToken ?? contextTokens?.accessToken ?? await this.authManager.getToken();
     if (!accessToken) {
@@ -46,23 +106,14 @@ class GraphClient {
     try {
       const response = await this.performRequest(endpoint, accessToken, options);
       if (response.status === 403) {
-        const errorText = await response.text();
-        if (errorText.includes("scope") || errorText.includes("permission")) {
-          throw new Error(
-            `Microsoft Graph API scope error: ${response.status} ${response.statusText} - ${errorText}. This tool requires organization mode. Please restart with --org-mode flag.`
-          );
-        }
-        throw new Error(
-          `Microsoft Graph API error: ${response.status} ${response.statusText} - ${errorText}`
-        );
+        throw await this.createGraphApiError(response);
       }
       if (!response.ok) {
-        throw new Error(
-          `Microsoft Graph API error: ${response.status} ${response.statusText} - ${await response.text()}`
-        );
+        throw await this.createGraphApiError(response);
       }
       const contentTypeHeader = response.headers?.get?.("content-type") || "";
       const isBinaryResponse = isBinaryContentType(contentTypeHeader);
+      let metadata = { http_status: response.status };
       let result;
       if (isBinaryResponse) {
         const buffer = Buffer.from(await response.arrayBuffer());
@@ -87,16 +138,22 @@ class GraphClient {
           }
         }
       }
+      if (endpoint === "/$batch") {
+        metadata = { ...metadata, ...extractBatchMetadata(result) };
+      }
       if (options.includeHeaders) {
         const etag = response.headers.get("ETag") || response.headers.get("etag");
         if (result && typeof result === "object" && !Array.isArray(result)) {
           return {
-            ...result,
-            _etag: etag || "no-etag-found"
+            data: {
+              ...result,
+              _etag: etag || "no-etag-found"
+            },
+            metadata
           };
         }
       }
-      return result;
+      return { data: result, metadata };
     } catch (error) {
       logger.error("Microsoft Graph API request failed:", error);
       throw error;
@@ -120,20 +177,10 @@ class GraphClient {
       }
       const response = await this.performRequest(endpoint, accessToken, options);
       if (response.status === 403) {
-        const errorText = await response.text();
-        if (errorText.includes("scope") || errorText.includes("permission")) {
-          throw new Error(
-            `Microsoft Graph API scope error: ${response.status} ${response.statusText} - ${errorText}. This tool requires organization mode. Please restart with --org-mode flag.`
-          );
-        }
-        throw new Error(
-          `Microsoft Graph API error: ${response.status} ${response.statusText} - ${errorText}`
-        );
+        throw await this.createGraphApiError(response);
       }
       if (!response.ok) {
-        throw new Error(
-          `Microsoft Graph API error: ${response.status} ${response.statusText} - ${await response.text()}`
-        );
+        throw await this.createGraphApiError(response);
       }
       if (!response.body) {
         throw new Error("Microsoft Graph returned an empty response body");
@@ -149,7 +196,8 @@ class GraphClient {
       }
       return {
         contentType: response.headers.get("content-type") || "application/octet-stream",
-        contentLength
+        contentLength,
+        httpStatus: response.status
       };
     } catch (error) {
       logger.error("Microsoft Graph file download failed:", error);
@@ -161,11 +209,30 @@ class GraphClient {
       }
     }
   }
+  async createGraphApiError(response) {
+    const errorText = await response.text();
+    const graphErrorCode = extractGraphErrorCode(errorText);
+    const isPermissionOrScopeError = errorText.includes("scope") || errorText.includes("permission");
+    if (response.status === 403 && isPermissionOrScopeError) {
+      return new GraphApiError(
+        `Microsoft Graph API scope error: ${response.status} ${response.statusText} - ${errorText}. This tool requires organization mode. Please restart with --org-mode flag.`,
+        response.status,
+        graphErrorCode
+      );
+    }
+    return new GraphApiError(
+      `Microsoft Graph API error: ${response.status} ${response.statusText} - ${errorText}`,
+      response.status,
+      graphErrorCode
+    );
+  }
   async performRequest(endpoint, accessToken, options) {
     const cloudEndpoints = getCloudEndpoints(this.secrets.cloudType);
     const apiVersion = options.apiVersion || "v1.0";
     const url = `${cloudEndpoints.graphApi}/${apiVersion}${endpoint}`;
     logger.info(`[GRAPH CLIENT] Final URL being sent to Microsoft: ${url}`);
+    const method = options.method || "GET";
+    const body = applyMessageSignoffToRequest(method, endpoint, options.body);
     const headers = {
       Authorization: `Bearer ${accessToken}`,
       "Content-Type": "application/json",
@@ -174,10 +241,10 @@ class GraphClient {
     return fetchWithResilience(
       url,
       {
-        method: options.method || "GET",
+        method,
         headers,
         // Node's fetch accepts Buffer/Uint8Array; TS BodyInit doesn't.
-        body: options.body
+        body
       },
       loadResilienceConfig(),
       getSharedBreaker()
@@ -208,22 +275,36 @@ class GraphClient {
       logger.info(
         `Calling ${endpoint} with options: ${JSON.stringify(safeOptions)}${_redacted ? " [accessToken=REDACTED]" : ""}`
       );
-      const result = await this.makeRequest(endpoint, options);
+      const { data, metadata } = await this.makeRequestWithMetadata(endpoint, options);
       const outputFormat = options.forceJsonOutput ? "json" : this.outputFormat;
-      return this.formatJsonResponse(
-        result,
-        options.rawResponse,
-        options.excludeResponse,
-        outputFormat
+      return this.withResponseMetadata(
+        this.formatJsonResponse(data, options.rawResponse, options.excludeResponse, outputFormat),
+        metadata
       );
     } catch (error) {
       logger.error(`Error in Graph API request: ${error}`);
+      const metadata = error instanceof GraphApiError ? definedMetadata({
+        http_status: error.httpStatus,
+        error_code: error.graphErrorCode
+      }) : void 0;
       return {
         content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
-        isError: true
+        isError: true,
+        ...metadata && Object.keys(metadata).length > 0 ? { _meta: metadata } : {}
       };
     }
   }
+  withResponseMetadata(response, metadata) {
+    const cleanMetadata = definedMetadata(metadata);
+    if (Object.keys(cleanMetadata).length === 0) return response;
+    return {
+      ...response,
+      _meta: {
+        ...response._meta,
+        ...cleanMetadata
+      }
+    };
+  }
   formatJsonResponse(data, rawResponse = false, excludeResponse = false, outputFormat = this.outputFormat) {
     if (excludeResponse) {
       return {
@@ -299,6 +380,7 @@ class GraphClient {
 }
 var graph_client_default = GraphClient;
 export {
+  GraphApiError,
   graph_client_default as default,
   isBinaryContentType
 };

package/dist/graph-tools.js

@@ -76,6 +76,86 @@ const DEFAULT_MAX_ITEMS = 1e4;
 function isConfirmGateEnabled() {
   return process.env.MS365_MCP_REQUIRE_CONFIRM === "true";
 }
+function auditHttpStatus(value) {
+  if (typeof value === "number" && Number.isInteger(value)) return value;
+  if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
+  return void 0;
+}
+function auditErrorCode(value) {
+  return typeof value === "string" || typeof value === "number" ? value : void 0;
+}
+function auditNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : void 0;
+}
+function auditStringNumberMap(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const entries = Object.entries(value).filter(
+    (entry) => typeof entry[1] === "number" && Number.isInteger(entry[1]) && entry[1] >= 0
+  );
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+function graphResponseAuditFields(response) {
+  const httpStatus = auditHttpStatus(response._meta?.http_status);
+  const errorCode = response.isError ? auditErrorCode(response._meta?.error_code) : void 0;
+  const graphBatchSubrequestCount = auditNonNegativeInteger(
+    response._meta?.graph_batch_subrequest_count
+  );
+  const graphBatchHttpStatusCounts = auditStringNumberMap(
+    response._meta?.graph_batch_http_status_counts
+  );
+  const graphBatchErrorCodeCounts = auditStringNumberMap(
+    response._meta?.graph_batch_error_code_counts
+  );
+  return {
+    ...httpStatus !== void 0 ? { http_status: httpStatus } : {},
+    ...errorCode !== void 0 ? { error_code: errorCode } : {},
+    ...graphBatchSubrequestCount !== void 0 ? { graph_batch_subrequest_count: graphBatchSubrequestCount } : {},
+    ...graphBatchHttpStatusCounts !== void 0 ? { graph_batch_http_status_counts: graphBatchHttpStatusCounts } : {},
+    ...graphBatchErrorCodeCounts !== void 0 ? { graph_batch_error_code_counts: graphBatchErrorCodeCounts } : {}
+  };
+}
+function thrownErrorAuditFields(error) {
+  const err = error;
+  const httpStatus = auditHttpStatus(err?.httpStatus ?? err?.status);
+  const errorCode = auditErrorCode(err?.graphErrorCode ?? err?.code ?? err?.status);
+  return {
+    ...httpStatus !== void 0 ? { http_status: httpStatus } : {},
+    ...errorCode !== void 0 ? { error_code: errorCode } : {}
+  };
+}
+async function executeUtilityTool(utility, ctx, params) {
+  const requestId = randomUUID();
+  const startTime = Date.now();
+  const upn = getUserIdentityForAudit(getRequestTokens()?.accessToken);
+  try {
+    const response = await utility.execute(params, ctx);
+    auditLog({
+      event: "tool.call",
+      request_id: requestId,
+      user_principal_name: upn,
+      tool: utility.name,
+      http_method: utility.method.toUpperCase(),
+      status: response.isError ? "error" : "success",
+      duration_ms: Date.now() - startTime,
+      ...graphResponseAuditFields(response)
+    });
+    return response;
+  } catch (error) {
+    const err = error;
+    auditLog({
+      event: "tool.call",
+      request_id: requestId,
+      user_principal_name: upn,
+      tool: utility.name,
+      http_method: utility.method.toUpperCase(),
+      status: "error",
+      duration_ms: Date.now() - startTime,
+      error_type: err?.name || "Error",
+      ...thrownErrorAuditFields(error)
+    });
+    throw error;
+  }
+}
 function formatDisabledToolsForLog(disabledTools) {
   const shown = disabledTools.slice(0, 20).map((tool) => `${tool.toolName} (missing: ${tool.missingScopes.join(", ")})`);
   const suffix = disabledTools.length > shown.length ? `, ... +${disabledTools.length - shown.length} more` : "";
@@ -316,12 +396,15 @@ const UTILITY_TOOLS = [
                 bytesWritten: result.contentLength
               })
             }
-          ]
+          ],
+          ...result.httpStatus !== void 0 ? { _meta: { http_status: result.httpStatus } } : {}
         };
       } catch (error) {
+        const metadata = thrownErrorAuditFields(error);
         return {
           content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
-          isError: true
+          isError: true,
+          ...Object.keys(metadata).length > 0 ? { _meta: metadata } : {}
         };
       }
     }
@@ -496,7 +579,8 @@ const UTILITY_TOOLS = [
                 })
               }
             ],
-            isError: true
+            isError: true,
+            _meta: response._meta
           };
         }
         const file = item?.file;
@@ -511,12 +595,15 @@ const UTILITY_TOOLS = [
                 contentType: file?.mimeType
               })
             }
-          ]
+          ],
+          _meta: response._meta
         };
       } catch (error) {
+        const metadata = thrownErrorAuditFields(error);
         return {
           content: [{ type: "text", text: JSON.stringify({ error: error.message }) }],
-          isError: true
+          isError: true,
+          ...Object.keys(metadata).length > 0 ? { _meta: metadata } : {}
         };
       }
     }
@@ -532,7 +619,7 @@ function registerUtilityToolWithMcp(server, utility, ctx) {
       readOnlyHint: utility.readOnlyHint ?? true,
       openWorldHint: utility.openWorldHint ?? true
     },
-    async (params) => utility.execute(params, ctx)
+    async (params) => executeUtilityTool(utility, ctx, params)
   );
 }
 function namesNestedBodyType(value) {
@@ -886,6 +973,11 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
             const nextPath = url.pathname.replace(/^\/(v1\.0|beta)/, "") + url.search;
             const nextOptions = { ...options };
             const nextResponse = await graphClient.graphRequest(nextPath, nextOptions);
+            if (nextResponse?.isError) {
+              response = nextResponse;
+              combinedResponse = void 0;
+              break;
+            }
             if (nextResponse?.content?.[0]?.text) {
               const nextJsonResponse = JSON.parse(nextResponse.content[0].text);
               if (Array.isArray(nextJsonResponse.value)) {
@@ -900,25 +992,27 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
               break;
             }
           }
-          if (pageCount >= maxPages) {
-            logger.warn(`Reached maximum page limit (${maxPages}) for pagination`);
-          }
-          if (allItems.length >= maxItems) {
-            logger.warn(
-              `Reached maximum item limit (${maxItems}) for pagination \u2014 truncated at ${allItems.length} items`
+          if (combinedResponse !== void 0) {
+            if (pageCount >= maxPages) {
+              logger.warn(`Reached maximum page limit (${maxPages}) for pagination`);
+            }
+            if (allItems.length >= maxItems) {
+              logger.warn(
+                `Reached maximum item limit (${maxItems}) for pagination \u2014 truncated at ${allItems.length} items`
+              );
+            }
+            combinedResponse.value = allItems;
+            if (combinedResponse["@odata.count"]) {
+              combinedResponse["@odata.count"] = allItems.length;
+            }
+            delete combinedResponse["@odata.nextLink"];
+            if (deltaLink) {
+              combinedResponse["@odata.deltaLink"] = deltaLink;
+            }
+            logger.info(
+              `Pagination complete: collected ${allItems.length} items across ${pageCount} pages`
             );
           }
-          combinedResponse.value = allItems;
-          if (combinedResponse["@odata.count"]) {
-            combinedResponse["@odata.count"] = allItems.length;
-          }
-          delete combinedResponse["@odata.nextLink"];
-          if (deltaLink) {
-            combinedResponse["@odata.deltaLink"] = deltaLink;
-          }
-          logger.info(
-            `Pagination complete: collected ${allItems.length} items across ${pageCount} pages`
-          );
         }
       } catch (e) {
         logger.error(`Error during pagination: ${e}`);
@@ -953,7 +1047,8 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       http_method: httpMethod,
       status: response.isError ? "error" : "success",
       duration_ms: Date.now() - startTime,
-      ...targetResource ? { target_resource: targetResource } : {}
+      ...targetResource ? { target_resource: targetResource } : {},
+      ...graphResponseAuditFields(response)
     });
     return {
       content,
@@ -973,7 +1068,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       duration_ms: Date.now() - startTime,
       ...targetResource ? { target_resource: targetResource } : {},
       error_type: err?.name || "Error",
-      error_code: err?.status ?? err?.code
+      ...thrownErrorAuditFields(error)
     });
     return {
       content: [
@@ -1450,7 +1545,7 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
       }
       const utility = utilityByName.get(tool_name);
       if (utility) {
-        return utility.execute(parameters, utilityCtx);
+        return executeUtilityTool(utility, utilityCtx, parameters);
       }
       return {
         content: [