@chrischall/office-outlook-mcp 0.6.0 → 0.6.2

package/dist/client.js

@@ -6,8 +6,8 @@
  * held, every request is a plain Node `fetch` — the bridge is never on the hot
  * path.
  */
-import { createApiClient, decodeJwtExp, errorKindOf, errorStatusOf, McpToolError, parseBoolEnv, readEnvVar, } from '@chrischall/mcp-utils';
-import { TokenManager } from '@chrischall/mcp-utils/session';
+import { createApiClient, describeTransportFailure, errorKindOf, errorStatusOf, McpToolError, parseBoolEnv, readEnvVar, } from '@chrischall/mcp-utils';
+import { createCapturedTokenManager } from '@chrischall/mcp-utils/session';
 import { createTokenCache, reportCacheWriteFailure } from './token-cache.js';
 /**
  * Load the bridge bootstrap lazily.
@@ -34,35 +34,11 @@ async function captureTokenLazily() {
  * is the host that answers. Verified live 2026-09-20.
  */
 export const DEFAULT_API_BASE = 'https://outlook.office.com/api/v2.0';
-/**
- * Fallback lifetime for a token whose `exp` we cannot read.
- *
- * Real Outlook tokens are JWTs carrying `exp` (~25h out), so this is only
- * reached for a hand-supplied opaque `OUTLOOK_ACCESS_TOKEN`. Deliberately
- * short: being wrong in this direction costs one extra 401-and-replay, while
- * being wrong the other way makes every call fail until a restart.
- */
-const UNKNOWN_TOKEN_TTL_MS = 10 * 60 * 1000;
-/**
- * Sentinel standing in for a refresh token this flow does not have.
- *
- * Outlook Web's token comes from MSAL's hidden-iframe flow; there is no refresh
- * grant we can drive. "Refreshing" therefore means capturing a new one. The
- * sentinel exists because `TokenManager` only calls `refresh` when a refresh
- * token is present, and without it an expired token would have no path back
- * short of restarting the process.
- */
-const RECAPTURE_SENTINEL = 'fetchproxy:recapture';
-function toBearerTokens(accessToken) {
-    let expiresAt;
-    try {
-        // decodeJwtExp returns seconds; a non-JWT throws.
-        expiresAt = decodeJwtExp(accessToken) * 1000;
-    }
-    catch {
-        expiresAt = Date.now() + UNKNOWN_TOKEN_TTL_MS;
-    }
-    return { accessToken, refreshToken: RECAPTURE_SENTINEL, expiresAt };
+/** The URL a `fetch` was called with, for naming its host in a transport failure. */
+function urlOf(input) {
+    if (typeof input === 'string')
+        return input;
+    return input instanceof URL ? input.href : input.url;
 }
 /**
  * Whether `e` is about the credential rather than the request: no token
@@ -97,7 +73,20 @@ export class OutlookClient {
         // and calling it as `this.#fetchImpl(...)` binds `this` to the client, and
         // older undici (Node 18-20, which several MCP hosts still bundle) throws
         // `Illegal invocation` for any receiver that is not `globalThis`.
-        this.#fetchImpl = opts.fetchImpl ?? ((input, init) => fetch(input, init));
+        const fetchImpl = opts.fetchImpl ?? ((input, init) => fetch(input, init));
+        // undici reports every transport failure (DNS, refused/reset connection,
+        // untrusted TLS, a proxy refusing the tunnel) as a bare `TypeError('fetch
+        // failed')`; name the host, the cause code and what to check instead. The
+        // client still marks it a transport failure, so a sent write whose
+        // connection drops stays outcome-unknown.
+        this.#fetchImpl = async (input, init) => {
+            try {
+                return await fetchImpl(input, init);
+            }
+            catch (e) {
+                throw describeTransportFailure(e, urlOf(input), 'Outlook') ?? e;
+            }
+        };
         this.#baseUrl = readEnvVar('OUTLOOK_API_BASE', { env: this.#env }) ?? DEFAULT_API_BASE;
         const direct = readEnvVar('OUTLOOK_ACCESS_TOKEN', { env: this.#env });
         const bridgeOff = parseBoolEnv('OUTLOOK_DISABLE_FETCHPROXY', { env: this.#env });
@@ -119,59 +108,31 @@ export class OutlookClient {
             throw this.#configError;
     }
     #tokenManager() {
-        if (this.#tokens)
-            return this.#tokens;
         const direct = readEnvVar('OUTLOOK_ACCESS_TOKEN', { env: this.#env });
-        const persistence = direct === undefined ? createTokenCache(this.#env) : null;
-        const mint = async () => toBearerTokens(direct ?? (await this.#capture()));
-        this.#tokens = new TokenManager({
-            initial: mint,
-            // There is no refresh grant — re-capture instead. The sentinel argument
-            // is ignored by design.
-            //
-            // But a token supplied as OUTLOOK_ACCESS_TOKEN must NOT be "refreshed" by
-            // reaching for the browser: that silently swaps the credential the
-            // operator chose for whichever account a tab happens to be signed into,
-            // and on a machine with no bridge it just hangs for the capture window on
-            // every 401. Say what is wrong instead.
-            refresh: async () => {
-                if (direct !== undefined) {
-                    throw new McpToolError('OUTLOOK_ACCESS_TOKEN was rejected by Outlook.', {
-                        hint: 'A directly-supplied token cannot be refreshed automatically. Replace ' +
-                            'OUTLOOK_ACCESS_TOKEN with a current one, or unset it to capture from a ' +
-                            'signed-in Outlook browser tab instead.',
-                        status: 401,
-                        kind: 'credential_rejected',
-                    });
-                }
-                return toBearerTokens(await this.#capture());
-            },
-            // A failed cache write must not fail the call that triggered it: the
-            // token is in hand and re-capturable, so a read-only data dir should cost
-            // the next cold start a capture, not this request.
-            ...(persistence
-                ? {
-                    persistence: {
-                        load: () => persistence.load(),
-                        save: (t) => {
-                            try {
-                                persistence.save(t);
-                            }
-                            catch (e) {
-                                reportCacheWriteFailure(e);
-                            }
-                        },
-                        clear: () => {
-                            try {
-                                persistence.clear();
-                            }
-                            catch {
-                                /* nothing useful to do; the next capture overwrites it */
-                            }
-                        },
-                    },
-                }
-                : {}),
+        // Captures on first use (or loads a still-valid cached capture); there is
+        // no refresh grant, so a 401 or an expiring token re-captures instead.
+        //
+        // But a token supplied as OUTLOOK_ACCESS_TOKEN is never cached and never
+        // "refreshed" by reaching for the browser: that silently swaps the
+        // credential the operator chose for whichever account a tab happens to be
+        // signed into, and on a machine with no bridge it just hangs for the
+        // capture window on every 401. Say what is wrong instead.
+        //
+        // A failed cache write must not fail the call that triggered it: the
+        // token is in hand and re-capturable, so a read-only data dir should cost
+        // the next cold start a capture, not this request.
+        this.#tokens ??= createCapturedTokenManager({
+            capture: () => this.#capture(),
+            direct,
+            onDirectRejected: () => new McpToolError('OUTLOOK_ACCESS_TOKEN was rejected by Outlook.', {
+                hint: 'A directly-supplied token cannot be refreshed automatically. Replace ' +
+                    'OUTLOOK_ACCESS_TOKEN with a current one, or unset it to capture from a ' +
+                    'signed-in Outlook browser tab instead.',
+                status: 401,
+                kind: 'credential_rejected',
+            }),
+            persistence: direct === undefined ? createTokenCache(this.#env) : null,
+            onPersistError: reportCacheWriteFailure,
         });
         return this.#tokens;
     }

