@chrischall/office-outlook-mcp 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/client.js CHANGED
@@ -13,14 +13,14 @@ import { createTokenCache, reportCacheWriteFailure } from './token-cache.js';
13
13
  * Load the bridge bootstrap lazily.
14
14
  *
15
15
  * `auth-fetchproxy.ts` pulls in `@chrischall/mcp-utils/fetchproxy`, which
16
- * imports the OPTIONAL `@fetchproxy/server` peer. That package is
17
- * esbuild-`--external`, and the `.mcpb` bundle ships no `node_modules` — so a
18
- * top-level import here would throw `ERR_MODULE_NOT_FOUND` the moment a host
19
- * spawns the bundled server, before it can answer `initialize`. The host then
20
- * reports only "Server transport closed unexpectedly".
16
+ * imports `@fetchproxy/server`. In `dist/bundle.js` that package is INLINED —
17
+ * the bundle script marks only `dotenv` as `--external` — so the `.mcpb`
18
+ * needs no `node_modules` for it, and a top-level import would also work.
21
19
  *
22
- * Deferring it means the default path never touches the package, and a user who
23
- * supplies `OUTLOOK_ACCESS_TOKEN` never needs it installed at all.
20
+ * The dynamic import only DEFERS loading: the bridge module (and, for a plain
21
+ * `npm` install, the package itself) is evaluated on the first capture rather
22
+ * than at boot, so a server running on `OUTLOOK_ACCESS_TOKEN` or a cached token
23
+ * never initialises it.
24
24
  */
25
25
  async function captureTokenLazily() {
26
26
  const mod = await import('./auth-fetchproxy.js');
@@ -186,7 +186,8 @@ export class OutlookClient {
186
186
  * — measured 9.4x smaller on a real message, and it also normalises a mixed
187
187
  * HTML/Text collection to one type. `prefer` sets the `Prefer` header
188
188
  * directly, for anything else the API takes there (notably
189
- * `outlook.timezone="…"`).
189
+ * `outlook.timezone="…"`). `query` is serialised by mcp-utils'
190
+ * `buildQueryString`, which drops `undefined`/empty values.
190
191
  */
191
192
  async get(path, opts = {}) {
192
193
  this.#requireConfigured();
@@ -196,6 +197,7 @@ export class OutlookClient {
196
197
  ].filter((p) => p !== undefined);
197
198
  return this.#client().fetchJson('GET', path, {
198
199
  headers: prefer.length ? { Prefer: prefer.join(', ') } : undefined,
200
+ ...(opts.query ? { query: opts.query } : {}),
199
201
  });
200
202
  }
201
203
  /**
@@ -239,6 +241,9 @@ export class OutlookClient {
239
241
  return this.#client().fetchJson('POST', path, {
240
242
  body,
241
243
  headers: opts.prefer ? { Prefer: opts.prefer } : undefined,
244
+ // Read-only: a timeout or dropped connection is safe to retry, so keep
245
+ // the plain error rather than mcp-utils' WriteOutcomeUnknownError.
246
+ idempotent: true,
242
247
  });
243
248
  }
244
249
  /**
package/dist/timezone.js CHANGED
@@ -1,5 +1,29 @@
1
+ /**
2
+ * The mailbox's own Windows time-zone name.
3
+ *
4
+ * Outlook's calendar endpoints default to UTC, which is wrong twice over: a
5
+ * read shows a 7:15am Eastern meeting as 11:15 behind nothing louder than
6
+ * `TimeZone: "UTC"`, and a WRITE books "3pm" four hours off in a real
7
+ * calendar. The mailbox already declares its zone, so the default is knowable
8
+ * rather than guessable — both sides ask here.
9
+ *
10
+ * Cached because it is a per-mailbox constant and paying a round trip per call
11
+ * to re-learn it is not worth it. Keyed by CLIENT rather than held in a module
12
+ * variable: the zone belongs to the mailbox, not the process, so a global
13
+ * would hand one mailbox's zone to another client in the same process — and
14
+ * would leak between tests in file order, which is how a test that believes it
15
+ * exercised the failure path quietly stops doing so.
16
+ *
17
+ * For a READ a failure is swallowed deliberately — the zone is a default, not
18
+ * a requirement, and must not take the calendar down with it. A WRITE passes
19
+ * `required: true` and gets an error instead: there the fallback is booking
20
+ * the caller's "3pm" in UTC, with invitations already sent. Either way a
21
+ * failure is NOT cached, so a transient blip does not pin the mailbox to UTC
22
+ * for the life of the server.
23
+ */
24
+ import { McpToolError } from '@chrischall/mcp-utils';
1
25
  const zoneByClient = new WeakMap();
