@chrischall/office-outlook-mcp 0.8.2 → 0.8.4

package/dist/tools/_paging.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
 import { McpToolError } from '@chrischall/mcp-utils';
 import { stripOData } from '../view.js';
@@ -38,6 +39,19 @@ export function plainCollection(data) {
         out.nextLink = next;
     return out;
 }
+/** An Id this short is kept as is (a key, or a test fixture); a real Outlook Id is ~150 characters. */
+const MAX_KEY_LENGTH = 16;
+/**
+ * The key a position keeps for a message Id: the Id itself when short, else
+ * 12 base64url characters (72 bits) of its SHA-256. Keys only tell apart the
+ * messages tied at ONE instant, so a collision is not a practical concern,
+ * and a burst of messages in one second costs ~15 characters each in the token
+ * rather than a whole Id. A token from an earlier release, carrying whole Ids,
+ * is re-keyed on read.
+ */
+export function idKey(id) {
+    return id.length <= MAX_KEY_LENGTH ? id : createHash('sha256').update(id).digest('base64url').slice(0, 12);
+}
 export const fromParam = z
     .string()
     .min(1)
@@ -104,7 +118,7 @@ export function decodeFrom(from) {
         !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 };
+    return { t: utcLiteral(ms), ids: [...new Set(p.ids.map(idKey))] };
 }
 /**
  * The `$filter` date bound and `$top` for a page from `pos`. The bound is
@@ -121,21 +135,21 @@ export function fromQuery(pos, limit) {
  * 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 seen = new Set(pos.ids.map(idKey));
+    const fresh = rows.filter((r) => r.Id === undefined || !seen.has(idKey(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 }))
+        .map((r) => ({ id: r.Id === undefined ? undefined : idKey(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)) : [];
+    const carried = newest === Date.parse(pos.t) ? pos.ids.map(idKey).filter((id) => !tied.includes(id)) : [];
     return { t: utcLiteral(newest), ids: [...carried, ...tied] };
 }

package/dist/tools/export.js

@@ -158,8 +158,15 @@ const eventArgsSchema = z.object({
     format: z.enum(['jsonl', 'markdown']),
     attachments: z.boolean().optional(),
 });
-/** Where the next part starts: a keyset position, or a nextLink page + rows consumed from it. */
+/**
+ * Where the next part starts: a keyset position, or a nextLink page + rows
+ * consumed from it. The keyset position is kept as plain `{ t, ids }` (`at`):
+ * the cursor is base64'd as a whole, so a nested `next_from` token would be
+ * encoded twice. `from` (that nested token) is still read from cursors an
+ * earlier release handed out.
+ */
 const positionSchema = z.union([
+    z.object({ at: z.object({ t: z.string().min(1), ids: z.array(z.string()) }) }),
     z.object({ from: z.string().min(1) }),
     z.object({ link: z.string().min(1).optional(), offset: z.number().int().min(0).max(MAX_TOP) }),
 ]);