package/dist/token-cache.js

@@ -1,4 +1,4 @@
-import { createFileStatePersistence, resolveStateFile, } from '@chrischall/mcp-utils/session';
+import { createFileStatePersistence, isBearerTokens, resolveStateFile, } from '@chrischall/mcp-utils/session';
 import { readEnvVar, parseBoolEnv } from '@chrischall/mcp-utils';
 /**
  * Where the captured Outlook access token is cached between runs.
@@ -15,15 +15,6 @@ export function tokenCachePath(env = process.env) {
         fileName: 'token.json',
     });
 }
-function isToken(raw) {
-    if (raw === null || typeof raw !== 'object')
-        return false;
-    const t = raw;
-    return (typeof t.accessToken === 'string' &&
-        t.accessToken !== '' &&
-        typeof t.expiresAt === 'number' &&
-        (t.refreshToken === undefined || typeof t.refreshToken === 'string'));
-}
 /**
  * What a cached token is bound to, or `null` when there is nothing worth
  * caching.
@@ -51,7 +42,7 @@ export function createTokenCache(env = process.env) {
     return createFileStatePersistence({
         filePath: tokenCachePath(env),
         boundTo,
-        validate: (raw) => (isToken(raw) ? raw : null),
+        validate: (raw) => (isBearerTokens(raw) ? raw : null),
     });
 }
 /**

package/dist/tools/writes.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { CONFIRM_FLOW_SENTENCE, CONFIRM_INJECTION_RULE, confirmTokenParam, confirmWrite, errorKindOf, errorStatusOf, mapWithConcurrency, McpToolError, minifiedResult, WriteOutcomeUnknownError, } from '@chrischall/mcp-utils';
+import { CONFIRM_FLOW_SENTENCE, CONFIRM_INJECTION_RULE, confirmTokenParam, confirmWrite, errorKindOf, errorStatusOf, mapWithConcurrency, McpToolError, minifiedResult, unknownOutcomeReason, writeOrUnknown as runWriteOrUnknown, WriteOutcomeUnknownError, } from '@chrischall/mcp-utils';
 import { isCredentialFailure } from '../client.js';
 import { mailboxTimeZone } from '../timezone.js';
 import { cappedRecipients, MAX_RECIPIENTS } from '../view.js';
@@ -31,6 +31,14 @@ const teamsMeetingParam = z
     .boolean()
     .optional()
     .describe('Attach a Microsoft Teams meeting (default true). false leaves it off.');
+/**
+ * On update the Teams meeting is opt-in: an edit to an in-person meeting (or one
+ * on another provider) must not change how people join it unless asked.
+ */
+const addTeamsMeetingParam = z
+    .boolean()
+    .optional()
+    .describe('true adds a Microsoft Teams meeting to an event that lacks one (default false: the way people join is left as it is).');
 const EVENT_STATE_SELECT = 'Id,Subject,IsOrganizer,Start,End,Location,Attendees,IsOnlineMeeting,OnlineMeetingProvider,OnlineMeeting';
 function attendee(Address, Type) {
     return { Type, EmailAddress: { Address } };
@@ -72,21 +80,11 @@ const TIMEOUT_SENTENCE = 'If Outlook does not answer in time (or the connection
  * send a second identical email. Any other failure is a real failure and
  * still throws.
  */
-async function writeOrUnknown(run, checkWhere) {
-    try {
-        return { ok: true, value: await run() };
-    }
-    catch (e) {
-        if (!(e instanceof WriteOutcomeUnknownError))
-            throw e;
-        return {
-            ok: false,
-            result: minifiedResult({
-                status: 'unknown',
-                warning: `Outlook did not confirm this write (${e.timedOut ? 'it did not answer in time' : 'the connection dropped'}), so it may already have happened. Check ${checkWhere} before retrying; do not resend blindly.`,
-            }),
-        };
-    }
+function writeOrUnknown(run, checkWhere) {
+    return runWriteOrUnknown(run, (e) => minifiedResult({
+        status: 'unknown',
+        warning: `Outlook did not confirm this write (${unknownOutcomeReason(e)}), so it may already have happened. Check ${checkWhere} before retrying; do not resend blindly.`,
+    }));
 }
 const INVITE_EVENT_SELECT = 'Id,Subject,IsOrganizer,IsCancelled,Start,End,Organizer,ResponseStatus';
 const DELETE_EVENT_SELECT = 'Id,Subject,IsOrganizer,IsCancelled,ResponseStatus,Type,SeriesMasterId,Start,End,Organizer,Attendees';
@@ -242,37 +240,32 @@ export function registerWriteTools(server, client) {
         return minifiedResult({ sent: true, subject, recipients: recipients || null });
     });
     server.registerTool('outlook_create_draft', {
-        description: 'Create a draft message in the Drafts folder without sending it. Returns the created draft, which can be reviewed and sent from Outlook.' +
-            ' ' +
-            CONFIRM_FLOW_SENTENCE,
-        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+        description: 'Create a draft message in the Drafts folder without sending it. Returns the created draft, which can be reviewed and sent from Outlook. ' +
+            'It does not ask to confirm: a draft reaches nobody until it is sent from Outlook. Calling it twice leaves two drafts. ' +
+            TIMEOUT_SENTENCE,
+        // Self-only and additive, like outlook_reply with draftOnly: nothing is
+        // overwritten or sent. Not idempotent: a repeat creates a second draft.
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
         inputSchema: z.object({
             to: recipientList,
             cc: recipientList,
             subject: z.string().describe('Subject line'),
             body: z.string().describe('Message body'),
             html: z.boolean().optional().describe('Compose the body as HTML (default: plain text)'),
-            confirmToken: confirmTokenParam,
         }),
-    }, async ({ to, cc, subject, body, html, confirmToken }, ctx) => {
+    }, async ({ to, cc, subject, body, html }) => {
         const payload = {
             ...messageBody(subject, body, html),
             ToRecipients: toRecipients(to),
             ...(cc?.length ? { CcRecipients: toRecipients(cc) } : {}),
         };
-        const gate = await confirmWrite(ctx, {
-            tool: 'outlook_create_draft',
-            action: 'mail.create_draft',
-            message: 'Review and confirm this draft:',
-            summary: `Create draft "${subject}"`,
-            // One signed-in mailbox per server process.
-            account: undefined,
-            request: { method: 'POST', path: '/me/messages', body: payload },
-            confirmToken,
-        });
-        if (gate)
-            return gate;
-        const created = await client.write('POST', '/me/messages', payload);
+        // Nothing leaves the mailbox, so there is no one to protect with a
+        // confirmation (same rule as outlook_reply draftOnly). A lost answer
+        // says to look in Drafts before retrying, so a retry does not duplicate.
+        const create = await writeOrUnknown(() => client.write('POST', '/me/messages', payload), 'Drafts');
+        if (!create.ok)
+            return create.result;
+        const created = create.value;
         return minifiedResult({ created: true, Id: created?.Id, WebLink: created?.WebLink });
     });
     server.registerTool('outlook_mark_read', {
@@ -507,7 +500,7 @@ export function registerWriteTools(server, client) {
         });
     });
     server.registerTool('outlook_update_event', {
-        description: 'Update a meeting you organize: retitle, move, relocate, edit the description, or add/remove attendees. Moving only `start` keeps the meeting\'s length. A Microsoft Teams meeting is added if the event lacks one (`teamsMeeting: false` to skip). Attendees are sent an updated invitation. Only the organizer can update a meeting — an attendee\'s edit would change their own copy alone, so it is refused. The result is verified by re-reading the event.' +
+        description: 'Update a meeting you organize: retitle, move, relocate, edit the description, or add/remove attendees. Moving only `start` keeps the meeting\'s length. It does not add a Microsoft Teams meeting unless you pass `teamsMeeting: true` (on an event that lacks one). Attendees are sent an updated invitation. Only the organizer can update a meeting — an attendee\'s edit would change their own copy alone, so it is refused. The result is verified by re-reading the event.' +
             ' ' +
             CONFIRM_FLOW_SENTENCE +
             ' ' +
@@ -530,7 +523,7 @@ export function registerWriteTools(server, client) {
             addAttendees: recipientList.describe('Required attendees to add'),
             addOptionalAttendees: recipientList.describe('Optional attendees to add'),
             removeAttendees: recipientList.describe('Attendees to remove'),
-            teamsMeeting: teamsMeetingParam,
+            teamsMeeting: addTeamsMeetingParam,
             confirmToken: confirmTokenParam,
         }),
     }, async (args, ctx) => {
@@ -603,19 +596,26 @@ export function registerWriteTools(server, client) {
             }
             payload.Attendees = next;
         }
