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

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

@@ -100,10 +100,33 @@ async function loadModule() {
 }
 function createMockServer() {
   const tools = /* @__PURE__ */ new Map();
+  const requestHandlers = /* @__PURE__ */ new Map();
+  const installDefaultToolCallHandler = () => {
+    if (requestHandlers.has("tools/call")) return;
+    requestHandlers.set("tools/call", async (request) => {
+      const params = request.params;
+      const toolName = params?.name ?? "unknown";
+      const tool = tools.get(toolName);
+      if (!tool) {
+        throw new Error(`Tool ${toolName} not found`);
+      }
+      return tool.handler(params?.arguments ?? {});
+    });
+  };
+  const lowLevelServer = {
+    _requestHandlers: requestHandlers,
+    setRequestHandler: vi.fn(
+      (_schema, handler) => {
+        requestHandlers.set("tools/call", handler);
+      }
+    )
+  };
   return {
+    server: lowLevelServer,
     tool: vi.fn(
       (name, description, schema, annotations, handler) => {
         tools.set(name, { description, schema, handler });
+        installDefaultToolCallHandler();
       }
     ),
     registerTool: vi.fn(
@@ -113,6 +136,7 @@ function createMockServer() {
           schema: config.inputSchema?.shape ?? config.inputSchema,
           handler
         });
+        installDefaultToolCallHandler();
       }
     ),
     tools
@@ -1817,6 +1841,65 @@ describe("graph-tools", () => {
       expect(server.tools.has("list-mail-messages")).toBe(true);
       expect(server.tools.has("list-calendar-events")).toBe(false);
     });