@@ -877,12 +884,20 @@ export function registerExportTools(server, client, opts = {}) {
         const folder = args.search !== undefined ? 'all' : (args.folder ?? 'inbox');
         const path = folder === 'all' ? '/me/messages' : `/me/mailfolders/${encodeURIComponent(folder)}/messages`;
         const perPage = args.attachments === true ? Math.min(pageSize, ATTACHMENT_PAGE_SIZE) : pageSize;
-        const pos = resumed?.pos ?? (args.search !== undefined ? { offset: 0 } : { from: encodeFrom({ t: since ?? EPOCH, ids: [] }) });
-        if ('from' in pos)
-            decodeFrom(pos.from); // validate a cursor's position before any work
+        const stored = resumed?.pos;
+        // Validate (and normalise) a cursor's keyset position before any work; read an older cursor's nested token.
+        const pos = stored === undefined
+            ? args.search !== undefined
+                ? { offset: 0 }
+                : { at: { t: since ?? EPOCH, ids: [] } }
+            : 'from' in stored
+                ? { at: decodeFrom(stored.from) }
+                : 'at' in stored
+                    ? { at: decodeFrom(encodeFrom(stored.at)) }
+                    : stored;
         const fetch = async (p, remaining) => {
-            if ('from' in p) {
-                const at = decodeFrom(p.from);
+            if ('at' in p) {
+                const { at } = p;
                 const limit = Math.min(remaining, perPage);
                 const { bound, top } = fromQuery(at, limit);
                 const filter = until ? `${bound} and ReceivedDateTime lt ${until}` : bound;
@@ -900,7 +915,7 @@ export function registerExportTools(server, client, opts = {}) {
                         posAfter: () => p,
                     };
                 }
-                if (page.has_more && page.next_from === p.from) {
+                if (page.has_more && page.next_from === encodeFrom(at)) {
                     // No row carried a usable ReceivedDateTime, so the position did not
                     // move; asking again would return (and duplicate) the same page forever.
                     return {
@@ -913,10 +928,12 @@ export function registerExportTools(server, client, opts = {}) {
                 }
                 return {
                     rows: page.rows,
-                    pos: { from: page.next_from },
+                    pos: { at: decodeFrom(page.next_from) },
                     hasMore: page.has_more,
                     // The first n rows are fresh and ascending, so the keyset position after them is computed the same way.
-                    posAfter: (n) => n >= page.rows.length ? { from: page.next_from } : { from: fromPage(page.rows.slice(0, n), at, n, true).next_from },
+                    posAfter: (n) => n >= page.rows.length
+                        ? { at: decodeFrom(page.next_from) }
+                        : { at: decodeFrom(fromPage(page.rows.slice(0, n), at, n, true).next_from) },
                 };
             }
             return linkBatch(p, remaining, () => with429Retry(() => client.get(path, {
@@ -1010,9 +1027,10 @@ export function registerExportTools(server, client, opts = {}) {
         }
         const prefer = args.time_zone ? `outlook.timezone="${args.time_zone}"` : undefined;
         const path = args.calendar !== undefined ? `/me/calendars/${encodeURIComponent(args.calendar)}/calendarview` : '/me/calendarview';
-        const pos = resumed?.pos ?? { offset: 0 };
-        if ('from' in pos)
+        const stored = resumed?.pos ?? { offset: 0 };
+        if (!('offset' in stored))
             throw new McpToolError('`cursor` is not a valid export cursor for this tool.');
+        const pos = stored;
         const fetch = (p, remaining) => linkBatch(p, remaining, () => with429Retry(() => client.get(path, {
             text: true,
             ...(prefer ? { prefer } : {}),

package/dist/tools/mail.js

@@ -1,5 +1,9 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { z } from 'zod';
-import { imageResult, mapWithConcurrency, minifiedResult, resolveView, viewParam, McpToolError, } from '@chrischall/mcp-utils';
+import { expandPath, mapWithConcurrency, readEnvVar, minifiedResult, resolveView, viewParam, McpToolError, } from '@chrischall/mcp-utils';
+import { blobStoreFromEnv, deliverFile, isHostedEnv } from '@chrischall/mcp-utils/export';
 import { briefDate, briefLine, briefResult, spaced, workMeta } from './_hints.js';
 import { addr, addrs, cappedRecipients, compactFolder, compactMessage, fullMessage, projectCollection, VIEWS, } from '../view.js';
 import { EVENT_EXPAND, INVITE_GONE, MEETING_MESSAGE_TYPE, resolvedEvent } from './_invite.js';
@@ -111,6 +115,30 @@ function stripUndefined(o) {
 export const ATTACHMENT_META_SELECT = 'Id,Name,ContentType,Size,IsInline';
 /** Above this an attachment is never inlined, whatever its type (base64 inflates it ~4/3 again). */
 const MAX_INLINE_BYTES = 5 * 1024 * 1024;
+/**
+ * Largest attachment whose bytes are downloaded to hand over as a link or a
+ * saved file (the export tool's per-file cap too). Outlook returns them as one
+ * base64 JSON string, so this bounds the memory one call can take.
+ */
+const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
+const SERVER_NAME = 'office-outlook-mcp';
+const OUTPUT_DIR_ENV = 'OUTLOOK_OUTPUT_DIR';
+function deliveryRoutes(env) {
+    const store = blobStoreFromEnv(env);
+    if (isHostedEnv(env))
+        return { hosted: true, ...(store ? { store } : {}) };
+    const configured = readEnvVar(OUTPUT_DIR_ENV, { env });
+    if (configured !== undefined)
+        return { hosted: false, diskDir: expandPath(configured) };
+    const downloads = join(readEnvVar('HOME', { env }) ?? homedir(), 'Downloads');
+    return { hosted: false, ...(existsSync(downloads) ? { diskDir: join(downloads, SERVER_NAME) } : {}) };
+}
+/** Why an attachment's bytes have no way back to the caller here. */
+function noRouteHint(routes, why) {
+    return routes.hosted
+        ? `${why} This hosted server has no blob store configured (MCP_BLOB_BASE_URL / MCP_BLOB_SIGNING_KEY), so it cannot hand over a download link. Open it in Outlook to read it.`
+        : `${why} Set ${OUTPUT_DIR_ENV} (or create ~/Downloads) to have it saved to disk, or open it in Outlook.`;
+}
 /** Decoded text is cut here; a longer file is marked `textTruncated`. */
 const MAX_TEXT_BYTES = 200 * 1024;
 /**
@@ -192,7 +220,8 @@ async function listFrom(client, pos, opts) {
         : 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) {
+export function registerMailTools(server, client, opts = {}) {
+    const env = opts.env ?? process.env;
     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 (' +
             WELL_KNOWN.join(', ') +
@@ -433,7 +462,7 @@ export function registerMailTools(server, client) {
         return minifiedResult(plainCollection(data));
     });
     server.registerTool('outlook_get_attachment', {
-        description: "Get one attachment's content (ids from outlook_list_attachments). An image comes back as image content the model can see; a text-like file (text/*, JSON, CSV, XML, .ics) is decoded to `text`, capped at 200 KB (`textTruncated` marks a cut). Any other binary (PDF, Office, archives) and anything over 5 MB is returned as metadata only — its bytes are not inlined. An attached Outlook item (a forwarded email or event) or a cloud-file link has no bytes to return; the result says which." +
+        description: "Get one attachment's content (ids from outlook_list_attachments). A text-like file (text/*, JSON, CSV, XML, .ics) up to 5 MB is decoded to `text`, capped at 200 KB (`textTruncated` marks a cut). An image up to 5 MB comes back as image content the model can see. Anything else (PDF, Office, archives) or larger, up to 50 MB, is handed over as the file itself: on a hosted server a signed, expiring download link (`downloadUrl`, valid until `downloadExpiresAt`) — give it to the user; on a local install a fresh file (`path`) under OUTLOOK_OUTPUT_DIR, else ~/Downloads/office-outlook-mcp. `via` says which (image, resource, link or disk). Where neither route exists the result is metadata only and `hint` says why. An attached Outlook item (a forwarded email or event) or a cloud-file link has no bytes to return; the result says which." +
             ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
         annotations: { readOnlyHint: true, openWorldHint: true },
         _meta: workMeta('lookup'),
@@ -469,12 +498,23 @@ export function registerMailTools(server, client) {
             return mailboxUntrusted(out);
         }
         const image = isImage(contentType);
-        if (!image && !isText(contentType, name)) {
-            out.hint = 'Binary content is not inlined: only images and text-like files are returned. Open it in Outlook to read it.';
-            return mailboxUntrusted(out);
+        const text = !image && isText(contentType, name);
+        const size = meta.Size ?? 0;
+        const routes = deliveryRoutes(env);
+        const canHandOver = routes.store !== undefined || routes.diskDir !== undefined;
+        // Decide before downloading, so a 25 MB PDF is never fetched only to be dropped.
+        if (!canHandOver) {
+            if (!image && !text) {
+                out.hint = noRouteHint(routes, 'Binary content is not inlined: only images and text-like files are returned.');
+                return mailboxUntrusted(out);
+            }
+            if (size > MAX_INLINE_BYTES) {
+                out.hint = noRouteHint(routes, 'Content is not inlined above 5 MB.');
+                return mailboxUntrusted(out);
+            }
         }
-        if ((meta.Size ?? 0) > MAX_INLINE_BYTES) {
-            out.hint = 'Content is not inlined above 5 MB. Open it in Outlook to read it.';
+        if (size > MAX_DOWNLOAD_BYTES) {
+            out.hint = 'Attachments over 50 MB are not downloaded. Open it in Outlook to read it.';
             return mailboxUntrusted(out);
         }
         const full = await client.get(path);
@@ -485,20 +525,51 @@ export function registerMailTools(server, client) {
         }
         // Size is Outlook's figure for the whole record and can understate the
         // file; the base64 length bounds the real size, so judge it before decoding.
-        if (base64DecodedLength(bytes) > MAX_INLINE_BYTES) {
-            out.hint = 'Content is not inlined above 5 MB. Open it in Outlook to read it.';
+        const decodedSize = base64DecodedLength(bytes);
+        if (decodedSize > MAX_DOWNLOAD_BYTES) {
+            out.hint = 'Attachments over 50 MB are not downloaded. Open it in Outlook to read it.';
+            return mailboxUntrusted(out);
+        }
+        if (decodedSize > MAX_INLINE_BYTES && !canHandOver) {
+            out.hint = noRouteHint(routes, 'Content is not inlined above 5 MB.');
             return mailboxUntrusted(out);
         }
         const buf = Buffer.from(bytes, 'base64');
-        out.inlined = true;
-        if (image) {
-            // The name is the sender's text, so the metadata keeps its envelope; the image follows it.
-            const env = mailboxUntrusted(out);
-            return { ...env, content: [...env.content, ...imageResult(bytes, contentType).content] };
+        if (text && buf.length <= MAX_INLINE_BYTES) {
+            out.inlined = true;
+            out.text = buf.subarray(0, utf8Boundary(buf, MAX_TEXT_BYTES)).toString('utf8');
+            if (buf.length > MAX_TEXT_BYTES)
+                out.textTruncated = true;
+            return mailboxUntrusted(out);
         }
-        out.text = buf.subarray(0, utf8Boundary(buf, MAX_TEXT_BYTES)).toString('utf8');
-        if (buf.length > MAX_TEXT_BYTES)
-            out.textTruncated = true;
-        return mailboxUntrusted(out);
+        // The bytes themselves: an image inline when it fits; otherwise a signed
+        // link (hosted) or a fresh 0600 file in the download directory (local).
+        const delivered = await deliverFile({
+            // A standalone copy: a small Buffer shares Node's allocation pool, and
+            // mcp-utils' blob PUT (3.7.1) sends `view.slice().buffer` — for a Buffer
+            // that is the WHOLE pool, i.e. unrelated process memory.
+            bytes: new Uint8Array(buf),
+            fileName: name || 'attachment',
+            ...(contentType ? { mimeType: contentType } : {}),
+            store: routes.store ?? null,
+            keyPrefix: 'attachments',
+            inlineMaxBytes: MAX_INLINE_BYTES,
+            // Locally a non-image is saved rather than inlined as an embedded resource.
+            prefer: image || routes.store !== undefined ? 'auto' : 'disk',
+            ...(routes.diskDir !== undefined ? { disk: { dir: routes.diskDir, mode: 0o600 } } : {}),
+        });
+        out.inlined = delivered.via === 'image' || delivered.via === 'resource';
+        out.via = delivered.via;
+        if (delivered.url !== undefined)
+            out.downloadUrl = delivered.url;
+        if (delivered.expiresAt !== undefined)
+            out.downloadExpiresAt = delivered.expiresAt;
+        if (delivered.path !== undefined)
+            out.path = delivered.path;
+        if (delivered.note !== undefined)
+            out.deliveryNote = delivered.note;
+        // The name is the sender's text, so the metadata keeps its envelope; any inline bytes follow it.
+        const result = mailboxUntrusted(out);
+        return { ...result, content: [...result.content, ...delivered.content] };
     });
 }

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.8.2'; // x-release-please-version
+export const VERSION = '0.8.4'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/office-outlook-mcp",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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>",
@@ -45,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.check.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^3.3.1",
+    "@chrischall/mcp-utils": "^3.7.2",
     "@fetchproxy/server": "^3.6.2",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.1",

package/server.json

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