@softeria/ms-365-mcp-server 0.46.1 → 0.46.2

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

@@ -0,0 +1,355 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { z } from "zod";
+vi.mock("../logger.js", () => ({
+  default: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn()
+  }
+}));
+const mockEndpoints = [];
+vi.mock("../generated/client.js", () => ({
+  api: {
+    get endpoints() {
+      return mockEndpoints;
+    }
+  }
+}));
+let mockEndpointsJson = [];
+vi.mock("fs", async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    readFileSync: (filePath, encoding) => {
+      if (typeof filePath === "string" && filePath.includes("endpoints.json")) {
+        return JSON.stringify(mockEndpointsJson);
+      }
+      return actual.readFileSync(filePath, encoding);
+    }
+  };
+});
+vi.mock("../tool-categories.js", () => ({
+  TOOL_CATEGORIES: {}
+}));
+function makeEndpoint(overrides = {}) {
+  return {
+    method: "get",
+    path: "/me/messages",
+    alias: "test-tool",
+    description: "Test tool",
+    requestFormat: "json",
+    parameters: [
+      { name: "filter", type: "Query", schema: z.string().optional() },
+      { name: "search", type: "Query", schema: z.string().optional() },
+      { name: "select", type: "Query", schema: z.string().optional() },
+      { name: "orderby", type: "Query", schema: z.string().optional() },
+      { name: "count", type: "Query", schema: z.boolean().optional() },
+      { name: "top", type: "Query", schema: z.number().optional() },
+      { name: "skip", type: "Query", schema: z.number().optional() }
+    ],
+    response: z.any(),
+    ...overrides
+  };
+}
+function makeConfig(overrides = {}) {
+  return {
+    pathPattern: "/me/messages",
+    method: "get",
+    toolName: "test-tool",
+    scopes: ["Mail.Read"],
+    ...overrides
+  };
+}
+function createMockGraphClient(responses) {
+  const responseQueue = [...responses || []];
+  return {
+    graphRequest: vi.fn().mockImplementation(async () => {
+      if (responseQueue.length > 0) {
+        return responseQueue.shift();
+      }
+      return {
+        content: [{ type: "text", text: JSON.stringify({ value: [] }) }]
+      };
+    })
+  };
+}
+async function loadModule() {
+  vi.resetModules();
+  const mod = await import("../graph-tools.js");
+  return mod;
+}
+function createMockServer() {
+  const tools = /* @__PURE__ */ new Map();
+  return {
+    tool: vi.fn(
+      (name, description, schema, annotations, handler) => {
+        tools.set(name, { description, schema, handler });
+      }
+    ),
+    tools
+  };
+}
+describe("graph-tools", () => {
+  beforeEach(() => {
+    mockEndpoints.length = 0;
+    mockEndpointsJson = [];
+    vi.clearAllMocks();
+  });
+  describe("$count advanced query mode", () => {
+    it("should set ConsistencyLevel: eventual header when $count=true", async () => {
+      const endpoint = makeEndpoint();
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ value: [] }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("test-tool");
+      expect(tool).toBeDefined();
+      await tool.handler({ count: true });
+      expect(graphClient.graphRequest).toHaveBeenCalledTimes(1);
+      const [url] = graphClient.graphRequest.mock.calls[0];
+      expect(url).toContain("$count=true");
+    });
+  });
+  describe("fetchAllPages pagination", () => {
+    it("should follow @odata.nextLink and combine results", async () => {
+      const endpoint = makeEndpoint();
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      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"
+              })
+            }
+          ]
+        },
+        {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                value: [{ id: "3" }]
+              })
+            }
+          ]
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("test-tool");
+      const result = await tool.handler({ fetchAllPages: true });
+      expect(graphClient.graphRequest).toHaveBeenCalledTimes(2);
+      const parsed = JSON.parse(result.content[0].text);
+      expect(parsed.value).toHaveLength(3);
+      expect(parsed.value.map((v) => v.id)).toEqual(["1", "2", "3"]);
+      expect(parsed["@odata.nextLink"]).toBeUndefined();
+    });
+    it("should stop at 100 page limit", async () => {
+      const endpoint = makeEndpoint();
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const responses = [];
+      for (let i = 0; i < 101; i++) {
+        responses.push({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                value: [{ id: `item-${i}` }],
+                "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/messages?$skip=" + (i + 1)
+              })
+            }
+          ]
+        });
+      }
+      const graphClient = createMockGraphClient(responses);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("test-tool");
+      await tool.handler({ fetchAllPages: true });
+      expect(graphClient.graphRequest).toHaveBeenCalledTimes(100);
+    });
+  });
+  describe("parameter describe() overrides", () => {
+    it("should apply custom descriptions to OData parameters", async () => {
+      const endpoint = makeEndpoint();
+      const config = makeConfig();
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, createMockGraphClient());
+      const tool = server.tools.get("test-tool");
+      expect(tool).toBeDefined();
+      const schema = tool.schema;
+      expect(schema["filter"]).toBeDefined();
+      expect(schema["filter"].description).toContain("OData filter expression");
+      expect(schema["filter"].description).toContain("$count=true");
+      expect(schema["search"]).toBeDefined();
+      expect(schema["search"].description).toContain("KQL search query");
+      expect(schema["select"]).toBeDefined();
+      expect(schema["select"].description).toContain("Comma-separated fields");
+      expect(schema["orderby"]).toBeDefined();
+      expect(schema["orderby"].description).toContain("Sort expression");
+      expect(schema["count"]).toBeDefined();
+      expect(schema["count"].description).toContain("advanced query mode");
+    });
+  });
+  describe("returnDownloadUrl", () => {
+    it("should strip /content from path and return downloadUrl when returnDownloadUrl=true", async () => {
+      const endpoint = makeEndpoint({
+        alias: "download-file",
+        path: "/me/drive/items/:driveItem-id/content",
+        parameters: [{ name: "driveItem-id", type: "Path", schema: z.string() }]
+      });
+      const config = makeConfig({
+        toolName: "download-file",
+        pathPattern: "/me/drive/items/{driveItem-id}/content",
+        returnDownloadUrl: true
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const downloadUrl = "https://download.example.com/file.pdf";
+      const graphClient = createMockGraphClient([
+        {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                "@microsoft.graph.downloadUrl": downloadUrl,
+                name: "file.pdf"
+              })
+            }
+          ]
+        }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("download-file");
+      expect(tool).toBeDefined();
+      await tool.handler({ "driveItem-id": "abc123" });
+      const [requestedPath] = graphClient.graphRequest.mock.calls[0];
+      expect(requestedPath).not.toContain("/content");
+      expect(requestedPath).toContain("/me/drive/items/abc123");
+    });
+  });
+  describe("kebab-case path param normalization", () => {
+    it("should substitute path when LLM passes message-id (kebab) but schema has messageId (camelCase)", async () => {
+      const endpoint = makeEndpoint({
+        alias: "get-mail-message",
+        method: "get",
+        path: "/me/messages/:messageId",
+        parameters: [
+          { name: "messageId", type: "Path", schema: z.string() },
+          { name: "select", type: "Query", schema: z.string().optional() }
+        ]
+      });
+      const config = makeConfig({
+        toolName: "get-mail-message",
+        pathPattern: "/me/messages/{message-id}"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ id: "AAMk123", subject: "Test" }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-mail-message");
+      expect(tool).toBeDefined();
+      await tool.handler({ "message-id": "AAMk123abc=" });
+      const [requestedPath] = graphClient.graphRequest.mock.calls[0];
+      expect(requestedPath).toContain("AAMk123abc=");
+      expect(requestedPath).not.toContain(":messageId");
+    });
+    it("should also work when LLM passes messageId (camelCase) directly", async () => {
+      const endpoint = makeEndpoint({
+        alias: "get-mail-message2",
+        method: "get",
+        path: "/me/messages/:messageId",
+        parameters: [{ name: "messageId", type: "Path", schema: z.string() }]
+      });
+      const config = makeConfig({
+        toolName: "get-mail-message2",
+        pathPattern: "/me/messages/{message-id}"
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ id: "AAMk456" }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("get-mail-message2");
+      await tool.handler({ messageId: "AAMk456xyz=" });
+      const [requestedPath] = graphClient.graphRequest.mock.calls[0];
+      expect(requestedPath).toContain("AAMk456xyz=");
+      expect(requestedPath).not.toContain(":messageId");
+    });
+  });
+  describe("supportsTimezone", () => {
+    it("should set Prefer: outlook.timezone header when timezone param provided", async () => {
+      const endpoint = makeEndpoint({
+        alias: "list-calendar-events",
+        path: "/me/events",
+        parameters: []
+      });
+      const config = makeConfig({
+        toolName: "list-calendar-events",
+        pathPattern: "/me/events",
+        supportsTimezone: true
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ value: [] }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const tool = server.tools.get("list-calendar-events");
+      expect(tool).toBeDefined();
+      expect(tool.schema["timezone"]).toBeDefined();
+      expect(tool.schema["timezone"].description).toContain("IANA timezone");
+      await tool.handler({ timezone: "Europe/Brussels" });
+      const [, options] = graphClient.graphRequest.mock.calls[0];
+      expect(options.headers["Prefer"]).toContain('outlook.timezone="Europe/Brussels"');
+    });
+    it("should NOT add timezone parameter when supportsTimezone is false/absent", async () => {
+      const endpoint = makeEndpoint({
+        alias: "list-mail",
+        path: "/me/messages",
+        parameters: []
+      });
+      const config = makeConfig({
+        toolName: "list-mail",
+        pathPattern: "/me/messages"
+        // no supportsTimezone
+      });
+      mockEndpoints.push(endpoint);
+      mockEndpointsJson = [config];
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, createMockGraphClient());
+      const tool = server.tools.get("list-mail");
+      expect(tool.schema["timezone"]).toBeUndefined();
+    });
+  });
+});

