@softeria/ms-365-mcp-server 0.166.1 → 0.168.0

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

@@ -4190,4 +4190,317 @@ describe("graph-tools", () => {
       expect(isDestructiveOperation("DELETE", { readOnly: true })).toBe(true);
     });
   });
+  describe("rewriteMentionShorthand", () => {
+    const U1 = "11111111-2222-3333-4444-555555555555";
+    const U2 = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+    const html = (content, extra = {}) => ({
+      body: { contentType: "html", content },
+      ...extra
+    });
+    const mention = (id, userId, name) => ({
+      id,
+      mentionText: name,
+      mentioned: { user: { id: userId, displayName: name, userIdentityType: "aadUser" } }
+    });
+    it("rewrites one tag and builds the mentions array", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      expect(rewriteMentionShorthand(html(`Hi <at user-id="${U1}">Jane Doe</at>!`)).body).toEqual(
+        html('Hi <at id="0">Jane Doe</at>!', { mentions: [mention(0, U1, "Jane Doe")] })
+      );
+    });
+    it("numbers several tags in order, including a repeated user", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const out = rewriteMentionShorthand(
+        html(
+          `<at user-id="${U1}">Jane</at> <at user-id="${U2}">Bob</at> <at user-id="${U1}">Jane</at>`
+        )
+      ).body;
+      expect(out.body.content).toBe(
+        '<at id="0">Jane</at> <at id="1">Bob</at> <at id="2">Jane</at>'
+      );
+      expect(out.mentions.map((m) => m.id)).toEqual([0, 1, 2]);
+    });
+    it("starts above ids already in the content and mentions", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = html(`<at id="0">Old</at> <at user-id="${U1}">Jane</at>`, {
+        mentions: [mention(0, U2, "Old")]
+      });
+      const out = rewriteMentionShorthand(input).body;
+      expect(out.body.content).toBe('<at id="0">Old</at> <at id="1">Jane</at>');
+      expect(out.mentions).toEqual([mention(0, U2, "Old"), mention(1, U1, "Jane")]);
+    });
+    it("passes a correct hand-built body through unchanged", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = html('<at id="0">Jane</at>', { mentions: [mention(0, U1, "Jane")] });
+      expect(rewriteMentionShorthand(input).body).toBe(input);
+    });
+    it("returns an error for a user-id that is not a GUID", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = html('<at user-id="jane@contoso.com">Jane</at>');
+      const out = rewriteMentionShorthand(input);
+      expect(out.error).toContain("jane@contoso.com");
+      expect(out.body).toBe(input);
+    });
+    it("leaves non-html content without the shorthand alone", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const text = { body: { contentType: "text", content: "plain words" } };
+      const bare = { body: { content: "plain words" } };
+      expect(rewriteMentionShorthand(text).body).toBe(text);
+      expect(rewriteMentionShorthand(bare).body).toBe(bare);
+    });
+    it.each([
+      ["text", { contentType: "text" }],
+      ["missing", {}]
+    ])("returns an error for the shorthand when contentType is %s", async (_label, type) => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = { body: { ...type, content: `<at user-id="${U1}">Jane</at>` } };
+      const out = rewriteMentionShorthand(input);
+      expect(out.error).toContain("contentType");
+      expect(out.body).toBe(input);
+    });
+    it.each([
+      ["single-quoted user-id", `<at user-id='${U1}'>Jane</at>`],
+      ["spaces around =", `<at user-id = "${U1}">Jane</at>`],
+      ["an extra attribute", `<at user-id="${U1}" class="x">Jane</at>`],
+      ["nested markup in the name", `<at user-id="${U1}"><b>Jane</b></at>`]
+    ])("returns an error for an unsupported tag form: %s", async (_label, tag) => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const input = html(`Hi ${tag}`);
+      const out = rewriteMentionShorthand(input);
+      expect(out.error).toContain("Unsupported mention tag form");
+      expect(out.body).toBe(input);
+    });
+    it("leaves a raw string body alone", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      expect(rewriteMentionShorthand('{"body":{}}').body).toBe('{"body":{}}');
+      expect(rewriteMentionShorthand(null).body).toBeNull();
+    });
+    it("keeps the display name verbatim", async () => {
+      const { rewriteMentionShorthand } = await loadModule();
+      const out = rewriteMentionShorthand(html(`<at user-id="${U1}">Smith &amp; Co</at>`)).body;
+      expect(out.body.content).toBe('<at id="0">Smith &amp; Co</at>');
+      expect(out.mentions[0].mentionText).toBe("Smith &amp; Co");
+    });
+  });
+  describe("mention shorthand (tool wiring)", () => {
+    const U1 = "11111111-2222-3333-4444-555555555555";
+    const aliases = [
+      ["send-channel-message", "post"],
+      ["reply-to-channel-message", "post"],
+      ["update-channel-message", "patch"],
+      ["update-channel-message-reply", "patch"],
+      ["send-chat-message", "post"],
+      ["reply-to-chat-message", "post"],
+      ["update-chat-message", "patch"]
+    ];
+    async function call(alias, method, body) {
+      mockEndpoints.push(
+        makeEndpoint({
+          alias,
+          method,
+          path: "/chats/{chat-id}/messages",
+          parameters: [{ name: "body", type: "Body", schema: z.object({}).passthrough() }]
+        })
+      );
+      mockEndpointsJson = [
+        makeConfig({ toolName: alias, method, pathPattern: "/chats/{chat-id}/messages" })
+      ];
+      const graphClient = createMockGraphClient([
+        { content: [{ type: "text", text: JSON.stringify({ id: "m1" }) }] }
+      ]);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const result = await server.tools.get(alias).handler({ "chat-id": "c1", body, confirm: true });
+      return { result, graphClient };
+    }
+    const sent = (graphClient) => JSON.parse(graphClient.graphRequest.mock.calls[0][1].body);
+    it.each(aliases)("rewrites the shorthand on %s", async (alias, method) => {
+      const { graphClient } = await call(alias, method, {
+        body: { contentType: "html", content: `Hi <at user-id="${U1}">Jane</at>` }
+      });
+      const out = sent(graphClient);
+      expect(out.body.content).toBe('Hi <at id="0">Jane</at>');
+      expect(out.mentions).toEqual([
+        {
+          id: 0,
+          mentionText: "Jane",
+          mentioned: { user: { id: U1, displayName: "Jane", userIdentityType: "aadUser" } }
+        }
+      ]);
+    });
+    it("returns a tool error and sends nothing for a bad user-id", async () => {
+      const { result, graphClient } = await call("send-chat-message", "post", {
+        body: { contentType: "html", content: '<at user-id="jane">Jane</at>' }
+      });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("not an Entra object id");
+      expect(graphClient.graphRequest).not.toHaveBeenCalled();
+    });
+    it("does not rewrite on a tool outside the seven", async () => {
+      const { graphClient } = await call("create-draft-email", "post", {
+        body: { contentType: "html", content: `<at user-id="${U1}">Jane</at>` }
+      });
+      expect(sent(graphClient).body.content).toBe(`<at user-id="${U1}">Jane</at>`);
+    });
+    it("lists only tools that exist in endpoints.json and documents the shorthand", async () => {
+      const actualFs = await vi.importActual("fs");
+      const endpoints = JSON.parse(
+        actualFs.readFileSync(join(__dirname, "..", "endpoints.json"), "utf8")
+      );
+      for (const [alias] of aliases) {
+        const entry = endpoints.find((e) => e.toolName === alias);
+        expect(entry, alias).toBeDefined();
+        const tip = entry.llmTip;
+        expect(tip, alias).toContain("user-id=");
+        expect(tip, alias).not.toContain("name param");
+        expect(tip, alias).toContain("userId");
+        expect(tip.split("To @mention someone").length - 1, alias).toBe(1);
+      }
+    });
+  });
+  describe("filterMembersByName", () => {
+    const body = {
+      value: [
+        { id: "1", displayName: "Jane Doe", email: "jane@contoso.com" },
+        { id: "2", displayName: "John Smith", email: "jsmith@contoso.com" },
+        { id: "3", displayName: null, email: null }
+      ],
+      "@odata.count": 3
+    };
+    const ids = (r) => r.value.map((m) => m.id);
+    it("matches displayName case-insensitively", async () => {
+      const { filterMembersByName } = await loadModule();
+      expect(ids(filterMembersByName(body, "JANE"))).toEqual(["1"]);
+    });
+    it("matches email", async () => {
+      const { filterMembersByName } = await loadModule();
+      expect(ids(filterMembersByName(body, "jsmith@"))).toEqual(["2"]);
+    });
+    it("returns an empty value array when nothing matches", async () => {
+      const { filterMembersByName } = await loadModule();
+      expect(ids(filterMembersByName(body, "zzz"))).toEqual([]);
+    });
+    it("returns everything for an empty or whitespace-only name", async () => {
+      const { filterMembersByName } = await loadModule();
+      expect(ids(filterMembersByName(body, "   "))).toEqual(["1", "2", "3"]);
+    });
+    it("does not match or throw on null fields", async () => {
+      const { filterMembersByName } = await loadModule();
+      expect(ids(filterMembersByName(body, "null"))).toEqual([]);
+    });
+    it("keeps other top-level fields", async () => {
+      const { filterMembersByName } = await loadModule();
+      expect(filterMembersByName(body, "jane")["@odata.count"]).toBe(3);
+    });
+    it("returns non-collection input unchanged", async () => {
+      const { filterMembersByName } = await loadModule();
+      expect(filterMembersByName("plain", "x")).toBe("plain");
+      expect(filterMembersByName({ id: "1" }, "x")).toEqual({ id: "1" });
+    });
+  });
+  describe("member name filter (tool wiring)", () => {
+    const membersBody = {
+      value: [
+        { id: "1", displayName: "Jane Doe", email: "jane@contoso.com" },
+        { id: "2", displayName: "John Smith", email: "jsmith@contoso.com" },
+        { id: "3", displayName: null, email: null }
+      ],
+      "@odata.count": 3
+    };
+    const page = (b) => ({ content: [{ type: "text", text: JSON.stringify(b) }] });
+    const ids = (result) => JSON.parse(result.content[0].text).value.map((m) => m.id);
+    async function run(args, responses = [page(membersBody)], alias = "list-team-members", path = "/teams/{team-id}/members", outputFormat = "json") {
+      mockEndpoints.push(makeEndpoint({ alias, path }));
+      mockEndpointsJson = [makeConfig({ toolName: alias, pathPattern: path })];
+      const graphClient = createMockGraphClient(responses, outputFormat);
+      const server = createMockServer();
+      const { registerGraphTools } = await loadModule();
+      registerGraphTools(server, graphClient);
+      const result = await server.tools.get(alias).handler({ "team-id": "t1", ...args });
+      return { result, graphClient };
+    }
+    it("filters list-team-members by name", async () => {
+      const { result } = await run({ name: "jane" });
+      expect(ids(result)).toEqual(["1"]);
+    });
+    it("filters list-chat-members by email", async () => {
+      const { result } = await run(
+        { "chat-id": "c1", name: "jsmith" },
+        [page(membersBody)],
+        "list-chat-members",
+        "/chats/{chat-id}/members"
+      );
+      expect(ids(result)).toEqual(["2"]);
+    });
+    it("does not send name to Graph", async () => {
+      const { graphClient } = await run({ name: "jane" });
+      expect(graphClient.graphRequest.mock.calls[0][0]).not.toContain("name");
+    });
+    it("returns the full list for a whitespace-only name", async () => {
+      const { result } = await run({ name: "  " });
+      expect(ids(result)).toEqual(["1", "2", "3"]);
+    });
+    it("leaves an error response untouched", async () => {
+      const err = { content: [{ type: "text", text: '{"error":"nope"}' }], isError: true };
+      const { result } = await run({ name: "jane" }, [err]);
+      expect(result.content[0].text).toBe('{"error":"nope"}');
+    });
+    it("keeps @odata.count as the unfiltered total", async () => {
+      const { result } = await run({ name: "jane" });
+      expect(JSON.parse(result.content[0].text)["@odata.count"]).toBe(3);
+    });
+    it("filters after fetchAllPages merges the pages", async () => {
+      const { result } = await run({ name: "ann", fetchAllPages: true }, [
+        page({
+          value: [{ id: "1", displayName: "Ann", email: "a@x.com" }],
+          "@odata.nextLink": "https://graph.microsoft.com/v1.0/teams/t1/members?$skiptoken=x"
+        }),
+        page({
+          value: [
+            { id: "2", displayName: "Bob", email: "b@x.com" },
+            { id: "3", displayName: "Annette", email: "n@x.com" }
+          ]
+        })
+      ]);
+      expect(ids(result)).toEqual(["1", "3"]);
+    });
+    it("matches only fields that survive $select projection", async () => {
+      const { result } = await run({ select: "id,displayName", name: "contoso" });
+      expect(ids(result)).toEqual([]);
+    });
+    describe("under --toon", () => {
+      const parseToon = (result) => JSON.parse(result.content[0].text.replace(/^TOON:/, ""));
+      const toon = (args, responses = [page(membersBody)]) => run(args, responses, "list-team-members", "/teams/{team-id}/members", "toon");
+      it("filters when no projection or merge applies", async () => {
+        const { result } = await toon({ name: "jane" });
+        expect(parseToon(result).value.map((m) => m.id)).toEqual(["1"]);
+      });
+      it("filters when $select projects the body", async () => {
+        const { result } = await toon({ select: "id,displayName", name: "jane" });
+        expect(parseToon(result).value).toEqual([{ id: "1", displayName: "Jane Doe" }]);
+      });
+      it("filters after fetchAllPages merges the pages", async () => {
+        const { result } = await toon({ name: "ann", fetchAllPages: true }, [
+          page({
+            value: [{ id: "1", displayName: "Ann", email: "a@x.com" }],
+            "@odata.nextLink": "https://graph.microsoft.com/v1.0/teams/t1/members?$skiptoken=x"
+          }),
+          page({
+            value: [
+              { id: "2", displayName: "Bob", email: "b@x.com" },
+              { id: "3", displayName: "Annette", email: "n@x.com" }
+            ]
+          })
+        ]);
+        expect(parseToon(result).value.map((m) => m.id)).toEqual(["1", "3"]);
+      });
+    });
+    it("still matches a projected field", async () => {
+      const { result } = await run({ select: "id,displayName", name: "jane" });
+      expect(JSON.parse(result.content[0].text).value).toEqual([
+        { id: "1", displayName: "Jane Doe" }
+      ]);
+    });
+  });
 });

