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

package/dist/__tests__/graph-client.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import GraphClient from "../graph-client.js";
+import { fetchWithResilience } from "../lib/graph-resilience.js";
+vi.mock("../logger.js", () => ({
+  default: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn()
+  }
+}));
+vi.mock("../lib/graph-resilience.js", () => ({
+  fetchWithResilience: vi.fn(),
+  getSharedBreaker: vi.fn(() => ({})),
+  loadResilienceConfig: vi.fn(() => ({}))
+}));
+const fetchWithResilienceMock = vi.mocked(fetchWithResilience);
+function createGraphClient() {
+  return new GraphClient(
+    {
+      getToken: vi.fn().mockResolvedValue("token")
+    },
+    {
+      clientId: "client-id",
+      tenantId: "tenant-id",
+      cloudType: "global"
+    }
+  );
+}
+describe("GraphClient audit metadata", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  it("adds HTTP status metadata to successful Graph responses", async () => {
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(JSON.stringify({ id: "user-1" }), {
+        status: 200,
+        headers: { "content-type": "application/json" }
+      })
+    );
+    const result = await createGraphClient().graphRequest("/me");
+    expect(result._meta).toMatchObject({ http_status: 200 });
+    expect(JSON.parse(result.content[0].text)).toEqual({ id: "user-1" });
+  });
+  it("preserves HTTP status metadata when response headers are requested", async () => {
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(JSON.stringify({ id: "task-1" }), {
+        status: 200,
+        headers: { "content-type": "application/json", etag: 'W/"etag-1"' }
+      })
+    );
+    const result = await createGraphClient().graphRequest("/me/planner/tasks/task-1", {
+      includeHeaders: true
+    });
+    expect(result._meta).toMatchObject({ http_status: 200 });
+    expect(JSON.parse(result.content[0].text)).toMatchObject({
+      id: "task-1",
+      _etag: 'W/"etag-1"'
+    });
+  });
+  it("adds HTTP status and Graph error code metadata to failed Graph responses", async () => {
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          error: {
+            code: "accessDenied",
+            message: "Access denied"
+          }
+        }),
+        {
+          status: 403,
+          statusText: "Forbidden",
+          headers: { "content-type": "application/json" }
+        }
+      )
+    );
+    const result = await createGraphClient().graphRequest("/me/drive");
+    expect(result.isError).toBe(true);
+    expect(result._meta).toMatchObject({
+      http_status: 403,
+      error_code: "accessDenied"
+    });
+    expect(JSON.parse(result.content[0].text).error).toContain(
+      "Microsoft Graph API error: 403 Forbidden"
+    );
+  });
+  it("adds aggregate subrequest metadata to successful Graph batch responses", async () => {
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          responses: [
+            { id: "1", status: 200, body: { id: "message-1" } },
+            {
+              id: "2",
+              status: 403,
+              body: { error: { code: "accessDenied", message: "Access denied" } }
+            },
+            {
+              id: "3",
+              status: 429,
+              body: { error: { code: "tooManyRequests", message: "Slow down" } }
+            },
+            {
+              id: "4",
+              status: 403,
+              body: { error: { code: "accessDenied", message: "Access denied" } }
+            }
+          ]
+        }),
+        {
+          status: 200,
+          headers: { "content-type": "application/json" }
+        }
+      )
+    );
+    const result = await createGraphClient().graphRequest("/$batch", {
+      method: "POST",
+      body: JSON.stringify({ requests: [] })
+    });
+    expect(result.isError).toBeUndefined();
+    expect(result._meta).toMatchObject({
+      http_status: 200,
+      graph_batch_subrequest_count: 4,
+      graph_batch_http_status_counts: { "200": 1, "403": 2, "429": 1 },
+      graph_batch_error_code_counts: { accessDenied: 2, tooManyRequests: 1 }
+    });
+  });
+});

package/dist/__tests__/graph-tools.test.js

@@ -3,14 +3,23 @@ import { z } from "zod";
 import { tmpdir } from "os";
 import { join } from "path";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+const loggerMock = vi.hoisted(() => ({
+  info: vi.fn(),
+  warn: vi.fn(),
+  error: vi.fn(),
+  debug: vi.fn()
+}));
 vi.mock("../logger.js", () => ({
-  default: {
-    info: vi.fn(),
-    warn: vi.fn(),
-    error: vi.fn(),
-    debug: vi.fn()
-  }
+  default: loggerMock
 }));
