@softeria/ms-365-mcp-server 0.151.0 → 0.152.0

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

@@ -42,6 +42,52 @@ describe("GraphClient audit metadata", () => {
     expect(result._meta).toMatchObject({ http_status: 200 });
     expect(JSON.parse(result.content[0].text)).toEqual({ id: "user-1" });
   });
+  it("derives result volume from a collection response", async () => {
+    const body = JSON.stringify({
+      value: [{ id: "m1" }, { id: "m2" }, { id: "m3" }],
+      "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=3"
+    });
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(body, { status: 200, headers: { "content-type": "application/json" } })
+    );
+    const result = await createGraphClient().graphRequest("/me/messages");
+    expect(result._meta).toMatchObject({
+      result_count: 3,
+      result_has_more: true,
+      response_bytes: Buffer.byteLength(body, "utf8")
+    });
+  });
+  it("reports result_has_more false, not absent, for a complete collection", async () => {
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(JSON.stringify({ value: [{ id: "m1" }] }), {
+        status: 200,
+        headers: { "content-type": "application/json" }
+      })
+    );
+    const result = await createGraphClient().graphRequest("/me/messages");
+    expect(result._meta).toMatchObject({ result_count: 1, result_has_more: false });
+  });
+  it("omits result fields for a single-object response but still records size", async () => {
+    const body = JSON.stringify({ id: "user-1" });
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(body, { status: 200, headers: { "content-type": "application/json" } })
+    );
+    const result = await createGraphClient().graphRequest("/me");
+    expect(result._meta).toMatchObject({ response_bytes: Buffer.byteLength(body, "utf8") });
+    expect(result._meta).not.toHaveProperty("result_count");
+    expect(result._meta).not.toHaveProperty("result_has_more");
+  });
+  it("records the pre-base64 byte count for binary content", async () => {
+    const raw = Buffer.from("binary-attachment-payload-\xFF\xFE");
+    fetchWithResilienceMock.mockResolvedValue(
+      new Response(raw, {
+        status: 200,
+        headers: { "content-type": "application/octet-stream" }
+      })
+    );
+    const result = await createGraphClient().graphRequest("/me/messages/m1/$value");
+    expect(result._meta).toMatchObject({ response_bytes: raw.byteLength });
+  });
   it("preserves HTTP status metadata when response headers are requested", async () => {
     fetchWithResilienceMock.mockResolvedValue(
       new Response(JSON.stringify({ id: "task-1" }), {

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

@@ -333,6 +333,172 @@ describe("graph-tools", () => {
       );
     });
   });
+  describe("audit response volume", () => {
+    it("lifts result volume from _meta onto the audit event", async () => {
+      const endpoint = makeEndpoint({
+        method: "get",
+        path: "/me/messages",
+        alias: "list-mail-messages"
+      });
+      const config = makeConfig({
+        pathPattern: "/me/messages",
+        method: "get",
+        toolName: "list-mail-messages"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [{ type: "text", text: JSON.stringify({ value: [{ id: "m1" }] }) }],
+          _meta: {
+            http_status: 200,
+            result_count: 4821,
+            result_has_more: true,
+            response_bytes: 8412004
+          }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      await server.tools.get("list-mail-messages").handler({});
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          tool: "list-mail-messages",
+          status: "success",
+          result_count: 4821,
+          result_has_more: true,
+          response_bytes: 8412004
+        })
+      );
+    });
+    it("keeps result_has_more when it is false rather than dropping it", async () => {
+      const endpoint = makeEndpoint({
+        method: "get",
+        path: "/me/messages",
+        alias: "list-mail-messages"
+      });
+      const config = makeConfig({
+        pathPattern: "/me/messages",
+        method: "get",
+        toolName: "list-mail-messages"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [{ type: "text", text: JSON.stringify({ value: [] }) }],
+          _meta: { http_status: 200, result_count: 0, result_has_more: false }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      await server.tools.get("list-mail-messages").handler({});
+      const [payload] = auditLogMock.mock.calls[0];
+      expect(payload.result_count).toBe(0);
+      expect(payload.result_has_more).toBe(false);
+    });
+    it("restates count and bytes for the whole read when pages are merged", async () => {
+      mockEndpoints.push(makeEndpoint());
+      mockEndpointsJson = [makeConfig()];
+      const graphClient = createMockGraphClient([
+        {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                value: [{ id: "1" }, { id: "2" }],
+                "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=2"
+              })
+            }
+          ],
+          _meta: { http_status: 200, result_count: 2, result_has_more: true, response_bytes: 1e3 }
+        },
+        {
+          content: [{ type: "text", text: JSON.stringify({ value: [{ id: "3" }] }) }],
+          _meta: { http_status: 200, result_count: 1, result_has_more: false, response_bytes: 700 }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      await server.tools.get("test-tool").handler({ fetchAllPages: true });
+      const [payload] = auditLogMock.mock.calls[0];
+      expect(payload.result_count).toBe(3);
+      expect(payload.result_has_more).toBe(false);
+      expect(payload.response_bytes).toBe(1700);
+    });
+    it("reports result_has_more when the merge loop stopped on a page cap", async () => {
+      const prevMaxPages = process.env.MS365_MCP_MAX_PAGES;
+      process.env.MS365_MCP_MAX_PAGES = "2";
+      try {
+        mockEndpoints.push(makeEndpoint());
+        mockEndpointsJson = [makeConfig()];
+        const graphClient = createMockGraphClient(
+          Array.from({ length: 5 }, (_, i) => ({
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  value: [{ id: `item-${i}` }],
+                  "@odata.nextLink": `https://graph.microsoft.com/v1.0/me/messages?$skip=${i + 1}`
+                })
+              }
+            ],
+            _meta: { http_status: 200, result_count: 1, result_has_more: true, response_bytes: 50 }
+          }))
+        );
+        const server = createMockServer();
+        const { registerGraphTools } = await loadModule();
+        registerGraphTools(server, graphClient);
+        await server.tools.get("test-tool").handler({ fetchAllPages: true });
+        const [payload] = auditLogMock.mock.calls[0];
+        expect(payload.result_count).toBe(2);
+        expect(payload.result_has_more).toBe(true);
+        expect(payload.response_bytes).toBe(100);
+      } finally {
+        if (prevMaxPages === void 0) {
+          delete process.env.MS365_MCP_MAX_PAGES;
+        } else {
+          process.env.MS365_MCP_MAX_PAGES = prevMaxPages;
+        }
+      }
+    });
+    it("omits the volume fields when the client supplied none", async () => {
+      const endpoint = makeEndpoint({ method: "get", path: "/me", alias: "get-current-user" });
+      const config = makeConfig({
+        pathPattern: "/me",
+        method: "get",
+        toolName: "get-current-user"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        {
+          content: [{ type: "text", text: JSON.stringify({ id: "user-1" }) }],
+          _meta: { http_status: 200 }
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        graphClient
+      );
+      await server.tools.get("get-current-user").handler({});
+      const [payload] = auditLogMock.mock.calls[0];
+      expect(payload).not.toHaveProperty("result_count");
+      expect(payload).not.toHaveProperty("result_has_more");
+      expect(payload).not.toHaveProperty("response_bytes");
+    });
+  });
   describe("audit recipient metadata", () => {
     const draftEndpoint = () => {
       const endpoint = makeEndpoint({

package/dist/graph-client.js

@@ -66,6 +66,13 @@ function extractGraphErrorCodeFromBody(body) {
   const code = isRecord(error) ? error.code : body.code;
   return typeof code === "string" ? code : void 0;
 }
+function extractPayloadMetadata(data) {
+  if (!isRecord(data) || !Array.isArray(data.value)) return {};
+  return {
+    result_count: data.value.length,
+    result_has_more: typeof data["@odata.nextLink"] === "string"
+  };
+}
 function extractBatchMetadata(data) {
   if (!isRecord(data) || !Array.isArray(data.responses)) return {};
   const httpStatusCounts = {};
@@ -125,8 +132,10 @@ class GraphClient {
           contentLength: buffer.byteLength,
           contentBytes: buffer.toString("base64")
         };
+        metadata = { ...metadata, response_bytes: buffer.byteLength };
       } else {
         const text = await response.text();
+        metadata = { ...metadata, response_bytes: Buffer.byteLength(text, "utf8") };
         if (text === "") {
           result = { message: TRANSPORT_OK_MESSAGE };
         } else if (options.rawResponse) {
@@ -142,6 +151,7 @@ class GraphClient {
       if (endpoint === "/$batch") {
         metadata = { ...metadata, ...extractBatchMetadata(result) };
       }
+      metadata = { ...metadata, ...extractPayloadMetadata(result) };
       if (options.includeHeaders) {
         const etag = response.headers.get("ETag") || response.headers.get("etag");
         if (result && typeof result === "object" && !Array.isArray(result)) {

package/dist/graph-tools.js

@@ -256,7 +256,13 @@ function graphResponseAuditFields(response) {
   const graphBatchErrorCodeCounts = auditStringNumberMap(
     response._meta?.graph_batch_error_code_counts
   );
+  const resultCount = auditNonNegativeInteger(response._meta?.result_count);
+  const responseBytes = auditNonNegativeInteger(response._meta?.response_bytes);
+  const resultHasMore = typeof response._meta?.result_has_more === "boolean" ? response._meta.result_has_more : void 0;
   return {
+    ...resultCount !== void 0 ? { result_count: resultCount } : {},
+    ...resultHasMore !== void 0 ? { result_has_more: resultHasMore } : {},
+    ...responseBytes !== void 0 ? { response_bytes: responseBytes } : {},
     ...httpStatus !== void 0 ? { http_status: httpStatus } : {},
     ...errorCode !== void 0 ? { error_code: errorCode } : {},
     ...graphBatchSubrequestCount !== void 0 ? { graph_batch_subrequest_count: graphBatchSubrequestCount } : {},
@@ -770,7 +776,14 @@ const UTILITY_TOOLS = [
               })
             }
           ],
-          ...result.httpStatus !== void 0 ? { _meta: { http_status: result.httpStatus } } : {}
+          // response_bytes must describe the file written, not this receipt.
+          // Streaming to disk means the payload never appears in the response,
+          // so without this the most extraction-shaped tool in the server would
+          // audit a 250MB download at the size of an error message.
+          _meta: {
+            ...result.httpStatus !== void 0 ? { http_status: result.httpStatus } : {},
+            ...typeof result.contentLength === "number" ? { response_bytes: result.contentLength } : {}
+          }
         };
       } catch (error) {
         const metadata = thrownErrorAuditFields(error);
@@ -1376,6 +1389,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
           let allItems = firstValue;
           let nextLink = combinedResponse["@odata.nextLink"];
           let pageCount = 1;
+          let totalResponseBytes = response._meta?.response_bytes;
           const maxPages = positiveIntFromEnv("MS365_MCP_MAX_PAGES", DEFAULT_MAX_PAGES);
           const maxItems = positiveIntFromEnv("MS365_MCP_MAX_ITEMS", DEFAULT_MAX_ITEMS);
           let deltaLink = combinedResponse["@odata.deltaLink"];
@@ -1396,6 +1410,9 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
                 allItems = allItems.concat(nextJsonResponse.value);
               }
               nextLink = nextJsonResponse["@odata.nextLink"];
+              if (typeof totalResponseBytes === "number" && typeof nextResponse._meta?.response_bytes === "number") {
+                totalResponseBytes += nextResponse._meta.response_bytes;
+              }
               if (nextJsonResponse["@odata.deltaLink"]) {
                 deltaLink = nextJsonResponse["@odata.deltaLink"];
               }
@@ -1418,6 +1435,12 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
               combinedResponse["@odata.count"] = allItems.length;
             }
             delete combinedResponse["@odata.nextLink"];
+            response._meta = {
+              ...response._meta,
+              result_count: allItems.length,
+              result_has_more: Boolean(nextLink),
+              ...totalResponseBytes !== void 0 ? { response_bytes: totalResponseBytes } : {}
+            };
             if (deltaLink) {
               combinedResponse["@odata.deltaLink"] = deltaLink;
             }

package/docs/deployment.md

@@ -213,7 +213,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
 - **Disable Dynamic Client Registration**: when only a known client talks to the server, set `MS365_MCP_DISABLE_DCR=true` (or pass `--no-dynamic-registration`) to close the anonymous `/register` endpoint
-- **Structured audit log**: enabled by default. Every tool invocation that reaches Microsoft Graph emits one JSON line on stderr (captured by the container platform's log collector) and to `~/.ms-365-mcp-server/logs/audit.log` (mode `0o600`, or under `MS365_MCP_LOG_DIR` when set) with `{ event, request_id, user_principal_name, tool, http_method, http_status?, status, duration_ms, recipient_count?, recipient_domains?, recipient_domains_truncated?, graph_batch_subrequest_count?, graph_batch_http_status_counts?, graph_batch_error_code_counts?, target_resource?, error_type?, error_code? }`. A few refusals short-circuit before that and emit nothing: a confirm-gate rejection, an `account` param that contradicts the bearer identity, and a failure to resolve an account token. Policy-blocked tool attempts emit `event: "tool.denied"` with `status: "denied"`, `reason` (`allowed_scopes` or `tool_allowlist`), and `missing_scopes` when applicable. When an audited generated Microsoft Graph tool targets a derivable resource through an ID-like path parameter such as `{message-id}` or `{driveItem-id}`, `target_resource` is `{ type, id }`, where `id` is the Graph path up to that resource ID. Later path parameters such as `{path}`, query values, returned content, 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. Two things derived from tool parameters **are** recorded, both deliberately. First, `target_resource.id` substitutes ID-like path parameters into the resource path, so a tool on `/users/{user-id}/...` records whatever identifier the caller passed, which may be a full email address. Second, a request whose body carries `toRecipients` / `ccRecipients` / `bccRecipients` / `attendees` / `recipients`, at any casing and several levels down, including inside a `graph-batch` sub-request, records `recipient_count`, the number of entries in those arrays, and `recipient_domains`, the **domain part only** of their addresses and only where it parses as a plain hostname, never the local part and never a subject or message body. An entry that names someone without an address (a `driveRecipient` given as `alias` or `objectId`) counts but contributes no domain. It keys on body shape rather than on the endpoint, so it covers sends, forwards, invites and file shares but equally draft creation and edits, event updates and `findMeetingTimes`, and it reads high rather than low: an attached message's own recipients are counted too. `recipient_domains` holds at most 50 **distinct domains**, alphabetically, and sets `recipient_domains_truncated: true` when there were more; `recipient_count` is unaffected by the cap. All three are absent when the body carries no recipient array at all. A request that fails after reaching Graph still records recipients, since a timeout is not proof of non-delivery. Gaps remain, so absence proves nothing: a draft composed outside this server and sent by id, the original thread's recipients on a reply (Graph resolves those server-side), and a body nesting recipients deeper than the walker descends. This describes the structured audit log only; the operational logger is separate and does log tool parameters. Forms the "who accessed what, when" trail required for GDPR / HIPAA / PIPEDA / SOC 2 audit. Opt-out: `MS365_MCP_AUDIT_LOG=false`
+- **Structured audit log**: enabled by default. Every tool invocation that reaches Microsoft Graph emits one JSON line on stderr (captured by the container platform's log collector) and to `~/.ms-365-mcp-server/logs/audit.log` (mode `0o600`, or under `MS365_MCP_LOG_DIR` when set) with `{ event, request_id, user_principal_name, tool, http_method, http_status?, status, duration_ms, recipient_count?, recipient_domains?, recipient_domains_truncated?, graph_batch_subrequest_count?, graph_batch_http_status_counts?, graph_batch_error_code_counts?, result_count?, result_has_more?, response_bytes?, target_resource?, error_type?, error_code? }`. A few refusals short-circuit before that and emit nothing: a confirm-gate rejection, an `account` param that contradicts the bearer identity, and a failure to resolve an account token. Policy-blocked tool attempts emit `event: "tool.denied"` with `status: "denied"`, `reason` (`allowed_scopes` or `tool_allowlist`), and `missing_scopes` when applicable. When an audited generated Microsoft Graph tool targets a derivable resource through an ID-like path parameter such as `{message-id}` or `{driveItem-id}`, `target_resource` is `{ type, id }`, where `id` is the Graph path up to that resource ID. Later path parameters such as `{path}`, query values, returned content, 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. Response _metadata_ is recorded — `result_count`, `result_has_more` and `response_bytes` describe how much came back so that a bulk read is distinguishable from an ordinary one; none of them reveals any of its content. Two things derived from tool parameters **are** recorded, both deliberately. First, `target_resource.id` substitutes ID-like path parameters into the resource path, so a tool on `/users/{user-id}/...` records whatever identifier the caller passed, which may be a full email address. Second, a request whose body carries `toRecipients` / `ccRecipients` / `bccRecipients` / `attendees` / `recipients`, at any casing and several levels down, including inside a `graph-batch` sub-request, records `recipient_count`, the number of entries in those arrays, and `recipient_domains`, the **domain part only** of their addresses and only where it parses as a plain hostname, never the local part and never a subject or message body. An entry that names someone without an address (a `driveRecipient` given as `alias` or `objectId`) counts but contributes no domain. It keys on body shape rather than on the endpoint, so it covers sends, forwards, invites and file shares but equally draft creation and edits, event updates and `findMeetingTimes`, and it reads high rather than low: an attached message's own recipients are counted too. `recipient_domains` holds at most 50 **distinct domains**, alphabetically, and sets `recipient_domains_truncated: true` when there were more; `recipient_count` is unaffected by the cap. All three are absent when the body carries no recipient array at all. A request that fails after reaching Graph still records recipients, since a timeout is not proof of non-delivery. Gaps remain, so absence proves nothing: a draft composed outside this server and sent by id, the original thread's recipients on a reply (Graph resolves those server-side), and a body nesting recipients deeper than the walker descends. This describes the structured audit log only; the operational logger is separate and does log tool parameters. 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`
 - **Confirm gate on destructive tools**: opt-in, **off by default**. Enable with `MS365_MCP_REQUIRE_CONFIRM=true`. When on, destructive tools (POST except `readOnly`, PATCH, PUT, DELETE — `delete-mail-message`, `send-mail`, `update-event`, etc.) return `{ "error": "confirmation_required" }` until the caller re-invokes them with `"confirm": true`. Mitigates accidental writes when an LLM misroutes a request or follows an injected instruction. Shipped opt-in so it is a non-breaking, additive layer that can coexist with client-side elicitation prompts (MCP Elicitation API) where the client supports them.
 

package/package.json

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