package/dist/endpoints.json

@@ -1737,7 +1737,7 @@
     "toolName": "list-chat-members",
     "presets": ["teams", "work"],
     "workScopes": ["ChatMember.Read"],
-    "llmTip": "Lists members of a chat. Each member has displayName, email, roles (owner/guest), and visibleHistoryStartDateTime. For meeting chats, use the chatInfo.threadId from get-online-meeting as the chat-id to see who participated in the meeting chat."
+    "llmTip": "Lists members of a chat. Each member has displayName, email, roles (owner/guest), and visibleHistoryStartDateTime. For meeting chats, use the chatInfo.threadId from get-online-meeting as the chat-id to see who participated in the meeting chat. Pass name to keep only members whose displayName or email contains that text (case-insensitive); use the returned userId in an @mention."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages",
@@ -1759,7 +1759,8 @@
     "method": "patch",
     "toolName": "update-chat-message",
     "presets": ["teams", "work"],
-    "workScopes": ["Chat.ReadWrite"]
+    "workScopes": ["Chat.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/hostedContents",
@@ -1775,7 +1776,7 @@
     "toolName": "send-chat-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChatMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/me/joinedTeams",
@@ -1878,7 +1879,8 @@
     "method": "patch",
     "toolName": "update-channel-message",
     "presets": ["teams", "work"],
-    "workScopes": ["ChannelMessage.ReadWrite"]
+    "workScopes": ["ChannelMessage.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents",
@@ -1894,7 +1896,7 @@
     "toolName": "send-channel-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChannelMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -1902,7 +1904,7 @@
     "toolName": "reply-to-channel-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChannelMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -1916,7 +1918,8 @@
     "method": "patch",
     "toolName": "update-channel-message-reply",
     "presets": ["teams", "work"],
-    "workScopes": ["ChannelMessage.ReadWrite"]
+    "workScopes": ["ChannelMessage.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/teams/{team-id}/members",
@@ -1958,7 +1961,8 @@
     "method": "get",
     "toolName": "list-team-members",
     "presets": ["teams", "work"],
-    "workScopes": ["TeamMember.Read.All"]
+    "workScopes": ["TeamMember.Read.All"],
+    "llmTip": "Lists members of a team. Each member has displayName, email, roles and userId. Pass name to keep only members whose displayName or email contains that text (case-insensitive); use the returned userId in an @mention."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/filesFolder",
@@ -1981,7 +1985,7 @@
     "toolName": "reply-to-chat-message",
     "presets": ["teams", "work"],
     "workScopes": ["ChatMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/setReaction",

package/dist/graph-tools.js

@@ -203,6 +203,17 @@ function rewriteMailSearchQuotes(expr) {
   }
   return balanceTrailingSlashes(out.trim());
 }
+const MEMBER_NAME_FILTER_TOOLS = /* @__PURE__ */ new Set(["list-team-members", "list-chat-members"]);
+const MEMBER_NAME_PARAM_DESCRIPTION = "Case-insensitive text to match against each member's displayName and email. Applied after $select projection, so only fields you can see are matched. Without fetchAllPages only the fetched page is filtered, and @odata.count still reports the unfiltered total.";
+function filterMembersByName(parsed, name) {
+  const needle = name.trim().toLowerCase();
+  if (needle === "" || !isPlainObject(parsed) || !Array.isArray(parsed.value)) return parsed;
+  const matches = (member) => isPlainObject(member) && ["displayName", "email"].some((field) => {
+    const value = member[field];
+    return typeof value === "string" && value.toLowerCase().includes(needle);
+  });
+  return { ...parsed, value: parsed.value.filter(matches) };
+}
 function normalizeSearchQueryParam(queryParams, path2, toolAlias) {
   if (!isOutlookMailPath(path2)) return;
   const raw = queryParams["$search"];
@@ -386,6 +397,63 @@ function collectRecipients(node, domains, counter, depth = 0) {
     collectRecipients(value, domains, counter, depth + 1);
   }
 }
+const MENTION_SHORTHAND_TOOLS = /* @__PURE__ */ new Set([
+  "send-channel-message",
+  "reply-to-channel-message",
+  "update-channel-message",
+  "update-channel-message-reply",
+  "send-chat-message",
+  "reply-to-chat-message",
+  "update-chat-message"
+]);
+const AAD_GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHORTHAND_AT = /<at\s+user-id="([^"]*)">([^<]*)<\/at>/gi;
+const HAS_SHORTHAND = /<at\b[^>]*\buser-id\b/i;
+function rewriteMentionShorthand(body) {
+  if (!isPlainObject(body) || !isPlainObject(body.body)) return { body };
+  const itemBody = body.body;
+  const content = itemBody.content;
+  if (typeof content !== "string" || !HAS_SHORTHAND.test(content)) return { body };
+  if (String(itemBody.contentType).toLowerCase() !== "html") {
+    return {
+      body,
+      error: 'The <at user-id> mention shorthand needs contentType "html" on the message body. Set body.contentType to "html".'
+    };
+  }
+  const existing = Array.isArray(body.mentions) ? body.mentions : [];
+  let nextId = 0;
+  for (const m of existing) {
+    if (isPlainObject(m) && typeof m.id === "number") nextId = Math.max(nextId, m.id + 1);
+  }
+  for (const m of content.matchAll(/<at\s+id="(\d+)"/gi)) {
+    nextId = Math.max(nextId, Number(m[1]) + 1);
+  }
+  const added = [];
+  let error;
+  const rewritten = content.replace(SHORTHAND_AT, (tag, userId, name) => {
+    if (!AAD_GUID.test(userId)) {
+      error ?? (error = `Mention user-id "${userId}" is not an Entra object id (GUID). Use the userId from list-team-members or list-chat-members.`);
+      return tag;
+    }
+    const id = nextId++;
+    added.push({
+      id,
+      mentionText: name,
+      mentioned: { user: { id: userId, displayName: name, userIdentityType: "aadUser" } }
+    });
+    return `<at id="${id}">${name}</at>`;
+  });
+  if (error) return { body, error };
+  if (HAS_SHORTHAND.test(rewritten)) {
+    return {
+      body,
+      error: 'Unsupported mention tag form. Write <at user-id="<guid>">Name</at> with double quotes, no other attributes and plain text inside.'
+    };
+  }
+  return {
+    body: { ...body, body: { ...itemBody, content: rewritten }, mentions: [...existing, ...added] }
+  };
+}
 function bodyForRecipientWalk(body) {
   if (typeof body !== "string") return body;
   if (!/^\s*[{[]/.test(body)) return void 0;
@@ -1541,8 +1609,10 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
       parameterDefinitions.find((p) => p.type === "Body")?.schema
     );
     const strayBodyFields = {};
+    const memberNameFilter = MEMBER_NAME_FILTER_TOOLS.has(tool.alias) && typeof params.name === "string" ? params.name : void 0;
     for (const [paramName, paramValue] of Object.entries(params)) {
       if (paramName === "fileName" && config?.blobOutput) continue;
+      if (paramName === "name" && MEMBER_NAME_FILTER_TOOLS.has(tool.alias)) continue;
       if ([
         "account",
         "confirm",
@@ -1717,6 +1787,16 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
         );
       }
     }
+    if (MENTION_SHORTHAND_TOOLS.has(tool.alias)) {
+      const rewritten = rewriteMentionShorthand(body);
+      if (rewritten.error) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: rewritten.error }) }],
+          isError: true
+        };
+      }
+      body = rewritten.body;
+    }
     if (TOP_UNSUPPORTED_DELTA_TOOLS.has(tool.alias)) {
       delete queryParams["$top"];
     }