+    it("audits direct calls to Graph tools denied by allowed scopes", async () => {
+      mockEndpoints.push({
+        alias: "get-drive-item",
+        method: "get",
+        path: "/drives/:driveId/items/:driveItemId",
+        description: "Get drive item",
+        parameters: [
+          { name: "driveId", type: "Path", schema: z.string() },
+          { name: "driveItemId", type: "Path", schema: z.string() }
+        ]
+      });
+      mockEndpointsJson = [
+        {
+          toolName: "get-drive-item",
+          method: "get",
+          pathPattern: "/drives/{drive-id}/items/{driveItem-id}",
+          scopes: ["Files.Read"]
+        }
+      ];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(
+        server,
+        createMockGraphClient(),
+        false,
+        void 0,
+        false,
+        void 0,
+        false,
+        [],
+        "Mail.Read"
+      );
+      const handler = server.server._requestHandlers.get("tools/call");
+      await expect(
+        handler?.(
+          {
+            method: "tools/call",
+            params: {
+              name: "get-drive-item",
+              arguments: { driveId: "drive-1", driveItemId: "item-2" }
+            }
+          },
+          {}
+        )
+      ).rejects.toThrow(/not found/);
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.denied",
+          tool: "get-drive-item",
+          status: "denied",
+          reason: "allowed_scopes",
+          missing_scopes: ["Files.Read"],
+          target_resource: {
+            type: "drive_item",
+            id: "/drives/drive-1/items/item-2"
+          }
+        })
+      );
+    });
     it("discovery hides Graph tools outside the allowed scopes", async () => {
       mockEndpoints.push(
         {
@@ -1866,6 +1949,117 @@ describe("graph-tools", () => {
       expect(found).toContain("list-mail-messages");
       expect(found).not.toContain("list-calendar-events");
     });
+    it("audits execute-tool attempts denied by allowed scopes", async () => {
+      mockEndpoints.push({
+        alias: "get-drive-item",
+        method: "get",
+        path: "/drives/:driveId/items/:driveItemId",
+        description: "Get drive item",
+        parameters: [
+          { name: "driveId", type: "Path", schema: z.string() },
+          { name: "driveItemId", type: "Path", schema: z.string() }
+        ]
+      });
+      mockEndpointsJson = [
+        {
+          toolName: "get-drive-item",
+          method: "get",
+          pathPattern: "/drives/{drive-id}/items/{driveItem-id}",
+          scopes: ["Files.Read"]
+        }
+      ];
+      const server = createMockServer();
+      const { registerDiscoveryTools } = await loadModule();
+      registerDiscoveryTools(
+        server,
+        {},
+        false,
+        false,
+        void 0,
+        false,
+        [],
+        void 0,
+        "Mail.Read"
+      );
+      const result = await server.tools.get("execute-tool").handler({
+        tool_name: "get-drive-item",
+        parameters: { driveId: "drive-1", driveItemId: "item-2" }
+      });
+      expect(result.isError).toBe(true);
+      expect(JSON.parse(result.content[0].text).error).toMatch(/not found/i);
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.denied",
+          tool: "get-drive-item",
+          status: "denied",
+          reason: "allowed_scopes",
+          missing_scopes: ["Files.Read"],
+          target_resource: {
+            type: "drive_item",
+            id: "/drives/drive-1/items/item-2"
+          }
+        })
+      );
+    });
+    it("audits direct discovery-mode calls to Graph tools denied by allowed scopes", async () => {
+      mockEndpoints.push({
+        alias: "get-drive-item",
+        method: "get",
+        path: "/drives/:driveId/items/:driveItemId",
+        description: "Get drive item",
+        parameters: [
+          { name: "driveId", type: "Path", schema: z.string() },
+          { name: "driveItemId", type: "Path", schema: z.string() }
+        ]
+      });
+      mockEndpointsJson = [
+        {
+          toolName: "get-drive-item",
+          method: "get",
+          pathPattern: "/drives/{drive-id}/items/{driveItem-id}",
+          scopes: ["Files.Read"]
+        }
+      ];
+      const server = createMockServer();
+      const { registerDiscoveryTools } = await loadModule();
+      registerDiscoveryTools(
+        server,
+        {},
+        false,
+        false,
+        void 0,
+        false,
+        [],
+        void 0,
+        "Mail.Read"
+      );
+      const handler = server.server._requestHandlers.get("tools/call");
+      await expect(
+        handler?.(
+          {
+            method: "tools/call",
+            params: {
+              name: "get-drive-item",
+              arguments: { driveId: "drive-1", driveItemId: "item-2" }
+            }
+          },
+          {}
+        )
+      ).rejects.toThrow(/not found/);
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.denied",
+          tool: "get-drive-item",
+          status: "denied",
+          reason: "allowed_scopes",
+          missing_scopes: ["Files.Read"],
+          target_resource: {
+            type: "drive_item",
+            id: "/drives/drive-1/items/item-2"
+          }
+        })
+      );
+    });
   });
   describe("discovery mode: utility tools", () => {
     it('search-tools surfaces download-bytes for "download" queries', async () => {
@@ -1970,6 +2164,65 @@ describe("graph-tools", () => {
       expect(found).toContain("list-mail-messages");
       expect(found).not.toContain("list-calendar-events");
     });
+    it("audits execute-tool attempts denied by the enabled-tools allow-list", async () => {
+      mockEndpoints.push(
+        {
+          alias: "get-drive-item",
+          method: "get",
+          path: "/drives/:driveId/items/:driveItemId",
+          description: "Get drive item",
+          parameters: [
+            { name: "driveId", type: "Path", schema: z.string() },
+            { name: "driveItemId", type: "Path", schema: z.string() }
+          ]
+        },
+        {
+          alias: "list-mail-messages",
+          method: "get",
+          path: "/me/messages",
+          description: "List mail",
+          parameters: []
+        }
+      );
+      mockEndpointsJson = [
+        {
+          toolName: "get-drive-item",
+          method: "get",
+          pathPattern: "/drives/{drive-id}/items/{driveItem-id}"
+        },
+        { toolName: "list-mail-messages", method: "get", pathPattern: "/me/messages" }
+      ];
+      const server = createMockServer();
+      const { registerDiscoveryTools } = await loadModule();
+      registerDiscoveryTools(
+        server,
+        {},
+        false,
+        false,
+        void 0,
+        false,
+        [],
+        "^list-mail-messages$"
+      );
+      const result = await server.tools.get("execute-tool").handler({
+        tool_name: "get-drive-item",
+        parameters: { driveId: "drive-1", driveItemId: "item-2" }
+      });
+      expect(result.isError).toBe(true);
+      expect(JSON.parse(result.content[0].text).error).toMatch(/not found/i);
+      expect(auditLogMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          event: "tool.denied",
+          tool: "get-drive-item",
+          status: "denied",
+          reason: "tool_allowlist",
+          target_resource: {
+            type: "drive_item",
+            id: "/drives/drive-1/items/item-2"
+          }
+        })
+      );
+    });
     it("utility tools obey the regex too", async () => {
       mockEndpoints.length = 0;
       mockEndpointsJson = [];

package/dist/endpoints.json

@@ -212,7 +212,7 @@
     "toolName": "add-mail-attachment",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"],
-    "llmTip": "Max 3MB. Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}."
+    "llmTip": "The only path for attachments under 3MB. contentBytes must carry the complete base64 verbatim; a truncated argument fails with 400 UnableToDeserializePostBody. At 3MB and above use create-mail-attachment-upload-session, which rejects anything smaller. Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}."
   },
   {
     "pathPattern": "/me/messages/{message-id}/attachments/createUploadSession",
@@ -220,7 +220,7 @@
     "toolName": "create-mail-attachment-upload-session",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"],
-    "llmTip": "For large attachments (3-150MB). Body: { AttachmentItem: { attachmentType: 'file', name: 'report.pdf', size: 5000000 } }. Returns a pre-authenticated uploadUrl for direct PUT of file bytes."
+    "llmTip": "For attachments 3MB to 150MB. Graph rejects smaller files with ErrorAttachmentSizeShouldNotBeLessThanMinimumSize, so under 3MB use add-mail-attachment instead. Body: { AttachmentItem: { attachmentType: 'file', name: 'report.pdf', size: 5000000 } }. Returns a pre-authenticated uploadUrl; the caller PUTs the bytes there itself in ranges up to 4MB. This server does not perform the PUT."
   },
   {
     "pathPattern": "/me/messages/{message-id}/attachments",
@@ -607,7 +607,7 @@
     "toolName": "upload-file-content",
     "presets": ["files", "onedrive", "personal"],
     "scopes": ["Files.ReadWrite"],
-    "llmTip": "Body is a base64-encoded string of the file bytes; the server decodes it before PUT. Max 4MB inline (use create-upload-session above 4MB). For new files use path format: /items/root:/path/to/file.txt:/content. Overwrites existing files without warning."
+    "llmTip": "Body is a base64-encoded string of the file bytes; the server decodes it before PUT. Graph accepts up to 250MB here, but the whole string travels as a tool argument and a truncated one decodes to a truncated file with no error, so use create-upload-session rather than emitting a large base64 string. For new files use path format: /items/root:/path/to/file.txt:/content. Overwrites existing files without warning."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/createUploadSession",
@@ -615,7 +615,7 @@
     "toolName": "create-upload-session",
     "presets": ["files", "onedrive", "personal"],
     "scopes": ["Files.ReadWrite"],
-    "llmTip": "For large file uploads (no size limit). Returns a pre-authenticated uploadUrl for direct PUT of file bytes. For new files use path: /items/{parentId}:/{fileName}:/createUploadSession. Body (optional): { item: { '@microsoft.graph.conflictBehavior': 'rename' } }."
+    "llmTip": "For large file uploads (no size limit, and no minimum unlike the Outlook attachment session). Returns a pre-authenticated uploadUrl; the caller PUTs the bytes there itself. This server does not perform the PUT. For new files use path: /items/{parentId}:/{fileName}:/createUploadSession. Body (optional): { item: { '@microsoft.graph.conflictBehavior': 'rename' } }."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -2609,7 +2609,7 @@
     "presets": ["personal"],
     "scopes": ["User.ReadWrite"],
     "contentType": "image/jpeg",
-    "llmTip": "Uploads a new profile photo for the signed-in user. Body is a base64-encoded string of the image bytes (the server decodes before PUT). Photo must be JPEG, max 4 MB. Microsoft 365 generates HD downsized variants automatically (48x48, 64x64, 96x96, 120x120, 240x240, 360x360, 432x432, 504x504, 648x648). For work or school accounts, ProfilePhoto.ReadWrite.All is the more granular alternative permission. Use download-bytes with target=/me/photo/$value to retrieve the current photo."
+    "llmTip": "Uploads a new profile photo for the signed-in user. Body is a base64-encoded string of the image bytes (the server decodes before PUT). Photo must be JPEG, max 4 MB; the base64 travels as a tool argument and a truncated one is written without error, so resize before encoding instead of emitting a large string. Microsoft 365 generates HD downsized variants automatically (48x48, 64x64, 96x96, 120x120, 240x240, 360x360, 432x432, 504x504, 648x648). For work or school accounts, ProfilePhoto.ReadWrite.All is the more granular alternative permission. Use download-bytes with target=/me/photo/$value to retrieve the current photo."
   },
   {
     "pathPattern": "/me/todo/lists",

package/dist/generated/client.js

@@ -448,7 +448,9 @@ const microsoft_graph_chat = z.object({
   permissionGrants: z.array(microsoft_graph_resourceSpecificPermissionGrant).describe("A collection of permissions granted to apps for the chat.").optional(),
   pinnedMessages: z.array(microsoft_graph_pinnedChatMessageInfo).describe("A collection of all the pinned messages in the chat. Nullable.").optional(),
   tabs: z.array(microsoft_graph_teamsTab).describe("A collection of all the tabs in the chat. Nullable.").optional(),
-  targetedMessages: z.array(microsoft_graph_targetedChatMessage).optional()
+  targetedMessages: z.array(microsoft_graph_targetedChatMessage).describe(
+    "A collection of targeted messages in the chat that are visible only to specific users. Nullable. You can't expand this relationship using $expand. Targeted messages can also be retrieved via the userTeamwork: getAllTargetedMessages API."
+  ).optional()
 }).passthrough();
 const microsoft_graph_ODataErrors_ErrorDetails = z.object({ code: z.string(), message: z.string(), target: z.string().nullish() }).passthrough();
 const microsoft_graph_ODataErrors_InnerError = z.object({

package/dist/graph-tools.js

@@ -1,3 +1,4 @@
+import { CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "crypto";
 import logger from "./logger.js";
 import { auditLog, getUserIdentityForAudit } from "./audit-log.js";
@@ -161,6 +162,87 @@ function formatDisabledToolsForLog(disabledTools) {
   const suffix = disabledTools.length > shown.length ? `, ... +${disabledTools.length - shown.length} more` : "";
   return `${shown.join("; ")}${suffix}`;
 }
+function deniedToolPolicyForGraphTool(tool, config, reason, missingScopes) {
+  return {
+    toolName: tool.alias,
+    reason,
+    ...missingScopes && missingScopes.length > 0 ? { missingScopes } : {},
+    pathPattern: config?.pathPattern ?? tool.path
+  };
+}
+function collectDeniedToolPolicies(options) {
+  const deniedTools = /* @__PURE__ */ new Map();
+  const allowedScopes = parseAllowedScopes(options.allowedScopesValue);
+  for (const tool of allEndpoints) {
+    const endpointConfig = endpointsData.find((e) => e.toolName === tool.alias);
+    if (!options.orgMode && endpointConfig && !endpointConfig.scopes && endpointConfig.workScopes) {
+      continue;
+    }
+    const method = tool.method.toUpperCase();
+    if (options.readOnly && method !== "GET" && !(method === "POST" && endpointConfig?.readOnly)) {
+      continue;
+    }
+    if (options.enabledToolsRegex && !options.enabledToolsRegex.test(tool.alias)) {
+      deniedTools.set(
+        tool.alias,
+        deniedToolPolicyForGraphTool(tool, endpointConfig, "tool_allowlist")
+      );
+      continue;
+    }
+    const missingScopes = allowedScopes !== void 0 && !endpointConfig ? ["endpoint scope metadata"] : getMissingAllowedScopesForGroups(
+      getEndpointScopeGroups(endpointConfig, options.orgMode),
+      allowedScopes
+    );
+    if (missingScopes.length > 0) {
+      deniedTools.set(
+        tool.alias,
+        deniedToolPolicyForGraphTool(tool, endpointConfig, "allowed_scopes", missingScopes)
+      );
+    }
+  }
+  for (const utility of UTILITY_TOOLS) {
+    if (options.readOnly && !utility.readOnlyHint) continue;
+    if (options.httpMode && utility.stdioOnly) continue;
+    if (options.enabledToolsRegex && !options.enabledToolsRegex.test(utility.name)) {
+      deniedTools.set(utility.name, {
+        toolName: utility.name,
+        reason: "tool_allowlist"
+      });
+    }
+  }
+  return deniedTools;
+}
+function auditToolDenied(policy, params = {}) {
+  const targetResource = policy.pathPattern ? deriveTargetResource({ pathPattern: policy.pathPattern, params }) : void 0;
+  auditLog({
+    event: "tool.denied",
+    request_id: randomUUID(),
+    user_principal_name: getUserIdentityForAudit(getRequestTokens()?.accessToken),
+    tool: policy.toolName,
+    status: "denied",
+    reason: policy.reason,
+    ...policy.missingScopes ? { missing_scopes: policy.missingScopes } : {},
+    ...targetResource ? { target_resource: targetResource } : {}
+  });
+}
+function installDeniedToolAuditHandler(server, deniedTools) {
+  if (deniedTools.size === 0) return;
+  const lowLevel = server.server;
+  const handlers = lowLevel._requestHandlers;
+  const original = handlers?.get("tools/call");
+  if (!original) {
+    logger.warn("Skipping denied-tool audit hook: tools/call handler not found");
+    return;
+  }
+  lowLevel.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const policy = deniedTools.get(request.params.name);
+    if (policy) {
+      const params = request.params.arguments && typeof request.params.arguments === "object" ? request.params.arguments : {};
+      auditToolDenied(policy, params);
+    }
+    return original(request, extra);
+  });
+}
 async function checkAccountParamInBearerMode(accountParam, authManager) {
   if (!accountParam || !authManager) return null;
   const contextToken = getRequestTokens()?.accessToken;
@@ -1098,6 +1180,13 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
   let failedCount = 0;
   const allowedScopes = parseAllowedScopes(allowedScopesValue);
   const disabledByAllowedScopes = [];
+  const deniedTools = collectDeniedToolPolicies({
+    readOnly,
+    orgMode,
+    enabledToolsRegex,
+    allowedScopesValue,
+    httpMode
+  });
   for (const tool of allEndpoints) {
     const endpointConfig = endpointsData.find((e) => e.toolName === tool.alias);
     if (!orgMode && endpointConfig && !endpointConfig.scopes && endpointConfig.workScopes) {
@@ -1256,6 +1345,7 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
   logger.info(
     `Tool registration complete: ${registeredCount} registered, ${skippedCount} skipped, ${failedCount} failed`
   );
+  installDeniedToolAuditHandler(server, deniedTools);
   return registeredCount;
 }
 function buildToolsRegistry(readOnly, orgMode, enabledToolsRegex, allowedScopesValue, disabledByAllowedScopes = []) {
@@ -1372,6 +1462,13 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
     }
   }
   const disabledByAllowedScopes = [];
+  const deniedTools = collectDeniedToolPolicies({
+    readOnly,
+    orgMode,
+    enabledToolsRegex,
+    allowedScopesValue,
+    httpMode
+  });
   const toolsRegistry = buildToolsRegistry(
     readOnly,
     orgMode,
@@ -1547,6 +1644,10 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
       if (utility) {
         return executeUtilityTool(utility, utilityCtx, parameters);
       }
+      const deniedPolicy = deniedTools.get(tool_name);
+      if (deniedPolicy) {
+        auditToolDenied(deniedPolicy, parameters);
+      }
       return {
         content: [
           {
@@ -1561,6 +1662,7 @@ function registerDiscoveryTools(server, graphClient, readOnly = false, orgMode =
       };
     }
   );
+  installDeniedToolAuditHandler(server, deniedTools);
 }
 export {
   UTILITY_TOOLS,

package/dist/mcp-instructions.js

@@ -6,7 +6,7 @@ function buildGeneralMcpInstructions(opts) {
     "When you need an organizational user or recipient address, resolve it with list-users (or another directory tool); do not invent SMTP addresses.",
     "Directory $search on collections such as /users or /groups requires ConsistencyLevel: eventual when the tool exposes that header.",
     "Teams chat and channel messages: prefer HTML contentType in the body; plain text is often mangled by Graph.",
-    "Files / binary content: for large drive/SharePoint file content, prefer get-download-url to resolve a pre-authenticated URL for out-of-band download. Use download-bytes for authenticated byte reads such as mail attachments, profile photos, Teams hosted content, and meeting recordings. In stdio mode, download-bytes-to-file writes those same authenticated bytes straight to a local absolute path instead of returning base64 \u2014 the only out-of-band option for large mail attachments and meeting recordings, which get-download-url cannot handle. These tools take relative Microsoft Graph paths, not absolute URLs. For uploads, upload-file-content takes a base64 string body up to 4MB; use create-upload-session above that."
+    "Files / binary content: for large drive/SharePoint file content, prefer get-download-url to resolve a pre-authenticated URL for out-of-band download. Use download-bytes for authenticated byte reads such as mail attachments, profile photos, Teams hosted content, and meeting recordings. In stdio mode, download-bytes-to-file writes those same authenticated bytes straight to a local absolute path instead of returning base64 \u2014 the only out-of-band option for large mail attachments and meeting recordings, which get-download-url cannot handle. These tools take relative Microsoft Graph paths, not absolute URLs. For uploads, upload-file-content takes a base64 string body (Graph allows 250MB, but the whole string passes through the agent context and a truncated one is written without error); use create-upload-session for anything but small files."
   ];
   if (opts.readOnly) parts.push("This server is read-only; write operations are disabled.");
   if (opts.multiAccount)

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 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`) with `{ event, request_id, user_principal_name, tool, http_method, status, duration_ms, target_resource?, error_type?, error_code? }`. 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, tool parameters, 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. 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 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`) with `{ event, request_id, user_principal_name, tool, http_method, status, duration_ms, target_resource?, error_type?, error_code? }`. 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, tool parameters, 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. 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.144.0",
+  "version": "0.145.1",
   "description": " A Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph API",
   "type": "module",
   "main": "dist/index.js",

package/src/endpoints.json

@@ -212,7 +212,7 @@
     "toolName": "add-mail-attachment",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"],
-    "llmTip": "Max 3MB. Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}."
+    "llmTip": "The only path for attachments under 3MB. contentBytes must carry the complete base64 verbatim; a truncated argument fails with 400 UnableToDeserializePostBody. At 3MB and above use create-mail-attachment-upload-session, which rejects anything smaller. Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}."
   },
   {
     "pathPattern": "/me/messages/{message-id}/attachments/createUploadSession",
@@ -220,7 +220,7 @@
     "toolName": "create-mail-attachment-upload-session",
     "presets": ["mail", "outlook", "personal"],
     "scopes": ["Mail.ReadWrite"],
-    "llmTip": "For large attachments (3-150MB). Body: { AttachmentItem: { attachmentType: 'file', name: 'report.pdf', size: 5000000 } }. Returns a pre-authenticated uploadUrl for direct PUT of file bytes."
+    "llmTip": "For attachments 3MB to 150MB. Graph rejects smaller files with ErrorAttachmentSizeShouldNotBeLessThanMinimumSize, so under 3MB use add-mail-attachment instead. Body: { AttachmentItem: { attachmentType: 'file', name: 'report.pdf', size: 5000000 } }. Returns a pre-authenticated uploadUrl; the caller PUTs the bytes there itself in ranges up to 4MB. This server does not perform the PUT."
   },
   {
     "pathPattern": "/me/messages/{message-id}/attachments",
@@ -607,7 +607,7 @@
     "toolName": "upload-file-content",
     "presets": ["files", "onedrive", "personal"],
     "scopes": ["Files.ReadWrite"],
-    "llmTip": "Body is a base64-encoded string of the file bytes; the server decodes it before PUT. Max 4MB inline (use create-upload-session above 4MB). For new files use path format: /items/root:/path/to/file.txt:/content. Overwrites existing files without warning."
+    "llmTip": "Body is a base64-encoded string of the file bytes; the server decodes it before PUT. Graph accepts up to 250MB here, but the whole string travels as a tool argument and a truncated one decodes to a truncated file with no error, so use create-upload-session rather than emitting a large base64 string. For new files use path format: /items/root:/path/to/file.txt:/content. Overwrites existing files without warning."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/createUploadSession",
@@ -615,7 +615,7 @@
     "toolName": "create-upload-session",
     "presets": ["files", "onedrive", "personal"],
     "scopes": ["Files.ReadWrite"],
-    "llmTip": "For large file uploads (no size limit). Returns a pre-authenticated uploadUrl for direct PUT of file bytes. For new files use path: /items/{parentId}:/{fileName}:/createUploadSession. Body (optional): { item: { '@microsoft.graph.conflictBehavior': 'rename' } }."
+    "llmTip": "For large file uploads (no size limit, and no minimum unlike the Outlook attachment session). Returns a pre-authenticated uploadUrl; the caller PUTs the bytes there itself. This server does not perform the PUT. For new files use path: /items/{parentId}:/{fileName}:/createUploadSession. Body (optional): { item: { '@microsoft.graph.conflictBehavior': 'rename' } }."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -2609,7 +2609,7 @@
     "presets": ["personal"],
     "scopes": ["User.ReadWrite"],
     "contentType": "image/jpeg",
-    "llmTip": "Uploads a new profile photo for the signed-in user. Body is a base64-encoded string of the image bytes (the server decodes before PUT). Photo must be JPEG, max 4 MB. Microsoft 365 generates HD downsized variants automatically (48x48, 64x64, 96x96, 120x120, 240x240, 360x360, 432x432, 504x504, 648x648). For work or school accounts, ProfilePhoto.ReadWrite.All is the more granular alternative permission. Use download-bytes with target=/me/photo/$value to retrieve the current photo."
+    "llmTip": "Uploads a new profile photo for the signed-in user. Body is a base64-encoded string of the image bytes (the server decodes before PUT). Photo must be JPEG, max 4 MB; the base64 travels as a tool argument and a truncated one is written without error, so resize before encoding instead of emitting a large string. Microsoft 365 generates HD downsized variants automatically (48x48, 64x64, 96x96, 120x120, 240x240, 360x360, 432x432, 504x504, 648x648). For work or school accounts, ProfilePhoto.ReadWrite.All is the more granular alternative permission. Use download-bytes with target=/me/photo/$value to retrieve the current photo."
   },
   {
     "pathPattern": "/me/todo/lists",