@softeria/ms-365-mcp-server 0.167.0 → 0.169.0

package/README.md

@@ -736,6 +736,7 @@ Environment variables:
 - `MS365_MCP_BLOB_MAX_BYTES=<n>`: With blob output on, the largest file a download tool reads (positive integer, default `5242880`). The server stops reading past it and answers an error naming the limit.
 - `MS365_MCP_BODY_FORMAT=html`: Return email bodies as HTML instead of plain text (default: text)
 - `MS365_MCP_OBO_ALLOWED_TENANTS=<ids>` / `MS365_MCP_OBO_ALLOWED_USERS=<ids>`: With `--obo`, only callers whose token `tid` (tenant id) / `oid` (user object id) is listed may use the server; others get 403 before any On-Behalf-Of exchange. Comma or space separated; unset = everyone. The claims are read without verifying the signature, which Entra verifies during the exchange, so a token that lies about them still gets no Graph token. A token Entra rejects at the exchange (bad signature, expired, wrong audience, consent needed) gets 401 with a `WWW-Authenticate` challenge so the client signs in again
+- `MS365_MCP_READ_MAIL_TEXT_MAX_CHARS=<n>`: Largest result `read-mail-text` returns, in characters (default `80000`). A larger result is refused whole, naming the largest messages, rather than cut (see Reading Mail as Clean Text below)
 - `MS365_MCP_MESSAGE_SIGNOFF_PREFIX=<text>`: Signoff prepended to outgoing messages so recipients can tell they were agent-sent, e.g. `🤖`. Default: none. CLI equivalent: `--message-signoff-prefix <text>` (see Message Signoff below)
 - `MS365_MCP_MESSAGE_SIGNOFF_SUFFIX=<text>`: Signoff appended to outgoing messages. Default: none. CLI equivalent: `--message-signoff-suffix <text>`. `--no-message-signoff` disables both (see Message Signoff below)
 - `MS365_MCP_RATE_LIMIT_DISABLED=true|1`: Disable per-IP rate limiting in HTTP mode (default: enabled — 30 req/min on `/authorize`, `/token`, `/register`; 120 req/min on `/mcp`)
@@ -760,6 +761,46 @@ Environment variables:
 - `MS365_MCP_EXPECTED_USERNAME`: Require local MSAL auth to use this Microsoft account username (case-insensitive; CLI flag takes precedence)
 - `MS365_MCP_EXPECTED_HOME_ACCOUNT_ID`: Require local MSAL auth to use this exact MSAL homeAccountId (CLI flag takes precedence)
 
+## Reading Mail as Clean Text
+
+`read-mail-text` returns messages as text with the bulk junk removed. Graph's
+plain-text body is still mostly not the message: links are wrapped in Safe Links
+or tracking redirects several hundred characters long, marketing mail pads its
+preheader with invisible characters, images become `[https://…png]` lines, and
+replies carry the whole quoted thread. On a real mailbox, 20 inbox messages came
+to about 280,000 characters through `list-mail-messages` and 70,000 through
+`read-mail-text`.
+
+The rule is: remove obvious junk, never cut or rewrite the message; anything
+ambiguous is kept. It removes runs of invisible padding characters, image
+placeholders (a bracketed address of an image file), and quoted reply history
+from its header down (a dated `On … wrote:`, also `>`-quoted, an Outlook
+`From:/Sent:` block, `-----Original Message-----`). Forwards keep the forwarded
+content: a subject starting `FW:` / `Fwd:` or a localised prefix (`VS:`, `WG:`,
+`TR:`, `RV:`, `I:`, `ENC:`, …, also after tags such as `[EXTERNAL]`), or history
+directly under a `Forwarded message` / `Begin forwarded message:` marker. Links are kept:
+Safe Links, Proofpoint URL Defense and Google redirects are unwrapped to the real
+address, tracking parameters (`utm_*` and similar) are dropped, and only an
+address still longer than 300 characters (a tracking redirect) is shortened to
+`⟦link: domain⟧`. Line endings become `\n`, and the marker brackets are
+reserved: a body's own `⟦ ⟧` appear as `[ ]`, so text cannot pose as a marker.
+Everything else — signatures, footers, whitespace, repeated links — is left as
+the message has it. `get-mail-message` returns the raw body.
+
+- `messageIds` (up to 20, one `$batch`), or `folderId` with optional `top`
+  (max 20), `filter` or `search`.
+- Each message is cut to `maxChars` characters, default 3,000 (marked
+  `truncated`): a page of 20 then fits the result limit, and a typical message
+  is whole. Ticket systems that repeat their history in every update put the
+  newest entry first, so the cut keeps it. Pass a larger `maxChars` (up to
+  300,000; a raw body beyond that is cleaned only that far) for the whole of a
+  long message; `get-mail-message` has the raw body.
+- Returns `[{ id, from, to, cc, subject, received, hasAttachments, text, chars, truncated }]`;
+  an unknown id comes back as `{ id, error }`.
+- A result over `MS365_MCP_READ_MAIL_TEXT_MAX_CHARS` (default 80,000) is refused
+  whole with the largest messages listed, so the agent narrows the query instead
+  of silently getting part of it.
+
 ## Server-Minted Attachment URLs
 
 `get-download-url` returns Microsoft's own pre-authenticated `@microsoft.graph.downloadUrl`

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