@@ -1848,12 +1928,23 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
     const mergePages = fetchAllPages && paginationEnabled;
     const willProject = (requestedSelect.length > 0 || isUserFieldBoundary) && params.excludeResponse !== true;
     const willProjectBatch = batchRestricted.size > 0 && params.excludeResponse !== true;
-    if (mergePages || willProject || willProjectBatch) {
+    const willFilterMembers = memberNameFilter !== void 0 && memberNameFilter.trim() !== "" && params.excludeResponse !== true;
+    if (mergePages || willProject || willProjectBatch || willFilterMembers) {
       options.forceJsonOutput = true;
     }
     let response = await graphClient.graphRequest(path2, options);
     const shouldProject = willProject && !response?.isError;
     let projectionHandled = false;
+    let memberFilterHandled = false;
+    const applyMemberFilter = (body2) => {
+      if (!willFilterMembers) return body2;
+      memberFilterHandled = true;
+      const filtered = filterMembersByName(body2, memberNameFilter);
+      if (isPlainObject(filtered) && Array.isArray(filtered.value) && response._meta) {
+        response._meta = { ...response._meta, result_count: filtered.value.length };
+      }
+      return filtered;
+    };
     const applyProjection = (body2) => {
       if (isTransportEnvelope(body2)) {
         logger.info("Skipping $select projection: body is a transport envelope, not a resource");
@@ -1948,7 +2039,9 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
         logger.error(`Error during pagination: ${e}`);
       }
       if (combinedResponse !== void 0) {
-        const merged = shouldProject ? applyProjection(combinedResponse) : combinedResponse;
+        const merged = applyMemberFilter(
+          shouldProject ? applyProjection(combinedResponse) : combinedResponse
+        );
         projectionHandled = shouldProject;
         response.content[0].text = graphClient.serialize(merged);
       }
@@ -1956,7 +2049,9 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
     if (shouldProject && !projectionHandled && !response?.isError && response?.content?.[0]?.text) {
       try {
         const parsed = JSON.parse(response.content[0].text);
-        response.content[0].text = graphClient.serialize(applyProjection(parsed));
+        response.content[0].text = graphClient.serialize(
+          applyMemberFilter(applyProjection(parsed))
+        );
       } catch {
       }
     }
@@ -1969,6 +2064,14 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
       } catch {
       }
     }