-        const addTeams = args.teamsMeeting !== false && !(current && isTeams(current));
+        const addTeams = args.teamsMeeting === true && !(current && isTeams(current));
         if (addTeams)
             Object.assign(payload, TEAMS);
         if (Object.keys(payload).length === 0) {
             throw new McpToolError('Nothing to update.', {
-                hint: 'Pass at least one of subject, start, end, location, body, or attendee changes.',
+                hint: 'Pass at least one of subject, start, end, location, body, attendee changes, or teamsMeeting: true.',
             });
         }
         const gate = await confirmWrite(ctx, {
             tool: 'outlook_update_event',
             action: 'calendar.update_event',
-            message: 'Review and confirm this change (attendees are sent an updated invitation):',
-            summary: `Update "${current?.Subject ?? args.id}": ${Object.keys(payload).join(', ')}`,
+            message: addTeams
+                ? 'Review and confirm this change (attendees are sent an updated invitation). This will also make it a Microsoft Teams meeting: attendees get a Teams join link.'
+                : 'Review and confirm this change (attendees are sent an updated invitation):',
+            summary: `Update "${current?.Subject ?? args.id}": ${[
+                Object.keys(payload).filter((k) => !(k in TEAMS)).join(', '),
+                addTeams ? 'this will also make it a Microsoft Teams meeting' : '',
+            ]
+                .filter((part) => part !== '')
+                .join('; ')}`,
             // One signed-in mailbox per server process.
             account: undefined,
             target: args.id,

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/office-outlook-mcp",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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,8 +45,8 @@
     "typecheck": "tsc -p tsconfig.check.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^3.0.1",
-    "@fetchproxy/server": "^3.6.0",
+    "@chrischall/mcp-utils": "^3.1.0",
+    "@fetchproxy/server": "^3.6.2",
     "@modelcontextprotocol/server": "^2.3.0",
     "dotenv": "^18.0.1",
     "zod": "^4.6.5"

package/server.json

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