package/dist/endpoints.json

@@ -110,13 +110,15 @@
     "pathPattern": "/me/messages/{message-id}",
     "method": "delete",
     "toolName": "delete-mail-message",
-    "scopes": ["Mail.ReadWrite"]
+    "scopes": ["Mail.ReadWrite"],
+    "llmTip": "Soft delete — moves to Deleted Items. To permanently delete, delete again from Deleted Items."
   },
   {
     "pathPattern": "/me/messages/{message-id}/move",
     "method": "post",
     "toolName": "move-mail-message",
-    "scopes": ["Mail.ReadWrite"]
+    "scopes": ["Mail.ReadWrite"],
+    "llmTip": "destinationId accepts folder ID or well-known name (inbox, drafts, sentitems, deleteditems, junkemail, archive)."
   },
   {
     "pathPattern": "/me/messages/{message-id}",
@@ -128,7 +130,8 @@
     "pathPattern": "/me/messages/{message-id}/attachments",
     "method": "post",
     "toolName": "add-mail-attachment",
-    "scopes": ["Mail.ReadWrite"]
+    "scopes": ["Mail.ReadWrite"],
+    "llmTip": "Max 3MB. Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}."
   },
   {
     "pathPattern": "/me/messages/{message-id}/attachments",
@@ -192,7 +195,8 @@
     "pathPattern": "/me/messages/{message-id}/send",
     "method": "post",
     "toolName": "send-draft-message",
-    "scopes": ["Mail.Send"]
+    "scopes": ["Mail.Send"],
+    "llmTip": "No request body needed — just call with the message ID. Draft must exist in Drafts folder."
   },
   {
     "pathPattern": "/me/events",
@@ -200,7 +204,8 @@
     "toolName": "list-calendar-events",
     "scopes": ["Calendars.Read"],
     "supportsTimezone": true,
-    "supportsExpandExtendedProperties": true
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "WARNING: Does NOT expand recurring events — only returns seriesMaster. Use get-calendar-view instead to see individual occurrences within a date range."
   },
   {
     "pathPattern": "/me/events/{event-id}",
@@ -222,13 +227,14 @@
     "method": "patch",
     "toolName": "update-calendar-event",
     "scopes": ["Calendars.ReadWrite"],
-    "llmTip": "CRITICAL: Do not try to guess the email address of the recipients. Use the list-users tool to find the email address of the recipients."
+    "llmTip": "CRITICAL: Do not try to guess the email address of the recipients. Use the list-users tool to find the email address of the recipients. WARNING: Setting attendees replaces the entire attendee list — include all attendees, not just new ones."
   },
   {
     "pathPattern": "/me/events/{event-id}",
     "method": "delete",
     "toolName": "delete-calendar-event",
-    "scopes": ["Calendars.ReadWrite"]
+    "scopes": ["Calendars.ReadWrite"],
+    "llmTip": "Deleting a seriesMaster deletes ALL occurrences of the recurring event. To cancel a single occurrence, delete that specific instance ID from list-calendar-event-instances."
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events",
@@ -236,7 +242,8 @@
     "toolName": "list-specific-calendar-events",
     "scopes": ["Calendars.Read"],
     "supportsTimezone": true,
-    "supportsExpandExtendedProperties": true
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "WARNING: Does NOT expand recurring events — only returns seriesMaster. Use get-specific-calendar-view instead."
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events/{event-id}",
@@ -258,13 +265,14 @@
     "method": "patch",
     "toolName": "update-specific-calendar-event",
     "scopes": ["Calendars.ReadWrite"],
-    "llmTip": "CRITICAL: Do not try to guess the email address of the recipients. Use the list-users tool to find the email address of the recipients."
+    "llmTip": "CRITICAL: Do not try to guess the email address of the recipients. Use the list-users tool to find the email address of the recipients. WARNING: Setting attendees replaces the entire attendee list — include all attendees, not just new ones."
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events/{event-id}",
     "method": "delete",
     "toolName": "delete-specific-calendar-event",
-    "scopes": ["Calendars.ReadWrite"]
+    "scopes": ["Calendars.ReadWrite"],
+    "llmTip": "Deleting a seriesMaster deletes ALL occurrences. To cancel a single occurrence, use the specific instance ID."
   },
   {
     "pathPattern": "/me/calendarView",
@@ -334,7 +342,8 @@
     "method": "get",
     "toolName": "download-onedrive-file-content",
     "scopes": ["Files.Read"],
-    "returnDownloadUrl": true
+    "returnDownloadUrl": true,
+    "llmTip": "Returns a temporary download URL, NOT the file content directly."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -346,7 +355,8 @@
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/content",
     "method": "put",
     "toolName": "upload-file-content",
-    "scopes": ["Files.ReadWrite"]
+    "scopes": ["Files.ReadWrite"],
+    "llmTip": "Max 4MB. 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}/workbook/worksheets/{workbookWorksheet-id}/charts/add",
@@ -413,14 +423,16 @@
     "method": "post",
     "toolName": "create-onenote-page",
     "scopes": ["Notes.Create"],
-    "contentType": "text/html"
+    "contentType": "text/html",
+    "llmTip": "Body must be a full HTML document (with <html><head><title>...</title></head><body>...</body></html>). Partial HTML or plain text fails silently or creates malformed pages."
   },
   {
     "pathPattern": "/me/onenote/sections/{onenoteSection-id}/pages",
     "method": "post",
     "toolName": "create-onenote-section-page",
     "scopes": ["Notes.Create"],
-    "contentType": "text/html"
+    "contentType": "text/html",
+    "llmTip": "Body must be a full HTML document (with <html><head><title>...</title></head><body>...</body></html>). Partial HTML fails silently."
   },
   {
     "pathPattern": "/me/todo/lists",
@@ -465,7 +477,8 @@
     "pathPattern": "/me/planner/tasks",
     "method": "get",
     "toolName": "list-planner-tasks",
-    "scopes": ["Tasks.Read"]
+    "scopes": ["Tasks.Read"],
+    "llmTip": "Priority values: 0=Urgent, 1=Important, 3=Medium, 5=Low, 9=unset."
   },
   {
     "pathPattern": "/planner/plans/{plannerPlan-id}",
@@ -477,13 +490,15 @@
     "pathPattern": "/planner/plans/{plannerPlan-id}/tasks",
     "method": "get",
     "toolName": "list-plan-tasks",
-    "scopes": ["Tasks.Read"]
+    "scopes": ["Tasks.Read"],
+    "llmTip": "Priority values: 0=Urgent, 1=Important, 3=Medium, 5=Low, 9=unset."
   },
   {
     "pathPattern": "/planner/tasks/{plannerTask-id}",
     "method": "get",
     "toolName": "get-planner-task",
-    "scopes": ["Tasks.Read"]
+    "scopes": ["Tasks.Read"],
+    "llmTip": "Response includes @odata.etag — save it, required as If-Match header for update-planner-task. Use includeHeaders=true to capture it."
   },
   {
     "pathPattern": "/planner/tasks",
@@ -495,25 +510,29 @@
     "pathPattern": "/planner/tasks/{plannerTask-id}",
     "method": "patch",
     "toolName": "update-planner-task",
-    "scopes": ["Tasks.ReadWrite"]
+    "scopes": ["Tasks.ReadWrite"],
+    "llmTip": "CRITICAL: Requires If-Match header with the task's @odata.etag value, otherwise returns 412 Precondition Failed. Get the ETag from get-planner-task with includeHeaders=true. Priority values: 0=Urgent, 1=Important, 3=Medium, 5=Low, 9=unset."
   },
   {
     "pathPattern": "/planner/tasks/{plannerTask-id}/details",
     "method": "get",
     "toolName": "get-planner-task-details",
-    "scopes": ["Tasks.Read"]
+    "scopes": ["Tasks.Read"],
+    "llmTip": "Response includes @odata.etag — required for update-planner-task-details. Use includeHeaders=true."
   },
   {
     "pathPattern": "/planner/tasks/{plannerTask-id}/details",
     "method": "patch",
     "toolName": "update-planner-task-details",
-    "scopes": ["Tasks.ReadWrite"]
+    "scopes": ["Tasks.ReadWrite"],
+    "llmTip": "CRITICAL: Requires If-Match header with ETag from get-planner-task-details (use includeHeaders=true). Checklist items use GUID keys: {\"checklist\": {\"<guid>\": {\"title\": \"...\", \"isChecked\": false}}}."
   },
   {
     "pathPattern": "/me/contacts",
     "method": "get",
     "toolName": "list-outlook-contacts",
-    "scopes": ["Contacts.Read"]
+    "scopes": ["Contacts.Read"],
+    "llmTip": "$filter only supports startswith() — contains() and eq on emailAddresses do not work. Use $search as alternative for broader matching."
   },
   {
     "pathPattern": "/me/contacts/{contact-id}",
@@ -531,7 +550,8 @@
     "pathPattern": "/me/contacts/{contact-id}",
     "method": "patch",
     "toolName": "update-outlook-contact",
-    "scopes": ["Contacts.ReadWrite"]
+    "scopes": ["Contacts.ReadWrite"],
+    "llmTip": "emailAddresses array is replaced entirely — include all addresses, not just new ones."
   },
   {
     "pathPattern": "/me/contacts/{contact-id}",
@@ -573,7 +593,8 @@
     "pathPattern": "/chats/{chat-id}/messages",
     "method": "post",
     "toolName": "send-chat-message",
-    "workScopes": ["ChatMessage.Send"]
+    "workScopes": ["ChatMessage.Send"],
+    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API."
   },
   {
     "pathPattern": "/me/joinedTeams",
@@ -615,13 +636,15 @@
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages",
     "method": "post",
     "toolName": "send-channel-message",
-    "workScopes": ["ChannelMessage.Send"]
+    "workScopes": ["ChannelMessage.Send"],
+    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
     "method": "post",
     "toolName": "reply-to-channel-message",
-    "workScopes": ["ChannelMessage.Send"]
+    "workScopes": ["ChannelMessage.Send"],
+    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -645,7 +668,8 @@
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/replies",
     "method": "post",
     "toolName": "reply-to-chat-message",
-    "workScopes": ["ChatMessage.Send"]
+    "workScopes": ["ChatMessage.Send"],
+    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API."
   },
   {
     "pathPattern": "/sites",
@@ -699,13 +723,15 @@
     "pathPattern": "/sites/{site-id}/lists/{list-id}/items",
     "method": "get",
     "toolName": "list-sharepoint-site-list-items",
-    "workScopes": ["Sites.Read.All"]
+    "workScopes": ["Sites.Read.All"],
+    "llmTip": "Add $expand=fields to include actual column values. Without it, only metadata is returned."
   },
   {
     "pathPattern": "/sites/{site-id}/lists/{list-id}/items/{listItem-id}",
     "method": "get",
     "toolName": "get-sharepoint-site-list-item",
-    "workScopes": ["Sites.Read.All"]
+    "workScopes": ["Sites.Read.All"],
+    "llmTip": "Add $expand=fields to include actual column values. Without it, only metadata is returned."
   },
   {
     "pathPattern": "/sites/{site-id}/getByPath(path='{path}')",
@@ -770,18 +796,21 @@
     "pathPattern": "/groups/{group-id}/conversations",
     "method": "get",
     "toolName": "list-group-conversations",
-    "workScopes": ["Group.Read.All"]
+    "workScopes": ["Group.Read.All"],
+    "llmTip": "Legacy — Microsoft recommends Teams channels instead of group conversations."
   },
   {
     "pathPattern": "/groups/{group-id}/threads",
     "method": "get",
     "toolName": "list-group-threads",
-    "workScopes": ["Group.Read.All"]
+    "workScopes": ["Group.Read.All"],
+    "llmTip": "Legacy — Microsoft recommends Teams channels instead of group threads."
   },
   {
     "pathPattern": "/groups/{group-id}/threads/{conversationThread-id}/reply",
     "method": "post",
     "toolName": "reply-to-group-thread",
-    "workScopes": ["Group.ReadWrite.All"]
+    "workScopes": ["Group.ReadWrite.All"],
+    "llmTip": "Legacy — Microsoft recommends Teams channels instead of group threads."
   }
 ]