+    if (willFilterMembers && !memberFilterHandled && !response?.isError && response?.content?.[0]?.text) {
+      try {
+        response.content[0].text = graphClient.serialize(
+          applyMemberFilter(JSON.parse(response.content[0].text))
+        );
+      } catch {
+      }
+    }
     if (response?.content?.[0]?.text) {
       const responseText = response.content[0].text;
       logger.info(`Response size: ${responseText.length} characters`);
@@ -2125,6 +2228,9 @@ function registerGraphTools(server, graphClient, options = {}) {
       const maxPages = getMaxPages();
       paramSchema["fetchAllPages"] = z.boolean().describe(getFetchAllPagesParamDescription(maxPages, tool.alias)).optional();
     }
+    if (MEMBER_NAME_FILTER_TOOLS.has(tool.alias)) {
+      paramSchema["name"] = z.string().describe(MEMBER_NAME_PARAM_DESCRIPTION).optional();
+    }
     if (isSkiptokenApplicable(tool, Object.keys(paramSchema))) {
       paramSchema["skiptoken"] = z.string().describe(SKIPTOKEN_PARAM_DESCRIPTION).optional();
     }
@@ -2545,8 +2651,10 @@ export {
   UTILITY_TOOLS,
   buildDiscoverySearchIndex,
   buildToolsRegistry,
+  filterMembersByName,
   isDestructiveOperation,
   registerDiscoveryTools,
   registerGraphTools,
+  rewriteMentionShorthand,
   scoreDiscoveryQuery
 };

package/package.json

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

package/src/endpoints.json

@@ -1737,7 +1737,7 @@
     "toolName": "list-chat-members",
     "presets": ["teams", "work"],
     "workScopes": ["ChatMember.Read"],
-    "llmTip": "Lists members of a chat. Each member has displayName, email, roles (owner/guest), and visibleHistoryStartDateTime. For meeting chats, use the chatInfo.threadId from get-online-meeting as the chat-id to see who participated in the meeting chat."
+    "llmTip": "Lists members of a chat. Each member has displayName, email, roles (owner/guest), and visibleHistoryStartDateTime. For meeting chats, use the chatInfo.threadId from get-online-meeting as the chat-id to see who participated in the meeting chat. Pass name to keep only members whose displayName or email contains that text (case-insensitive); use the returned userId in an @mention."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages",
@@ -1759,7 +1759,8 @@
     "method": "patch",
     "toolName": "update-chat-message",
     "presets": ["teams", "work"],
-    "workScopes": ["Chat.ReadWrite"]
+    "workScopes": ["Chat.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/hostedContents",
@@ -1775,7 +1776,7 @@
     "toolName": "send-chat-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChatMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/me/joinedTeams",
@@ -1878,7 +1879,8 @@
     "method": "patch",
     "toolName": "update-channel-message",
     "presets": ["teams", "work"],
-    "workScopes": ["ChannelMessage.ReadWrite"]
+    "workScopes": ["ChannelMessage.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/hostedContents",
@@ -1894,7 +1896,7 @@
     "toolName": "send-channel-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChannelMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -1902,7 +1904,7 @@
     "toolName": "reply-to-channel-message",
     "presets": ["teams", "teams-write", "work"],
     "workScopes": ["ChannelMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies",
@@ -1916,7 +1918,8 @@
     "method": "patch",
     "toolName": "update-channel-message-reply",
     "presets": ["teams", "work"],
-    "workScopes": ["ChannelMessage.ReadWrite"]
+    "workScopes": ["ChannelMessage.ReadWrite"],
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType html in the body."
   },
   {
     "pathPattern": "/teams/{team-id}/members",
@@ -1958,7 +1961,8 @@
     "method": "get",
     "toolName": "list-team-members",
     "presets": ["teams", "work"],
-    "workScopes": ["TeamMember.Read.All"]
+    "workScopes": ["TeamMember.Read.All"],
+    "llmTip": "Lists members of a team. Each member has displayName, email, roles and userId. Pass name to keep only members whose displayName or email contains that text (case-insensitive); use the returned userId in an @mention."
   },
   {
     "pathPattern": "/teams/{team-id}/channels/{channel-id}/filesFolder",
@@ -1981,7 +1985,7 @@
     "toolName": "reply-to-chat-message",
     "presets": ["teams", "work"],
     "workScopes": ["ChatMessage.Send"],
-    "llmTip": "Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. To @mention someone, put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
+    "llmTip": "To @mention someone, put <at user-id=\"<aad-user-id>\">Display Name</at> in the html content; the server numbers the tag and builds the mentions array. Use the userId field (not id) from list-team-members or list-chat-members. Use contentType 'html' in the body — plain text contentType gets mangled by Graph API. Alternatively, hand-build the raw form: put an <at id=\"0\">Name</at> tag in the html content and add a mentions array to the request body, as a sibling of the body property (not a separate top-level tool parameter): { body: { contentType: 'html', content: 'Hi <at id=\"0\">Name</at>' }, mentions: [{ id: 0, mentionText: 'Name', mentioned: { user: { id: '<aad-user-id>', displayName: 'Name', userIdentityType: 'aadUser' } } }] }. Each mention id must match its <at id> value; include userIdentityType: 'aadUser' or Graph returns 400 'value without a type name'."
   },
   {
     "pathPattern": "/chats/{chat-id}/messages/{chatMessage-id}/setReaction",