@chrischall/office-outlook-mcp 0.5.2 → 0.6.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Outlook / Microsoft 365 — mail, calendar, contacts and tasks via natural language",
-    "version": "0.5.2"
+    "version": "0.6.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Outlook (Microsoft 365)",
       "source": "./",
       "description": "MCP server for Outlook / Microsoft 365 — triage unread mail, reply, answer meeting invites and schedule meetings, plus folders, calendar, contacts and tasks, with confirmation before anything is sent",
-      "version": "0.5.2",
+      "version": "0.6.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "office-outlook-mcp",
   "displayName": "Outlook (Microsoft 365)",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Outlook / Microsoft 365 for Claude — triage unread mail, reply, answer meeting invites and schedule meetings, plus folders, calendar, contacts and tasks, with confirmation before anything is sent, using your signed-in browser session",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -202,6 +202,18 @@ each asks you to confirm first — except a reply saved with `draftOnly: true`
 (it stays in Drafts until you send it) and an invite response with
 `sendResponse: false` (only your calendar changes; the organizer is not told).
 
+## Paging from a time
+
+`outlook_get_unread` and `outlook_list_messages` also page **oldest first**
+from a point in time: pass `from` as an ISO 8601 UTC time
+(`2026-10-01T00:00:00Z`). The result carries `next_from` — pass it back
+unchanged as `from` for the next page — and `has_more`. To backfill, start
+from an old time and keep passing `next_from` until `has_more` is false; then
+keep polling with the last `next_from` to pick up new mail (an empty page
+returns the same position). Messages that share a timestamp are never skipped
+or repeated across pages, and marking mail read between pages loses nothing.
+`from` cannot be combined with `nextLink`, `sinceHours`, `search` or `skip`.
+
 ## Confirmations
 
 Every write asks you to confirm before anything is sent or changed (except a

package/dist/bundle.js

@@ -37588,7 +37588,7 @@ var init_version = __esm({
   "src/version.ts"() {
     "use strict";
     PACKAGE_NAME = "office-outlook-mcp";
-    VERSION = "0.5.2";
+    VERSION = "0.6.0";
   }
 });
 
@@ -49028,6 +49028,7 @@ function isMeetingMessage(m) {
 
 // src/tools/_paging.ts
 init_zod();
+init_dist2();
 var nextLinkParam = external_exports.string().min(1).optional().describe(
   "Continue a previous listing: pass its `nextLink` value unchanged to fetch the next page. When set, the paging/filter arguments are taken from the link and ignored here."
 );
@@ -49043,6 +49044,71 @@ function plainCollection(data) {
   if (next) out.nextLink = next;
   return out;
 }
+var fromParam = external_exports.string().min(1).optional().describe(
+  'Page oldest first from this point: an ISO 8601 UTC time (e.g. "2026-10-01T00:00:00Z"; one with no zone is read as UTC), or a previous result\'s `next_from` passed unchanged. The result always carries `next_from` and `has_more`.'
+);
+var MAX_TOP = 1e3;
+var FROM_HINT = "Pass a previous next_from unchanged, or an ISO 8601 time such as 2026-10-01T00:00:00Z (one with no zone is read as UTC).";
+var ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/i;
+function utcLiteral(ms) {
+  return new Date(ms).toISOString().replace(/\.000Z$/, "Z");
+}
+function parseTime(raw) {
+  if (!ISO_DATE_TIME.test(raw)) return void 0;
+  const t = /T[\d:.]+$/.test(raw) ? `${raw}Z` : raw;
+  const ms = Date.parse(t);
+  if (Number.isNaN(ms)) return void 0;
+  if (new Date(ms + offsetMs(t)).toISOString().slice(0, 10) !== t.slice(0, 10)) return void 0;
+  return ms;
+}
+function offsetMs(t) {
+  const m = /([+-])(\d{2}):?(\d{2})$/.exec(t);
+  if (!m || /Z$/i.test(t)) return 0;
+  const mins = Number(m[2]) * 60 + Number(m[3]);
+  return (m[1] === "-" ? -1 : 1) * mins * 6e4;
+}
+function encodeFrom(pos) {
+  return Buffer.from(JSON.stringify({ t: pos.t, ids: pos.ids }), "utf8").toString("base64url");
+}
+function decodeFrom(from) {
+  if (/^\d{4}-/.test(from)) {
+    const ms2 = parseTime(from);
+    if (ms2 === void 0) {
+      throw new McpToolError(`\`from\` is not a valid ISO 8601 UTC date-time: ${from}`, { hint: FROM_HINT });
+    }
+    return { t: utcLiteral(ms2), ids: [] };
+  }
+  let parsed;
+  try {
+    parsed = /^[A-Za-z0-9_-]+$/.test(from) ? JSON.parse(Buffer.from(from, "base64url").toString("utf8")) : void 0;
+  } catch {
+    parsed = void 0;
+  }
+  const p = parsed;
+  const ms = typeof p?.t === "string" ? parseTime(p.t) : void 0;
+  if (ms === void 0 || !Array.isArray(p?.ids) || !p.ids.every((id) => typeof id === "string")) {
+    throw new McpToolError("`from` is neither an ISO 8601 time nor a next_from token.", { hint: FROM_HINT });
+  }
+  return { t: utcLiteral(ms), ids: p.ids };
+}
+function fromQuery(pos, limit) {
+  return { bound: `ReceivedDateTime ge ${pos.t}`, top: Math.min(limit + pos.ids.length, MAX_TOP) };
+}
+function fromPage(rows, pos, limit, apiHasMore) {
+  const seen = new Set(pos.ids);
+  const fresh = rows.filter((r) => r.Id === void 0 || !seen.has(r.Id));
+  const kept = fresh.slice(0, limit);
+  const next = nextPosition(kept, pos);
+  return { rows: kept, next_from: encodeFrom(next), has_more: fresh.length > limit || apiHasMore };
+}
+function nextPosition(rows, pos) {
+  const dated = rows.map((r) => ({ id: r.Id, ms: r.ReceivedDateTime ? Date.parse(r.ReceivedDateTime) : NaN })).filter((r) => r.id !== void 0 && !Number.isNaN(r.ms));
+  if (dated.length === 0) return pos;
+  const newest = Math.max(...dated.map((r) => r.ms));
+  const tied = dated.filter((r) => r.ms === newest).map((r) => r.id);
+  const carried = newest === Date.parse(pos.t) ? pos.ids.filter((id) => !tied.includes(id)) : [];
+  return { t: utcLiteral(newest), ids: [...carried, ...tied] };
+}
 
 // src/tools/_untrusted.ts
 init_dist2();
@@ -49152,6 +49218,37 @@ function utf8Boundary(buf, max) {
 function sinceLiteral(hours) {
   return new Date(Date.now() - hours * 36e5).toISOString().replace(/\.\d{3}Z$/, "Z");
 }
+function fromPosition(from, conflicts) {
+  if (from === void 0) return void 0;
+  for (const [name, value] of Object.entries(conflicts)) {
+    if (value === void 0) continue;
+    throw new McpToolError(`\`from\` and \`${name}\` cannot be combined.`, {
+      hint: name === "nextLink" ? "To continue a `from` listing, pass its `next_from` as `from`; `nextLink` belongs to the newest-first listing." : `\`from\` pages oldest first by time; drop \`${name}\`, or omit \`from\` for the newest-first listing.`
+    });
+  }
+  return decodeFrom(from);
+}
+var FROM_DESCRIPTION = "Pass `from` (an ISO 8601 UTC time, or a previous `next_from`) to page OLDEST first from that time instead: the result carries `next_from` (pass it back unchanged as `from` for the next page; on an empty page it is the same position, so it can be polled for new arrivals) and `has_more` (more already waiting), and no nextLink. Backfill: pass an old `from` and keep passing `next_from` until `has_more` is false; then keep polling with the last `next_from` for new mail.";
+async function listFrom(client2, pos, opts) {
+  const { bound, top } = fromQuery(pos, opts.limit);
+  const data = await client2.get(
+    `/me/mailfolders/${folderSegment(opts.folder ?? "inbox")}/messages`,
+    {
+      query: {
+        $top: top,
+        $select: LIST_SELECT,
+        // The date bound leads: Outlook rejects a $filter that does not start with the $orderby property.
+        $filter: opts.unreadOnly === true ? `${bound} and IsRead eq false` : bound,
+        $orderby: "ReceivedDateTime asc"
+      }
+    }
+  );
+  const listed = Array.isArray(data?.value) ? data.value : [];
+  const page = fromPage(listed, pos, opts.limit, Boolean(data?.["@odata.nextLink"]));
+  const { "@odata.nextLink": _superseded, ...rest } = data ?? {};
+  const body = opts.view === "raw" ? { ...rest, value: page.rows } : projectCollection({ value: page.rows }, opts.view === "full" ? fullMessage : compactMessage, "message");
+  return mailboxUntrusted({ ...body, next_from: page.next_from, has_more: page.has_more });
+}
 function registerMailTools(server, client2) {
   server.registerTool(
     "outlook_list_folders",
@@ -49180,7 +49277,7 @@ function registerMailTools(server, client2) {
   server.registerTool(
     "outlook_list_messages",
     {
-      description: 'List messages in a folder, newest first. Defaults to the inbox. Use `unreadOnly` for a triage view. Bodies are NOT included \u2014 call outlook_get_message for one. Note `search` and `unreadOnly` cannot be combined on a first-page request (the API rejects $search with $filter); pass `search` alone to search the whole mailbox. When following a `nextLink`, both are ignored, so echoing them back is harmless. Each message\'s To list (and Cc, in the full view) holds at most 20 addresses; a longer list adds ToCount/ToTruncated (CcCount/CcTruncated) with the full count \u2014 pass view:"raw" for every address. ' + UNTRUSTED_DESCRIPTION_SUFFIX,
+      description: 'List messages in a folder, newest first. Defaults to the inbox. Use `unreadOnly` for a triage view. Bodies are NOT included \u2014 call outlook_get_message for one. Note `search` and `unreadOnly` cannot be combined on a first-page request (the API rejects $search with $filter); pass `search` alone to search the whole mailbox. When following a `nextLink`, both are ignored, so echoing them back is harmless. Each message\'s To list (and Cc, in the full view) holds at most 20 addresses; a longer list adds ToCount/ToTruncated (CcCount/CcTruncated) with the full count \u2014 pass view:"raw" for every address. ' + FROM_DESCRIPTION + " Cannot combine with `search`, `skip` or `nextLink`. " + UNTRUSTED_DESCRIPTION_SUFFIX,
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: external_exports.object({
         view: viewParam(VIEWS2),
@@ -49189,10 +49286,15 @@ function registerMailTools(server, client2) {
         skip: external_exports.number().int().min(0).optional().describe("Offset for paging"),
         unreadOnly: external_exports.boolean().optional().describe("Only unread messages"),
         search: external_exports.string().optional().describe("Full-text search across the whole mailbox; cannot combine with unreadOnly on a first page (ignored with nextLink)"),
+        from: fromParam,
         nextLink: nextLinkParam
       })
     },
-    async ({ view, folder, limit, skip, unreadOnly, search, nextLink }) => {
+    async ({ view, folder, limit, skip, unreadOnly, search, from, nextLink }) => {
+      const pos = fromPosition(from, { nextLink, search, skip });
+      if (pos !== void 0) {
+        return listFrom(client2, pos, { view: resolveView(view, VIEWS2), folder, limit: limit ?? 25, unreadOnly });
+      }
       if (nextLink === void 0 && search !== void 0 && unreadOnly === true) {
         throw new McpToolError("`search` and `unreadOnly` cannot be combined.", {
           hint: "Outlook rejects $search together with $filter. Search first, then filter the results."
@@ -49246,19 +49348,24 @@ function registerMailTools(server, client2) {
   server.registerTool(
     "outlook_get_unread",
     {
-      description: 'Triage batch: the unread messages in a folder (default inbox), newest first, each WITH its plain-text body (truncated to `maxBodyChars`) in one call \u2014 no follow-up outlook_get_message needed. Every item has a `kind`: "mail", "meetingRequest", "meetingCancelled" or "meetingResponse" (a reply to an invite you sent). Requests and cancellations also carry `event` (id, time, organizer, your current `responseStatus`) so the invite can be answered by its event id (when the meeting is no longer on your calendar \u2014 already declined, cancelled or deleted \u2014 the item has a `hint` instead and there is nothing to respond to). `to`/`cc` list at most 20 addresses; a longer list adds `toCount`/`ccCount` and `toTruncated`/`ccTruncated`. This does NOT mark anything read. Processing loop: read the batch \u2192 act on each item (reply, respond to the invite, file, flag \u2014 or leave it) \u2192 call outlook_mark_read on the plain mail you handled, so the next call returns only what is still new. An invite you answer with outlook_respond_to_invite needs no mark-read: Outlook moves it to Deleted Items under a new id, so its old id would 404. Follow `nextLink` for more. ' + UNTRUSTED_DESCRIPTION_SUFFIX,
+      description: 'Triage batch: the unread messages in a folder (default inbox), newest first, each WITH its plain-text body (truncated to `maxBodyChars`) in one call \u2014 no follow-up outlook_get_message needed. Every item has a `kind`: "mail", "meetingRequest", "meetingCancelled" or "meetingResponse" (a reply to an invite you sent). Requests and cancellations also carry `event` (id, time, organizer, your current `responseStatus`) so the invite can be answered by its event id (when the meeting is no longer on your calendar \u2014 already declined, cancelled or deleted \u2014 the item has a `hint` instead and there is nothing to respond to). `to`/`cc` list at most 20 addresses; a longer list adds `toCount`/`ccCount` and `toTruncated`/`ccTruncated`. This does NOT mark anything read. Processing loop: read the batch \u2192 act on each item (reply, respond to the invite, file, flag \u2014 or leave it) \u2192 call outlook_mark_read on the plain mail you handled, so the next call returns only what is still new. An invite you answer with outlook_respond_to_invite needs no mark-read: Outlook moves it to Deleted Items under a new id, so its old id would 404. Follow `nextLink` for more. ' + FROM_DESCRIPTION + " Cannot combine with `sinceHours` or `nextLink`. " + UNTRUSTED_DESCRIPTION_SUFFIX,
       annotations: { readOnlyHint: true, openWorldHint: true },
       inputSchema: external_exports.object({
         folder: external_exports.string().min(1).optional().describe('Folder id or well-known name (default "inbox")'),
         limit: external_exports.number().int().min(1).max(50).optional().describe("Max messages (default 25, max 50)"),
-        sinceHours: external_exports.number().positive().max(24 * 365).optional().describe("Only mail received in the last N hours"),
+        sinceHours: external_exports.number().positive().max(24 * 365).optional().describe("Only mail received in the last N hours (not with `from`)"),
         includeBody: external_exports.boolean().optional().describe("Fetch each plain-text body (default true). Invite events are resolved either way."),
         maxBodyChars: external_exports.number().int().min(100).max(1e5).optional().describe("Truncate each body to this many characters (default 4000); `bodyTruncated` marks a cut"),
+        from: fromParam,
         nextLink: nextLinkParam
       })
     },
-    async ({ folder, limit, sinceHours, includeBody, maxBodyChars, nextLink }) => {
+    async ({ folder, limit, sinceHours, includeBody, maxBodyChars, from, nextLink }) => {
+      const pos = fromPosition(from, { nextLink, sinceHours });
+      const max = limit ?? 25;
+      const keyset = pos !== void 0 ? fromQuery(pos, max) : void 0;
       const filter = [
+        keyset?.bound,
         sinceHours !== void 0 ? `ReceivedDateTime ge ${sinceLiteral(sinceHours)}` : void 0,
         "IsRead eq false"
       ].filter((c) => c !== void 0).join(" and ");
@@ -49268,14 +49375,16 @@ function registerMailTools(server, client2) {
         `/me/mailfolders/${folderSegment(folder ?? "inbox")}/messages`,
         {
           query: {
-            $top: limit ?? 25,
+            $top: keyset?.top ?? max,
             $select: UNREAD_SELECT,
             $filter: filter,
-            $orderby: "ReceivedDateTime desc"
+            $orderby: keyset ? "ReceivedDateTime asc" : "ReceivedDateTime desc"
           }
         }
       );
-      const rows = Array.isArray(data?.value) ? data.value : [];
+      const listed = Array.isArray(data?.value) ? data.value : [];
+      const page = pos !== void 0 ? fromPage(listed, pos, max, Boolean(data?.["@odata.nextLink"])) : void 0;
+      const rows = page?.rows ?? listed;
       const wantBody = includeBody !== false;
       const cap = maxBodyChars ?? 4e3;
       const items = await mapWithConcurrency(rows, BODY_CONCURRENCY, async (m) => {
@@ -49323,8 +49432,13 @@ function registerMailTools(server, client2) {
         return item;
       });
       const out = { count: items.length, items };
-      const next = data?.["@odata.nextLink"];
-      if (next) out.nextLink = next;
+      if (page !== void 0) {
+        out.next_from = page.next_from;
+        out.has_more = page.has_more;
+      } else {
+        const next = data?.["@odata.nextLink"];
+        if (next) out.nextLink = next;
+      }
       return mailboxUntrusted(out);
     }
   );

package/dist/tools/_paging.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { McpToolError } from '@chrischall/mcp-utils';
 import { stripOData } from '../view.js';
 /**
  * Paging for every list tool.
@@ -37,3 +38,104 @@ export function plainCollection(data) {
         out.nextLink = next;
     return out;
 }
+export const fromParam = z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Page oldest first from this point: an ISO 8601 UTC time (e.g. "2026-10-01T00:00:00Z"; one with no zone is read as UTC), or a previous result\'s `next_from` passed unchanged. The result always carries `next_from` and `has_more`.');
+/** Outlook's per-request `$top` ceiling. */
+const MAX_TOP = 1000;
+const FROM_HINT = 'Pass a previous next_from unchanged, or an ISO 8601 time such as 2026-10-01T00:00:00Z (one with no zone is read as UTC).';
+/** An ISO 8601 date, or date-time with or without a zone. */
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/i;
+/**
+ * The OData literal for `t` (unquoted), and the canonical form kept in a
+ * token. Milliseconds are dropped only when zero — truncating a real fraction
+ * would widen `ge` to messages older than the position and repeat them.
+ */
+function utcLiteral(ms) {
+    return new Date(ms).toISOString().replace(/\.000Z$/, 'Z');
+}
+function parseTime(raw) {
+    if (!ISO_DATE_TIME.test(raw))
+        return undefined;
+    // A date-time with no zone would parse as LOCAL time; `from` is UTC, so it is pinned there.
+    // (A bare date already parses as UTC.)
+    const t = /T[\d:.]+$/.test(raw) ? `${raw}Z` : raw;
+    const ms = Date.parse(t);
+    if (Number.isNaN(ms))
+        return undefined;
+    // Date.parse rolls 2026-02-30 over to March; a round trip of the date part catches it.
+    if (new Date(ms + offsetMs(t)).toISOString().slice(0, 10) !== t.slice(0, 10))
+        return undefined;
+    return ms;
+}
+/** The zone offset written in `t`, so the calendar date can be checked as written. */
+function offsetMs(t) {
+    const m = /([+-])(\d{2}):?(\d{2})$/.exec(t);
+    if (!m || /Z$/i.test(t))
+        return 0;
+    const mins = Number(m[2]) * 60 + Number(m[3]);
+    return (m[1] === '-' ? -1 : 1) * mins * 60_000;
+}
+export function encodeFrom(pos) {
+    return Buffer.from(JSON.stringify({ t: pos.t, ids: pos.ids }), 'utf8').toString('base64url');
+}
+/** Read `from`: an ISO time, or a `next_from` token. Anything else is a tool error with a hint. */
+export function decodeFrom(from) {
+    if (/^\d{4}-/.test(from)) {
+        const ms = parseTime(from);
+        if (ms === undefined) {
+            throw new McpToolError(`\`from\` is not a valid ISO 8601 UTC date-time: ${from}`, { hint: FROM_HINT });
+        }
+        return { t: utcLiteral(ms), ids: [] };
+    }
+    let parsed;
+    try {
+        parsed = /^[A-Za-z0-9_-]+$/.test(from) ? JSON.parse(Buffer.from(from, 'base64url').toString('utf8')) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    const p = parsed;
+    const ms = typeof p?.t === 'string' ? parseTime(p.t) : undefined;
+    if (ms === undefined ||
+        !Array.isArray(p?.ids) ||
+        !p.ids.every((id) => typeof id === 'string')) {
+        throw new McpToolError('`from` is neither an ISO 8601 time nor a next_from token.', { hint: FROM_HINT });
+    }
+    return { t: utcLiteral(ms), ids: p.ids };
+}
+/**
+ * The `$filter` date bound and `$top` for a page from `pos`. The bound is
+ * inclusive (`ge`), so the tied ids come back again: ask for that many extra
+ * rows so dropping them still leaves a full page.
+ */
+export function fromQuery(pos, limit) {
+    return { bound: `ReceivedDateTime ge ${pos.t}`, top: Math.min(limit + pos.ids.length, MAX_TOP) };
+}
+/**
+ * Cut an ascending page fetched with `fromQuery` down to what the caller
+ * sees: drop the rows already returned at `pos.t`, keep the first `limit`,
+ * and work out the next position. `has_more` is true when rows were left over
+ * or the API has another page.
+ */
+export function fromPage(rows, pos, limit, apiHasMore) {
+    const seen = new Set(pos.ids);
+    const fresh = rows.filter((r) => r.Id === undefined || !seen.has(r.Id));
+    const kept = fresh.slice(0, limit);
+    const next = nextPosition(kept, pos);
+    return { rows: kept, next_from: encodeFrom(next), has_more: fresh.length > limit || apiHasMore };
+}
+function nextPosition(rows, pos) {
+    const dated = rows
+        .map((r) => ({ id: r.Id, ms: r.ReceivedDateTime ? Date.parse(r.ReceivedDateTime) : NaN }))
+        .filter((r) => r.id !== undefined && !Number.isNaN(r.ms));
+    if (dated.length === 0)
+        return pos;
+    const newest = Math.max(...dated.map((r) => r.ms));
+    const tied = dated.filter((r) => r.ms === newest).map((r) => r.id);
+    // The position did not move: earlier ties at this instant stay excluded.
+    const carried = newest === Date.parse(pos.t) ? pos.ids.filter((id) => !tied.includes(id)) : [];
+    return { t: utcLiteral(newest), ids: [...carried, ...tied] };
+}

package/dist/tools/mail.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { imageResult, mapWithConcurrency, minifiedResult, resolveView, viewParam, McpToolError, } from '@chrischall/mcp-utils';
 import { addr, addrs, cappedRecipients, compactFolder, compactMessage, fullMessage, projectCollection, VIEWS, } from '../view.js';
 import { EVENT_EXPAND, INVITE_GONE, MEETING_MESSAGE_TYPE, resolvedEvent } from './_invite.js';
-import { fetchPage, nextLinkParam, plainCollection } from './_paging.js';
+import { decodeFrom, fetchPage, fromPage, fromParam, fromQuery, nextLinkParam, plainCollection, } from './_paging.js';
 import { mailboxUntrusted, UNTRUSTED_DESCRIPTION_SUFFIX } from './_untrusted.js';
 /**
  * Well-known folder names the API accepts wherever a folder id is taken.
@@ -146,6 +146,43 @@ function utf8Boundary(buf, max) {
 function sinceLiteral(hours) {
     return new Date(Date.now() - hours * 3_600_000).toISOString().replace(/\.\d{3}Z$/, 'Z');
 }
+/** Read `from` once the arguments it cannot be combined with are ruled out. */
+function fromPosition(from, conflicts) {
+    if (from === undefined)
+        return undefined;
+    for (const [name, value] of Object.entries(conflicts)) {
+        if (value === undefined)
+            continue;
+        throw new McpToolError(`\`from\` and \`${name}\` cannot be combined.`, {
+            hint: name === 'nextLink'
+                ? 'To continue a `from` listing, pass its `next_from` as `from`; `nextLink` belongs to the newest-first listing.'
+                : `\`from\` pages oldest first by time; drop \`${name}\`, or omit \`from\` for the newest-first listing.`,
+        });
+    }
+    return decodeFrom(from);
+}
+/** How `from` reads, shared by both mail listings. */
+const FROM_DESCRIPTION = 'Pass `from` (an ISO 8601 UTC time, or a previous `next_from`) to page OLDEST first from that time instead: the result carries `next_from` (pass it back unchanged as `from` for the next page; on an empty page it is the same position, so it can be polled for new arrivals) and `has_more` (more already waiting), and no nextLink. Backfill: pass an old `from` and keep passing `next_from` until `has_more` is false; then keep polling with the last `next_from` for new mail.';
+/** `outlook_list_messages` with `from`: one oldest-first keyset page. */
+async function listFrom(client, pos, opts) {
+    const { bound, top } = fromQuery(pos, opts.limit);
+    const data = await client.get(`/me/mailfolders/${folderSegment(opts.folder ?? 'inbox')}/messages`, {
+        query: {
+            $top: top,
+            $select: LIST_SELECT,
+            // The date bound leads: Outlook rejects a $filter that does not start with the $orderby property.
+            $filter: opts.unreadOnly === true ? `${bound} and IsRead eq false` : bound,
+            $orderby: 'ReceivedDateTime asc',
+        },
+    });
+    const listed = Array.isArray(data?.value) ? data.value : [];
+    const page = fromPage(listed, pos, opts.limit, Boolean(data?.['@odata.nextLink']));
+    const { '@odata.nextLink': _superseded, ...rest } = data ?? {};
+    const body = opts.view === 'raw'
+        ? { ...rest, value: page.rows }
+        : projectCollection({ value: page.rows }, opts.view === 'full' ? fullMessage : compactMessage, 'message');
+    return mailboxUntrusted({ ...body, next_from: page.next_from, has_more: page.has_more });
+}
 export function registerMailTools(server, client) {
     server.registerTool('outlook_list_folders', {
         description: 'List mail folders with unread and total counts. Use this to discover folder ids before listing messages; the well-known names (' +
@@ -170,7 +207,9 @@ export function registerMailTools(server, client) {
         return minifiedResult(projectCollection(data, compactFolder, 'mail folder'));
     });
     server.registerTool('outlook_list_messages', {
-        description: "List messages in a folder, newest first. Defaults to the inbox. Use `unreadOnly` for a triage view. Bodies are NOT included — call outlook_get_message for one. Note `search` and `unreadOnly` cannot be combined on a first-page request (the API rejects $search with $filter); pass `search` alone to search the whole mailbox. When following a `nextLink`, both are ignored, so echoing them back is harmless. Each message's To list (and Cc, in the full view) holds at most 20 addresses; a longer list adds ToCount/ToTruncated (CcCount/CcTruncated) with the full count — pass view:\"raw\" for every address." +
+        description: "List messages in a folder, newest first. Defaults to the inbox. Use `unreadOnly` for a triage view. Bodies are NOT included — call outlook_get_message for one. Note `search` and `unreadOnly` cannot be combined on a first-page request (the API rejects $search with $filter); pass `search` alone to search the whole mailbox. When following a `nextLink`, both are ignored, so echoing them back is harmless. Each message's To list (and Cc, in the full view) holds at most 20 addresses; a longer list adds ToCount/ToTruncated (CcCount/CcTruncated) with the full count — pass view:\"raw\" for every address. " +
+            FROM_DESCRIPTION +
+            ' Cannot combine with `search`, `skip` or `nextLink`.' +
             ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: z.object({
@@ -186,9 +225,14 @@ export function registerMailTools(server, client) {
                 .string()
                 .optional()
                 .describe('Full-text search across the whole mailbox; cannot combine with unreadOnly on a first page (ignored with nextLink)'),
+            from: fromParam,
             nextLink: nextLinkParam,
         }),
-    }, async ({ view, folder, limit, skip, unreadOnly, search, nextLink }) => {
+    }, async ({ view, folder, limit, skip, unreadOnly, search, from, nextLink }) => {
+        const pos = fromPosition(from, { nextLink, search, skip });
+        if (pos !== undefined) {
+            return listFrom(client, pos, { view: resolveView(view, VIEWS), folder, limit: limit ?? 25, unreadOnly });
+        }
         // With nextLink the filters come from the link and are ignored here, so
         // the conflict only matters for a first-page request.
         if (nextLink === undefined && search !== undefined && unreadOnly === true) {
@@ -240,7 +284,9 @@ export function registerMailTools(server, client) {
         return mailboxUntrusted(v === 'full' ? fullMessage(data) : compactMessage(data));
     });
     server.registerTool('outlook_get_unread', {
-        description: 'Triage batch: the unread messages in a folder (default inbox), newest first, each WITH its plain-text body (truncated to `maxBodyChars`) in one call — no follow-up outlook_get_message needed. Every item has a `kind`: "mail", "meetingRequest", "meetingCancelled" or "meetingResponse" (a reply to an invite you sent). Requests and cancellations also carry `event` (id, time, organizer, your current `responseStatus`) so the invite can be answered by its event id (when the meeting is no longer on your calendar — already declined, cancelled or deleted — the item has a `hint` instead and there is nothing to respond to). `to`/`cc` list at most 20 addresses; a longer list adds `toCount`/`ccCount` and `toTruncated`/`ccTruncated`. This does NOT mark anything read. Processing loop: read the batch → act on each item (reply, respond to the invite, file, flag — or leave it) → call outlook_mark_read on the plain mail you handled, so the next call returns only what is still new. An invite you answer with outlook_respond_to_invite needs no mark-read: Outlook moves it to Deleted Items under a new id, so its old id would 404. Follow `nextLink` for more.' +
+        description: 'Triage batch: the unread messages in a folder (default inbox), newest first, each WITH its plain-text body (truncated to `maxBodyChars`) in one call — no follow-up outlook_get_message needed. Every item has a `kind`: "mail", "meetingRequest", "meetingCancelled" or "meetingResponse" (a reply to an invite you sent). Requests and cancellations also carry `event` (id, time, organizer, your current `responseStatus`) so the invite can be answered by its event id (when the meeting is no longer on your calendar — already declined, cancelled or deleted — the item has a `hint` instead and there is nothing to respond to). `to`/`cc` list at most 20 addresses; a longer list adds `toCount`/`ccCount` and `toTruncated`/`ccTruncated`. This does NOT mark anything read. Processing loop: read the batch → act on each item (reply, respond to the invite, file, flag — or leave it) → call outlook_mark_read on the plain mail you handled, so the next call returns only what is still new. An invite you answer with outlook_respond_to_invite needs no mark-read: Outlook moves it to Deleted Items under a new id, so its old id would 404. Follow `nextLink` for more. ' +
+            FROM_DESCRIPTION +
+            ' Cannot combine with `sinceHours` or `nextLink`.' +
             ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
         annotations: { readOnlyHint: true, openWorldHint: true },
         inputSchema: z.object({
@@ -251,7 +297,7 @@ export function registerMailTools(server, client) {
                 .positive()
                 .max(24 * 365)
                 .optional()
-                .describe('Only mail received in the last N hours'),
+                .describe('Only mail received in the last N hours (not with `from`)'),
             includeBody: z
                 .boolean()
                 .optional()
@@ -263,12 +309,17 @@ export function registerMailTools(server, client) {
                 .max(100_000)
                 .optional()
                 .describe('Truncate each body to this many characters (default 4000); `bodyTruncated` marks a cut'),
+            from: fromParam,
             nextLink: nextLinkParam,
         }),
-    }, async ({ folder, limit, sinceHours, includeBody, maxBodyChars, nextLink }) => {
+    }, async ({ folder, limit, sinceHours, includeBody, maxBodyChars, from, nextLink }) => {
+        const pos = fromPosition(from, { nextLink, sinceHours });
+        const max = limit ?? 25;
+        const keyset = pos !== undefined ? fromQuery(pos, max) : undefined;
         // Outlook rejects a $filter that does not lead with the $orderby
         // property ("InefficientFilter"), so the date bound goes first.
         const filter = [
+            keyset?.bound,
             sinceHours !== undefined ? `ReceivedDateTime ge ${sinceLiteral(sinceHours)}` : undefined,
             'IsRead eq false',
         ]
@@ -276,13 +327,15 @@ export function registerMailTools(server, client) {
             .join(' and ');
         const data = await fetchPage(client, nextLink, `/me/mailfolders/${folderSegment(folder ?? 'inbox')}/messages`, {
             query: {
-                $top: limit ?? 25,
+                $top: keyset?.top ?? max,
                 $select: UNREAD_SELECT,
                 $filter: filter,
-                $orderby: 'ReceivedDateTime desc',
+                $orderby: keyset ? 'ReceivedDateTime asc' : 'ReceivedDateTime desc',
             },
         });
-        const rows = Array.isArray(data?.value) ? data.value : [];
+        const listed = Array.isArray(data?.value) ? data.value : [];
+        const page = pos !== undefined ? fromPage(listed, pos, max, Boolean(data?.['@odata.nextLink'])) : undefined;
+        const rows = page?.rows ?? listed;
         const wantBody = includeBody !== false;
         const cap = maxBodyChars ?? 4000;
         const items = await mapWithConcurrency(rows, BODY_CONCURRENCY, async (m) => {
@@ -334,9 +387,16 @@ export function registerMailTools(server, client) {
             return item;
         });
         const out = { count: items.length, items };
-        const next = data?.['@odata.nextLink'];
-        if (next)
-            out.nextLink = next;
+        if (page !== undefined) {
+            // The token supersedes the API link, which would resume newest-first.
+            out.next_from = page.next_from;
+            out.has_more = page.has_more;
+        }
+        else {
+            const next = data?.['@odata.nextLink'];
+            if (next)
+                out.nextLink = next;
+        }
         return mailboxUntrusted(out);
     });
     server.registerTool('outlook_list_attachments', {

package/dist/version.js

@@ -10,4 +10,4 @@
  * line below and nowhere else — not even in prose.
  */
 export const PACKAGE_NAME = 'office-outlook-mcp';
-export const VERSION = '0.5.2'; // x-release-please-version
+export const VERSION = '0.6.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/office-outlook-mcp",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "mcpName": "io.github.chrischall/office-outlook-mcp",
   "description": "Outlook / Microsoft 365 MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/office-outlook-mcp",
     "source": "github"
   },
-  "version": "0.5.2",
+  "version": "0.6.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/office-outlook-mcp",
-      "version": "0.5.2",
+      "version": "0.6.0",
       "transport": {
         "type": "stdio"
       },