@@ -1164,7 +1164,7 @@ describe("graph-tools", () => {
       expect(request).toContain("$skiptoken=next-token");
     });
     it.each(["list-calendar-events-delta", "list-calendar-view-delta"])(
-      "ignores stale mixed-case top values for %s",
+      "rejects mixed-case top values before Graph dispatch for %s",
       async (alias) => {
         mockEndpoints.push(makeEndpoint({ alias }));
         mockEndpointsJson = [makeConfig({ toolName: alias })];
@@ -1173,12 +1173,10 @@ describe("graph-tools", () => {
         const { registerGraphTools } = await loadModule();
         registerGraphTools(server, graphClient);
         for (const key of ["top", "$top", "TOP", "$TOP", "$Top"]) {
-          await server.tools.get(alias).handler({ [key]: 10 });
-        }
-        expect(graphClient.graphRequest).toHaveBeenCalledTimes(5);
-        for (const call of graphClient.graphRequest.mock.calls) {
-          expect(JSON.stringify(call)).not.toContain("$top");
+          const result = await server.tools.get(alias).handler({ [key]: 10 });
+          expect(result.isError).toBe(true);
         }
+        expect(graphClient.graphRequest).not.toHaveBeenCalled();
       }
     );
     it.each(["list-joined-teams", "list-my-associated-teams"])(
@@ -1212,7 +1210,7 @@ describe("graph-tools", () => {
       expect(graphClient.graphRequest).not.toHaveBeenCalled();
     });
     it("sends a calendar field array as comma-separated text in one Graph request", async () => {
-      const alias = "list-calendar-events-delta";
+      const alias = "list-calendar-events";
       mockEndpoints.push(makeEndpoint({ alias }));
       mockEndpointsJson = [makeConfig({ toolName: alias })];
       const graphClient = createMockGraphClient();
@@ -4190,6 +4188,175 @@ 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: [

package/dist/endpoints.json

@@ -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",
@@ -1982,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",
@@ -2540,7 +2543,7 @@
     "toolName": "list-calendar-events-delta",
     "presets": ["calendar", "outlook", "personal"],
     "scopes": ["Calendars.Read"],
-    "llmTip": "Incremental sync of events across the default calendar. First call returns all events plus @odata.deltaLink. Subsequent calls with that link return only additions/updates/removals. Use $select to limit fields. Deltas expire after ~30 days — start over if the server returns 410 Gone. For a time-bounded view with delta semantics, use list-calendar-view-delta instead."
+    "llmTip": "Incremental sync of events across the default calendar. First call returns all events plus @odata.deltaLink. Subsequent calls with that link return only additions/updates/removals. Deltas expire after ~30 days — start over if the server returns 410 Gone. For a time-bounded view with delta semantics, use list-calendar-view-delta instead."
   },
   {
     "pathPattern": "/me/calendarView/delta()",

package/dist/graph-tools.js

@@ -38,10 +38,8 @@ import {
   isSkiptokenApplicable,
   paginationAllowed,
   positiveIntFromEnv,
-  shouldOmitTopParam,
   SKIPTOKEN_PARAM_DESCRIPTION,
-  TIMEZONE_PARAM_DESCRIPTION,
-  TOP_UNSUPPORTED_DELTA_TOOLS
+  TIMEZONE_PARAM_DESCRIPTION
 } from "./lib/param-descriptions.js";
 import { describePathParam } from "./lib/path-params.js";
 import { queryParameterSchema } from "./lib/query-parameter-schema.js";
@@ -52,6 +50,18 @@ import {
   projectSelectedFields
 } from "./lib/select-projection.js";
 import { parseTeamsUrl } from "./lib/teams-url-parser.js";
+import {
+  MAIL_TEXT_DEFAULT_MAX_RESPONSE_CHARS,
+  MAIL_TEXT_DEFAULT_MAX_CHARS,
+  MAIL_TEXT_MAX_INPUT_CHARS,
+  MAIL_TEXT_MAX_IDS,
+  MAIL_TEXT_MAX_TOP,
+  MAIL_TEXT_SELECT,
+  PREFER_TEXT_BODY,
+  oversizeError,
+  toMailTextEntry,
+  validateMailTextArgs
+} from "./lib/mail-text.js";
 import { describeToolSchema, describeUtilityToolSchema } from "./lib/tool-schema.js";
 import {
   restrictUserFieldQuery,
@@ -397,6 +407,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;
@@ -864,6 +931,139 @@ const UTILITY_TOOLS = [
       }
     }
   },
+  {
+    name: "read-mail-text",
+    method: "GET",
+    path: "tool:read-mail-text",
+    searchKeywords: "triage inbox skim many emails at once without quoted history signature footer tracking links",
+    description: "Triage view of up to 20 mail messages at once, as text with the bulk junk removed: invisible padding, image placeholders and quoted reply history (forwards keep theirs). Links are kept: Safe Links, Proofpoint and Google redirects are unwrapped to the real address and tracking parameters (utm_* and similar) dropped; only an address still over 300 characters (a tracking redirect) is shortened to \u27E6link: domain\u27E7. Everything else (signatures, footers, whitespace) is left as the message has it; line endings become \\n and \u27E6 \u27E7 in the body itself appear as [ ]. Use get-mail-message for the raw body or the quoted thread. Give messageIds (up to 20), or folderId with optional top and filter or search for the newest messages in a folder. Each message is cut to maxChars characters (default 3,000; marked truncated: true): pass a larger maxChars, up to 300,000, for the whole of a long message; a body over 300,000 characters is cleaned only that far. If the whole result would exceed the server limit (MS365_MCP_READ_MAIL_TEXT_MAX_CHARS, default 80000) the call fails, listing the largest messages, instead of returning part of it. Returns [{ id, from, to, cc, subject, received, hasAttachments, text, chars, truncated }].",
+    readOnlyHint: true,
+    openWorldHint: true,
+    buildSchema: (ctx) => {
+      const schema = {
+        messageIds: z.array(z.string()).max(MAIL_TEXT_MAX_IDS).optional().describe(
+          `Ids of the messages to read (max ${MAIL_TEXT_MAX_IDS}). Give messageIds or folderId, not both.`
+        ),
+        folderId: z.string().optional().describe(
+          "Folder to read from: a well-known name (inbox, sentitems, drafts, archive, deleteditems, junkemail) or a folder id."
+        ),
+        top: z.number().int().min(1).max(MAIL_TEXT_MAX_TOP).optional().describe(
+          `With folderId: how many messages, newest first (default and max ${MAIL_TEXT_MAX_TOP}).`
+        ),
+        filter: z.string().optional().describe(
+          "With folderId: OData $filter, e.g. receivedDateTime ge 2026-10-01T00:00:00Z or from/emailAddress/address eq 'a@example.com'."
+        ),
+        search: z.string().optional().describe(
+          'With folderId: KQL search, e.g. from:paul subject:"quarterly report" (quoting is normalised as for list-mail-messages). Graph cannot combine it with filter.'
+        ),
+        maxChars: z.number().int().min(1).max(MAIL_TEXT_MAX_INPUT_CHARS).optional().describe(
+          "Cut each message text to this many characters (marked truncated). Default 3,000; pass up to 300,000 for the whole of a long message (a body over 300,000 characters is cleaned only that far, also marked truncated)."
+        )
+      };
+      if (ctx.multiAccount) {
+        schema["account"] = z.string().optional().describe(
+          "Account to use when multiple Microsoft accounts are configured. Required when multiple accounts exist (see list-accounts)."
+        );
+      }
+      return schema;
+    },
+    execute: async (params, { graphClient, authManager }) => {
+      const fail = (error) => ({
+        content: [{ type: "text", text: JSON.stringify({ error }) }],
+        isError: true
+      });
+      const invalid = validateMailTextArgs(params);
+      if (invalid) return fail(invalid);
+      const ids = params.messageIds;
+      const folderId = params.folderId;
+      const top = params.top;
+      const filter = params.filter;
+      const search = params.search;
+      const maxChars = params.maxChars ?? MAIL_TEXT_DEFAULT_MAX_CHARS;
+      const accountParam = params.account;
+      const envLimit = Number(process.env.MS365_MCP_READ_MAIL_TEXT_MAX_CHARS);
+      const limit = Number.isInteger(envLimit) && envLimit > 0 ? envLimit : MAIL_TEXT_DEFAULT_MAX_RESPONSE_CHARS;
+      try {
+        const accountModeError = await checkAccountParamInBearerMode(accountParam, authManager);
+        if (accountModeError) return fail(accountModeError);
+        let accessToken;
+        if (authManager && !authManager.isOAuthModeEnabled() && !getRequestTokens()) {
+          accessToken = await authManager.getTokenForAccount(accountParam);
+        }
+        const requestJson = async (endpoint, options) => {
+          const response = await graphClient.graphRequest(endpoint, {
+            ...options,
+            accessToken,
+            forceJsonOutput: true
+          });
+          if (response?.isError) return { error: response };
+          const text2 = response?.content?.[0]?.text;
+          try {
+            return { data: JSON.parse(typeof text2 === "string" ? text2 : "") };
+          } catch {
+            return { error: fail("Unexpected non-JSON response from Microsoft Graph.") };
+          }
+        };
+        let entries;
+        if (ids !== void 0) {
+          const requests = ids.map((id, i) => ({
+            id: String(i),
+            method: "GET",
+            url: `/me/messages/${encodeURIComponent(id)}?$select=${MAIL_TEXT_SELECT}`,
+            headers: { Prefer: PREFER_TEXT_BODY }
+          }));
+          const r = await requestJson("/$batch", {
+            method: "POST",
+            body: JSON.stringify({ requests }),
+            headers: { "Content-Type": "application/json" }
+          });
+          if (r.error) return r.error;
+          const responses = r.data?.responses ?? [];
+          const byId = new Map(responses.map((x) => [x.id, x]));
+          entries = ids.map((id, i) => {
+            const x = byId.get(String(i));
+            if (!x) return { id, error: "no response" };
+            if (x.status !== 200) {
+              const e = x.body?.error;
+              return {
+                id,
+                error: x.status === 404 ? "not found" : `${e?.code ?? x.status}: ${e?.message ?? ""}`.trim()
+              };
+            }
+            return toMailTextEntry(x.body ?? {}, maxChars);
+          });
+        } else {
+          const queryParams = {
+            $select: MAIL_TEXT_SELECT,
+            $top: String(top ?? MAIL_TEXT_MAX_TOP)
+          };
+          if (filter !== void 0) queryParams["$filter"] = filter;
+          if (search !== void 0) {
+            queryParams["$search"] = search;
+            const searchError = normalizeSearchQueryParam(
+              queryParams,
+              "/me/mailFolders/{mailFolder-id}/messages",
+              "read-mail-text"
+            );
+            if (searchError) return searchError;
+          }
+          const r = await requestJson(
+            `/me/mailFolders/${encodeURIComponent(folderId)}/messages?${new URLSearchParams(queryParams)}`,
+            { headers: { Prefer: PREFER_TEXT_BODY } }
+          );
+          if (r.error) return r.error;
+          entries = (r.data?.value ?? []).map(
+            (m) => toMailTextEntry(m, maxChars)
+          );
+        }
+        const text = JSON.stringify(entries);
+        if (text.length > limit) return fail(oversizeError(entries, text.length, limit));
+        return { content: [{ type: "text", text }] };
+      } catch (error) {
+        return fail(error.message);
+      }
+    }
+  },
   {
     name: "download-bytes",
     method: "GET",
@@ -1588,8 +1788,7 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
         (p) => p.name === paramName || p.name === camelCaseParamName || isOdataParam && p.name.replace(/^\$/, "").toLowerCase() === normalizedParamName
       );
       const isQuery = paramDef?.type === "Query" || isOdataParam;
-      const ignoredDeltaTop = shouldOmitTopParam(tool.alias) && normalizedParamName === "top";
-      if (isQuery && !ignoredDeltaTop && paramValue != null && paramValue !== "") {
+      if (isQuery && paramValue != null && paramValue !== "") {
         const schema = queryParameterSchema(
           tool.alias,
           normalizedParamName,
@@ -1730,8 +1929,15 @@ async function executeGraphTool(tool, config, graphClient, params, authManager,
         );
       }
     }
-    if (TOP_UNSUPPORTED_DELTA_TOOLS.has(tool.alias)) {
-      delete queryParams["$top"];
+    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;
     }
     const skiptokenError = normalizeSkiptokenQueryParam(queryParams, tool.alias);
     if (skiptokenError) return skiptokenError;
@@ -2588,5 +2794,6 @@ export {
   isDestructiveOperation,
   registerDiscoveryTools,
   registerGraphTools,
+  rewriteMentionShorthand,
   scoreDiscoveryQuery
 };

package/dist/lib/mail-text.js

@@ -0,0 +1,293 @@
+const MAIL_TEXT_MAX_IDS = 20;
+const MAIL_TEXT_MAX_TOP = 20;
+const MAIL_TEXT_DEFAULT_MAX_RESPONSE_CHARS = 8e4;
+const MAIL_TEXT_DEFAULT_MAX_CHARS = 3e3;
+const MAIL_TEXT_MAX_INPUT_CHARS = 3e5;
+const MAIL_TEXT_SELECT = "id,subject,from,toRecipients,ccRecipients,receivedDateTime,hasAttachments,body";
+const PREFER_TEXT_BODY = 'outlook.body-content-type="text"';
+const QUOTE_START = [
+  /^On .{1,300}wrote:\s*$/i,
+  // Gmail / Apple Mail
+  /^-{2,}\s*Original Message\s*-{2,}/i,
+  // Outlook classic
+  /^Le .{1,300}a écrit\s*:\s*$/i,
+  /^Am .{1,300}schrieb .{0,200}:\s*$/i
+];
+const DATED = [true, false, true, true];
+function isReplyHeader(l) {
+  return QUOTE_START.some((r, k) => r.test(l) && (!DATED[k] || /\d/.test(l)));
+}
+const HEADER_FROM = /^\*?From:\*?\s+\S/i;
+const HEADER_NEXT = /^\*?(Sent|Date|To|Subject):\*?\s/i;
+const SEPARATOR = /^_{10,}\s*$/;
+function isHeaderBlock(lines, i) {
+  const l = lines[i]?.trim() ?? "";
+  if (l.length > 2e3 || !HEADER_FROM.test(l)) return false;
+  let headers = 0;
+  for (let j = i + 1; j < Math.min(lines.length, i + 6); j++) {
+    if (lines[j].length < 2e3 && HEADER_NEXT.test(lines[j].trim())) headers++;
+  }
+  return headers >= 2;
+}
+const FORWARD_MARKER = /^(?:-{2,}\s*Forwarded message\s*-{2,}|Begin forwarded message:)$/i;
+function forwardMarkerAbove(lines, q) {
+  let seen = 0;
+  for (let j = q - 1; j >= 0 && seen < 3; j--) {
+    const l = lines[j].trim();
+    if (!l) continue;
+    if (l.length < 100 && FORWARD_MARKER.test(l)) return true;
+    seen++;
+  }
+  return false;
+}
+function quoteStart(lines) {
+  for (let i = 0; i < lines.length; i++) {
+    const l = lines[i].trim();
+    if (l.length > 2e3) continue;
+    if (isReplyHeader(l)) return i;
+    if (l.startsWith(">") && isReplyHeader(l.replace(/^(?:>[ \t]?){1,20}/, "").trim())) return i;
+    if (/^On .{1,200}/i.test(l) && /\d/.test(l) && i + 1 < lines.length && l.length + lines[i + 1].length < 320 && /wrote:\s*$/i.test(lines[i + 1].trim())) {
+      return i;
+    }
+    if (isHeaderBlock(lines, i)) return i;
+    if (SEPARATOR.test(l)) {
+      let j = i + 1;
+      while (j < lines.length && j <= i + 2 && !lines[j].trim()) j++;
+      if (isHeaderBlock(lines, j)) return i;
+    }
+  }
+  return -1;
+}
+const MARK_OPEN = "\u27E6";
+const mark = (host) => `\u27E6link: ${host}\u27E7`;
+const MAX_KEPT_URL = 300;
+const TRACKING_PARAM = /^(utm_[a-z_]+|mc_cid|mc_eid|_hsenc|_hsmi|__hstc|__hssc|__hsfp|mkt_tok|gclid|dclid|fbclid|msclkid|yclid|igshid)$/i;
+const LINKEDIN_TRACKING_PARAM = /^(trackingid|refid|lipi|midtoken|midsig|trk|trkemail)$/i;
+const RUN_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function unwrapUrlDefenseV3(u) {
+  const m = /^https:\/\/urldefense\.com\/v3\/__(.{1,4096}?)__;([A-Za-z0-9_-]{0,4096})!/.exec(u);
+  if (!m) return void 0;
+  const replaced = [...Buffer.from(m[2], "base64url").toString("utf8")];
+  let next = 0;
+  let out = m[1].replace(/\*\*(.)|\*/g, (tok, run) => {
+    const n = run === void 0 ? 1 : RUN_CHARS.indexOf(run) + 2;
+    if (n < 1) return tok;
+    const s = replaced.slice(next, next + n).join("");
+    next += n;
+    return s;
+  });
+  out = out.replace(/^(https?:)\/(?!\/)/i, "$1//");
+  return new URL(out).href;
+}
+function unwrapOnce(u) {
+  const url = new URL(u);
+  const host = url.hostname.toLowerCase();
+  if (/(^|\.)safelinks\.protection\.outlook\.com$/.test(host)) {
+    const w = url.searchParams.get("url");
+    return w ? new URL(w).href : void 0;
+  }
+  if (host === "urldefense.com") return unwrapUrlDefenseV3(u);
+  if (host === "urldefense.proofpoint.com") {
+    const w = url.searchParams.get("u");
+    return w ? new URL(decodeURIComponent(w.replace(/_/g, "/").replace(/-/g, "%"))).href : void 0;
+  }
+  if (/^(www\.)?google\.[a-z.]{2,6}$/.test(host) && url.pathname === "/url") {
+    const w = url.searchParams.get("q") ?? url.searchParams.get("url");
+    return w && /^https?:\/\//i.test(w) ? new URL(w).href : void 0;
+  }
+  return void 0;
+}
+function unwrapLink(u) {
+  let real = u;
+  for (let i = 0; i < 3; i++) {
+    let next;
+    try {
+      next = unwrapOnce(real);
+    } catch {
+      next = void 0;
+    }
+    if (!next || next === real) break;
+    real = next;
+  }
+  try {
+    const r = new URL(real);
+    const linkedIn = /(^|\.)linkedin\.com$/i.test(r.hostname);
+    let dropped = false;
+    for (const k of [...r.searchParams.keys()]) {
+      if (TRACKING_PARAM.test(k) || linkedIn && LINKEDIN_TRACKING_PARAM.test(k)) {
+        r.searchParams.delete(k);
+        dropped = true;
+      }
+    }
+    return dropped ? r.href : real;
+  } catch {
+    return real;
+  }
+}
+function hostOf(u) {
+  try {
+    return new URL(u).hostname.replace(/^www\./, "") || "link";
+  } catch {
+    return "link";
+  }
+}
+function showLink(u) {
+  const real = unwrapLink(u);
+  return real.length <= MAX_KEPT_URL ? real : mark(hostOf(real));
+}
+function splitUrlTail(u) {
+  let opens = 0;
+  let closes = 0;
+  for (const c of u) {
+    if (c === "(") opens++;
+    else if (c === ")") closes++;
+  }
+  let end = u.length;
+  while (end > 0) {
+    const c = u[end - 1];
+    if (".,;:!?".includes(c)) {
+      end--;
+    } else if (c === ")" && closes > opens) {
+      end--;
+      closes--;
+    } else {
+      break;
+    }
+  }
+  return [u.slice(0, end), u.slice(end)];
+}
+function isImageUrl(u) {
+  try {
+    return /\.(png|jpe?g|gif|webp|svg|bmp|ico)$/i.test(new URL(u).pathname);
+  } catch {
+    return false;
+  }
+}
+function cleanLinks(t) {
+  t = t.replace(/<((?:https?|mailto|tel):[^<>\s]{1,4096})>/gi, (m, u) => {
+    if (/^(mailto|tel):/i.test(u)) return m;
+    const shown = showLink(u);
+    return shown.startsWith(MARK_OPEN) ? shown : `<${shown}>`;
+  });
+  return t.replace(
+    /(^|[^<])\b(https?:\/\/[^\s<>"'[\]\u27e6\u27e7]{1,4096})/gi,
+    (_m, pre, raw) => {
+      const [u, tail] = splitUrlTail(raw);
+      return pre + showLink(u) + tail;
+    }
+  );
+}
+const IMAGE_PLACEHOLDER = /\[[ \t]{0,20}(https?:\/\/[^\s<>"'[\]\u27e6\u27e7]{1,4096})[ \t]{0,20}\]/gi;
+function cleanMailText(raw, opts = {}) {
+  const t = String(raw ?? "").replace(/\r\n?/g, "\n").replace(/(?:(?:[\u200b-\u200d\u2060\ufeff\u00ad]|\u034f)[ \t\u00a0\u2007\u202f]*){3,}/g, " ").replace(/\u27e6/g, "[").replace(/\u27e7/g, "]");
+  let lines = t.split("\n");
+  if (!opts.keepQuoted) {
+    const q = quoteStart(lines);
+    if (q >= 0 && lines.slice(0, q).join("").trim() && !forwardMarkerAbove(lines, q)) {
+      lines = lines.slice(0, q).concat("");
+    }
+  }
+  const body = lines.join("\n").replace(IMAGE_PLACEHOLDER, (m, u) => isImageUrl(u) ? "" : m);
+  return cleanLinks(body);
+}
+function validateMailTextArgs(p) {
+  const isInt = (v, min, max = Number.MAX_SAFE_INTEGER) => typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+  const hasIds = p.messageIds !== void 0;
+  const hasFolder = p.folderId !== void 0;
+  if (hasIds === hasFolder) return "Give messageIds or folderId (exactly one).";
+  if (p.maxChars !== void 0 && !isInt(p.maxChars, 1, MAIL_TEXT_MAX_INPUT_CHARS)) {
+    return `maxChars must be an integer from 1 to ${MAIL_TEXT_MAX_INPUT_CHARS}.`;
+  }
+  if (hasIds) {
+    const ids = p.messageIds;
+    if (!Array.isArray(ids) || ids.length === 0 || ids.some((x) => typeof x !== "string" || !x.trim())) {
+      return "messageIds must be a non-empty list of message ids.";
+    }
+    if (ids.length > MAIL_TEXT_MAX_IDS) return `At most ${MAIL_TEXT_MAX_IDS} messageIds per call.`;
+    if (p.top !== void 0 || p.filter !== void 0 || p.search !== void 0) {
+      return "top, filter and search apply only with folderId.";
+    }
+    return void 0;
+  }
+  if (typeof p.folderId !== "string" || !p.folderId.trim()) {
+    return "folderId must be a non-empty string.";
+  }
+  if (p.top !== void 0 && !isInt(p.top, 1, MAIL_TEXT_MAX_TOP)) {
+    return `top must be an integer from 1 to ${MAIL_TEXT_MAX_TOP}.`;
+  }
+  for (const k of ["filter", "search"]) {
+    const v = p[k];
+    if (v !== void 0 && (typeof v !== "string" || !v.trim())) {
+      return `${k} must be a non-empty string (omit it to read the newest messages).`;
+    }
+  }
+  if (p.filter !== void 0 && p.search !== void 0) {
+    return "Microsoft Graph cannot combine filter and search on messages; use one.";
+  }
+  return void 0;
+}
+function formatAddress(r) {
+  const e = r?.emailAddress;
+  if (!e) return "";
+  return e.name && e.address && e.name !== e.address ? `${e.name} <${e.address}>` : e.address || e.name || "";
+}
+const FORWARD_SUBJECT = new RegExp(
+  "^\\s*(?:\\[[^\\]\\n]{0,60}\\]\\s*){0,5}(?:fwd?|vs|vb|wg|tr|trs|rv|i|enc|doorst|vl|ed|fs|pd|yml|ilt|\u0130lt|tov\xE1bb\xEDt\xE1s|p\u0101rs\\.|\u03C0\u03C1\u03B8|\u8F6C\u53D1|\u8F49\u5BC4|\u05D4\u05D5\u05E2\u05D1\u05E8|\u05D4\u05E2\u05D1\u05E8\u05D4|\u0625\u0639\u0627\u062F\u0629 \u062A\u0648\u062C\u064A\u0647|\u0BAE\u0BC1\u0BA9\u0BCD\u0BA9\u0BA9\u0BC1\u0BAA\u0BCD\u0BAA\u0BC1)\\s*[:\uFF1A]",
+  "iu"
+);
+function isForwardSubject(subject) {
+  return FORWARD_SUBJECT.test(subject.slice(0, 500).normalize("NFC"));
+}
+function cutText(s, n) {
+  if (s.length <= n) return s;
+  const c = s.charCodeAt(n - 1);
+  return s.slice(0, c >= 55296 && c <= 56319 ? n - 1 : n);
+}
+function toMailTextEntry(m, maxChars) {
+  const subject = m.subject ?? "";
+  const keepQuoted = isForwardSubject(subject);
+  let raw = m.body?.content ?? "";
+  let truncated = false;
+  if (raw.length > MAIL_TEXT_MAX_INPUT_CHARS) {
+    raw = cutText(raw, MAIL_TEXT_MAX_INPUT_CHARS);
+    truncated = true;
+  }
+  let text = cleanMailText(raw, { keepQuoted });
+  const chars = text.length;
+  if (maxChars && chars > maxChars) {
+    text = cutText(text, maxChars);
+    truncated = true;
+  }
+  return {
+    id: m.id ?? "",
+    from: formatAddress(m.from),
+    to: (m.toRecipients ?? []).map(formatAddress),
+    cc: (m.ccRecipients ?? []).map(formatAddress),
+    subject,
+    received: m.receivedDateTime,
+    hasAttachments: !!m.hasAttachments,
+    text,
+    chars,
+    truncated
+  };
+}
+function oversizeError(entries, size, limit) {
+  const fmt = (n) => n.toLocaleString("en-US");
+  const largest = entries.filter((e) => "text" in e).sort((a, b) => b.text.length - a.text.length).slice(0, 5).map((e) => `"${(e.subject || "(no subject)").slice(0, 60)}" ${fmt(e.text.length)}`).join(", ");
+  return `Response would be ${fmt(size)} characters (limit ${fmt(limit)}). Largest: ${largest}. Narrow the query (fewer messages via top, a filter such as a date range or sender, specific messageIds) or set a smaller maxChars.`;
+}
+export {
+  MAIL_TEXT_DEFAULT_MAX_CHARS,
+  MAIL_TEXT_DEFAULT_MAX_RESPONSE_CHARS,
+  MAIL_TEXT_MAX_IDS,
+  MAIL_TEXT_MAX_INPUT_CHARS,
+  MAIL_TEXT_MAX_TOP,
+  MAIL_TEXT_SELECT,
+  PREFER_TEXT_BODY,
+  cleanMailText,
+  cutText,
+  isForwardSubject,
+  oversizeError,
+  toMailTextEntry,
+  validateMailTextArgs
+};

package/dist/lib/param-descriptions.js

@@ -1,10 +1,23 @@
 import logger from "../logger.js";
-const TOP_UNSUPPORTED_DELTA_TOOLS = /* @__PURE__ */ new Set([
-  "list-calendar-events-delta",
-  "list-calendar-view-delta"
-]);
-function shouldOmitTopParam(toolAlias) {
-  return TOP_UNSUPPORTED_DELTA_TOOLS.has(toolAlias);
+const SUPPORTED_QUERY_PARAMS = {
+  // https://learn.microsoft.com/en-us/graph/api/user-list-joinedteams
+  "list-joined-teams": [],
+  // https://learn.microsoft.com/en-us/graph/api/associatedteaminfo-list
+  "list-my-associated-teams": [],
+  // Documents only $top/$filter; $select is needed to opt in to image bytes.
+  // https://learn.microsoft.com/graph/api/teamworkmessaging-list-customemojis?view=graph-rest-beta
+  "list-custom-emojis": ["top", "filter", "select", "skiptoken"],
+  // https://learn.microsoft.com/en-us/graph/api/channel-list-messages
+  "list-channel-messages": ["top", "expand", "skiptoken"],
+  // https://learn.microsoft.com/en-us/graph/api/chatmessage-list-replies
+  "list-channel-message-replies": ["top", "skiptoken"],
+  // Delta rejects $select/$expand/$filter/$orderby/$search and documents no $top/$skip/$count;
+  // events delta takes no endDateTime. https://learn.microsoft.com/graph/api/event-delta?view=graph-rest-beta
+  "list-calendar-events-delta": ["startdatetime", "skiptoken"],
+  "list-calendar-view-delta": ["startdatetime", "enddatetime", "skiptoken"]
+};
+function isQueryParamSupported(toolAlias, bareName) {
+  return SUPPORTED_QUERY_PARAMS[toolAlias]?.includes(bareName) ?? true;
 }
 function paginationAllowed() {
   const raw = process.env.MS365_MCP_ALLOW_PAGINATION;
@@ -39,6 +52,8 @@ const SKIPTOKEN_PARAM_DESCRIPTION = "Next page: the @odata.nextLink from the pre
 const COLLECTION_QUERY_PARAMS = /* @__PURE__ */ new Set(["top", "filter", "orderby", "count"]);
 function isSkiptokenApplicable(tool, paramNames) {
   if (tool.method.toUpperCase() !== "GET") return false;
+  const supported = tool.alias ? SUPPORTED_QUERY_PARAMS[tool.alias] : void 0;
+  if (supported) return supported.includes("skiptoken");
   for (const name of paramNames) {
     if (COLLECTION_QUERY_PARAMS.has(name.replace(/^\$/, "").toLowerCase())) return true;
   }
@@ -95,15 +110,14 @@ export {
   SKIP_PARAM_DESCRIPTION,
   TIMEZONE_PARAM_DESCRIPTION,
   TOP_PARAM_DESCRIPTION,
-  TOP_UNSUPPORTED_DELTA_TOOLS,
   getAcceptParamDescription,
   getAccountParamDescription,
   getFetchAllPagesParamDescription,
   getMaxPages,
   getODataParamDescription,
   isFetchAllPagesApplicable,
+  isQueryParamSupported,
   isSkiptokenApplicable,
   paginationAllowed,
-  positiveIntFromEnv,
-  shouldOmitTopParam
+  positiveIntFromEnv
 };

package/dist/lib/query-parameter-schema.js

@@ -1,6 +1,5 @@
 import { z } from "zod";
-import { getODataParamDescription, shouldOmitTopParam } from "./param-descriptions.js";
-const TEAM_LIST_TOOLS = /* @__PURE__ */ new Set(["list-joined-teams", "list-my-associated-teams"]);
+import { getODataParamDescription, isQueryParamSupported } from "./param-descriptions.js";
 const CUSTOM_EMOJI_QUERY_DESCRIPTIONS = {
   top: "Number of custom emojis to return in one page. Base64 image content is opt-in with select; use a small page size when selecting contentBytes.",
   filter: "OData filter expression for custom emojis, forwarded to Microsoft Graph. Filter support is determined by the beta API.",
@@ -8,11 +7,7 @@ const CUSTOM_EMOJI_QUERY_DESCRIPTIONS = {
 };
 function queryParameterSchema(toolName, name, providerSchema) {
   const bareName = name.replace(/^\$/, "").toLowerCase();
-  if (TEAM_LIST_TOOLS.has(toolName)) return void 0;
-  if (toolName === "list-custom-emojis" && !["top", "filter", "select", "skiptoken"].includes(bareName)) {
-    return void 0;
-  }
-  if (bareName === "top" && shouldOmitTopParam(toolName)) return void 0;
+  if (!isQueryParamSupported(toolName, bareName)) return void 0;
   const source = providerSchema instanceof z.ZodOptional ? providerSchema.unwrap() : providerSchema;
   let schema = source;
   switch (bareName) {

package/dist/lib/tool-schema.js

@@ -58,7 +58,7 @@ function describeToolSchema(tool, config, ctx = {}) {
     });
   }
   if (isSkiptokenApplicable(
-    { method: tool.method },
+    { method: tool.method, alias: tool.alias },
     params.map((p) => p.name)
   )) {
     params.push({

package/dist/tool-categories.js

@@ -64,7 +64,8 @@ const SCOPED_UTILITY_TOOLS = {
   "get-download-url": ["files", "onedrive", "personal", "work", "search"],
   "get-upload-url": ["mail", "calendar", "outlook", "personal", "work"],
   "upload-attachment-from-file": ["mail", "calendar", "outlook", "personal", "work"],
-  "parse-teams-url": ["teams", "teams-write", "work"]
+  "parse-teams-url": ["teams", "teams-write", "work"],
+  "read-mail-text": ["mail", "outlook", "personal", "work"]
 };
 for (const [tool, presets] of Object.entries(SCOPED_UTILITY_TOOLS)) {
   for (const preset of presets) {

package/package.json

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

@@ -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",
@@ -1982,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",
@@ -2540,7 +2543,7 @@
     "toolName": "list-calendar-events-delta",
     "presets": ["calendar", "outlook", "personal"],
     "scopes": ["Calendars.Read"],
-    "llmTip": "Incremental sync of events across the default calendar. First call returns all events plus @odata.deltaLink. Subsequent calls with that link return only additions/updates/removals. Use $select to limit fields. Deltas expire after ~30 days — start over if the server returns 410 Gone. For a time-bounded view with delta semantics, use list-calendar-view-delta instead."
+    "llmTip": "Incremental sync of events across the default calendar. First call returns all events plus @odata.deltaLink. Subsequent calls with that link return only additions/updates/removals. Deltas expire after ~30 days — start over if the server returns 410 Gone. For a time-bounded view with delta semantics, use list-calendar-view-delta instead."
   },
   {
     "pathPattern": "/me/calendarView/delta()",