@chrischall/office-outlook-mcp 0.6.1 → 0.7.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.6.1"
+    "version": "0.7.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.6.1",
+      "version": "0.7.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "office-outlook-mcp",
   "displayName": "Outlook (Microsoft 365)",
-  "version": "0.6.1",
+  "version": "0.7.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

@@ -103,11 +103,12 @@ Everything is optional — with nothing set, the server captures from the browse
 | `OUTLOOK_CAPTURE_TIMEOUT` | Seconds to wait for the tab to make a readable request. Bounds the WHOLE capture, both declared hosts included. Defaults to `30`. |
 | `OUTLOOK_TOKEN_CACHE` | `false` to stop caching the token between runs. |
 | `OUTLOOK_TOKEN_FILE` | Path to the cached token. Defaults to `~/.office-outlook-mcp/token.json`. |
+| `OUTLOOK_OUTPUT_DIR` | Absolute directory `outlook_export_messages` and `outlook_export_events` write into. Defaults to `~/Downloads/office-outlook-mcp`. When set, a per-call `dest` must be inside it. See [Bulk export](#bulk-export). |
 
 ## Tools
 
 **Read** — `outlook_list_folders`, `outlook_list_messages`,
-`outlook_get_message`, `outlook_get_unread`, `outlook_list_attachments`,
+`outlook_get_message`, `outlook_list_unread_messages`, `outlook_list_attachments`,
 `outlook_get_attachment`, `outlook_list_events`, `outlook_get_event`,
 `outlook_list_calendars`, `outlook_find_meeting_times`,
 `outlook_get_schedule`, `outlook_get_profile`,
@@ -115,7 +116,7 @@ Everything is optional — with nothing set, the server captures from the browse
 `outlook_list_categories`, `outlook_list_tasks`
 
 **Write** (ask you to confirm first — see [Confirmations](#confirmations)) —
-`outlook_send_mail`, `outlook_create_draft`, `outlook_mark_read`,
+`outlook_send_message`, `outlook_create_draft`, `outlook_mark_read`,
 `outlook_update_message`, `outlook_move_message`, `outlook_create_event`,
 `outlook_update_event`, `outlook_respond_to_invite`, `outlook_delete_event`,
 `outlook_reply`.
@@ -146,6 +147,10 @@ what that decision needs in every view: `MyResponse`, `ResponseRequested`,
 `IsOrganizer`, `IsCancelled`, `Type` (SingleInstance, Occurrence, Exception or
 SeriesMaster), `ShowAs` and `IsAllDay`, plus `SeriesMasterId` in the full view.
 
+**Export** — `outlook_export_messages` (mail) and `outlook_export_events`
+(calendar) write JSONL or Markdown files, optionally with attachments, and
+return only where they are; see [Bulk export](#bulk-export).
+
 **Diagnostics** — `outlook_healthcheck`
 
 Every read tool takes `view: compact | full | raw`, defaulting to **compact**.
@@ -156,9 +161,10 @@ mailbox time zone, so its preview can name the zone it would book in; that is
 the one read a preview makes.)
 
 Mail and event text is written by other people, so `outlook_list_messages`,
-`outlook_get_message`, `outlook_get_unread`, `outlook_get_attachment`,
-`outlook_list_events`, `outlook_get_event`, `outlook_find_meeting_times` and
-`outlook_get_schedule` wrap every result (all views) in an untrusted-content
+`outlook_get_message`, `outlook_list_unread_messages`, `outlook_get_attachment`,
+`outlook_list_events`, `outlook_get_event`, `outlook_find_meeting_times`,
+`outlook_get_schedule`, `outlook_export_messages` and `outlook_export_events`
+wrap every result (all views) in an untrusted-content
 envelope — `untrusted_content: true` plus a `note` telling the model to treat
 the text as data, never instructions (a `view: raw` record that carries its
 own `untrusted_content`/`note` key is nested under `data`, so it cannot
@@ -173,7 +179,7 @@ before running non-read-only tools — as the real guard on outbound sends.
 
 An agent can work through new mail end to end without opening Outlook:
 
-1. **Read the batch** — `outlook_get_unread` returns the unread messages in a
+1. **Read the batch** — `outlook_list_unread_messages` returns the unread messages in a
    folder (default inbox), newest first, each with its plain-text body, in one
    call. It does **not** mark anything read. Each item has a `kind`: `mail`,
    `meetingRequest`, `meetingCancelled` or `meetingResponse`; requests and
@@ -198,7 +204,7 @@ An agent can work through new mail end to end without opening Outlook:
    `outlook_move_message` moves one to another folder.
 4. **Mark it handled** — `outlook_mark_read` (or `isRead: true` on
    `outlook_update_message`) on the plain mail you handled, so the next
-   `outlook_get_unread` returns only what is still new. Answered invites are
+   `outlook_list_unread_messages` returns only what is still new. Answered invites are
    already out of the inbox (see step 2).
 
 Replies, forwards, invite responses and new meetings reach other people, so
@@ -208,7 +214,7 @@ each asks you to confirm first — except a reply saved with `draftOnly: true`
 
 ## Paging from a time
 
-`outlook_get_unread` and `outlook_list_messages` also page **oldest first**
+`outlook_list_unread_messages` 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
@@ -218,6 +224,70 @@ 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`.
 
+## Bulk export
+
+`outlook_export_messages` exports mail and `outlook_export_events` exports
+the calendar in bulk, thousands of records at a time, and none of their text
+enters the conversation. The server pages the mailbox (or calendar) and writes
+the records to files. The tool returns only a small manifest: where the files
+are, their sizes, the record and attachment counts, the date span, and
+`has_more` plus a `cursor`. Have the agent read the files with shell tools
+(`jq`, `grep`, `rg`, `head`) rather than opening them whole.
+
+- **Mail arguments:** `folder` (a well-known name such as `inbox` or
+  `sentitems`, or a folder id; `all` exports the whole mailbox; default
+  `inbox`), `since` and `until` (ISO 8601), `search` (full-text, spans the
+  mailbox). Mail is exported oldest first.
+- **Event arguments:** `since` and `until` (ISO 8601, both required, at most
+  two years apart) and `calendar` (a calendar id; default, the default
+  calendar). Events come from the calendar view, so a recurring series is
+  expanded into its individual occurrences. Times are wall-clock times in the
+  mailbox's time zone, named on each record as `time_zone`.
+- **Both:** `format` (`jsonl`, the default, or `markdown`), `attachments`
+  (default `false`), `dest`, `cursor`, `max_items` (default 5000, max 50000)
+  and `budget_seconds` (default 90, max 600).
+- **Files:** `part-0001.jsonl` holds one JSON record per message (id,
+  conversation id, subject, from, to/cc/bcc, dates, flags, categories, web link
+  and the full plain-text body). Its first line is an `_export` header that
+  names the source, account, arguments and an untrusted-content note.
+  An event record carries the id, iCal UID, type and series id, subject,
+  start, end, time zone, location, organizer, attendees with their responses,
+  your response, show-as, categories, the join link and the full plain-text
+  body.
+  `format: "markdown"` writes `part-0001.md`, a readable transcript (one
+  section per message or event), instead.
+  `manifest.json` lists the counts and any errors, and the files: on disk
+  every part's files (it is rewritten as each part finishes); in a blob zip
+  the files in that zip.
+- **Attachments:** with `attachments: true`, each file attachment of up to
+  50 MB is saved as `attachments/<short id>/<name>` (the name sanitized), and
+  the record lists its attachments, each with its relative `path`, or with
+  `skipped` and the reason. Attached Outlook items (a forwarded email or
+  event), cloud-file links (OneDrive/SharePoint), larger files and failed
+  downloads are skipped. One bad attachment never fails the export.
+- **Resuming:** each call stops at `max_items` or `budget_seconds`, whichever
+  comes first. While `has_more` is true, pass `cursor` back unchanged. The
+  next call continues the same export as `part-0002`, `part-0003` and so on.
+  With attachments on, the budget is checked between small groups of
+  records, so a stop can fall inside a page; the cursor resumes at the next
+  record. If Outlook refuses the credential (including while downloading an
+  attachment), or keeps returning 429 after three
+  Retry-After waits, the call keeps what it already wrote and returns the
+  cursor. Re-authenticate, then resume.
+
+Where the files go depends on how the server runs:
+
+| mode | when | `location` in the result |
+| --- | --- | --- |
+| `disk` | any local (stdio) install, the default | an **absolute local directory**, `<dir>/outlook-mail-<YYYYMMDD-HHmmss>/` (or `outlook-events-…`); each file entry carries its absolute `path` |
+| `blob` | hosted on mcp-host, which sets both `MCP_BLOB_BASE_URL` and `MCP_BLOB_SIGNING_KEY` | a **signed download link** to one zip per call (`part-NNNN.zip`, which includes `manifest.json`), valid for **1 hour** (`url_expires_at`) |
+
+On disk, `<dir>` is the per-call `dest`, else `OUTLOOK_OUTPUT_DIR`, else
+`~/Downloads/office-outlook-mcp`. A `dest` must be inside `OUTLOOK_OUTPUT_DIR`
+when that is set. Otherwise it must be inside `~/Downloads`, `~/Documents` or
+`~/Desktop`. A resumed cursor's directory is checked against the same roots
+again.
+
 ## Confirmations
 
 Every write asks you to confirm before anything is sent or changed (except a

package/dist/auth-fetchproxy.js

@@ -24,9 +24,19 @@
  * cannot drive. Capture is the only path, which is why a failed capture is a
  * hard error with actionable guidance rather than a fallback.
  */
-import { createBootstrapOpts, createFetchproxyTransport, } from '@chrischall/mcp-utils/fetchproxy';
+import { captureBearerHeader } from '@chrischall/mcp-utils/fetchproxy';
 import { readPortEnv, readTtlMsEnv } from '@chrischall/mcp-utils';
 import { PACKAGE_NAME, VERSION } from './version.js';
+/**
+ * `raceCaptures` settles the per-host attempts under ONE overall deadline:
+ * `Promise.any` alone is not enough, because the bridge serializes the two
+ * hosts behind its single connection, so the wait was the sum rather than the
+ * max — measured live at 14.4s for a 5s window and 36s for a 20s one. At the
+ * 30s default that lands past the 60s request timeout an MCP client uses by
+ * default. Re-exported (it is mcp-utils', lifted from here) for the test that
+ * pins that bound.
+ */
+export { raceCaptures, stripBearer } from '@chrischall/mcp-utils/fetchproxy';
 /**
  * The fetchproxy concentrator port.
  *
@@ -87,81 +97,6 @@ export const TRUST_DOMAINS = [...CAPTURE_HOSTS];
  * enough that an idle tab does not hang a tool call for minutes.
  */
 const CAPTURE_TIMEOUT_MS = readTtlMsEnv('OUTLOOK_CAPTURE_TIMEOUT', 30_000);
-/**
- * The transport-wide deadline, derived from the capture window rather than left
- * at the library default.
- *
- * `captureRequestHeader`'s own `timeoutMs` is silently capped by
- * `fetchTimeoutMs`: a window raised past the deadline fails early at the
- * deadline's number, which reads as a timeout nobody configured. Deriving it
- * means the two cannot disagree.
- */
-const BRIDGE_DEADLINE_MS = Math.max(CAPTURE_TIMEOUT_MS + 15_000, 30_000);
-/**
- * Shortest plausible token. Real ones are ~5 KB of JWT; this only guards
- * against an empty or echoed header, not against a wrong-audience token.
- */
-const MIN_TOKEN_LENGTH = 100;
-/**
- * Add `fetch` to the derived capability set.
- *
- * `createBootstrapOpts` infers capabilities from the bootstrap DECLARATIONS and
- * the field REPLACES the server's defaults rather than extending them, so a
- * declaration-only set can silently lose `fetch`.
- */
-function withFetch(opts) {
-    const derived = opts.capabilities ?? [];
-    return {
-        ...opts,
-        capabilities: derived.includes('fetch')
-            ? derived
-            : [...derived, 'fetch'],
-    };
-}
-/**
- * Settle a set of per-host capture attempts under ONE overall deadline.
- *
- * `Promise.any` alone is not enough. The two declared hosts are documented as
- * raced, but the bridge serializes them behind its single connection, so the
- * wait was the sum rather than the max — measured live at 14.4s for a 5s window
- * and 36s for a 20s one. At the 30s default that lands past the 60s request
- * timeout an MCP client uses by default, so the host gave up before this code
- * could report the real reason. The window is a promise about total wait, and
- * this is what keeps it.
- *
- * Exported for the test that pins that bound.
- */
-export async function raceCaptures(attempts, windowMs) {
-    // A rejection that loses the race must not surface as an unhandled rejection
-    // once the winner has already settled the caller.
-    for (const a of attempts)
-        a.catch(() => { });
-    let timer;
-    const expiry = new Promise((_, reject) => {
-        timer = setTimeout(() => reject(new Error(`timed out after ${Math.round(windowMs / 1000)}s waiting for the page to ` +
-            'make a request we could read')), windowMs);
-    });
-    try {
-        // `any` resolves on the first SUCCESS rather than the first settle, so the
-        // host the user is not on failing does not sink the one they are on.
-        return await Promise.race([
-            Promise.any(attempts).catch((e) => {
-                throw new Error(e instanceof AggregateError
-                    ? e.errors.map((x) => x.message).join('; ')
-                    : e.message);
-            }),
-            expiry,
-        ]);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
-/** Normalise a captured header to a bare token, dropping any `Bearer ` prefix. */
-export function stripBearer(raw) {
-    const m = /^\s*Bearer\s+(.+)$/i.exec(raw);
-    return (m ? m[1] : raw).trim();
-}
 /**
  * Capture an Outlook access token from the user's signed-in browser tab.
  *
@@ -171,54 +106,23 @@ export function stripBearer(raw) {
  * Returns the bare token (no `Bearer ` prefix).
  */
 export async function captureTokenViaFetchproxy() {
-    const transport = createFetchproxyTransport({
-        ...withFetch(createBootstrapOpts({
-            domains: [...TRUST_DOMAINS],
-            bootstrap: {
-                captureHeaders: [{ ...CAPTURE_DECL_CLOUD }, { ...CAPTURE_DECL_OFFICE }],
-            },
-        })),
+    // `captureBearerHeader` declares only `capture_request_header` beside the
+    // `fetch` base verb, derives the bridge deadline from the window (window +
+    // 15 s, never under 30 s) so a raised window is not cut off early, starts the
+    // transport (skipping `start()` makes the first verb throw "ensureConnected
+    // called before listen()", which reads like a pairing problem), rejects a
+    // header too short to be a token (real ones are ~5 KB of JWT), and closes
+    // the transport whatever happened.
+    return captureBearerHeader({
+        captures: [CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE],
+        domains: TRUST_DOMAINS,
+        windowMs: CAPTURE_TIMEOUT_MS,
         port: getWsPort(),
-        fetchTimeoutMs: BRIDGE_DEADLINE_MS,
         serverName: PACKAGE_NAME,
         version: VERSION,
+        what: 'an Outlook token',
+        guidance: 'Open a signed-in Outlook tab (outlook.cloud.microsoft or ' +
+            'outlook.office.com), leave it in the foreground for a moment so the ' +
+            'page makes a request, and retry.',
     });
-    try {
-        // `start()` loads the identity keypair. It does not bind the port or dial —
-        // that stays lazy until the first verb — but skipping it makes the first
-        // verb throw "ensureConnected called before listen()", which reads exactly
-        // like a pairing problem and is not one.
-        await transport.start();
-        const attempts = [CAPTURE_DECL_CLOUD, CAPTURE_DECL_OFFICE].map((decl) => transport.server
-            .captureRequestHeader({ ...decl, timeoutMs: CAPTURE_TIMEOUT_MS })
-            .then((raw) => {
-            if (typeof raw !== 'string') {
-                throw new Error(`${decl.host}: capture returned no header`);
-            }
-            const token = stripBearer(raw);
-            if (token.length < MIN_TOKEN_LENGTH) {
-                throw new Error(`${decl.host}: authorization header was present but too short to be a ` +
-                    `token (${token.length} chars)`);
-            }
-            return token;
-        }));
-        try {
-            return await raceCaptures(attempts, CAPTURE_TIMEOUT_MS);
-        }
-        catch (e) {
-            const detail = e.message;
-            throw new Error(`could not capture an Outlook token from the browser (${detail}). ` +
-                'Open a signed-in Outlook tab (outlook.cloud.microsoft or ' +
-                'outlook.office.com), leave it in the foreground for a moment so the ' +
-                'page makes a request, and retry.');
-        }
-    }
-    finally {
-        try {
-            await transport.close();
-        }
-        catch {
-            /* the token, or the original failure, is what matters */
-        }
-    }
 }