2
- export async function mailboxTimeZone(client) {
26
+ export async function mailboxTimeZone(client, opts = {}) {
3
27
  const cached = zoneByClient.get(client);
4
28
  if (cached)
5
29
  return cached;
@@ -10,7 +34,12 @@ export async function mailboxTimeZone(client) {
10
34
  zoneByClient.set(client, zone);
11
35
  return zone;
12
36
  }
13
- catch {
14
- return undefined;
37
+ catch (e) {
38
+ if (!opts.required)
39
+ return undefined;
40
+ throw new McpToolError("Could not read the mailbox's time zone, so the event time is ambiguous.", {
41
+ hint: 'Retry, or pass `timeZone` explicitly (a Windows zone name such as "Eastern Standard Time"). ' +
42
+ `Cause: ${e instanceof Error ? e.message : String(e)}`,
43
+ });
15
44
  }
16
45
  }
@@ -14,9 +14,16 @@ export const nextLinkParam = z
14
14
  .min(1)
15
15
  .optional()
16
16
  .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.');
17
- /** Fetch the first page at `path`, or the page a previous `nextLink` points at. */
17
+ /**
18
+ * Fetch the first page at `path` with `query`, or the page a previous
19
+ * `nextLink` points at. A link already carries its own query, so `query` is
20
+ * dropped when following one.
21
+ */
18
22
  export function fetchPage(client, nextLink, path, opts = {}) {
19
- return nextLink !== undefined ? client.getAbsolute(nextLink, opts) : client.get(path, opts);
23
+ if (nextLink === undefined)
24
+ return client.get(path, opts);
25
+ const { query: _ignored, ...headerOpts } = opts;
26
+ return client.getAbsolute(nextLink, headerOpts);
20
27
  }
21
28
  /**
22
29
  * Pass a collection through without a typed projection, trimming the OData
@@ -1,20 +1,10 @@
1
1
  import { z } from 'zod';
2
2
  import { McpToolError, minifiedResult, resolveView, viewParam } from '@chrischall/mcp-utils';
3
3
  import { mailboxUntrusted, UNTRUSTED_DESCRIPTION_SUFFIX } from './_untrusted.js';
4
- import { compactEvent, fullEvent, projectCollection, } from '../view.js';
4
+ import { compactEvent, fullEvent, projectCollection, VIEWS, } from '../view.js';
5
5
  import { fetchPage, nextLinkParam, plainCollection } from './_paging.js';
6
- import { VIEWS } from './mail.js';
7
6
  import { mailboxTimeZone } from '../timezone.js';
8
7
  const EVENT_SELECT = 'Id,Subject,Start,End,Location,Organizer,IsAllDay,IsCancelled,ShowAs,OnlineMeetingUrl,OnlineMeeting,BodyPreview';
9
- function qs(params) {
10
- const parts = [];
11
- for (const [k, v] of Object.entries(params)) {
12
- if (v === undefined || v === '')
13
- continue;
14
- parts.push(`${k}=${encodeURIComponent(String(v))}`);
15
- }
16
- return parts.length ? `?${parts.join('&')}` : '';
17
- }
18
8
  /**
19
9
  * An Outlook `DateTimeTimeZone` for a caller-supplied time.
20
10
  *
@@ -50,7 +40,7 @@ export function registerCalendarTools(server, client) {
50
40
  server.registerTool('outlook_list_events', {
51
41
  description: 'List calendar events in a date window. This uses the calendar VIEW, which expands recurring series into their individual occurrences — the right tool for "what is on my schedule". Times are returned in `timeZone` when given.' +
52
42
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
53
- annotations: { readOnlyHint: true },
43
+ annotations: { readOnlyHint: true, openWorldHint: true },
54
44
  inputSchema: z.object({
55
45
  view: viewParam(VIEWS),
56
46
  start: z
@@ -67,13 +57,16 @@ export function registerCalendarTools(server, client) {
67
57
  }),
68
58
  }, async ({ view, start, end, timeZone, limit, nextLink }) => {
69
59
  const zone = timeZone ?? (await mailboxTimeZone(client));
70
- const data = await fetchPage(client, nextLink, `/me/calendarview${qs({
71
- startDateTime: start,
72
- endDateTime: end,
73
- $select: EVENT_SELECT,
74
- $orderby: 'Start/DateTime',
75
- $top: limit ?? 50,
76
- })}`, zone ? { prefer: `outlook.timezone="${zone}"` } : {});
60
+ const data = await fetchPage(client, nextLink, '/me/calendarview', {
61
+ query: {
62
+ startDateTime: start,
63
+ endDateTime: end,
64
+ $select: EVENT_SELECT,
65
+ $orderby: 'Start/DateTime',
66
+ $top: limit ?? 50,
67
+ },
68
+ ...(zone ? { prefer: `outlook.timezone="${zone}"` } : {}),
69
+ });
77
70
  const v = resolveView(view, VIEWS);
78
71
  if (v === 'raw')
79
72
  return mailboxUntrusted(data);
@@ -82,7 +75,7 @@ export function registerCalendarTools(server, client) {
82
75
  server.registerTool('outlook_get_event', {
83
76
  description: 'Get one calendar event in full, including attendees and their responses.' +
84
77
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
85
- annotations: { readOnlyHint: true },
78
+ annotations: { readOnlyHint: true, openWorldHint: true },
86
79
  inputSchema: z.object({
87
80
  view: viewParam(VIEWS),
88
81
  id: z.string().min(1).describe('Event Id from outlook_list_events'),
@@ -98,13 +91,13 @@ export function registerCalendarTools(server, client) {
98
91
  });
99
92
  server.registerTool('outlook_list_calendars', {
100
93
  description: 'List the calendars in the mailbox, for picking one to read or write against.',
101
- annotations: { readOnlyHint: true },
94
+ annotations: { readOnlyHint: true, openWorldHint: true },
102
95
  inputSchema: z.object({
103
96
  view: viewParam(VIEWS),
104
97
  nextLink: nextLinkParam,
105
98
  }),
106
99
  }, async ({ view, nextLink }) => {
107
- const data = await fetchPage(client, nextLink, `/me/calendars${qs({ $select: 'Id,Name,Color,CanEdit,Owner' })}`);
100
+ const data = await fetchPage(client, nextLink, '/me/calendars', { query: { $select: 'Id,Name,Color,CanEdit,Owner' } });
108
101
  if (resolveView(view, VIEWS) === 'raw')
109
102
  return minifiedResult(data);
110
103
  return minifiedResult(plainCollection(data));
@@ -112,7 +105,7 @@ export function registerCalendarTools(server, client) {
112
105
  server.registerTool('outlook_find_meeting_times', {
113
106
  description: "Find times when people can meet — Outlook's Scheduling Assistant. Give the attendees, a search window and a duration; Outlook checks everyone's free/busy (and the signed-in user's, as organizer) and returns ranked candidate slots with each attendee's availability. By default only working hours are searched. Use this to answer \"when can X and Y meet?\"; then book with outlook_create_event. `start`/`end` are local wall-clock times in `timeZone` (default: the mailbox zone), and returned slots are in that zone too." +
114
107
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
115
- annotations: { readOnlyHint: true },
108
+ annotations: { readOnlyHint: true, openWorldHint: true },
116
109
  inputSchema: z.object({
117
110
  view: viewParam(VIEWS),
118
111
  attendees: attendeeList('required attendees').min(1),
@@ -195,7 +188,7 @@ export function registerCalendarTools(server, client) {
195
188
  server.registerTool('outlook_get_schedule', {
196
189
  description: "Get people's free/busy blocks for a time window — the grid view of Outlook's Scheduling Assistant. Returns each person's busy, tentative and out-of-office items (with subject and location where their calendar shares them). Use outlook_find_meeting_times to have Outlook pick slots instead. `start`/`end` are local wall-clock times in `timeZone` (default: the mailbox zone)." +
197
190
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
198
- annotations: { readOnlyHint: true },
191
+ annotations: { readOnlyHint: true, openWorldHint: true },
199
192
  inputSchema: z.object({
200
193
  view: viewParam(VIEWS),
201
194
  people: attendeeList('people (or rooms) to look up').min(1).max(100),
@@ -1,17 +1,7 @@
1
1
  import { z } from 'zod';
2
2
  import { minifiedResult, resolveView, viewParam } from '@chrischall/mcp-utils';
3
- import { stripOData } from '../view.js';
4
- import { VIEWS } from './mail.js';
3
+ import { stripOData, VIEWS } from '../view.js';
5
4
  import { fetchPage, nextLinkParam, plainCollection } from './_paging.js';
6
- function qs(params) {
7
- const parts = [];
8
- for (const [k, v] of Object.entries(params)) {
9
- if (v === undefined || v === '')
10
- continue;
11
- parts.push(`${k}=${encodeURIComponent(String(v))}`);
12
- }
13
- return parts.length ? `?${parts.join('&')}` : '';
14
- }
15
5
  function collection(data, raw) {
16
6
  if (raw)
17
7
  return data;
@@ -20,17 +10,17 @@ function collection(data, raw) {
20
10
  export function registerDirectoryTools(server, client) {
21
11
  server.registerTool('outlook_get_profile', {
22
12
  description: "Get the signed-in mailbox's identity (email address, display name, alias). The cheapest call that proves the credential works.",
23
- annotations: { readOnlyHint: true },
13
+ annotations: { readOnlyHint: true, openWorldHint: true },
24
14
  inputSchema: z.object({}),
25
15
  }, async () => minifiedResult(stripOData(await client.get('/me'))));
26
16
  server.registerTool('outlook_get_mailbox_settings', {
27
17
  description: 'Get mailbox settings: time zone, working hours, language, and automatic-replies (out-of-office) configuration.',
28
- annotations: { readOnlyHint: true },
18
+ annotations: { readOnlyHint: true, openWorldHint: true },
29
19
  inputSchema: z.object({}),
30
20
  }, async () => minifiedResult(stripOData(await client.get('/me/MailboxSettings'))));
31
21
  server.registerTool('outlook_list_contacts', {
32
22
  description: 'List saved contacts from the mailbox address book.',
33
- annotations: { readOnlyHint: true },
23
+ annotations: { readOnlyHint: true, openWorldHint: true },
34
24
  inputSchema: z.object({
35
25
  view: viewParam(VIEWS),
36
26
  limit: z.number().int().min(1).max(200).optional().describe('Max contacts (default 50)'),
@@ -38,43 +28,49 @@ export function registerDirectoryTools(server, client) {
38
28
  nextLink: nextLinkParam,
39
29
  }),
40
30
  }, async ({ view, limit, skip, nextLink }) => {
41
- const data = await fetchPage(client, nextLink, `/me/contacts${qs({
42
- $top: limit ?? 50,
43
- $skip: skip,
44
- // `MobilePhone1`, not `MobilePhone`: the latter is the Graph name and
45
- // the v2.0 Contact type rejects it outright with a 400.
46
- $select: 'Id,DisplayName,EmailAddresses,CompanyName,JobTitle,MobilePhone1',
47
- })}`);
31
+ const data = await fetchPage(client, nextLink, '/me/contacts', {
32
+ query: {
33
+ $top: limit ?? 50,
34
+ $skip: skip,
35
+ // `MobilePhone1`, not `MobilePhone`: the latter is the Graph name and
36
+ // the v2.0 Contact type rejects it outright with a 400.
37
+ $select: 'Id,DisplayName,EmailAddresses,CompanyName,JobTitle,MobilePhone1',
38
+ },
39
+ });
48
40
  return minifiedResult(collection(data, resolveView(view, VIEWS) === 'raw'));
49
41
  });
50
42
  server.registerTool('outlook_list_people', {
51
43
  description: 'List people ranked by relevance to the user — colleagues and frequent correspondents, drawn from mail traffic rather than the saved address book. Better than outlook_list_contacts for resolving "who is X" in a work mailbox.',
52
- annotations: { readOnlyHint: true },
44
+ annotations: { readOnlyHint: true, openWorldHint: true },
53
45
  inputSchema: z.object({
54
46
  view: viewParam(VIEWS),
55
47
  limit: z.number().int().min(1).max(100).optional().describe('Max people (default 25)'),
56
48
  nextLink: nextLinkParam,
57
49
  }),
58
50
  }, async ({ view, limit, nextLink }) => {
59
- const data = await fetchPage(client, nextLink, `/me/people${qs({
60
- $top: limit ?? 25,
61
- $select: 'Id,DisplayName,ScoredEmailAddresses,JobTitle,CompanyName',
62
- })}`);
51
+ const data = await fetchPage(client, nextLink, '/me/people', {
52
+ query: {
53
+ $top: limit ?? 25,
54
+ $select: 'Id,DisplayName,ScoredEmailAddresses,JobTitle,CompanyName',
55
+ },
56
+ });
63
57
  return minifiedResult(collection(data, resolveView(view, VIEWS) === 'raw'));
64
58
  });
65
59
  server.registerTool('outlook_list_tasks', {
66
60
  description: 'List Outlook tasks with status and due dates.',
67
- annotations: { readOnlyHint: true },
61
+ annotations: { readOnlyHint: true, openWorldHint: true },
68
62
  inputSchema: z.object({
69
63
  view: viewParam(VIEWS),
70
64
  limit: z.number().int().min(1).max(200).optional().describe('Max tasks (default 50)'),
71
65
  nextLink: nextLinkParam,
72
66
  }),
73
67
  }, async ({ view, limit, nextLink }) => {
74
- const data = await fetchPage(client, nextLink, `/me/tasks${qs({
75
- $top: limit ?? 50,
76
- $select: 'Id,Subject,Status,Importance,DueDateTime,CompletedDateTime',
77
- })}`);
68
+ const data = await fetchPage(client, nextLink, '/me/tasks', {
69
+ query: {
70
+ $top: limit ?? 50,
71
+ $select: 'Id,Subject,Status,Importance,DueDateTime,CompletedDateTime',
72
+ },
73
+ });
78
74
  return minifiedResult(collection(data, resolveView(view, VIEWS) === 'raw'));
79
75
  });
80
76
  }
@@ -9,9 +9,10 @@ import { registerCredentialHealthcheckTool } from '@chrischall/mcp-utils/healthc
9
9
  * thing to report — what a broken install needs to know is whether a token
10
10
  * resolved and whether Outlook accepted it.
11
11
  *
12
- * Imported from `/healthcheck`, deliberately NOT from `/fetchproxy`: that
13
- * module pulls in the optional `@fetchproxy/server` peer, which is absent in
14
- * the `.mcpb` bundle.
12
+ * Imported from `/healthcheck`, not from `/fetchproxy`: the credential check
13
+ * needs nothing from the bridge, and `/fetchproxy` would load
14
+ * `@fetchproxy/server` at boot. (It is bundled into `dist/bundle.js`, so this
15
+ * is about not loading it eagerly, not about it being missing.)
15
16
  */
16
17
  export function registerHealthcheckTool(server, client) {
17
18
  registerCredentialHealthcheckTool({
@@ -1,9 +1,8 @@
1
1
  import { z } from 'zod';
2
2
  import { minifiedResult, resolveView, viewParam, McpToolError } from '@chrischall/mcp-utils';
3
- import { compactFolder, compactMessage, fullMessage, projectCollection, } from '../view.js';
3
+ import { compactFolder, compactMessage, fullMessage, projectCollection, VIEWS, } from '../view.js';
4
4
  import { fetchPage, nextLinkParam, plainCollection } from './_paging.js';
5
5
  import { mailboxUntrusted, UNTRUSTED_DESCRIPTION_SUFFIX } from './_untrusted.js';
6
- export const VIEWS = ['compact', 'full', 'raw'];
7
6
  /**
8
7
  * Well-known folder names the API accepts wherever a folder id is taken.
9
8
  * All eight verified present on a live mailbox 2026-09-20.
@@ -20,15 +19,6 @@ const WELL_KNOWN = [
20
19
  ];
21
20
  /** Fields worth listing. Anything not here costs bytes on every row. */
22
21
  const LIST_SELECT = 'Id,Subject,From,ToRecipients,ReceivedDateTime,IsRead,HasAttachments,BodyPreview';
23
- function qs(params) {
24
- const parts = [];
25
- for (const [k, v] of Object.entries(params)) {
26
- if (v === undefined || v === '')
27
- continue;
28
- parts.push(`${k}=${encodeURIComponent(String(v))}`);
29
- }
30
- return parts.length ? `?${parts.join('&')}` : '';
31
- }
32
22
  /** `inbox` etc. pass through; anything else is treated as an opaque folder id. */
33
23
  function folderSegment(folder) {
34
24
  return encodeURIComponent(folder);
@@ -37,15 +27,21 @@ export function registerMailTools(server, client) {
37
27
  server.registerTool('outlook_list_folders', {
38
28
  description: 'List mail folders with unread and total counts. Use this to discover folder ids before listing messages; the well-known names (' +
39
29
  WELL_KNOWN.join(', ') +
40
- ') can be used directly without a lookup.',
41
- annotations: { readOnlyHint: true },
30
+ ') can be used directly without a lookup. Lists ONE level: top-level folders by default, or the child folders of `parent`. A folder with `Children` > 0 has subfolders — list them with `parent` set to its Id.',
31
+ annotations: { readOnlyHint: true, openWorldHint: true },
42
32
  inputSchema: z.object({
43
33
  view: viewParam(VIEWS),
34
+ parent: z
35
+ .string()
36
+ .min(1)
37
+ .optional()
38
+ .describe('List the child folders of this folder (id or well-known name). Omit for the top level.'),
44
39
  limit: z.number().int().min(1).max(200).optional().describe('Max folders (default 50)'),
45
40
  nextLink: nextLinkParam,
46
41
  }),
47
- }, async ({ view, limit, nextLink }) => {
48
- const data = await fetchPage(client, nextLink, `/me/mailfolders${qs({ $top: limit ?? 50 })}`);
42
+ }, async ({ view, parent, limit, nextLink }) => {
43
+ const base = parent !== undefined ? `/me/mailfolders/${folderSegment(parent)}/childfolders` : '/me/mailfolders';
44
+ const data = await fetchPage(client, nextLink, base, { query: { $top: limit ?? 50 } });
49
45
  if (resolveView(view, VIEWS) === 'raw')
50
46
  return minifiedResult(data);
51
47
  return minifiedResult(projectCollection(data, compactFolder, 'mail folder'));
@@ -53,7 +49,7 @@ export function registerMailTools(server, client) {
53
49
  server.registerTool('outlook_list_messages', {
54
50
  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." +
55
51
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
56
- annotations: { readOnlyHint: true },
52
+ annotations: { readOnlyHint: true, openWorldHint: true },
57
53
  inputSchema: z.object({
58
54
  view: viewParam(VIEWS),
59
55
  folder: z
@@ -93,7 +89,7 @@ export function registerMailTools(server, client) {
93
89
  if (unreadOnly === true)
94
90
  params.$filter = 'IsRead eq false';
95
91
  }
96
- const data = await fetchPage(client, nextLink, `${base}${qs(params)}`);
92
+ const data = await fetchPage(client, nextLink, base, { query: params });
97
93
  const v = resolveView(view, VIEWS);
98
94
  if (v === 'raw')
99
95
  return mailboxUntrusted(data);
@@ -102,7 +98,7 @@ export function registerMailTools(server, client) {
102
98
  server.registerTool('outlook_get_message', {
103
99
  description: 'Get one message including its body. The body is requested as plain text rather than HTML (measured ~9x smaller and far easier to read); pass view:"raw" to get Outlook\'s untouched record.' +
104
100
  ' ' + UNTRUSTED_DESCRIPTION_SUFFIX,
105
- annotations: { readOnlyHint: true },
101
+ annotations: { readOnlyHint: true, openWorldHint: true },
106
102
  inputSchema: z.object({
107
103
  view: viewParam(VIEWS),
108
104
  id: z.string().min(1).describe('Message Id from outlook_list_messages'),
@@ -122,15 +118,13 @@ export function registerMailTools(server, client) {
122
118
  });
123
119
  server.registerTool('outlook_list_attachments', {
124
120
  description: "List a message's attachments (name, size, content type). Metadata only — this deliberately does not download bytes.",
125
- annotations: { readOnlyHint: true },
121
+ annotations: { readOnlyHint: true, openWorldHint: true },
126
122
  inputSchema: z.object({
127
123
  id: z.string().min(1).describe('Message Id'),
128
124
  nextLink: nextLinkParam,
129
125
  }),
130
126
  }, async ({ id, nextLink }) => {
131
- const data = await fetchPage(client, nextLink, `/me/messages/${encodeURIComponent(id)}/attachments${qs({
132
- $select: 'Id,Name,Size,ContentType',
133
- })}`);
127
+ const data = await fetchPage(client, nextLink, `/me/messages/${encodeURIComponent(id)}/attachments`, { query: { $select: 'Id,Name,Size,ContentType' } });
134
128
  return minifiedResult(plainCollection(data));
135
129
  });
136
130
  }
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { CONFIRM_FLOW_SENTENCE, CONFIRM_INJECTION_RULE, confirmTokenParam, confirmWrite, McpToolError, minifiedResult, } from '@chrischall/mcp-utils';
2
+ import { CONFIRM_FLOW_SENTENCE, CONFIRM_INJECTION_RULE, confirmTokenParam, confirmWrite, McpToolError, minifiedResult, WriteOutcomeUnknownError, } from '@chrischall/mcp-utils';
3
3
  import { mailboxTimeZone } from '../timezone.js';
4
4
  const recipientList = z
5
5
  .array(z.string().min(3))
@@ -52,6 +52,38 @@ function dateTimeTimeZone(value, zone) {
52
52
  }
53
53
  return { DateTime: value, TimeZone: zone };
54
54
  }
55
+ /**
56
+ * Tool-description sentence for a write whose timeout leaves the outcome
57
+ * unknown. Kept next to {@link unknownOutcome} so the two cannot drift.
58
+ */
59
+ const TIMEOUT_SENTENCE = 'If Outlook does not answer in time (or the connection drops) the result has status "unknown": the write may well have gone through, so check before retrying — never resend blindly.';
60
+ /**
61
+ * Run a non-idempotent write; a timeout or dropped connection after the
62
+ * request was sent (mcp-utils' WriteOutcomeUnknownError) becomes a non-error
63
+ * "unknown" result.
64
+ *
65
+ * By the time the write runs the confirm token is spent, and Outlook has
66
+ * often already accepted the request (sendmail queues with a 202). A plain
67
+ * error invites the model to start over — fresh preview, fresh token — and
68
+ * send a second identical email. Any other failure is a real failure and
69
+ * still throws.
70
+ */
71
+ async function writeOrUnknown(run, checkWhere) {
72
+ try {
73
+ return { ok: true, value: await run() };
74
+ }
75
+ catch (e) {
76
+ if (!(e instanceof WriteOutcomeUnknownError))
77
+ throw e;
78
+ return {
79
+ ok: false,
80
+ result: minifiedResult({
81
+ status: 'unknown',
82
+ 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.`,
83
+ }),
84
+ };
85
+ }
86
+ }
55
87
  /** Wall-clock arithmetic: both sides are naive times in one zone. */
56
88
  const naiveMs = (dt) => Date.parse(`${dt.replace(/\.\d+$/, '')}Z`);
57
89
  const fromNaiveMs = (ms) => new Date(ms).toISOString().replace(/\.\d{3}Z$/, '');
@@ -62,8 +94,10 @@ export function registerWriteTools(server, client) {
62
94
  ' ' +
63
95
  CONFIRM_FLOW_SENTENCE +
64
96
  ' The preview shows exactly what would be sent. ' +
97
+ TIMEOUT_SENTENCE +
98
+ ' ' +
65
99
  CONFIRM_INJECTION_RULE,
66
- annotations: { readOnlyHint: false, destructiveHint: true },
100
+ annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
67
101
  inputSchema: z.object({
68
102
  to: recipientList,
69
103
  cc: recipientList,
@@ -97,7 +131,9 @@ export function registerWriteTools(server, client) {
97
131
  });
98
132
  if (gate)
99
133
  return gate;
100
- await client.write('POST', '/me/sendmail', payload);
134
+ const sent = await writeOrUnknown(() => client.write('POST', '/me/sendmail', payload), 'Sent Items');
135
+ if (!sent.ok)
136
+ return sent.result;
101
137
  // sendmail returns 202 with an empty body; there is no id to report and
102
138
  // no resource to re-read, so say exactly what is known.
103
139
  return minifiedResult({ sent: true, subject, recipients: recipients || null });
@@ -106,7 +142,7 @@ export function registerWriteTools(server, client) {
106
142
  description: 'Create a draft message in the Drafts folder without sending it. Returns the created draft, which can be reviewed and sent from Outlook.' +
107
143
  ' ' +
108
144
  CONFIRM_FLOW_SENTENCE,
109
- annotations: { readOnlyHint: false, destructiveHint: false },
145
+ annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
110
146
  inputSchema: z.object({
111
147
  to: recipientList,
112
148
  cc: recipientList,
@@ -140,7 +176,7 @@ export function registerWriteTools(server, client) {
140
176
  description: 'Mark a message read or unread. The result is verified by re-reading the message — a 2xx alone is not proof it persisted.' +
141
177
  ' ' +
142
178
  CONFIRM_FLOW_SENTENCE,
143
- annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
179
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
144
180
  inputSchema: z.object({
145
181
  id: z.string().min(1).describe('Message Id'),
146
182
  isRead: z.boolean().describe('true to mark read, false to mark unread'),
@@ -176,7 +212,7 @@ export function registerWriteTools(server, client) {
176
212
  description: 'Move a message to another folder (e.g. "archive", "deleteditems", or a folder id from outlook_list_folders). Moving assigns a NEW message id, which is returned.' +
177
213
  ' ' +
178
214
  CONFIRM_FLOW_SENTENCE,
179
- annotations: { readOnlyHint: false, destructiveHint: false },
215
+ annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
180
216
  inputSchema: z.object({
181
217
  id: z.string().min(1).describe('Message Id'),
182
218
  destination: z
@@ -214,8 +250,10 @@ export function registerWriteTools(server, client) {
214
250
  ' ' +
215
251
  CONFIRM_FLOW_SENTENCE +
216
252
  ' ' +
253
+ TIMEOUT_SENTENCE +
254
+ ' ' +
217
255
  CONFIRM_INJECTION_RULE,
218
- annotations: { readOnlyHint: false, destructiveHint: false },
256
+ annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
219
257
  inputSchema: z.object({
220
258
  subject: z.string().describe('Event title'),
221
259
  start: z.string().min(1).describe('Start, ISO 8601 local time e.g. 2026-09-22T15:00:00'),
@@ -237,8 +275,9 @@ export function registerWriteTools(server, client) {
237
275
  ...(attendees ?? []).map((a) => attendee(a, 'Required')),
238
276
  ...(optionalAttendees ?? []).map((a) => attendee(a, 'Optional')),
239
277
  ];
240
- // Falls back to UTC only when the mailbox itself declares no zone.
241
- const tz = timeZone ?? (await mailboxTimeZone(client)) ?? 'UTC';
278
+ // Falls back to UTC only when the mailbox itself declares no zone; a
279
+ // failed lookup refuses rather than guessing.
280
+ const tz = timeZone ?? (await mailboxTimeZone(client, { required: true })) ?? 'UTC';
242
281
  const payload = {
243
282
  Subject: subject,
244
283
  Start: { DateTime: start, TimeZone: tz },
@@ -260,7 +299,10 @@ export function registerWriteTools(server, client) {
260
299
  });
261
300
  if (gate)
262
301
  return gate;
263
- const created = await client.write('POST', '/me/events', payload);
302
+ const write = await writeOrUnknown(() => client.write('POST', '/me/events', payload), 'the calendar (outlook_list_events)');
303
+ if (!write.ok)
304
+ return write.result;
305
+ const created = write.value;
264
306
  let joinUrl = joinUrlOf(created);
265
307
  // A 201 is not proof the Teams meeting was provisioned — the link is.
266
308
  // Re-read once in case it was filled in after the create returned.
@@ -272,6 +314,7 @@ export function registerWriteTools(server, client) {
272
314
  created: true,
273
315
  Id: created?.Id,
274
316
  WebLink: created?.WebLink,
317
+ TimeZone: tz,
275
318
  ...(joinUrl ? { JoinUrl: joinUrl } : {}),
276
319
  ...(wantTeams && !joinUrl
277
320
  ? { warning: 'The event was created, but Outlook returned no Teams join link.' }
@@ -284,7 +327,7 @@ export function registerWriteTools(server, client) {
284
327
  CONFIRM_FLOW_SENTENCE +
285
328
  ' ' +
286
329
  CONFIRM_INJECTION_RULE,
287
- annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
330
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
288
331
  inputSchema: z.object({
289
332
  id: z.string().min(1).describe('Event Id from outlook_list_events or outlook_get_event'),
290
333
  subject: z.string().optional().describe('New title'),
@@ -306,7 +349,7 @@ export function registerWriteTools(server, client) {
306
349
  confirmToken: confirmTokenParam,
307
350
  }),
308
351
  }, async (args, ctx) => {
309
- const tz = args.timeZone ?? (await mailboxTimeZone(client)) ?? 'UTC';
352
+ const tz = args.timeZone ?? (await mailboxTimeZone(client, { required: true })) ?? 'UTC';
310
353
  const path = `/me/events/${encodeURIComponent(args.id)}`;
311
354
  const readEvent = (zone) => client.get(`${path}?$select=${EVENT_STATE_SELECT}`, {
312
355
  prefer: `outlook.timezone="${zone}"`,
package/dist/version.js CHANGED
@@ -10,4 +10,4 @@
10
10
  * line below and nowhere else — not even in prose.
11
11
  */
12
12
  export const PACKAGE_NAME = 'office-outlook-mcp';
13
- export const VERSION = '0.4.0'; // x-release-please-version
13
+ export const VERSION = '0.4.1'; // x-release-please-version
package/dist/view.js CHANGED
@@ -11,6 +11,8 @@
11
11
  * "there was nothing there".
12
12
  */
13
13
  import { projectOrRaw } from '@chrischall/mcp-utils';
14
+ /** The `view` values every read tool accepts; `compact` is the default. */
15
+ export const VIEWS = ['compact', 'full', 'raw'];
14
16
  function addr(r) {
15
17
  const e = r?.EmailAddress;
16
18
  if (!e)
@@ -85,6 +87,8 @@ export function compactFolder(f) {
85
87
  Name: f.DisplayName,
86
88
  Unread: f.UnreadItemCount,
87
89
  Total: f.TotalItemCount,
90
+ // Listings are one level deep; a non-zero count says there is more below.
91
+ Children: f.ChildFolderCount,
88
92
  });
89
93
  }
90
94
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@chrischall/office-outlook-mcp",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "mcpName": "io.github.chrischall/office-outlook-mcp",
5
5
  "description": "Outlook / Microsoft 365 MCP server for Claude — developed and maintained by AI (Claude Code)",
6
6
  "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -45,7 +45,7 @@
45
45
  "typecheck": "tsc -p tsconfig.check.json"
46
46
  },
47
47
  "dependencies": {
48
- "@chrischall/mcp-utils": "^2.15.0",
48
+ "@chrischall/mcp-utils": "^3.0.1",
49
49
  "@fetchproxy/server": "^3.6.0",
50
50
  "@modelcontextprotocol/server": "^2.3.0",
51
51
  "dotenv": "^18.0.1",