+const auditLogMock = vi.hoisted(() => vi.fn());
+vi.mock("../audit-log.js", async () => {
+  const actual = await vi.importActual("../audit-log.js");
+  return {
+    ...actual,
+    auditLog: auditLogMock
+  };
+});
 const mockEndpoints = [];
 vi.mock("../generated/client-beta.js", () => ({ api: { endpoints: [] } }));
 vi.mock("../generated/client.js", () => ({
@@ -89,10 +98,6 @@ async function loadModule() {
   const mod = await import("../graph-tools.js");
   return mod;
 }
-async function spyOnAuditLogger() {
-  const { __testing } = await import("../audit-log.js");
-  return vi.spyOn(__testing.auditLogger, "info").mockImplementation(() => __testing.auditLogger);
-}
 function createMockServer() {
   const tools = /* @__PURE__ */ new Map();
   return {
@@ -123,6 +128,187 @@ describe("graph-tools", () => {
     mockEndpointsJson = [];
     vi.clearAllMocks();
   });
+  describe("audit outcome metadata", () => {
+    it("includes HTTP status on successful Graph tool calls", async () => {
+      const endpoint = makeEndpoint();
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [{ type: "text", text: JSON.stringify({ value: [] }) }],
+          _meta: { http_status: 200 }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      await server.tools.get("test-tool").handler({});
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "test-tool",
+          status: "success",
+          http_status: 200
+        })
+      );
+    });
+    it("includes HTTP status and Graph error code on failed Graph tool calls", async () => {
+      const endpoint = makeEndpoint();
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "Microsoft Graph API error: 403 Forbidden" })
+            }
+          ],
+          isError: true,
+          _meta: { http_status: 403, error_code: "accessDenied" }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      await server.tools.get("test-tool").handler({});
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "test-tool",
+          status: "error",
+          http_status: 403,
+          error_code: "accessDenied"
+        })
+      );
+    });
+    it("includes HTTP status on utility tool calls that reach Graph", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                contentType: "image/jpeg",
+                encoding: "base64",
+                contentBytes: "aGk="
+              })
+            }
+          ],
+          _meta: { http_status: 200 }
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      await server.tools.get("download-bytes").handler({ target: "/me/photo/$value" });
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "download-bytes",
+          status: "success",
+          http_method: "GET",
+          http_status: 200
+        })
+      );
+    });
+    it("includes HTTP status and Graph error code on failed utility Graph calls", async () => {
+      mockEndpoints.length = 0;
+      mockEndpointsJson = [];
+      const graphClient = {
+        graphRequest: vi.fn().mockResolvedValue({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "Microsoft Graph API error: 403 Forbidden" })
+            }
+          ],
+          isError: true,
+          _meta: { http_status: 403, error_code: "accessDenied" }
+        })
+      };
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      await server.tools.get("download-bytes").handler({ target: "/me/photo/$value" });
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "download-bytes",
+          status: "error",
+          http_status: 403,
+          error_code: "accessDenied"
+        })
+      );
+    });
+    it("copies Graph batch outcome metadata into audit events", async () => {
+      const endpoint = makeEndpoint({
+        method: "post",
+        path: "/$batch",
+        alias: "graph-batch",
+        parameters: [{ name: "body", type: "Body", schema: z.object({}).passthrough() }]
+      });
+      const config = makeConfig({
+        pathPattern: "/$batch",
+        method: "post",
+        toolName: "graph-batch"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                responses: [
+                  { id: "1", status: 200, body: { id: "message-1" } },
+                  {
+                    id: "2",
+                    status: 403,
+                    body: { error: { code: "accessDenied", message: "Access denied" } }
+                  }
+                ]
+              })
+            }
+          ],
+          _meta: {
+            http_status: 200,
+            graph_batch_subrequest_count: 2,
+            graph_batch_http_status_counts: { "200": 1, "403": 1 },
+            graph_batch_error_code_counts: { accessDenied: 1 }
+          }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      await server.tools.get("graph-batch").handler({
+        body: { requests: [{ id: "1", method: "GET", url: "/me" }] }
+      });
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "graph-batch",
+          status: "success",
+          http_status: 200,
+          graph_batch_subrequest_count: 2,
+          graph_batch_http_status_counts: { "200": 1, "403": 1 },
+          graph_batch_error_code_counts: { accessDenied: 1 }
+        })
+      );
+    });
+  });
   describe("$count advanced query mode", () => {
     it("should set ConsistencyLevel: eventual header when $count=true", async () => {
       const endpoint = makeEndpoint();
@@ -166,12 +352,11 @@ describe("graph-tools", () => {
       const server = createMockServer();
       const { registerGraphTools } = await loadModule();
       registerGraphTools(server, graphClient);
-      const auditSpy = await spyOnAuditLogger();
       await server.tools.get("get-drive-item").handler({
         driveId: "drive-1",
         driveItemId: "item-2"
       });
-      expect(auditSpy).toHaveBeenCalledWith(
+      expect(auditLogMock).toHaveBeenCalledWith(
         expect.objectContaining({
           event: "tool.call",
           tool: "get-drive-item",
@@ -182,7 +367,6 @@ describe("graph-tools", () => {
           }
         })
       );
-      auditSpy.mockRestore();
     });
     it("adds target_resource to failed generated Graph tool audit events", async () => {
       const endpoint = makeEndpoint({
@@ -210,13 +394,12 @@ describe("graph-tools", () => {
         server,
         graphClient
       );
-      const auditSpy = await spyOnAuditLogger();
       const result = await server.tools.get("get-drive-item").handler({
         driveId: "drive-1",
         driveItemId: "item-2"
       });
       expect(result.isError).toBe(true);
-      expect(auditSpy).toHaveBeenCalledWith(
+      expect(auditLogMock).toHaveBeenCalledWith(
         expect.objectContaining({
           event: "tool.call",
           tool: "get-drive-item",
@@ -228,7 +411,6 @@ describe("graph-tools", () => {
           }
         })
       );
-      auditSpy.mockRestore();
     });
     it("derives target_resource from generic ID path parameters", async () => {
       const endpoint = makeEndpoint({
@@ -248,11 +430,10 @@ describe("graph-tools", () => {
       const server = createMockServer();
       const { registerGraphTools } = await loadModule();
       registerGraphTools(server, graphClient);
-      const auditSpy = await spyOnAuditLogger();
       await server.tools.get("get-mail-message").handler({
         messageId: "message-1"
       });
-      expect(auditSpy).toHaveBeenCalledWith(
+      expect(auditLogMock).toHaveBeenCalledWith(
         expect.objectContaining({
           event: "tool.call",
           tool: "get-mail-message",
@@ -263,7 +444,6 @@ describe("graph-tools", () => {
           }
         })
       );
-      auditSpy.mockRestore();
     });
     it("omits target_resource when an ID path parameter is missing", async () => {
       const endpoint = makeEndpoint({
@@ -287,18 +467,16 @@ describe("graph-tools", () => {
       const server = createMockServer();
       const { registerGraphTools } = await loadModule();
       registerGraphTools(server, graphClient);
-      const auditSpy = await spyOnAuditLogger();
       await server.tools.get("get-drive-item").handler({
         driveId: "drive-1"
       });
-      const [payload] = auditSpy.mock.calls[0];
+      const [payload] = auditLogMock.mock.calls[0];
       expect(payload).toMatchObject({
         event: "tool.call",
         tool: "get-drive-item",
         status: "success"
       });
       expect(payload).not.toHaveProperty("target_resource");
-      auditSpy.mockRestore();
     });
     it("omits SharePoint path parameters from target_resource", async () => {
       const endpoint = makeEndpoint({
@@ -322,12 +500,11 @@ describe("graph-tools", () => {
       const server = createMockServer();
       const { registerGraphTools } = await loadModule();
       registerGraphTools(server, graphClient);
-      const auditSpy = await spyOnAuditLogger();
       await server.tools.get("get-sharepoint-site-by-path").handler({
         siteId: "contoso.sharepoint.com",
         path: "/sites/Finance"
       });
-      expect(auditSpy).toHaveBeenCalledWith(
+      expect(auditLogMock).toHaveBeenCalledWith(
         expect.objectContaining({
           event: "tool.call",
           tool: "get-sharepoint-site-by-path",
@@ -338,9 +515,8 @@ describe("graph-tools", () => {
           }
         })
       );
-      const [payload] = auditSpy.mock.calls[0];
+      const [payload] = auditLogMock.mock.calls[0];
       expect(JSON.stringify(payload)).not.toContain("Finance");
-      auditSpy.mockRestore();
     });
     it("omits target_resource for generated broad list/search audit events", async () => {
       const endpoint = makeEndpoint({
@@ -359,16 +535,14 @@ describe("graph-tools", () => {
       const server = createMockServer();
       const { registerGraphTools } = await loadModule();
       registerGraphTools(server, graphClient);
-      const auditSpy = await spyOnAuditLogger();
       await server.tools.get("list-mail-messages").handler({ search: "budget" });
-      const [payload] = auditSpy.mock.calls[0];
+      const [payload] = auditLogMock.mock.calls[0];
       expect(payload).toMatchObject({
         event: "tool.call",
         tool: "list-mail-messages",
         status: "success"
       });
       expect(payload).not.toHaveProperty("target_resource");
-      auditSpy.mockRestore();
     });
   });
   describe("fetchAllPages pagination", () => {
@@ -411,6 +585,55 @@ describe("graph-tools", () => {
       expect(parsed.value.map((v) => v.id)).toEqual(["1", "2", "3"]);
       expect(parsed["@odata.nextLink"]).toBeUndefined();
     });
+    it("returns and audits a later-page Graph error instead of partial success", async () => {
+      const endpoint = makeEndpoint();
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                value: [{ id: "1" }],
+                "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=1"
+              })
+            }
+          ],
+          _meta: { http_status: 200 }
+        },
+        {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: "Microsoft Graph API error: 429 Too Many Requests" })
+            }
+          ],
+          isError: true,
+          _meta: { http_status: 429, error_code: "tooManyRequests" }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const result = await server.tools.get("test-tool").handler({ fetchAllPages: true });
+      expect(result.isError).toBe(true);
+      expect(JSON.parse(result.content[0].text).error).toContain("429 Too Many Requests");
+      expect(graphClient.graphRequest).toHaveBeenCalledTimes(2);
+      expect(loggerMock.error).not.toHaveBeenCalledWith(
+        expect.stringContaining("Error during pagination")
+      );
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "test-tool",
+          status: "error",
+          http_status: 429,
+          error_code: "tooManyRequests"
+        })
+      );
+    });
     it("merges all pages under --toon and encodes the combined result once (#560)", async () => {
       const endpoint = makeEndpoint();
       const config = makeConfig();
@@ -1021,7 +1244,8 @@ describe("graph-tools", () => {
       const graphClient = {
         downloadToFile: vi.fn().mockResolvedValue({
           contentType: "image/jpeg",
-          contentLength: 2
+          contentLength: 2,
+          httpStatus: 200
         })
       };
       const server = createMockServer();
@@ -1039,6 +1263,15 @@ describe("graph-tools", () => {
       expect(result.isError).toBeUndefined();
       const payload = JSON.parse(result.content[0].text);
       expect(payload).toEqual({ path: outputPath, contentType: "image/jpeg", bytesWritten: 2 });
+      expect(result._meta).toMatchObject({ http_status: 200 });
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "download-bytes-to-file",
+          status: "success",
+          http_status: 200
+        })
+      );
     });
     it("rejects a relative outputPath", async () => {
       mockEndpoints.length = 0;
@@ -1178,7 +1411,8 @@ describe("graph-tools", () => {
                 "@microsoft.graph.downloadUrl": downloadUrl
               })
             }
-          ]
+          ],
+          _meta: { http_status: 200 }
         })
       };
       const server = createMockServer();
@@ -1196,6 +1430,15 @@ describe("graph-tools", () => {
       expect(payload.name).toBe("report.pdf");
       expect(payload.size).toBe(12727);
       expect(payload.contentType).toBe("application/pdf");
+      expect(result._meta).toMatchObject({ http_status: 200 });
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.call",
+          tool: "get-download-url",
+          status: "success",
+          http_status: 200
+        })
+      );
     });
     it("forces a JSON body on the metadata request so it works under --toon (#560)", async () => {
       mockEndpoints.length = 0;

package/dist/auth-tools.js

@@ -34,7 +34,6 @@ function registerAuthTools(server, authManager) {
                 type: "text",
                 text: JSON.stringify({
                   status: "Login successful",
-                  message: "Browser authentication completed successfully.",
                   ...loginResult
                 })
               }

package/dist/graph-client.js

@@ -31,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";
@@ -39,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) {
@@ -47,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());
@@ -88,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;
@@ -121,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");
@@ -150,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);
@@ -162,6 +209,23 @@ 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";
@@ -211,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 {
@@ -302,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: [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softeria/ms-365-mcp-server",
   "mcpName": "io.github.Softeria/ms-365-mcp-server",
-  "version": "0.143.0",
+  "version": "0.144.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",
@@ -19,7 +19,8 @@
     "format:check": "prettier --check \"**/*.{ts,mts,js,mjs,json,md}\"",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "verify": "npm run generate && npm run lint && npm run format:check && npm run build && npm run test",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run generate && npm run lint && npm run format:check && npm run typecheck && npm run build && npm run test",
     "inspector": "npx @modelcontextprotocol/inspector tsx src/index.ts"
   },
   "keywords": [