package/dist/graph-tools.js

@@ -62,15 +62,16 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       const normalizedParamName = paramName.startsWith("$") ? paramName.slice(1) : paramName;
       const isOdataParam = odataParams.includes(normalizedParamName.toLowerCase());
       const fixedParamName = isOdataParam ? `$${normalizedParamName.toLowerCase()}` : paramName;
+      const camelCaseParamName = paramName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
       const paramDef = parameterDefinitions.find(
-        (p) => p.name === paramName || isOdataParam && p.name === normalizedParamName
+        (p) => p.name === paramName || p.name === camelCaseParamName || isOdataParam && p.name === normalizedParamName
       );
       if (paramDef) {
         switch (paramDef.type) {
           case "Path": {
             const shouldSkipEncoding = config?.skipEncoding?.includes(paramName) ?? false;
             const encodedValue = shouldSkipEncoding ? paramValue : encodeURIComponent(paramValue).replace(/%3D/g, "=");
-            path2 = path2.replace(`{${paramName}}`, encodedValue).replace(`:${paramName}`, encodedValue);
+            path2 = path2.replace(`{${paramName}}`, encodedValue).replace(`:${paramName}`, encodedValue).replace(`{${camelCaseParamName}}`, encodedValue).replace(`:${camelCaseParamName}`, encodedValue);
             break;
           }
           case "Query":
@@ -106,6 +107,10 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       } else if (paramName === "body") {
         body = paramValue;
         logger.info(`Set body param: ${JSON.stringify(body)}`);
+      } else if (path2.includes(`:${paramName}`) || path2.includes(`{${paramName}}`) || path2.includes(`:${camelCaseParamName}`) || path2.includes(`{${camelCaseParamName}}`)) {
+        const encodedValue = encodeURIComponent(paramValue).replace(/%3D/g, "=");
+        path2 = path2.replace(`{${paramName}}`, encodedValue).replace(`:${paramName}`, encodedValue).replace(`{${camelCaseParamName}}`, encodedValue).replace(`:${camelCaseParamName}`, encodedValue);
+        logger.info(`Path param fallback: replaced :${camelCaseParamName} with encoded value`);
       }
     }
     const preferValues = [];
@@ -138,7 +143,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager)
       logger.info(`Setting custom Accept: ${config.acceptType}`);
     }
     if (Object.keys(queryParams).length > 0) {
-      const queryString = Object.entries(queryParams).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
+      const queryString = Object.entries(queryParams).map(([key, value]) => `${key}=${encodeURIComponent(value).replace(/%2C/gi, ",")}`).join("&");
       path2 = `${path2}${path2.includes("?") ? "&" : "?"}${queryString}`;
     }
     const options = {
@@ -300,9 +305,48 @@ function registerGraphTools(server, graphClient, readOnly = false, enabledToolsP
         paramSchema[param.name] = param.schema || z.any();
       }
     }
+    const pathParamMatches = tool.path.matchAll(/:([a-zA-Z]+)/g);
+    for (const match of pathParamMatches) {
+      const pathParamName = match[1];
+      if (!(pathParamName in paramSchema)) {
+        paramSchema[pathParamName] = z.string().describe(`Path parameter: ${pathParamName}`);
+      }
+    }
     if (tool.method.toUpperCase() === "GET" && tool.path.includes("/")) {
       paramSchema["fetchAllPages"] = z.boolean().describe("Automatically fetch all pages of results").optional();
     }
+    if (paramSchema["filter"] !== void 0 || paramSchema["$filter"] !== void 0) {
+      const key = paramSchema["$filter"] !== void 0 ? "$filter" : "filter";
+      paramSchema[key] = z.string().describe(
+        "OData filter expression. Add $count=true for advanced filters (flag/flagStatus, contains()). Cannot combine with $search."
+      ).optional();
+    }
+    if (paramSchema["search"] !== void 0 || paramSchema["$search"] !== void 0) {
+      const key = paramSchema["$search"] !== void 0 ? "$search" : "search";
+      paramSchema[key] = z.string().describe("KQL search query \u2014 wrap value in double quotes. Cannot combine with $filter.").optional();
+    }
+    if (paramSchema["select"] !== void 0 || paramSchema["$select"] !== void 0) {
+      const key = paramSchema["$select"] !== void 0 ? "$select" : "select";
+      paramSchema[key] = z.string().describe("Comma-separated fields to return, e.g. id,subject,from,receivedDateTime").optional();
+    }
+    if (paramSchema["orderby"] !== void 0 || paramSchema["$orderby"] !== void 0) {
+      const key = paramSchema["$orderby"] !== void 0 ? "$orderby" : "orderby";
+      paramSchema[key] = z.string().describe("Sort expression, e.g. receivedDateTime desc").optional();
+    }
+    if (paramSchema["top"] !== void 0 || paramSchema["$top"] !== void 0) {
+      const key = paramSchema["$top"] !== void 0 ? "$top" : "top";
+      paramSchema[key] = z.number().describe("Max items per page").optional();
+    }
+    if (paramSchema["skip"] !== void 0 || paramSchema["$skip"] !== void 0) {
+      const key = paramSchema["$skip"] !== void 0 ? "$skip" : "skip";
+      paramSchema[key] = z.number().describe("Items to skip for pagination. Not supported with $search.").optional();
+    }
+    if (paramSchema["count"] !== void 0 || paramSchema["$count"] !== void 0) {
+      const countKey = paramSchema["$count"] !== void 0 ? "$count" : "count";
+      paramSchema[countKey] = z.boolean().describe(
+        "Set true to enable advanced query mode (ConsistencyLevel: eventual). Required for complex $filter on flag/flagStatus or contains()."
+      ).optional();
+    }
     if (multiAccount) {
       const accountHint = accountNames.length > 0 ? `Known accounts: ${accountNames.join(", ")}. ` : "";
       paramSchema["account"] = z.string().describe(

package/logs/mcp-server.log

@@ -1,10 +1,10 @@
-2026-03-23 22:15:31 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
-2026-03-23 22:15:31 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
-2026-03-23 22:15:31 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
-2026-03-23 22:15:31 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me/messages
-2026-03-23 22:15:31 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me/calendar
-2026-03-23 22:15:32 INFO: Using environment variables for secrets
-2026-03-23 22:15:32 INFO: Using environment variables for secrets
-2026-03-23 22:15:32 INFO: Using environment variables for secrets
-2026-03-23 22:15:32 INFO: Using environment variables for secrets
-2026-03-23 22:15:32 INFO: Using environment variables for secrets
+2026-03-25 11:58:50 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
+2026-03-25 11:58:50 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
+2026-03-25 11:58:50 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me
+2026-03-25 11:58:50 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me/messages
+2026-03-25 11:58:50 INFO: [GRAPH CLIENT] Final URL being sent to Microsoft: https://graph.microsoft.com/v1.0/me/calendar
+2026-03-25 11:58:51 INFO: Using environment variables for secrets
+2026-03-25 11:58:51 INFO: Using environment variables for secrets
+2026-03-25 11:58:51 INFO: Using environment variables for secrets
+2026-03-25 11:58:51 INFO: Using environment variables for secrets
+2026-03-25 11:58:51 INFO: Using environment variables for secrets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softeria/ms-365-mcp-server",
-  "version": "0.46.1",
+  "version": "0.46.2",
   "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

@@ -110,13 +110,15 @@
     "pathPattern": "/me/messages/{message-id}",
     "method": "delete",
     "toolName": "delete-mail-message",
-    "scopes": ["Mail.ReadWrite"]
+    "scopes": ["Mail.ReadWrite"],
+    "llmTip": "Soft delete — moves to Deleted Items. To permanently delete, delete again from Deleted Items."
   },
   {
     "pathPattern": "/me/messages/{message-id}/move",
     "method": "post",
     "toolName": "move-mail-message",
-    "scopes": ["Mail.ReadWrite"]
+    "scopes": ["Mail.ReadWrite"],
+    "llmTip": "destinationId accepts folder ID or well-known name (inbox, drafts, sentitems, deleteditems, junkemail, archive)."
   },
   {
     "pathPattern": "/me/messages/{message-id}",
@@ -128,7 +130,8 @@
     "pathPattern": "/me/messages/{message-id}/attachments",
     "method": "post",
     "toolName": "add-mail-attachment",
-    "scopes": ["Mail.ReadWrite"]
+    "scopes": ["Mail.ReadWrite"],
+    "llmTip": "Max 3MB. Body requires @odata.type: {\"@odata.type\": \"#microsoft.graph.fileAttachment\", \"name\": \"file.pdf\", \"contentBytes\": \"<base64>\"}."
   },
   {
     "pathPattern": "/me/messages/{message-id}/attachments",
@@ -192,7 +195,8 @@
     "pathPattern": "/me/messages/{message-id}/send",
     "method": "post",
     "toolName": "send-draft-message",
-    "scopes": ["Mail.Send"]
+    "scopes": ["Mail.Send"],
+    "llmTip": "No request body needed — just call with the message ID. Draft must exist in Drafts folder."
   },
   {
     "pathPattern": "/me/events",
@@ -200,7 +204,8 @@
     "toolName": "list-calendar-events",
     "scopes": ["Calendars.Read"],
     "supportsTimezone": true,
-    "supportsExpandExtendedProperties": true
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "WARNING: Does NOT expand recurring events — only returns seriesMaster. Use get-calendar-view instead to see individual occurrences within a date range."
   },
   {
     "pathPattern": "/me/events/{event-id}",
@@ -222,13 +227,14 @@
     "method": "patch",
     "toolName": "update-calendar-event",
     "scopes": ["Calendars.ReadWrite"],
-    "llmTip": "CRITICAL: Do not try to guess the email address of the recipients. Use the list-users tool to find the email address of the recipients."
+    "llmTip": "CRITICAL: Do not try to guess the email address of the recipients. Use the list-users tool to find the email address of the recipients. WARNING: Setting attendees replaces the entire attendee list — include all attendees, not just new ones."
   },
   {
     "pathPattern": "/me/events/{event-id}",
     "method": "delete",
     "toolName": "delete-calendar-event",
-    "scopes": ["Calendars.ReadWrite"]
+    "scopes": ["Calendars.ReadWrite"],
+    "llmTip": "Deleting a seriesMaster deletes ALL occurrences of the recurring event. To cancel a single occurrence, delete that specific instance ID from list-calendar-event-instances."
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events",
@@ -236,7 +242,8 @@
     "toolName": "list-specific-calendar-events",
     "scopes": ["Calendars.Read"],
     "supportsTimezone": true,
-    "supportsExpandExtendedProperties": true
+    "supportsExpandExtendedProperties": true,
+    "llmTip": "WARNING: Does NOT expand recurring events — only returns seriesMaster. Use get-specific-calendar-view instead."
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events/{event-id}",
@@ -258,13 +265,14 @@
     "method": "patch",
     "toolName": "update-specific-calendar-event",
     "scopes": ["Calendars.ReadWrite"],
-    "llmTip": "CRITICAL: Do not try to guess the email address of the recipients. Use the list-users tool to find the email address of the recipients."
+    "llmTip": "CRITICAL: Do not try to guess the email address of the recipients. Use the list-users tool to find the email address of the recipients. WARNING: Setting attendees replaces the entire attendee list — include all attendees, not just new ones."
   },
   {
     "pathPattern": "/me/calendars/{calendar-id}/events/{event-id}",
     "method": "delete",
     "toolName": "delete-specific-calendar-event",
-    "scopes": ["Calendars.ReadWrite"]
+    "scopes": ["Calendars.ReadWrite"],
+    "llmTip": "Deleting a seriesMaster deletes ALL occurrences. To cancel a single occurrence, use the specific instance ID."
   },
   {
     "pathPattern": "/me/calendarView",
@@ -334,7 +342,8 @@
     "method": "get",
     "toolName": "download-onedrive-file-content",
     "scopes": ["Files.Read"],
-    "returnDownloadUrl": true
+    "returnDownloadUrl": true,
+    "llmTip": "Returns a temporary download URL, NOT the file content directly."
   },
   {
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}",
@@ -346,7 +355,8 @@
     "pathPattern": "/drives/{drive-id}/items/{driveItem-id}/content",
     "method": "put",
     "toolName": "upload-file-content",
-    "scopes": ["Files.ReadWrite"]
+    "scopes": ["Files.ReadWrite"],
+    "llmTip": "Max 4MB. 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}/workbook/worksheets/{workbookWorksheet-id}/charts/add",
@@ -413,14 +423,16 @@
     "method": "post",
     "toolName": "create-onenote-page",
     "scopes": ["Notes.Create"],
-    "contentType": "text/html"
+    "contentType": "text/html",
+    "llmTip": "Body must be a full HTML document (with <html><head><title>...</title></head><body>...</body></html>). Partial HTML or plain text fails silently or creates malformed pages."
   },
   {
     "pathPattern": "/me/onenote/sections/{onenoteSection-id}/pages",
     "method": "post",
     "toolName": "create-onenote-section-page",
     "scopes": ["Notes.Create"],
-    "contentType": "text/html"
+    "contentType": "text/html",
+    "llmTip": "Body must be a full HTML document (with <html><head><title>...</title></head><body>...</body></html>). Partial HTML fails silently."
   },
   {
     "pathPattern": "/me/todo/lists",
@@ -465,7 +477,8 @@
     "pathPattern": "/me/planner/tasks",
     "method": "get",
     "toolName": "list-planner-tasks",
-    "scopes": ["Tasks.Read"]
+    "scopes": ["Tasks.Read"],
+    "llmTip": "Priority values: 0=Urgent, 1=Important, 3=Medium, 5=Low, 9=unset."
   },
   {
     "pathPattern": "/planner/plans/{plannerPlan-id}",
@@ -477,13 +490,15 @@
     "pathPattern": "/planner/plans/{plannerPlan-id}/tasks",
     "method": "get",
     "toolName": "list-plan-tasks",
-    "scopes": ["Tasks.Read"]
+    "scopes": ["Tasks.Read"],
+    "llmTip": "Priority values: 0=Urgent, 1=Important, 3=Medium, 5=Low, 9=unset."
   },
   {
     "pathPattern": "/planner/tasks/{plannerTask-id}",
     "method": "get",
     "toolName": "get-planner-task",
-    "scopes": ["Tasks.Read"]
+    "scopes": ["Tasks.Read"],
+    "llmTip": "Response includes @odata.etag — save it, required as If-Match header for update-planner-task. Use includeHeaders=true to capture it."
   },
   {
     "pathPattern": "/planner/tasks",
@@ -495,25 +510,29 @@
     "pathPattern": "/planner/tasks/{plannerTask-id}",
     "method": "patch",
     "toolName": "update-planner-task",
-    "scopes": ["Tasks.ReadWrite"]
+    "scopes": ["Tasks.ReadWrite"],
+    "llmTip": "CRITICAL: Requires If-Match header with the task's @odata.etag value, otherwise returns 412 Precondition Failed. Get the ETag from get-planner-task with includeHeaders=true. Priority values: 0=Urgent, 1=Important, 3=Medium, 5=Low, 9=unset."
   },
   {
     "pathPattern": "/planner/tasks/{plannerTask-id}/details",
     "method": "get",
     "toolName": "get-planner-task-details",
-    "scopes": ["Tasks.Read"]
+    "scopes": ["Tasks.Read"],
+    "llmTip": "Response includes @odata.etag — required for update-planner-task-details. Use includeHeaders=true."
   },
   {
     "pathPattern": "/planner/tasks/{plannerTask-id}/details",
     "method": "patch",
     "toolName": "update-planner-task-details",
-    "scopes": ["Tasks.ReadWrite"]
+    "scopes": ["Tasks.ReadWrite"],
+    "llmTip": "CRITICAL: Requires If-Match header with ETag from get-planner-task-details (use includeHeaders=true). Checklist items use GUID keys: {\"checklist\": {\"<guid>\": {\"title\": \"...\", \"isChecked\": false}}}."
   },
   {
     "pathPattern": "/me/contacts",
     "method": "get",
     "toolName": "list-outlook-contacts",
-    "scopes": ["Contacts.Read"]
+    "scopes": ["Contacts.Read"],
+    "llmTip": "$filter only supports startswith() — contains() and eq on emailAddresses do not work. Use $search as alternative for broader matching."
   },
   {
     "pathPattern": "/me/contacts/{contact-id}",
@@ -531,7 +550,8 @@
     "pathPattern": "/me/contacts/{contact-id}",
     "method": "patch",
     "toolName": "update-outlook-contact",
-    "scopes": ["Contacts.ReadWrite"]
+    "scopes": ["Contacts.ReadWrite"],
+    "llmTip": "emailAddresses array is replaced entirely — include all addresses, not just new ones."
   },
   {
     "pathPattern": "/me/contacts/{contact-id}",
@@ -573,7 +593,8 @@
     "pathPattern": "/chats/{chat-id}/messages",
     "method": "post",
     "toolName": "send-chat-message",
-    "workScopes": ["ChatMessage.Send"]
+    "workScopes": ["ChatMessage.Send"],
+    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API."
   },
   {
     "pathPattern": "/me/joinedTeams",
@@ -615,13 +636,15 @@
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages",
     "method": "post",
     "toolName": "send-channel-message",
-    "workScopes": ["ChannelMessage.Send"]
+    "workScopes": ["ChannelMessage.Send"],
+    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
     "method": "post",
     "toolName": "reply-to-channel-message",
-    "workScopes": ["ChannelMessage.Send"]
+    "workScopes": ["ChannelMessage.Send"],
+    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -645,7 +668,8 @@
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/replies",
     "method": "post",
     "toolName": "reply-to-chat-message",
-    "workScopes": ["ChatMessage.Send"]
+    "workScopes": ["ChatMessage.Send"],
+    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API."
   },
   {
     "pathPattern": "/sites",
@@ -699,13 +723,15 @@
     "pathPattern": "/sites/{site-id}/lists/{list-id}/items",
     "method": "get",
     "toolName": "list-sharepoint-site-list-items",
-    "workScopes": ["Sites.Read.All"]
+    "workScopes": ["Sites.Read.All"],
+    "llmTip": "Add $expand=fields to include actual column values. Without it, only metadata is returned."
   },
   {
     "pathPattern": "/sites/{site-id}/lists/{list-id}/items/{listItem-id}",
     "method": "get",
     "toolName": "get-sharepoint-site-list-item",
-    "workScopes": ["Sites.Read.All"]
+    "workScopes": ["Sites.Read.All"],
+    "llmTip": "Add $expand=fields to include actual column values. Without it, only metadata is returned."
   },
   {
     "pathPattern": "/sites/{site-id}/getByPath(path='{path}')",
@@ -770,18 +796,21 @@
     "pathPattern": "/groups/{group-id}/conversations",
     "method": "get",
     "toolName": "list-group-conversations",
-    "workScopes": ["Group.Read.All"]
+    "workScopes": ["Group.Read.All"],
+    "llmTip": "Legacy — Microsoft recommends Teams channels instead of group conversations."
   },
   {
     "pathPattern": "/groups/{group-id}/threads",
     "method": "get",
     "toolName": "list-group-threads",
-    "workScopes": ["Group.Read.All"]
+    "workScopes": ["Group.Read.All"],
+    "llmTip": "Legacy — Microsoft recommends Teams channels instead of group threads."
   },
   {
     "pathPattern": "/groups/{group-id}/threads/{conversationThread-id}/reply",
     "method": "post",
     "toolName": "reply-to-group-thread",
-    "workScopes": ["Group.ReadWrite.All"]
+    "workScopes": ["Group.ReadWrite.All"],
+    "llmTip": "Legacy — Microsoft recommends Teams channels instead of group threads."
   }
 ]

package/tsup.config.ts

@@ -11,7 +11,7 @@ export default defineConfig({
   sourcemap: false,
   dts: false,
   publicDir: false,
-  onSuccess: 'chmod +x dist/index.js',
+  onSuccess: process.platform === 'win32' ? undefined : 'chmod +x dist/index.js',
   loader: {
     '.json': 'copy',
   },